@fastagent-sh/fastagent 0.18.0 → 0.20.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,23 @@
+/**
+ * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
+ *
+ * The temp name is fixed (`<path>.tmp`). It holds wherever one process writes one state root: a
+ * deployment runs one container, `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. Slack's onboarding state is the one file with two writers — `add slack`, and the
+ * config-token rotation inside `--tunnel` webhook registration — so a second terminal running
+ * `add slack --replace-config` can overlap a live `dev --tunnel`. Kept fixed anyway: that window is
+ * a single write at tunnel startup, its repair is the `add slack --replace-config` the registration
+ * failure already prints, and the fixed name is the seam several channel tests use to inject a write
+ * failure by occupying that path with a directory. Revisit for a writer that is neither rare nor
+ * self-repairing.
+ *
+ * `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 | Buffer, mode?: number): void;

package/dist/atomic-write.js

@@ -0,0 +1,53 @@
+/**
+ * One spelling of "a reader sees the whole file or none of it", after five copies of it drifted
+ * apart: two identical, three with different temp names and different permission handling.
+ *
+ * Synchronous, and there is no async sibling: every caller either sits on a path where a KB-sized
+ * write must complete BEFORE a transport ACK (channel state — an ACKed delivery is not redelivered)
+ * or on a CLI/startup path where the cost is not observable. An async spelling would buy one of them
+ * nothing and cost this module a second set of rules to keep true.
+ */
+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`). It holds wherever one process writes one state root: a
+ * deployment runs one container, `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. Slack's onboarding state is the one file with two writers — `add slack`, and the
+ * config-token rotation inside `--tunnel` webhook registration — so a second terminal running
+ * `add slack --replace-config` can overlap a live `dev --tunnel`. Kept fixed anyway: that window is
+ * a single write at tunnel startup, its repair is the `add slack --replace-config` the registration
+ * failure already prints, and the fixed name is the seam several channel tests use to inject a write
+ * failure by occupying that path with a directory. Revisit for a writer that is neither rare nor
+ * self-repairing.
+ *
+ * `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-limits.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The HOST's body ceilings, and the one place they are computed.
+ *
+ * Lambda Function URLs cap a request at 6 MB, so the forwarder cannot deliver more than that no
+ * matter what the adapter accepts; the body arrives base64-encoded (×4/3) inside a JSON envelope, so
+ * the ORIGINAL body ceiling is smaller still. This is a real capability difference from a resident
+ * host — the GitHub channel's own contract is 25 MiB — which is why `deploy agentcore` states it at
+ * plan time rather than letting an oversized payload surface as an opaque 502.
+ */
 /**
  * Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion.
  * Enforced by both the public forwarder and the runtime adapter.

package/dist/channels/agentcore-limits.js

@@ -1,3 +1,12 @@
+/**
+ * The HOST's body ceilings, and the one place they are computed.
+ *
+ * Lambda Function URLs cap a request at 6 MB, so the forwarder cannot deliver more than that no
+ * matter what the adapter accepts; the body arrives base64-encoded (×4/3) inside a JSON envelope, so
+ * the ORIGINAL body ceiling is smaller still. This is a real capability difference from a resident
+ * host — the GitHub channel's own contract is 25 MiB — which is why `deploy agentcore` states it at
+ * plan time rather than letting an oversized payload surface as an opaque 502.
+ */
 /** AWS Lambda Function URLs accept request payloads up to 6 MB. */
 const FUNCTION_URL_REQUEST_LIMIT = 6 * 1000 * 1000;
 /**

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

@@ -0,0 +1,55 @@
+/**
+ * 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 AgentcoreAdapterOptions } 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`) — 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).
+ *
+ * The adapter IS the surface: the agent's channels live in a table INSIDE the envelope dispatch, a
+ * separate namespace from these two paths, so a channel route named `/invocations` is reached
+ * through the Function URL as itself and cannot shadow anything.
+ */
+export declare function mountAgentcore(options: {
+    agent: Agent;
+    stateRoot: string;
+    schedules: readonly LoadedSchedule[];
+    onStateReady?: () => void;
+    /** Cancels the adapter's process-global registrations on close. */
+    signal?: AbortSignal;
+    /** The channel surface, constructed on the first envelope AFTER the state-snapshot restore — never
+     *  at boot, where the mount is pre-restore (channels/agentcore.ts). */
+    channels: AgentcoreAdapterOptions["channels"];
+}): Routes;

package/dist/channels/agentcore-service.js

