@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/README.md

@@ -157,21 +157,39 @@ const agent = createPiAgent({
 
 The root export intentionally contains the supported surface only.
 
+Engine-neutral and runtime-neutral are different properties, and the entries are layered by them —
+each layer drops one, and every layer's dependency list is asserted in CI:
+
+| | engine-neutral | runtime-neutral | costs |
+|---|---|---|---|
+| `/core`, `/session` | yes | yes | nothing |
+| `/node` | yes | no (filesystem, clock, environment) | `@hono/node-server`, `croner` |
+| `/pi` | no | no | the pi runtime |
+
+`Provider` and `ProviderAuth` are exported as types because our options name them; the factory that
+builds one, `createProvider`, comes from `@earendil-works/pi-ai` — add it as a direct dependency when
+you register a custom provider.
+
 | Area | Examples | Stability |
 |---|---|---|
 | Contract | `Agent`, `AgentEvent`, `collect` | Stable within SPEC v0.1 |
-| Channels/host | `createInvokeHandler`, `nodeListener`, `serveNode`, `router`, `Routes` | Reference implementation, pre-1.0 |
+| Directory → service | `createAgentService` (pi opener), `mountAgentService` + `MountableAgent` (neutral assembly), `AgentService` | The supported way to mount an agent directory in an app |
+| Mounting | `createInvokeHandler`, `Routes`, `ChannelHandler` | Reference implementation, pre-1.0 |
+| Node binding | `nodeListener`, `serveNode` (from `/node`) | The one runtime-specific piece; see below |
 | pi assembly | `createPiAgentFromDir`, `createPiAgentFromDefinition`, `createPiAgent` | Usable now, may tighten before 1.0 |
-| Tool/channel authoring | `defineTool`, `z`, `loadTools`, `loadChannels`, `ChannelModule` | Usable now, may tighten before 1.0 |
-| Injection ports | `PiSessionStore`, `inMemorySessionStore`, `jsonlSessionStore`, `Lease`, `Provider`, `createProvider` | Public because options reference them |
-| Not exported | L0 harness adapter, pi harness factory, prompt/config internals | Internal modules; no compatibility promise |
+| Tool/channel authoring | `defineTool`, `z`, `defineSchedule`, `ChannelModule` | Usable now, may tighten before 1.0 |
+| Injection ports | `PiSessionRecordStore`, `piSessionRecordStore`, `piInMemorySessionRecordStore`, `Lease`, `Provider` | Public because options reference them |
+| Not exported | The assembly's parts — `router`, `createControlPlane`, `loadTools`/`loadChannels`/`loadSchedules`, `createScheduler` — and prompt/config internals | `createAgentService` does this; no compatibility promise |
 
-Subpath exports:
+Subpath entry points (`./package.json` is also exported, for tools that read the version):
 
-- `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel/host kit, schedules;
+- `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel kit, schedules, and the session-control clients (`connectSessionControl`, `connectAgent`). **Zero third-party dependencies**, enforced by test;
+- `@fastagent-sh/fastagent/node` — the engine-neutral pieces that need a Node runtime: `mountAgentService` (the assembly), `serveNode` / `nodeListener` (the `node:http` ↔ Fetch binding);
+- `@fastagent-sh/fastagent/session` — the engine-neutral session-control contract (types and error codes);
 - `@fastagent-sh/fastagent/pi` — the pi reference implementation;
 - `@fastagent-sh/fastagent/github` — GitHub webhook channel;
 - `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
+- `@fastagent-sh/fastagent/slack` — Slack Events API bot channel;
 - `@fastagent-sh/fastagent/feishu` — canonical Feishu bot channel (飞书, open.feishu.cn);
 - `@fastagent-sh/fastagent/lark` — Lark-international compatibility profile over the Feishu engine.
 
@@ -196,7 +214,7 @@ FastAgent is pre-1.0. The stable design center is the Agent Handler contract in
 The neutral contract leaves room for capabilities that are not complete product features yet:
 
 - **Durable execution**: Telegram, Slack, and Feishu/Lark accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
-- **Sandboxed execution** — `ExecutionEnv` governs the default coding tools, but ② project context and author-written `tools/` still reach the local process; a complete sandbox adapter is future work.
+- **Sandboxed execution** — all seven coding tools, ② project context, channels, and author-written `tools/` reach the local process directly; a sandbox around the complete agent process is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
 - **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
 - **More deploy targets** — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.

package/dist/agent.d.ts

@@ -86,7 +86,7 @@ export type AgentEvent = {
 export declare const SESSION_BUSY_CODE = "session_busy";
 /**
  * The `failed.code` set when a run was DELIBERATELY stopped — a control-plane abort, or any
- * harness-level abort the engine attributes (`stopReason: "aborted"`) — rather than failing on its
+ * engine-level abort it attributes (`stopReason: "aborted"`) — rather than failing on its
  * own. Channels can render cancellation distinctly from an error, and MUST treat it as a settled
  * outcome — durable turn-intent cleanup included — so a deliberate stop is never replayed as a
  * fresh turn on restart. Exported as a constant for the same reason as {@link SESSION_BUSY_CODE}:

package/dist/agent.js

@@ -14,7 +14,7 @@
 export const SESSION_BUSY_CODE = "session_busy";
 /**
  * The `failed.code` set when a run was DELIBERATELY stopped — a control-plane abort, or any
- * harness-level abort the engine attributes (`stopReason: "aborted"`) — rather than failing on its
+ * engine-level abort it attributes (`stopReason: "aborted"`) — rather than failing on its
  * own. Channels can render cancellation distinctly from an error, and MUST treat it as a settled
  * outcome — durable turn-intent cleanup included — so a deliberate stop is never replayed as a
  * fresh turn on restart. Exported as a constant for the same reason as {@link SESSION_BUSY_CODE}:

package/dist/atomic-write.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
+ *
+ * The temp name is fixed (`<path>.tmp`). That is safe here because no two processes write one state
+ * root: a deployment runs one container, and `dev`'s supervisor respawns its worker only after the
+ * old one has EXITED (dev-supervisor.ts) — and these writes are synchronous, so an exited process
+ * has none in flight. The fixed name is also the seam several channel tests use to inject a write
+ * failure, by occupying that path with a directory. A unique name would trade that seam for a race
+ * this codebase does not have; revisit it if a second writer ever becomes real.
+ *
+ * `mode` is applied to the temp first, so the content is never briefly world-readable.
+ *
+ * The `chmod` is NOT redundant with the `mode` option: `writeFileSync` applies `mode` only when it
+ * CREATES the file, so a temp left behind by a crashed writer keeps its old, possibly loose
+ * permissions and the rename publishes them (verified: 0644 survives a `{ mode: 0o600 }` write).
+ * It runs on the temp, before the rename — the final path is then never observable with the wrong
+ * permissions, which a chmod after the rename cannot promise.
+ */
+export declare function writeFileAtomic(path: string, data: string, mode?: number): void;

package/dist/atomic-write.js

@@ -0,0 +1,48 @@
+/**
+ * One spelling of "a reader sees the whole file or none of it" for SYNCHRONOUS writes, after four
+ * copies of it drifted apart: two identical, two with different temp names and different permission
+ * handling.
+ *
+ * Slack's onboarding state stays on its own async path — this is deliberately not an async API, and
+ * converting that caller is a separate question from de-duplicating these four.
+ */
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
+ *
+ * The temp name is fixed (`<path>.tmp`). That is safe here because no two processes write one state
+ * root: a deployment runs one container, and `dev`'s supervisor respawns its worker only after the
+ * old one has EXITED (dev-supervisor.ts) — and these writes are synchronous, so an exited process
+ * has none in flight. The fixed name is also the seam several channel tests use to inject a write
+ * failure, by occupying that path with a directory. A unique name would trade that seam for a race
+ * this codebase does not have; revisit it if a second writer ever becomes real.
+ *
+ * `mode` is applied to the temp first, so the content is never briefly world-readable.
+ *
+ * The `chmod` is NOT redundant with the `mode` option: `writeFileSync` applies `mode` only when it
+ * CREATES the file, so a temp left behind by a crashed writer keeps its old, possibly loose
+ * permissions and the rename publishes them (verified: 0644 survives a `{ mode: 0o600 }` write).
+ * It runs on the temp, before the rename — the final path is then never observable with the wrong
+ * permissions, which a chmod after the rename cannot promise.
+ */
+export function writeFileAtomic(path, data, mode) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    try {
+        writeFileSync(tmp, data, mode === undefined ? undefined : { mode });
+        if (mode !== undefined)
+            chmodSync(tmp, mode);
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // `force` only forgives ENOENT: if the temp is a directory, rmSync throws its own error and
+            // would replace the write failure that actually explains what went wrong.
+        }
+        throw error;
+    }
+}

package/dist/{host/node.d.ts → channel.d.ts}

@@ -1,8 +1,28 @@
-import type { Agent } from "../agent.ts";
-import type { SessionControl } from "../session.ts";
-/** A mounted request handler (a channel's fetch, or a plain route like health). */
+/**
+ * The Channel contract — the trigger side of the product boundary (core.md §1), beside `agent.ts`
+ * (what an engine implements) and `session.ts` (the serving control plane). Pure types, no runtime
+ * dependency; importing a host, a framework, or an engine here is forbidden, as in those two.
+ *
+ * §7 fixes two module forms: a function is a route channel, an object with `connect` is a long
+ * connection. An agent directory ships hand-written `channels/*.ts` against them, which is why they
+ * live away from the code that serves them — a WebSocket ingress needs `LongConnection` and has no
+ * HTTP in it, and a `ChannelModule` import must not drag `node:http` in behind it.
+ *
+ * How a route table becomes a running server: `channels/serve.ts`.
+ */
+import type { Agent } from "./agent.ts";
+import type { SessionControl } from "./session.ts";
+/** A mounted request handler (a channel's fetch, or a plain route like health). Fetch-shaped by
+ *  contract (SPEC §11): the one signature every runtime and embedding app already speaks. */
 export type ChannelHandler = (req: Request) => Response | Promise<Response>;
-/** This deployment's HTTP surface: route key → handler. Key is `"/path"` or `"METHOD /path"`. */
+/**
+ * This deployment's HTTP surface: route key → handler.
+ *
+ * A key is `"/path"` (any method) or `"METHOD /path"`, with a LITERAL path — small on purpose, so
+ * that "would these two fight over a request?" is string equality rather than a prediction about a
+ * matcher, and no channel silently shadows another. `assertRouteKey` in `channels/serve.ts`
+ * enforces it; a handler owning a prefix is a `PrefixMount`, never a key.
+ */
 export type Routes = Record<string, ChannelHandler>;
 /**
  * What the framework hands a channel at mount time: the assembled agent plus the resolved state ROOT
@@ -34,27 +54,3 @@ export interface LongConnectionChannelModule {
     name: string;
     connect(ctx: ChannelContext, signal: AbortSignal): LongConnection;
 }
-/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
-export declare function parseRouteKey(key: string): {
-    method?: string;
-    path: string;
-};
-/**
- * Compose a {@link Routes} table into one handler: exact pathname match (optionally method-qualified),
- * 405 when the path exists under another method, 404 otherwise. No params/wildcards.
- */
-export declare function router(routes: Routes): ChannelHandler;
-/**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
- * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
- * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
- * `host` is the bind address; unset means all interfaces (what containers need).
- */
-export declare function serveNode(handler: ChannelHandler, options: {
-    port: number;
-    host?: string;
-}): {
-    listening: Promise<number>;
-    close: () => Promise<void>;
-    closeAllConnections: () => void;
-};

package/dist/channel.js

@@ -0,0 +1 @@
+export {};

package/dist/channels/agentcore-service.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The AgentCore serving assembly — the same product as `mountAgentService`, built differently
+ * because the host is.
+ *
+ * Two facts drive every difference. There is no public URL (the adapter's `POST /invocations` is the
+ * only ingress, and cron slots arrive through it from an external clock, so no resident timers), and
+ * **the state mount at boot is PRE-RESTORE** — empty after every version update. Discovering channels
+ * eagerly would therefore cache that emptiness (thread participation, delivery dedup, pending turns)
+ * and then clobber the restored files with it, so channels are constructed lazily on the first
+ * envelope. Everywhere else the state root is durable at boot and a broken channel fails startup.
+ *
+ * That is a different assembly, not a flag on the shared one: handler shape, discovery timing, clock
+ * source, long-connection support and shutdown all differ. What it is NOT is a different product —
+ * it returns the same {@link AgentService}, so `start` picks an assembly once and everything after
+ * that point is common.
+ */
+import type { Agent } from "../agent.ts";
+import type { Routes } from "../channel.ts";
+import type { LoadedSchedule } from "../schedule/schedule.ts";
+import { type AgentService, type MountableAgent } from "../service.ts";
+import { type RouteSurface } from "./agentcore.ts";
+export interface MountAgentcoreServiceOptions {
+    /** Wrap the opened agent before anything binds to it (the CLI's turn trace). */
+    wrapAgent?: (agent: Agent) => Agent;
+    /** Runs once the state snapshot is restored. The wake-alarm reconcile passes through here because
+     *  its sink is a PROCESS-global: the process entry owns that, not a service that can be closed. */
+    onStateReady?: () => void;
+    control?: {
+        tunnel?: boolean;
+        host?: string;
+    };
+}
+/** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
+export declare function isAgentcoreRuntime(): boolean;
+export declare function mountAgentcoreService(opened: MountableAgent, options?: MountAgentcoreServiceOptions): Promise<AgentService>;
+/**
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
+ * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
+ * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
+ * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
+ * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
+ */
+export declare function mountAgentcore(routes: Routes, options: {
+    agent: Agent;
+    stateRoot: string;
+    schedules: readonly LoadedSchedule[];
+    onStateReady?: () => void;
+    /** Cancels the adapter's process-global registrations on close. */
+    signal?: AbortSignal;
+    /** The serving path's LAZY channel surface: constructed by the adapter on the first envelope
+     *  AFTER the state-snapshot restore, never at boot (channels/agentcore.ts). When absent,
+     *  `routes` is the dispatch target — for wirings whose state root is already authoritative. */
+    lazyChannels?: () => Promise<RouteSurface>;
+}): Routes;

package/dist/channels/agentcore-service.js

@@ -0,0 +1,111 @@
+import { log } from "../log.js";
+import { fireScheduleOnce } from "../schedule/scheduler.js";
+import { assertNoControlPlaneCollision, mountSessionControl, routesFor, startSchedules, } from "../service.js";
+import { UnknownScheduleError, agentcoreRoutes } from "./agentcore.js";
+import { createStateSync } from "./agentcore-state.js";
+import { activeWork } from "./busy.js";
+import { routeKeysConflict, router } from "./serve.js";
+/** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
+export function isAgentcoreRuntime() {
+    return process.env.FASTAGENT_AGENTCORE === "1";
+}
+export async function mountAgentcoreService(opened, options = {}) {
+    const { agentDir, workspace, stateRoot, sessionControl } = opened;
+    const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
+    // The control plane mounts over an EMPTY route surface: the lazy channels join it later, and the
+    // collision rule runs again then (below) against what they actually brought.
+    const withControl = mountSessionControl({}, sessionControl, stateRoot, { ...options.control, agent });
+    const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule, {
+        externalClock: true,
+    });
+    const lazyChannels = async () => {
+        const lazy = await routesFor(agentDir, agent, stateRoot, sessionControl, { builtinInvoke: false });
+        if (lazy.longConnections.length > 0) {
+            throw new Error(`long-connection channel(s) ${lazy.longConnections.map((c) => c.name).join(", ")} cannot serve on ` +
+                `AgentCore (scale-to-zero severs resident connections) — use the channel's webhook form`);
+        }
+        // The SAME rule mountSessionControl applies, through the same function: its check ran against an
+        // empty base at boot, so it has to run again once the channels are real.
+        for (const plane of withControl.mounts)
+            assertNoControlPlaneCollision(lazy.routes, plane);
+        return { routes: lazy.routes, mounts: withControl.mounts };
+    };
+    // The adapter registers process-global listeners; this is what takes them down on close.
+    const closed = new AbortController();
+    const adapterRoutes = mountAgentcore({}, {
+        signal: closed.signal,
+        agent,
+        stateRoot,
+        schedules: scheduled.schedules,
+        onStateReady: options.onStateReady,
+        lazyChannels,
+    });
+    const handler = router(adapterRoutes, withControl.mounts);
+    log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
+    let unannounce;
+    return {
+        handler,
+        agent,
+        // The adapter IS the surface here; the channel routes arrive lazily BEHIND it. Reporting `{}`
+        // would make the startup line claim nothing is served.
+        routes: adapterRoutes,
+        agentDir,
+        workspace,
+        // Unknown at boot by design — a channel list here would be the pre-restore emptiness.
+        channels: { routes: [], longConnections: [], builtinInvoke: false },
+        schedules: scheduled.schedules,
+        ready: Promise.resolve(), // nothing to open: no port of our own, no resident connections
+        ...(withControl.control ? { control: withControl.control } : {}),
+        announce(boundPort) {
+            unannounce = withControl.announce(boundPort);
+        },
+        async close() {
+            // UNTESTED, deliberately noted: no test observes these timers being cleared. Installing fake
+            // timers early enough to count them deadlocks the assembly's own IO. What IS tested is that
+            // close() runs and is idempotent; the stop itself rides on scheduler.stop()'s own tests.
+            scheduled.stop();
+            closed.abort();
+            unannounce?.(); // a stale discovery file would point `attach` at a stopped service
+        },
+    };
+}
+/**
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
+ * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
+ * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
+ * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
+ * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
+ */
+export function mountAgentcore(routes, options) {
+    const { agent, stateRoot, schedules, onStateReady, lazyChannels, signal } = options;
+    const mounted = agentcoreRoutes({
+        routes: lazyChannels ?? { routes },
+        agent,
+        stateRoot,
+        isBusy: () => activeWork() > 0,
+        // Cross-deploy durability: AgentCore wipes the state mount on every runtime version update, so
+        // the state root is restored from (and pushed to) an S3 snapshot through presigned URLs the
+        // forwarder mints per envelope. Always wired on this path — the platform gives no other way to
+        // keep an agent's memory across a deploy.
+        stateSync: createStateSync({ stateRoot }),
+        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call. Absent =
+        // no forwarder in this topology, so only the public `invoke` kind is servable.
+        ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
+        onStateReady,
+        ...(signal ? { signal } : {}),
+        fire: schedules.length === 0
+            ? undefined
+            : (name, slot) => {
+                const schedule = schedules.find((s) => s.name === name);
+                if (!schedule)
+                    throw new UnknownScheduleError(name);
+                return fireScheduleOnce({ agent, stateRoot, schedule, slot });
+            },
+    });
+    const collisions = Object.keys(routes).filter((key) => Object.keys(mounted).some((adapterKey) => routeKeysConflict(key, adapterKey)));
+    if (collisions.length > 0) {
+        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the AgentCore adapter ` +
+            `(/invocations, /ping) — rename the channel route`);
+    }
+    return { ...routes, ...mounted };
+}

package/dist/channels/agentcore.d.ts

@@ -1,6 +1,7 @@
 import type { Agent } from "../agent.ts";
 import type { StateSync, StateUrls } from "./agentcore-state.ts";
-import type { Routes } from "../host/node.ts";
+import type { Routes } from "../channel.ts";
+import { type PrefixMount } from "../channels/serve.ts";
 import type { ScheduleFireOutcome } from "../schedule/scheduler.ts";
 /**
  * The HOST's webhook body limit, and the one place it is computed. Lambda Function URLs cap a request
@@ -71,6 +72,12 @@ export interface WebhookReply {
     headers: Record<string, string>;
     bodyB64: string;
 }
+/** What the lazy factory hands back: literal routes plus any prefix-owning mounts (the control
+ *  plane), so the adapter's INNER dispatch is assembled exactly like a direct host's. */
+export interface RouteSurface {
+    routes: Routes;
+    mounts?: readonly PrefixMount[];
+}
 export interface AgentcoreAdapterOptions {
     /** The serving routes a direct deployment would mount (channels or the builtin invoke + health).
      *  The serving path passes a LAZY factory: channel construction loads channel state and replays
@@ -78,7 +85,7 @@ export interface AgentcoreAdapterOptions {
      *  which happens at the first envelope's `stateSync.ready()` (the restore URLs only an envelope
      *  carries), never at boot, where the mount is pre-restore (empty after every version update).
      *  An eager `Routes` value remains supported for wirings whose state root is already durable. */
-    routes: Routes | (() => Promise<Routes> | Routes);
+    routes: RouteSurface | (() => Promise<RouteSurface> | RouteSurface);
     agent: Agent;
     /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
     stateRoot: string;
@@ -94,6 +101,9 @@ export interface AgentcoreAdapterOptions {
     /** FASTAGENT_INGRESS_SECRET: what makes an envelope the FORWARDER's rather than any IAM principal's.
      *  Undefined = nothing can be trusted, so only the public `invoke` kind is served. */
     ingressSecret?: string;
+    /** Cancels the adapter's process-global registrations. Without it a closed adapter keeps saving
+     *  state on every later idle edge — including work belonging to whatever mounted after it. */
+    signal?: AbortSignal;
     /** Runs ONCE, after the state root is authoritative (post-restore) — the wake-alarm reconcile, which
      *  at boot would see the mount the platform just wiped and conclude there is nothing pending. */
     onStateReady?: () => void;

package/dist/channels/agentcore.js

@@ -28,7 +28,7 @@
 import { Buffer } from "node:buffer";
 import { timingSafeEqual } from "node:crypto";
 import { beginWork, onIdle } from "./busy.js";
-import { router } from "../host/node.js";
+import { router } from "../channels/serve.js";
 import { log } from "../log.js";
 import { rememberWakeAlarmUrl } from "../schedule/wake-alarm.js";
 import { readBodyCapped } from "./body.js";
@@ -72,7 +72,7 @@ export function agentcoreRoutes(options) {
             // not escape before `dispatchP` is assigned (which would silently re-run the activation).
             dispatchP = Promise.resolve()
                 .then(() => (typeof routes === "function" ? routes() : routes))
-                .then(router);
+                .then((surface) => router(surface.routes, surface.mounts));
             dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
         }
         return dispatchP;
@@ -80,8 +80,10 @@ export function agentcoreRoutes(options) {
     const invokeHandler = createInvokeHandler(agent);
     // Snapshot on the 0-in-flight edge: webhook channels ACK fast and finish the turn in the
     // background, so "the request returned" is NOT when the state root settles.
-    if (stateSync)
-        onIdle(() => stateSync.save());
+    if (stateSync) {
+        const off = onIdle(() => stateSync.save());
+        options.signal?.addEventListener("abort", off, { once: true });
+    }
     let warnedUnsnapshotted = false;
     let stateReadyFired = false;
     const handleInvocation = async (req) => {

package/dist/channels/busy.d.ts

@@ -1,6 +1,6 @@
 /**
  * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
- * fire-and-forget on this process's event loop (host/node.ts) — so "is this process busy?" is not
+ * fire-and-forget on this process's event loop (serve.ts) — so "is this process busy?" is not
  * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
  * task-tracker side tasks) report here; a serving surface that must stay alive while background
  * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.

package/dist/channels/busy.js

@@ -1,6 +1,6 @@
 /**
  * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
- * fire-and-forget on this process's event loop (host/node.ts) — so "is this process busy?" is not
+ * fire-and-forget on this process's event loop (serve.ts) — so "is this process busy?" is not
  * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
  * task-tracker side tasks) report here; a serving surface that must stay alive while background
  * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.

package/dist/channels/control.d.ts

@@ -1,17 +1,18 @@
 import { type SessionControl, type SessionEvent } from "../session.ts";
 import type { Agent } from "../agent.ts";
-import type { Routes } from "../host/node.ts";
+import type { ChannelHandler } from "../channel.ts";
+import { type PrefixMount } from "./serve.ts";
 /** The SSE payload: one control-plane event in its transport envelope. */
 export interface WireEvent {
     sessionId: string;
-    /** Serving-process incarnation (per `controlRoutes` call). A change means the server restarted:
+    /** Serving-process incarnation (per `createControlPlane` call). A change means the server restarted:
      *  live continuity is gone — run the reconnect steps (entries cursor + state). */
     epoch: string;
     /** Per-connection monotonic counter. A gap means events were lost in transit on THIS connection. */
     seq: number;
     event: SessionEvent;
 }
-export interface ControlRoutesOptions {
+export interface ControlPlaneOptions {
     /** Shared bearer secret, required on every route. Never optional: an unauthenticated
      *  remote-control endpoint must not be constructible by omission. */
     token: string;
@@ -22,7 +23,16 @@ export interface ControlRoutesOptions {
     agent?: Agent;
 }
 /**
- * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
- * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * Create the control plane as a mountable prefix owner: `GET
+ * /control/capabilities|commands|state|entries|events` + `POST /control/dispatch`, all
+ * bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * The plane OWNS {@link CONTROL_PREFIX}: it is mounted as one sub-application, answers its own
+ * 404/405/preflight, and puts CORS headers on every reply — see {@link planeApp}.
  */
-export declare function controlRoutes(control: SessionControl, options: ControlRoutesOptions): Routes;
+export declare function createControlPlane(control: SessionControl, options: ControlPlaneOptions): PrefixMount;
+/** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
+ *  table is a set of literal paths. */
+export declare function mountControlPlane(routes: Record<string, ChannelHandler>): PrefixMount;
+/** The plane's route table. Exported so the conformance sweeps derive their route list from what is
+ *  actually mounted, rather than from a hand-kept copy that cannot notice a new route. */
+export declare function controlPlaneRoutes(control: SessionControl, options: ControlPlaneOptions): Record<string, ChannelHandler>;

package/dist/channels/control.js

@@ -1,9 +1,98 @@
 import { INVALID_COMMAND_CODE } from "../session.js";
 import { timingSafeEqual } from "node:crypto";
+import { parseRouteKey, withoutBody } from "./serve.js";
+import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
 import { MAX_BODY_BYTES, createInvokeHandler, sseHeartbeat } from "./http.js";
 import { text } from "./respond.js";
+/** The prefix this plane OWNS: everything under it is the plane's to answer. */
+const CONTROL_PREFIX = "/control";
 const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
+/**
+ * The plane as one mounted sub-application rather than routes sharing a prefix.
+ *
+ * CORS belongs to every reply that leaves the plane — including the ones no route produces (an
+ * unknown path, an unserved method, a throwing handler). As separate routes those came from the
+ * host, outside anything the plane could decorate. Owning the prefix makes them its own answers,
+ * headers applied at the single exit they share.
+ *
+ * `*` is the right origin: authorisation is the bearer token — never the origin, never a cookie —
+ * so an origin that cannot present it gets 401 either way, and a deployment cannot know the origins
+ * of the GUIs that will manage it (§14's asymmetry).
+ *
+ * `authorization` is not CORS-safelisted, so EVERY call preflights, including a plain GET.
+ * `content-type` is not either (only three values are, and `application/json` is not among them),
+ * so a browser POSTing to dispatch/invoke names it — allowing just `authorization` leaves precisely
+ * the WRITE routes unreachable while reads work.
+ */
+function planeApp(routes) {
+    // Normalised keys (see serve.ts): the method is upper-cased when parsed.
+    const byKey = new Map(Object.entries(routes).map(([key, handler]) => {
+        const { method, path } = parseRouteKey(key);
+        return [method ? `${method} ${path}` : path, handler];
+    }));
+    const methodsByPath = new Map();
+    for (const key of Object.keys(routes)) {
+        const { method, path } = parseRouteKey(key);
+        const methods = methodsByPath.get(path) ?? new Set();
+        if (method)
+            methods.add(method);
+        methodsByPath.set(path, methods);
+    }
+    // Per PATH, stating what it actually serves — omitting a method it does serve has the browser
+    // refuse a call that would have worked. `HEAD` is that case: every GET route answers it.
+    const allowMethods = (path, requested) => {
+        const methods = new Set(methodsByPath.get(path) ?? []);
+        if (methods.has("GET"))
+            methods.add("HEAD");
+        // The requested method is always allowed, even where this path does not serve it: preflight is a
+        // gate applied BEFORE the request exists, so refusing there means the real request is never sent
+        // and the client sees an opaque network error. Allowing it lets the plane's own 404/405 arrive,
+        // with these headers and an explanation.
+        if (requested)
+            methods.add(requested.toUpperCase());
+        return [...methods, "OPTIONS"].join(", ");
+    };
+    return async (req) => {
+        const path = new URL(req.url).pathname;
+        const known = methodsByPath.has(path);
+        const answer = async () => {
+            // A preflight carries no token — that is its purpose — so it is answered before auth, and for
+            // ANY path under the prefix: gating it would stop the request the 404 below is waiting for.
+            if (req.method === "OPTIONS")
+                return new Response(null, { status: 204 });
+            const handler = byKey.get(`${req.method} ${path}`) ?? byKey.get(path);
+            if (handler)
+                return await handler(req);
+            if (known && req.method === "HEAD") {
+                const get = byKey.get(`GET ${path}`);
+                if (get)
+                    return await get(req);
+            }
+            // 404 vs 405 as in the host router: a client reads 404 as "this serve predates the route".
+            if (known)
+                return text("method not allowed\n", 405);
+            return text("not found\n", 404);
+        };
+        let res;
+        try {
+            // HEAD carries no content, whichever branch answered — including this plane's own 404/405.
+            const answered = await answer();
+            res = req.method === "HEAD" ? withoutBody(answered) : answered;
+        }
+        catch (error) {
+            // The plane's own totality boundary: a rejecting handler (`commands()` on an unreadable
+            // definition) must still answer with the headers; the message stays internal.
+            log.error(`[control] ${req.method} ${path} failed: ${String(error)}`);
+            res = text("internal error\n", 500);
+        }
+        // THE single exit. Every reply above — route, preflight, 404, 405, 500 — leaves through here.
+        res.headers.set("access-control-allow-origin", "*");
+        res.headers.set("access-control-allow-headers", "authorization, content-type");
+        res.headers.set("access-control-allow-methods", allowMethods(path, req.headers.get("access-control-request-method")));
+        return res;
+    };
+}
 // ONE constant for every Prompt-bearing wire surface (imported from the invoke channel — the two
 // caps cannot drift apart): commands carry Prompts, which may ride base64 images.
 const DISPATCH_BODY_LIMIT = MAX_BODY_BYTES;
@@ -84,13 +173,26 @@ function parseWireCommand(raw) {
     }
 }
 /**
- * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
- * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * Create the control plane as a mountable prefix owner: `GET
+ * /control/capabilities|commands|state|entries|events` + `POST /control/dispatch`, all
+ * bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * The plane OWNS {@link CONTROL_PREFIX}: it is mounted as one sub-application, answers its own
+ * 404/405/preflight, and puts CORS headers on every reply — see {@link planeApp}.
  */
-export function controlRoutes(control, options) {
+export function createControlPlane(control, options) {
+    return mountControlPlane(controlPlaneRoutes(control, options));
+}
+/** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
+ *  table is a set of literal paths. */
+export function mountControlPlane(routes) {
+    return { prefix: CONTROL_PREFIX, handler: planeApp(routes) };
+}
+/** The plane's route table. Exported so the conformance sweeps derive their route list from what is
+ *  actually mounted, rather than from a hand-kept copy that cannot notice a new route. */
+export function controlPlaneRoutes(control, options) {
     const { token } = options;
     if (!token)
-        throw new Error("controlRoutes: a bearer token is required (empty tokens are not a mode)");
+        throw new Error("createControlPlane: a bearer token is required (empty tokens are not a mode)");
     const epoch = crypto.randomUUID();
     // Timing-safe: the bearer token is this surface's ONLY auth (and the --tunnel warning names it
     // as the sole protection on a public URL) — a plain === would leak byte-by-byte via timing.