feat(core): add launch, SessionState, and createAgent to @e2e-dev/core
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/engineand@e2e-dev/mobile/engineexport the factories and their types withouttest, so a program never loadse2e.- The engines'
e2epeer becomes optional, needed only by the main entry that extendstest. @e2e-dev/coregains its@e2e-dev/coreand@e2e-dev/core/agententries.@e2e-dev/core/agentalso exports whate2e/agentdoes.
What @e2e-dev/core adds
- Hosts and sessions:
launch(engine, options)returns a host, andhost.newSession()returns an isolated session withscreen,app,platform, and the engine's fixture.EngineHandle<Fixtures>makeslaunch(web())typesession.browser.defineEngine<Fixtures>()requires a factory infixturesfor each fixture it names (besidesscreen,app,platform), returning that fixture, and a union of fixture sets needs one member's factories.- A session publishes nothing to
globalThisand has no session deadline. - Each operation has a default timeout, set with
setDefaultTimeout. launchandnewSessiontake asignal, and the host closes on Ctrl-C.
- Saved state:
session.saveState()returns an in-memorySessionState.- It leaves the process only through
state.export({ key }), encrypted with AES-256-GCM as a newsession-state-1document (schema and fixtures inpackages/e2e/schema). - The state carries the secret values the session knew.
- It leaves the process only through
- Secrets: pass values to
launch({ secrets })and get handles fromhost.secret(name). There is no process-wide registry. - Agent:
createAgent(session, options)in@e2e-dev/core/agent.- With
cache, everyactnames its recording withcacheKey, enforced in types and at runtime.
- With
- Device links:
app.linkBaseplus a new optional engine hooksession.openLink(protocol methodsession/openLink) makeapp.open(path)open a link in a device app.@e2e-dev/mobileimplements 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/corewithoute2e: a scratch project installed only the packed@e2e-dev/coreand@e2e-dev/web, andnode_modulesheld noe2e. It ran a script on real Chromium: a login page with ahost.secret()fill,saveState(),export({ key })andSessionState.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.tsnow packs@e2e-dev/coretoo and fails on a second copy of it. It passes with pnpm 11 and pnpm 12, a single@e2e-dev/corecopy 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.main this branch cache 26 replayed · 3 handed off · 6 missed 26 replayed · 3 handed off · 6 missed failed tests (need a model) 8 8, 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
openLinkuses the input budget, so a timed-out open isACTION_MAY_HAVE_COMMITTED; linkBaserefuses an empty?or#and surrounding whitespace;- a recorded space press reads back (already broken on main for
presskeys); - agent operations follow
setDefaultTimeout; - a failed close on Ctrl-C is reported on stderr (new SIGINT test on a child process);
isRefusedLinkSchemeis shared from@e2e-dev/core/enginewith the mobile engine.
- mobile
-
defineEngine<Fixtures>typing (added after the split, maintainer's choice on the cubic thread):tests/types/sdk-types.tsasserts that a missing factory, a factory returning the wrong type, and a union with no member's factories fail to compile, and that narrowingappneeds none. Each assertion fails without the change.web()andmobile()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) andActResult.statuswere removed from this PR in85af095ab. They can come back as their own PR. @e2e-dev/core's tests still live inpackages/e2e/testsand import it through@e2e-dev/core/lib/*.- Integrations (
@e2e-dev/kernel,eas,testmu, and others) still peer one2e, so they don't yet work with@e2e-dev/corealone. @e2e-dev/core'stypes.tsstill declares the test API types. They are type-only and add nothing at runtime.session-state-1copies 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