@@ -0,0 +1,107 @@
+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 { 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,
+        channels: 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`) — 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).
+ *
+ * The adapter IS the surface: the agent's channels live in a table INSIDE the envelope dispatch, a
+ * separate namespace from these two paths, so a channel route named `/invocations` is reached
+ * through the Function URL as itself and cannot shadow anything.
+ */
+export function mountAgentcore(options) {
+    const { agent, stateRoot, schedules, onStateReady, channels, signal } = options;
+    return agentcoreRoutes({
+        channels,
+        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 });
+            },
+    });
+}

package/dist/channels/agentcore.d.ts

@@ -1,15 +1,8 @@
 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
- * at 6 MB, so the forwarder cannot deliver more than that no matter what the adapter accepts; the
- * body arrives base64-encoded (×4/3) inside a JSON envelope, so the ORIGINAL body ceiling is smaller
- * still. This is a real capability difference from a resident host — the GitHub channel's own
- * contract is 25 MiB — so `deploy agentcore` says so at plan time rather than letting an oversized
- * payload surface as an opaque 502.
- */
 /** What the forwarder Lambda / EventBridge deliver in the `/invocations` payload. Every kind may
  *  carry `wake` — the forwarder's self-resolved public URL, which the adapter persists so the wake
  *  ALARM sink (schedule/wake-alarm.ts) can call back without the URL being baked anywhere. */
@@ -71,14 +64,21 @@ 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
-     *  durable turn intent, so on AgentCore it must not run until the state root is authoritative —
-     *  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);
+    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health),
+     *  built LAZILY: channel construction loads channel state and replays durable turn intent, so on
+     *  AgentCore it must not run until the state root is authoritative — 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). A factory, not a value: there is no
+     *  moment during construction at which the right answer is knowable. May answer synchronously — the
+     *  resolution chain normalizes it either way. */
+    channels: () => Promise<RouteSurface> | RouteSurface;
     agent: Agent;
     /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
     stateRoot: string;
@@ -94,15 +94,17 @@ 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;
 }
 /**
- * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }`. The caller merges it
- * over its routes (collision-checked at the mount site, serve.ts) — the inner routes stay mounted
- * too, which is harmless (AgentCore routes only /invocations and /ping into the container) and keeps
- * a local `curl` debug surface.
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }` — the whole of what the
+ * platform routes into the container. The agent's own channels are not beside these: they are a table
+ * inside the envelope dispatch below, reached only by unwrapping a forwarder envelope.
  */
 export declare function agentcoreRoutes(options: AgentcoreAdapterOptions): Routes;
 /** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does

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";
@@ -48,14 +48,13 @@ function secretMatches(actual, expected) {
     return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
 }
 /**
- * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }`. The caller merges it
- * over its routes (collision-checked at the mount site, serve.ts) — the inner routes stay mounted
- * too, which is harmless (AgentCore routes only /invocations and /ping into the container) and keeps
- * a local `curl` debug surface.
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }` — the whole of what the
+ * platform routes into the container. The agent's own channels are not beside these: they are a table
+ * inside the envelope dispatch below, reached only by unwrapping a forwarder envelope.
  */
 export function agentcoreRoutes(options) {
-    const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
-    // Lazy channel construction (see AgentcoreAdapterOptions.routes) — resolved ONCE per process, on
+    const { channels, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
+    // Lazy channel construction (see AgentcoreAdapterOptions.channels) — resolved ONCE per process, on
     // the first trusted envelope after the state root is authoritative, and the outcome is cached
     // EITHER WAY. Success: the same resident channels a direct host keeps. Failure too: construction
     // is an ACTIVATION with side effects — loadChannels builds every healthy channel (starting its
@@ -71,8 +70,8 @@ export function agentcoreRoutes(options) {
             // The factory runs INSIDE the chain: a synchronous throw must land in the cached rejection,
             // 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(channels)
+                .then((surface) => router(surface.routes, surface.mounts));
             dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
         }
         return dispatchP;
@@ -80,8 +79,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) => {
@@ -299,6 +300,14 @@ export function agentcoreRoutes(options) {
     };
     // Settle-then-snapshot: when the envelope leaves nothing in flight, its writes are final now (a
     // background turn instead reports through the idle edge above).
+    //
+    // A public `invoke` is the one kind this MISSES, measurably: it answers with an unconsumed SSE
+    // stream, so the turn runs after this line and its records wait for the next envelope's snapshot.
+    // Counting it as in-flight work would close that and cost more than it buys — the stream drains at
+    // the CLIENT's pace, so one parked reader pins /ping at HealthyBusy and defeats the idle reclaim,
+    // which is the quota-exhaustion failure the ping contract below warns about. The kinds that carry
+    // conversations (webhook, schedule-fire, wake-poke) all run their turn inside the request or
+    // through `beginWork`, so they land on one of the two edges; `invoke` is the direct/debug door.
     const invocations = async (req) => {
         const response = await handleInvocation(req);
         if (stateSync && !isBusy())

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.