feat(core): add launch, SessionState, and createAgent to @e2e-dev/core

KD
6h ago
+3061-229

Stack 3/3: session-half split → move into @e2e-dev/core → this PR.

2026-11-15: rebased onto main 235986078 and the package renamed from e2e-core to @e2e-dev/core. Command output quoted below predates the rename.

@e2e-dev/core drives a browser or a native app from plain code. It is the engines, locators, agent, and replay cache, with no test runner, config file, or report. e2e is now built on it.

import { launch } from '@e2e-dev/core';
import { createAgent } from '@e2e-dev/core/agent';
import { web } from '@e2e-dev/web/engine';

await using shop = await launch(web(), { app: { url: 'https://shop.example.com' }, secrets: { PASSWORD: process.env.PASSWORD! } });
await using session = await shop.newSession();
await session.app.open('/login');
await session.screen.getByLabel('Password').fill(shop.secret('PASSWORD'));

const agent = createAgent(session, { model, cache: { dir: '.bot/cache' } });
await agent.act('add the item and apply the best coupon', { cacheKey: 'cart' });

Engines without e2e

  • @e2e-dev/web/engine and @e2e-dev/mobile/engine export the factories and their types without test, so a program never loads e2e.
  • The engines' e2e peer becomes optional, needed only by the main entry that extends test.
  • @e2e-dev/core gains its @e2e-dev/core and @e2e-dev/core/agent entries. @e2e-dev/core/agent also exports what e2e/agent does.

What @e2e-dev/core adds

  • Hosts and sessions: launch(engine, options) returns a host, and host.newSession() returns an isolated session with screen, app, platform, and the engine's fixture.
    • EngineHandle<Fixtures> makes launch(web()) type session.browser. defineEngine<Fixtures>() requires a factory in fixtures for each fixture it names (besides screen, app, platform), returning that fixture, and a union of fixture sets needs one member's factories.
    • A session publishes nothing to globalThis and has no session deadline.
    • Each operation has a default timeout, set with setDefaultTimeout.
    • launch and newSession take a signal, and the host closes on Ctrl-C.
  • Saved state: session.saveState() returns an in-memory SessionState.
    • It leaves the process only through state.export({ key }), encrypted with AES-256-GCM as a new session-state-1 document (schema and fixtures in packages/e2e/schema).
    • The state carries the secret values the session knew.
  • Secrets: pass values to launch({ secrets }) and get handles from host.secret(name). There is no process-wide registry.
  • Agent: createAgent(session, options) in @e2e-dev/core/agent.
    • With cache, every act names its recording with cacheKey, enforced in types and at runtime.
  • Device links: app.linkBase plus a new optional engine hook session.openLink (protocol method session/openLink) make app.open(path) open a link in a device app. @e2e-dev/mobile implements the hook.

Docs: a new docs/core.mdx, plus updates to the engine, config, errors, security, and agent reference pages.

Verified

Ran it locally: yes

  • @e2e-dev/core without e2e: a scratch project installed only the packed @e2e-dev/core and @e2e-dev/web, and node_modules held no e2e. It ran a script on real Chromium: a login page with a host.secret() fill, saveState(), export({ key }) and SessionState.import, then a new session restored from that state.

    e2e installed? 0
    e2e-core copies: 1
    price: 39,000
    browser fixture: object
    restored session signed in
    
  • Install smoke: scripts/install-smoke.ts now packs @e2e-dev/core too and fails on a second copy of it. It passes with pnpm 11 and pnpm 12, a single @e2e-dev/core copy after both the fresh and the frozen-lockfile install.

  • Built CLI: testbed default suite 588 passed. Web benchmark tests/ 93 passed.

  • Agentic benchmark (CI=1 test:agent --strict-cache, no model key): the branch matches main, so no cache key moved. The 8 failures on both are steps that need a model call.

    mainthis branch
    cache26 replayed · 3 handed off · 6 missed26 replayed · 3 handed off · 6 missed
    failed tests (need a model)88, the same tests
  • Review: a fresh-context review (GPT-6.1 Sol) found three secret-handling gaps in session state, all fixed with regression tests that fail without the fix:

    • a restored state lost redaction of the launch's own secrets;
    • saveState() errors bypassed the sanitized error boundary;
    • a malformed IV or tag threw a raw crypto error instead of SESSION_INVALID.
  • Fixes from cubic, each with a test that fails without it:

    • mobile openLink uses the input budget, so a timed-out open is ACTION_MAY_HAVE_COMMITTED;
    • linkBase refuses an empty ? or # and surrounding whitespace;
    • a recorded space press reads back (already broken on main for press keys);
    • agent operations follow setDefaultTimeout;
    • a failed close on Ctrl-C is reported on stderr (new SIGINT test on a child process);
    • isRefusedLinkScheme is shared from @e2e-dev/core/engine with the mobile engine.
  • defineEngine<Fixtures> typing (added after the split, maintainer's choice on the cubic thread): tests/types/sdk-types.ts asserts that a missing factory, a factory returning the wrong type, and a union with no member's factories fail to compile, and that narrowing app needs none. Each assertion fails without the change. web() and mobile() compile unchanged.

  • Since the split: this PR's code is the head reviewed and verified above, plus that typing change and the changesets split across the stack. A second fresh-context review (GPT-6.1 Sol) of the whole stack found the union bypass, fixed here.

Left for later

  • The agent guard (stop, deny, check) and ActResult.status were removed from this PR in 85af095ab. They can come back as their own PR.
  • @e2e-dev/core's tests still live in packages/e2e/tests and import it through @e2e-dev/core/lib/*.
  • Integrations (@e2e-dev/kernel, eas, testmu, and others) still peer on e2e, so they don't yet work with @e2e-dev/core alone.
  • @e2e-dev/core's types.ts still declares the test API types. They are type-only and add nothing at runtime.
  • session-state-1 copies session-1's 64 MiB cap without enforcing it on export, as session-1 does not; one rule for both formats would be its own change.

🤖 Generated with Claude Code