-
- Author agent behavior as React Server Components; compile it into a
- route-graph IR; emit native, independently distributable artifacts
- for each host; and execute hooks and MCP tools as Flight renders
- against a warm runtime. Flight is an internal transport only — the
- hosts see their own native JSON contracts, pinned by revision.
-
-
-
-
-
-
-
-
-
-
- {/* ======================================================== pipeline */}
-
-
-
- One flat config owns identity and policy; everything executable is a
- conventional file whose path is its identity. A generated MCP tool,
- resource, or prompt route module is one async default Server Component
- plus statically extractable
- config,
- inputSchema, and
- resultSchema exports — there is no
- execute/render split (exporting either is the AB4811 error). Other
- route kinds (events, CLI commands) carry their own export
- contracts; skills are Markdown documents parsed from frontmatter
- unless the rendered SKILL.tsx form is used.
-
-
-
- Conventional source tree
-
-
-
-
-
- real route}>
- src/mcp/curator/tools/search_audible.tsx
-
-
-
-
-
-
-
Route kinds compiled into the graph
-
src/mcp/<server>/{tools,resources,prompts,apps}/*.tsx, tool:curator/search, "Flight render in the generated MCP server"],
- ["event-route", src/events/<family>/*.tsx, src/events/stop.tsx, event:tool/before, "Hook wrapper → IPC → warm runtime (or standalone)"],
- ["cli", src/cli/**/*.ts(x) — nesting is the command path, cli:library/audit, "Generated package bin; .tsx renders via dispatcher"],
- ["script", src/scripts/*.ts(x) — direct children only, script:verify-release, "scripts/.mjs (+ -flight.mjs worker when rendered)"],
- ["provider", src/providers/*.ts — factory, not addressable, provider:build-info, "Wraps every render with request-scoped context values"],
- ]}
- />
-
- Source: routes/graph.ts routeGlobs + classifyModule; routes/types.ts. Config always
- wins: modules claimed by explicit scripts/hooks/bin/lib/mcp config never become routes.
-
-
-
-
-
- {/* ===================================================== compile+val */}
-
-
2 · Compile and validate: one immutable IR, structured diagnostics
-
- Discovery globs the conventional roots, rejects unsafe identity
- segments, and refuses to choose sides on any collision — an MCP
- server with both discovered routes and an explicit entry is a hard
- AB4800 error until routes.servers.<id> picks
- a mode. The graph digest covers only project-relative identity, so equal
- trees hash equally on every machine. Every failure is one diagnostic:
- stable AB code, severity, message, and usually a recovery hint.
-
-
-
AB30xx, "Skill documents: Markdown parsing and rendered-skill compilation"],
- [AB40xx, "Plugin metadata, skill fields, package identity (AB4008 version mismatch)"],
- [AB41xx / AB42xx, "Normalized-model invariants; hook configuration and native hook sources"],
- [AB43xx / AB44xx / AB46xx, "MCP servers and Apps; scripts; assets and the generated-runtime floor"],
- [AB47xx, "Package build (bin/lib, AB4716 declaration replay), migration nudges, prebuilt payloads"],
- [AB48xx, "Route graph: collisions AB4800–AB4803, static config grammar AB4805/AB4806, route contract AB4810/AB4811, event vocabulary + CLI command-graph collisions AB4813, CLI argv grammar AB4814, shared-runtime placement AB4817, state AB4818–AB4821"],
- [AB494x, "Providers: default-factory contract, key uniqueness, reserved processLifetime"],
- [AB5000 / AB60xx, "CLI and adapter failures; built-artifact validation against pinned schemas"],
- [AB70xx, "Host installation; read-only Doctor probes AB7300–AB7316; dev rebuilds (AB7103)"],
- [AB8xxx / AB9xxx, "Dev server configuration; eval selection, harnesses, persisted runs"],
- ]}
- />
-
- Source: docs/diagnostics.md. Only error severity gates a build; warnings and infos never block.
-
-
-
- A route's config export is parsed with the TypeScript compiler from a bounded literal
- grammar (object/array/string/number literals, as/satisfies casts). Anything dynamic
- compiles with an empty config beside a named AB4806 error. The same static approach
- projects each CLI route's zod inputSchema onto kebab-case argv options (AB4814 when a
- construct leaves the grammar) — the module's real zod schema still validates at run time.
-
-
-
-
-
- {/* ======================================================== emission */}
-
-
-
- Each adapter projects the normalized model against a pinned host
- capability table (a JSON file with observed versions, evidence
- strings, and per-event support states) and validates its output
- against pinned host schemas whose sha256 hashes ship in the artifact
- manifest. Every capability is supported or{" "}
- unavailable with a written reason — never a
- silent guess.
-
-
.claude-plugin/plugin.json,
- .codex-plugin/plugin.json,
- .cursor-plugin/plugin.json,
- plugin.json],
- ["Marketplace",
- .claude-plugin/marketplace.json,
- .agents/plugins/marketplace.json,
- .cursor-plugin/marketplace.json,
- "—"],
- ["Hooks wiring",
- "hooks/hooks.json, grouped { matcher, hooks: [{ type: 'command', command }] }",
- "same grouped shape; hook processes get PLUGIN_ROOT / PLUGIN_DATA",
- "hooks/hooks.json, flat { command, matcher?, timeout? } entries",
- "none — Agent Plugins 1.0.0 defines no hooks"],
- ["MCP registration",
- .mcp.json (stdio + streamable HTTP),
- .mcp.json,
- mcp.json at plugin root,
- "plugin.json mcp block, ${PLUGIN_ROOT} tokens"],
- ["Skills / rules / commands",
- "skills + commands",
- "skills",
- "skills + rules + commands",
- "skills"],
- ["Path token",
- {"${CLAUDE_PLUGIN_ROOT}"},
- "relative paths + PLUGIN_ROOT cwd",
- {"${CURSOR_PLUGIN_ROOT}"},
- {"${PLUGIN_ROOT}"}],
- ["Install",
- "claude plugin marketplace add ./ + install --scope user|project|local",
- "codex plugin add @ (user scope)",
- "copy to ~/.cursor/plugins/local/ (no non-interactive verb)",
- "distribution profile — no single host install location"],
- ]}
- />
-
- Source: src/adapters/capabilities/*.json (observed 2026-08-28…09-01) and src/adapters/{claude,codex,cursor,portable}.ts.
- A composite "plugin" target emits one directory loadable by both Claude and Codex, with a
- universal hook wrapper that discriminates the host at run time via PLUGIN_ROOT.
-
-
-
- Emitted artifact size by target and file kind (bytes)
-
-
- X: target directory · Y: total bytes, summed per emitted-file kind. Portable has no
- hook wrapper — its spec defines no hooks. Source: examples/hooks-and-scripts
- dist/agent-bundle.manifest.json.
-
-
-
- Provenance in every artifact
-
- agent-bundle.manifest.json records, per emitted file, its sha256 and the exact
- source inputs that produced it, plus the project revision (the artifact epoch),
- each projection's adapter revision, and the sha256 of every
- pinned host schema it was validated against. Its executables.hooks[] rows are the
- canonical hook inventory across hosts (no separate hook index file).
-
-
- Source: dist/agent-bundle.manifest.json fields files[].sha256, files[].sourceInputs,
- project.revision, projections[].schemas[], executables.hooks[].
-
-
-
-
-
-
-
- {/* ================================================== HOOKS DEEP DIVE */}
-
- Deep dive
-
4 · The hooks pipeline: what is on the wire at every step
-
- Two authoring shapes share the emitted hooks.json wiring. A{" "}
- plain handler hook{" "}
- (config hooks: { sessionStart: { handler } })
- compiles into a self-contained wrapper that decodes the native envelope, calls the
- default-export function, and encodes the result — no IPC. An{" "}
- event route{" "}
- (src/events/**) compiles into a thin
- client that forwards the validated envelope over a per-user Unix socket (a named pipe on
- Windows) to the warm runtime living inside the generated MCP server process, where the
- route component renders as a Flight request. The walkthrough below is the event-route
- path for a Claude PreToolUse on a{" "}
- tool/before route.
-
-
-
- generated wiring}>
- What the host actually invokes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Failure semantics: fail closed, one narrow fallback
-
runtime-unavailable, "No live socket (connect refused / missing)", "Standalone fallback if the route declares runtime or fallback 'standalone'; otherwise nonzero exit"],
- [runtime-timeout, "No reply within timeoutMs (default 5 s)", "Nonzero exit — never a fabricated response"],
- [epoch-mismatch, "Wrapper and runtime built from different artifact epochs", "Nonzero exit; no fallback — stale code never answers"],
- [invalid-message, "Payload over 1 MiB, non-JSON, or off-schema", "Nonzero exit"],
- [runtime-failed, "Render threw, socket error, endpoint contention", "Nonzero exit"],
- ]}
- />
-
- Source: src/events/ipc.ts (EventRuntimeTransportError, requestEventRuntime) and the
- generated wrapper in src/adapters/hook-contract.ts — fallback fires only on
- runtime-unavailable with fallback: 'standalone'.
-
-
-
-
The standalone path
-
- A route with runtime: 'standalone' (or
- as fallback) bundles the route module into the wrapper itself: the same
- createCanonicalEventProps builds identity, the component resolves in-process
- (Server Components and Agent protocol elements only), and the same
- projectEventDocument lowers the output. No shared state, no warm process —
- identical wire contract to the host.
-
-
-
- AB4817 guards placement: an event route requiring the shared runtime on a target
- with no generated MCP entry hosting it — and no standalone fallback — fails the build.
-
-
-
-
-
-
-
- The event runtime server claims its endpoint with an exclusive{" "}
- .lock file recording pid and (on
- Linux) the /proc start time. A stale claim is reclaimed only when its owner is
- provably dead — signal-0 probe plus start-time comparison — and on Linux the
- reclamation itself is serialized through a kernel-released abstract-socket gate, so
- a namespace squatter can force bounded retries (100 × 10 ms) but never steal
- ownership. Live endpoints are never stolen; unverifiable claims stay fail-closed.
- Reads use StringDecoder for chunk-safe UTF-8; each connection gets an
- AbortController wired to close/end/error so orphaned renders cancel; teardown
- removes the socket only when its device and inode still match the one it created.
-
-
- Source: src/events/ipc.ts — claimEndpoint, reclaimOrphanedEndpointClaim,
- tryAcquireEndpointRecoveryGate, readOneMessage, closeServer.
-
-
-
-
-
-
-
- {/* ==================================================== event matrix */}
-
-
5 · Event families × hosts
-
- The v1 vocabulary is seven canonical families. Six are supported on
- all three interactive hosts under their native names;{" "}
- workspace/open is supported on
- Cursor as a fire-and-forget observation (the optional native pluginPaths
- return is deliberately not modeled) and stays unavailable on Claude and
- Codex — with a written reason per host, not a silent gap.
-
-
-
- Source: events/projection.ts projectEventDocument and the wrapper validateResult in
- adapters/hook-contract.ts — illegal combinations throw before anything reaches the host.
-
-
-
-
Canonical tool selectors → native matchers
-
file.read, ^Read$, "—", ^Read$],
- [file.write, ^(?:Write|Edit)$, ^(?:apply_patch|Edit|Write)$, ^Write$],
- [shell, ^Bash$, ^Bash$, ^Shell$],
- [mcp, ^mcp__, ^mcp__, ^MCP:],
- [agent, "—", "—", ^Task$],
- ]}
- />
-
- A hook can also pin host-scoped native tool names; a selector no target can map is a
- per-target diagnostic, never a silently empty matcher.
-
-
-
-
- standalone example}>
- src/events/tool/after.tsx — a real event route
-
-
-
-
-
-
-
-
-
- {/* ======================================================== MCP flow */}
-
-
6 · MCP tools: the same architecture, request-shaped
-
-
-
-
-
-
-
-
-
-
- The generated entry carries the compiled route table as data and hands a warm worker to
- the shared server runtime (createGeneratedRouteMcpServer). Each tools/call validates
- input with the route's real zod schema, renders the async default component inside
- runAgentRequest — with providers, the state kernel, and the notice ledger bound —
- streams Flight bytes back, and projects them onto MCP: progress reports become
- notifications, Agent.Result becomes structured content validated by resultSchema. MCP
- Apps embed their built HTML into the bundle as resources keyed by resourceUri. When the
- bundle has event routes, exactly one generated server also hosts the event runtime IPC
- socket — that is the warm runtime hooks talk to, so hooks share process state with tools.
-
-
- Source: build/entry-shell.ts (generatedRouteMcpEntrySource, generatedRouteFlightWorkerSource),
- src/mcp-server-runtime.ts (startEventRuntime, projectMcpRenderStream), build/entries.ts.
-
-
-
-
-
- {/* ==================================================== supporting */}
-
-
7 · Supporting systems
-
-
- State
-
-
-
-
- Drivers supply storage for exactly one lifetime — memory for request/process,
- SQLite under the plugin root's state/ for workspace-durable; external needs
- embedder wiring and is rejected for generated mounting (AB4820). Budgets
- (bytes, revisions, commit latency) fail closed with budget-exceeded. Doctor
- inventories durable stores by filesystem metadata only — it never opens a database.
-
-
-
-
-
- Notices
-
-
-
- An append-only ledger co-mounted with state (reserved id, AB4821). A notice
- targets a recipient — the conjunction of observed identity axes — and moves
- through evidenced states only: pending, attempted, expired, unavailable,
- withdrawn. Delivery is attempted on the next event render; a recipient-scoped
- MCP inbox resource (agent-bundle://notices/inbox) exposes pending notices with
- exposure receipts. No host claims are fabricated.
-
-
- pending
- attempted
- expired
- unavailable
- withdrawn
-
-
-
-
-
- Context axes
-
-
-
- Inside any route, await agent() returns the request context: host, session,
- actor, and workspace each as an Observed value — either
- { state: 'available', value, source } or
- { state: 'unavailable', reason }. Honest absence is the contract: a CLI
- render reports host unavailable ('unsupported-surface') rather than inventing
- one. Capabilities (command, filesystem, network, projectRoot) follow the same
- shape; src/providers/* factories add request-scoped values beside the
- framework-owned processLifetime.
-
-
-
-
-
-
-
-
-
-
- {/* ======================================================== dev loop */}
-
-
8 · The dev loop: epochs, Workbench, doctor, install
-
- agent-bundle dev watches the project, serializes rebuilds, and commits each successful
- build as an immutable epoch under .agent-bundle/epochs/<uuid>/ with an
- active-epoch.json pointer — the same epoch identity that fences hook IPC, so a stale
- wrapper can never talk to a newer runtime. A package-build failure never invalidates a
- committed artifact epoch (it surfaces as the AB7103 warning and retries). Generated
- route declarations publish atomically to .agent-bundle/routes.d.ts.
-
-
-
-
Workbench (desktop web UI over the dev server)
-
-
-
-
Doctor and install
-
- agent-bundle doctor is strictly read-only (AB7300–AB7316): host CLI probes,
- installed-bundle inventory, bundle-to-source comparison, registration proof, event
- runtime endpoint health, and durable-state inventory. It never repairs anything.
-
-
-
- Every target directory is independently distributable with a generated INSTALL.md;
- cursor/portable/plugin targets also ship a standalone install.mjs whose staged copy
- is idempotent for identical content, refuses version or content collisions, and
- never touches sudo or PATH. The packed proof level (agent-bundle/test) runs the
- same mcp-server-runtime in memory, and deleted-source proofs verify artifacts stay
- self-contained after the source tree is gone.
-
-
-
-
-
-
-
- {/* ========================================================== footer */}
-
-
- Verified against /fast/projects/agent-bundle source: routes/{graph,types,contract,public}.ts ·
- config/validate.ts · adapters/hook-contract.ts + capabilities/*.json ·
- events/{ipc,project,projection}.ts · build/{entries,entry-shell}.ts ·
- mcp-server-runtime.ts · rsc-runtime state/notices/agent-request · docs/diagnostics.md +
- docs/framework-mode.md · examples/{hooks-and-scripts,audiobook-curator,rsc-agent-runtime}.
- Wire payloads in section 4 are illustrative values over verified shapes. Reflects the
- post-PR-#280 split of React rendering (events/project.ts) from envelope projection
- (events/projection.ts). Host capability facts pinned at Claude Code 2.1.260, Codex
- 0.147.0, Cursor 2026-08-28, Agent Plugins 1.0.0 (observed 2026-08-28 … 2026-09-01).
-
-
- Generated 2026-09-01 · colors follow the host theme ({t.kind})
-
-
-
- );
-}
diff --git a/docs/effect-conventions.md b/docs/effect-conventions.md
index 8b5196698..b8979cbe5 100644
--- a/docs/effect-conventions.md
+++ b/docs/effect-conventions.md
@@ -28,7 +28,7 @@ Each Effect-consuming package has exactly one `src/effect/boundary.ts`:
The boundary owns:
-- `runPromise` / `runSync` (plus `runPromiseExit` where a caller branches on `Exit`)
+- `runPromise` / `runSync` (a caller that branches on `Exit` wraps its program in `Effect.exit`)
- `AbortSignal` ↔ interruption (`interruptWhenAborted`, `scopedAbortSignal`, `signal` on `runPromise`)
- mapping the Effect error channel onto the existing typed Error contracts
@@ -207,7 +207,7 @@ keep boundary-runner assertions on the package boundary they are testing.
Stage 2 uses Effect `Stream` for the #145 dispatcher: Flight bytes via
`Stream.unfold` that waits for event-stream demand *before* `reader.read()`,
pending boundaries via `Stream.paginate`, contract bounds as the emit stage
-(`boundRenderEventStream` / `createAgentRenderEventSequence`), and progress
+(`emitBoundRenderEvent` / `createAgentRenderEventSequence`), and progress
via `Stream.merge` + `takeUntil(complete)` (not `Stream.callback` — a failed
callback producer does not fail the stream). A `Latch` opened from the
public event-stream pull gates Flight bytes after the shell. Host
diff --git a/package.json b/package.json
index a298b7ae7..b469a868c 100644
--- a/package.json
+++ b/package.json
@@ -21,7 +21,7 @@
"test:watch": "rstest --config rstest.config.ts --watch",
"lint": "rslint .",
"bench:hook-cold-start": "node scripts/measure-hook-cold-start.mjs",
- "bench:preflight-cold-start": "node scripts/measure-preflight-cold-start.mjs",
+ "record:claude-hooks-fixtures": "node scripts/record-claude-hooks-schema-fixtures.mjs",
"typecheck": "node scripts/check-dist-fresh.mjs && tsc --noEmit && tsc --project packages/workbench/tsconfig.json && tsc --project packages/create-agent-bundle/tsconfig.json && tsc --project packages/rsc-markdown-stream/tsconfig.json && tsc --project packages/agent-bundle/tsconfig.web-host.json && pnpm --filter @agent-bundle/docs typecheck",
"check": "pnpm build && pnpm test:unit && pnpm test:route-unit && pnpm test:projection && pnpm test:integration:run && pnpm lint && pnpm typecheck",
"check:local-ci": "node scripts/local-ci.mjs",
@@ -41,7 +41,6 @@
"test:host-install": "rstest --config rstest.config.ts packages/agent-bundle/tests/host-install-proof.test.ts packages/agent-bundle/tests/dev-host-install.test.ts packages/agent-bundle/tests/dev-live-host.test.ts packages/agent-bundle/tests/claude-plugin-validate-acceptance.test.ts",
"test:host-install:build": "pnpm build && pnpm test:host-install",
"test:host-install:packed": "rstest --config rstest.config.ts packages/agent-bundle/tests/packed-host-install-proof.test.ts",
- "test:host-install:packed:build": "pnpm build && pnpm test:host-install:packed",
"test:host-install:session": "rstest --config rstest.config.ts packages/agent-bundle/tests/host-install-session.test.ts",
"test:host-install:session:claude": "pnpm build && AGENT_BUNDLE_HOST_INSTALL_CLAUDE_SESSION=1 pnpm test:host-install:session",
"changeset": "changeset",
@@ -75,7 +74,6 @@
"@rstest/playwright": "0.11.12",
"@types/node": "26.4.1",
"agent-bundle": "workspace:*",
- "commander": "15.0.0",
"pkg-pr-new": "0.0.88",
"playwright": "1.62.1",
"playwright-core": "1.62.1",
diff --git a/packages/agent-bundle/fixtures/contracts/epoch-atomicity/local-linux.json b/packages/agent-bundle/fixtures/contracts/epoch-atomicity/local-linux.json
deleted file mode 100644
index 2fc2a9bb0..000000000
--- a/packages/agent-bundle/fixtures/contracts/epoch-atomicity/local-linux.json
+++ /dev/null
@@ -1,132 +0,0 @@
-{
- "environment": {
- "architecture": "x64",
- "nodeVersion": "v22.23.1",
- "platform": "linux",
- "runtime": "node"
- },
- "operations": [
- {
- "id": "failed-publication-retention",
- "mechanism": "stage-write then atomic rename",
- "observed": {
- "activeEpochIdAfterFailure": "epoch-1",
- "candidateEpochId": "epoch-2",
- "retainedPriorActive": true
- },
- "steps": [
- {
- "action": "seed-active",
- "result": {
- "epochId": "epoch-1"
- }
- },
- {
- "action": "stage-candidate",
- "result": {
- "epochId": "epoch-2"
- }
- },
- {
- "action": "inject-failure-before-rename",
- "result": {
- "error": "simulated publication failure before atomic rename"
- }
- },
- {
- "action": "read-active-after-failure",
- "result": {
- "epochId": "epoch-1"
- }
- }
- ]
- },
- {
- "id": "live-lock-second-writer-rejection",
- "observed": {
- "firstWriter": {
- "status": "acquired"
- },
- "liveOwner": {
- "status": "running"
- },
- "secondWriter": {
- "observedOwner": "writer-a",
- "reason": "lock-exists",
- "status": "rejected"
- }
- },
- "steps": [
- {
- "action": "acquire-exclusive-lock",
- "actor": "writer-a",
- "result": {
- "status": "acquired"
- }
- },
- {
- "action": "probe-live-owner",
- "actor": "writer-a",
- "result": {
- "status": "running"
- }
- },
- {
- "action": "acquire-exclusive-lock",
- "actor": "writer-b",
- "result": {
- "observedOwner": "writer-a",
- "reason": "lock-exists",
- "status": "rejected"
- }
- }
- ]
- },
- {
- "id": "dead-pid-lock-recovery",
- "observed": {
- "recoveredWriter": {
- "status": "acquired"
- },
- "staleOwner": {
- "status": "not-running",
- "systemCode": "ESRCH"
- }
- },
- "steps": [
- {
- "action": "seed-stale-lock",
- "actor": "dead-writer",
- "result": {
- "stalePid": 2147483647
- }
- },
- {
- "action": "probe-owner-pid",
- "actor": "dead-writer",
- "result": {
- "status": "not-running",
- "systemCode": "ESRCH"
- }
- },
- {
- "action": "remove-stale-lock-after-esrch",
- "result": {
- "removed": true
- }
- },
- {
- "action": "acquire-exclusive-lock",
- "actor": "writer-c",
- "result": {
- "status": "acquired"
- }
- }
- ]
- }
- ],
- "spike": {
- "name": "atomic-epoch-publication-and-lock-ownership",
- "scope": "disposable local filesystem probe; evidence only"
- }
-}
diff --git a/packages/agent-bundle/package.json b/packages/agent-bundle/package.json
index 4382f8999..630c95912 100644
--- a/packages/agent-bundle/package.json
+++ b/packages/agent-bundle/package.json
@@ -125,7 +125,6 @@
"ignore": "7.0.8",
"jiti": "2.7.0",
"npm-package-arg": "14.0.0",
- "open": "11.0.2",
"ws": "8.21.3",
"yaml": "2.9.0"
},
diff --git a/packages/agent-bundle/src/contracts/playground.ts b/packages/agent-bundle/src/contracts/playground.ts
deleted file mode 100644
index ff4d8e78a..000000000
--- a/packages/agent-bundle/src/contracts/playground.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-/**
- * Browser-consumable contract surface for Playground sessions, operation
- * requests, and native host catalogs. The host vocabulary is the only
- * runtime export; everything else is type-only because the playground
- * services behind these shapes touch Node builtins.
- */
-export { NATIVE_HOSTS, NATIVE_HOST_LABELS } from '../host-contracts/native-hosts.ts';
-export type { PlaygroundOperationRequest, PlaygroundRun } from '../dev/playground/playground-contract.ts';
-export type { NativePlaygroundCatalog } from '../dev/playground/native-playground-service.ts';
-export type { NativePlaygroundHost } from '../dev/playground/native-playground-types.ts';
-export type {
- DraftEvalCase,
- PlaygroundEpochIdentity,
- PlaygroundExport,
- PlaygroundJsonObject,
- PlaygroundJsonValue,
- PlaygroundReplay,
- PlaygroundSession,
- PlaygroundTarget,
- PlaygroundTraceEvent,
- PlaygroundTraceSource,
-} from '../dev/playground/playground-store.ts';
diff --git a/packages/agent-bundle/src/core/durability-test-hook.ts b/packages/agent-bundle/src/core/durability-test-hook.ts
deleted file mode 100644
index 74de9ca78..000000000
--- a/packages/agent-bundle/src/core/durability-test-hook.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-/**
- * Shared reader for the stores' symbol-keyed durability test seams.
- *
- * Each filesystem-backed store publishes a `Symbol.for` key (the key strings
- * are part of the test contract in tests/support/durability.ts and must not
- * change). A hook installed at that key on `globalThis` is visible only while
- * the process explicitly runs with NODE_ENV=test; outside test mode the seam
- * reads as absent, so production behavior cannot be altered through it.
- */
-export const testModeGlobalValue = (key: symbol): Value | undefined => {
- if (process.env.NODE_ENV !== 'test') return undefined;
- const globals = globalThis as typeof globalThis & Record;
- return globals[key];
-};
diff --git a/packages/agent-bundle/src/core/durable-fs.ts b/packages/agent-bundle/src/core/durable-fs.ts
index 8a8f179b5..cb5f88322 100644
--- a/packages/agent-bundle/src/core/durable-fs.ts
+++ b/packages/agent-bundle/src/core/durable-fs.ts
@@ -1,21 +1,12 @@
-import { Buffer } from 'node:buffer';
-import { closeSync, constants, fsyncSync, openSync } from 'node:fs';
-import { link, lstat, open, realpath, rename, rm, writeFile, type FileHandle } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { link, open, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
import { isErrno, isTolerableWin32SyncError } from './errors.ts';
-import { isInsideOrEqual, sameFile } from './paths.ts';
-import { parseJsonWithoutDuplicateKeys } from './strict-json.ts';
/**
- * Shared filesystem durability toolkit for the playground, eval run, and
- * epoch stores. Every primitive here parameterizes only the differences the
- * stores genuinely have (error vocabularies, test-hook phases, injectable
- * handle opens) while keeping one implementation of each durability
- * algorithm: atomic temp+rename JSON publication, staged hard-link
- * publication, file and directory fsync with the documented Windows
- * directory tolerance, pinned single-link file verification, and
- * torn-tail-tolerant JSONL decoding.
+ * Filesystem durability primitives behind the dev lock's link-published
+ * owner document: file and directory fsync with the documented Windows
+ * directory tolerance, and staged hard-link publication.
*/
/** Minimal handle surface the async sync primitives need; `FileHandle` satisfies it. */
@@ -53,60 +44,6 @@ export const syncPath = async (path: string, options: SyncPathOptions = {}): Pro
}
};
-export interface SyncDirectorySyncOptions {
- /** Runs after the descriptor opens, immediately before the fsync attempt. */
- readonly beforeFsync?: () => void;
- /** Runs immediately before the directory descriptor opens. */
- readonly beforeOpen?: () => void;
- /** Defaults to `process.platform`. */
- readonly platform?: NodeJS.Platform;
-}
-
-/** Synchronous directory fsync with the same Windows tolerance as {@link syncPath}. */
-export const syncDirectorySync = (path: string, options: SyncDirectorySyncOptions = {}): void => {
- options.beforeOpen?.();
- const descriptor = openSync(path, constants.O_RDONLY);
- try {
- options.beforeFsync?.();
- fsyncSync(descriptor);
- } catch (error) {
- // See syncPath: only documented Windows directory FlushFileBuffers
- // capability failures are tolerated.
- if (isTolerableWin32SyncError(options.platform ?? process.platform, error)) return;
- throw error;
- } finally {
- closeSync(descriptor);
- }
-};
-
-export interface AtomicJsonWriteOptions {
- /** Caller-named staging path; it must share a directory with the destination. */
- readonly temporaryPath: string;
- readonly open?: DurableHandleOpen;
- readonly platform?: NodeJS.Platform;
-}
-
-/**
- * Atomically publishes a serialized JSON document: write to the staging path,
- * fsync it, rename it over the destination, then fsync the directory so the
- * rename itself is durable. The staging file never survives, even on failure.
- */
-export const writeJsonFileAtomically = async (
- path: string,
- serialized: string,
- options: AtomicJsonWriteOptions,
-): Promise => {
- const sync = { open: options.open, platform: options.platform };
- try {
- await writeFile(options.temporaryPath, serialized, 'utf8');
- await syncPath(options.temporaryPath, sync);
- await rename(options.temporaryPath, path);
- await syncPath(dirname(path), { ...sync, directory: true });
- } finally {
- await rm(options.temporaryPath, { force: true });
- }
-};
-
/** Staging handle surface the link publication needs; `FileHandle` satisfies it. */
export interface DurableStagingHandle extends DurableHandle {
writeFile(data: string, encoding: 'utf8'): Promise;
@@ -195,170 +132,3 @@ export const publishFileByLink = async (
}
return created;
};
-
-export interface WriteNewPinnedFileOptions {
- /** Runs after the fsync succeeds so callers can mark the file recoverable. */
- readonly afterFsync?: () => void;
- readonly beforeFsync?: () => void | Promise;
- readonly beforeWrite?: () => void | Promise;
- /** Store-specific error for a create that did not pin a singly linked regular file. */
- readonly invalid: () => Error;
-}
-
-/**
- * Exclusively creates a new durable file (O_EXCL, no symlink following),
- * proves the created handle pins a singly linked regular file, then writes
- * and fsyncs its contents.
- */
-export const writeNewPinnedFile = async (
- path: string,
- contents: string,
- options: WriteNewPinnedFileOptions,
-): Promise => {
- const handle = await open(
- path,
- constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
- 0o600,
- );
- try {
- const stat = await handle.stat();
- if (!stat.isFile() || stat.nlink !== 1) throw options.invalid();
- await options.beforeWrite?.();
- await handle.writeFile(contents, 'utf8');
- await options.beforeFsync?.();
- await handle.sync();
- options.afterFsync?.();
- } finally {
- await handle.close();
- }
-};
-
-export interface OpenPinnedContainedFileOptions {
- readonly flags: number;
- /** Store-specific error for a path that is not a singly linked contained regular file. */
- readonly invalid: () => Error;
- readonly name: string;
- readonly root: string;
-}
-
-/**
- * Opens `name` inside `root` and proves that the handle and the path name the
- * same singly linked regular file (matching dev/ino, nlink 1, no symlink)
- * whose real path stays contained under `root`. The handle is closed when any
- * check fails.
- */
-export const openPinnedContainedFile = async (options: OpenPinnedContainedFileOptions): Promise => {
- const path = join(options.root, options.name);
- const handle = await open(path, options.flags | constants.O_NOFOLLOW);
- try {
- const [fileStat, pathStat] = await Promise.all([handle.stat(), lstat(path)]);
- const resolved = await realpath(path);
- if (!fileStat.isFile()
- || !pathStat.isFile()
- || pathStat.isSymbolicLink()
- || fileStat.nlink !== 1
- || pathStat.nlink !== 1
- || fileStat.dev !== pathStat.dev
- || fileStat.ino !== pathStat.ino
- || !isInsideOrEqual(options.root, resolved)
- || basename(resolved) !== options.name) {
- throw options.invalid();
- }
- return handle;
- } catch (error) {
- await handle.close();
- throw error;
- }
-};
-
-export interface ReadPinnedFileOptions {
- /** Store-specific error for a file that changed between lstat and the opened handle. */
- readonly changedWhileOpening: () => Error;
- /** Store-specific error for a file whose identity or size drifted across the read. */
- readonly changedWhileReading: () => Error;
- /** Upper bound on the pinned file's size in bytes. */
- readonly maximumBytes: number;
- /** Store-specific error for a symlinked, multiply linked, or oversized path. */
- readonly unsafe: () => Error;
- /** Re-verifies caller-tracked ancestor directory identities before and after the read. */
- readonly verifyAncestry?: () => Promise;
-}
-
-/**
- * Reads a whole pinned file while proving the path, the open descriptor, and
- * the post-read stats all describe the same singly linked regular file whose
- * size never changed — the shared TOCTOU defense for record reads.
- */
-export const readPinnedFile = async (path: string, options: ReadPinnedFileOptions): Promise => {
- await options.verifyAncestry?.();
- const before = await lstat(path);
- if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1 || before.size > options.maximumBytes) {
- throw options.unsafe();
- }
- const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
- try {
- const descriptor = await file.stat();
- if (!descriptor.isFile() || descriptor.nlink !== 1 || descriptor.size > options.maximumBytes || !sameFile(before, descriptor)) {
- throw options.changedWhileOpening();
- }
- const bytes = await file.readFile({ encoding: 'utf8' });
- const [after, final] = await Promise.all([lstat(path), file.stat()]);
- await options.verifyAncestry?.();
- if (after.isSymbolicLink() || !after.isFile() || after.nlink !== 1 || !sameFile(before, after) || !sameFile(descriptor, final) ||
- final.size !== descriptor.size || Buffer.byteLength(bytes, 'utf8') !== descriptor.size) {
- throw options.changedWhileReading();
- }
- return bytes;
- } finally {
- await file.close();
- }
-};
-
-export interface TornTailJsonlOptions {
- /** Decodes one complete strict-parsed line, throwing the store's error for invalid records. */
- readonly decode: (value: unknown, index: number) => Record;
- /** Store-specific error for an empty complete line. */
- readonly emptyRecord: () => Error;
- /** Store-specific error for a complete line that is not strict JSON. */
- readonly malformedRecord: () => Error;
- /** Store-specific error when a decoded record's sequence is not exactly index + 1. */
- readonly sequenceViolation: () => Error;
-}
-
-export interface TornTailJsonlRead {
- /** Present when the log ends in a torn, incomplete final append. */
- readonly incompleteTrailingRecord?: string;
- readonly records: readonly Record[];
-}
-
-/**
- * Decodes a JSONL journal tolerating exactly one torn trailing append: split
- * on newlines, drop the trailing fragment (or the empty string after a final
- * newline), reject empty complete lines, strict-parse each record without
- * duplicate keys, and verify sequences are exactly 1 through N.
- */
-export const readTornTailJsonl = (
- contents: string,
- options: TornTailJsonlOptions,
-): TornTailJsonlRead => {
- const lines = contents.split('\n');
- // The final element is the empty string after a trailing newline or a torn tail append; both are dropped.
- const trailing = lines.pop() ?? '';
- const records: Record[] = [];
- for (const [index, line] of lines.entries()) {
- if (line.length === 0) throw options.emptyRecord();
- let parsed: unknown;
- try {
- parsed = parseJsonWithoutDuplicateKeys(line);
- } catch {
- throw options.malformedRecord();
- }
- const record = options.decode(parsed, index);
- if (record.sequence !== index + 1) throw options.sequenceViolation();
- records.push(record);
- }
- return Object.freeze({
- records: Object.freeze(records),
- ...(trailing.length === 0 ? {} : { incompleteTrailingRecord: trailing }),
- });
-};
diff --git a/packages/agent-bundle/src/core/owner-lock.ts b/packages/agent-bundle/src/core/owner-lock.ts
index 2e480ac23..4540e9277 100644
--- a/packages/agent-bundle/src/core/owner-lock.ts
+++ b/packages/agent-bundle/src/core/owner-lock.ts
@@ -68,32 +68,3 @@ export const acquireOwnerLockFile = async (options: AcquireOwnerLockOpti
}
throw options.exhausted();
};
-
-/**
- * Process-wide serializer for owner-lock mutations, keyed by lock path.
- *
- * Sharing across store instances is intentional: two services recovering or
- * releasing the same on-disk lock must serialize their read-verify-unlink
- * windows even though each service holds its own instance. Entries are
- * removed as soon as the last queued mutation for a path settles, so the
- * registry never grows past the set of locks currently being mutated.
- */
-export class OwnerMutationSerializer {
- readonly #tails = new Map>();
-
- async run(path: string, operation: () => Promise): Promise {
- const previous = this.#tails.get(path) ?? Promise.resolve();
- const boundary = Promise.withResolvers();
- this.#tails.set(path, boundary.promise);
- await previous;
- try {
- return await operation();
- } finally {
- boundary.resolve();
- if (this.#tails.get(path) === boundary.promise) this.#tails.delete(path);
- }
- }
-}
-
-/** The one process-wide owner-mutation serializer every store instance shares. */
-export const sharedOwnerMutationSerializer = new OwnerMutationSerializer();
diff --git a/packages/agent-bundle/src/core/strict-json.ts b/packages/agent-bundle/src/core/strict-json.ts
index 22dd2fc36..44108b4d2 100644
--- a/packages/agent-bundle/src/core/strict-json.ts
+++ b/packages/agent-bundle/src/core/strict-json.ts
@@ -245,12 +245,6 @@ const snapshotJsonValue = (value: unknown, ancestors: Set