@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/README.md

@@ -8,6 +8,7 @@
 [![node](https://img.shields.io/node/v/@fastagent-sh/fastagent.svg)](https://nodejs.org)
 [![built with pi](https://img.shields.io/badge/built%20with-pi-0b7285.svg)](https://pi.dev)
 [![GitHub stars](https://img.shields.io/github/stars/fastagent-sh/fastagent?style=social)](https://github.com/fastagent-sh/fastagent/stargazers)
+[![follow @kid7st](https://img.shields.io/badge/follow-%40kid7st-000?logo=x)](https://x.com/kid7st)
 
 <p align="center">
   <sub>Built on</sub>
@@ -64,7 +65,9 @@ FastAgent stays a small serving layer, so it never dictates your stack. Capabili
 
 ## Install
 
-For agents — paste this into Claude Code, Codex, Cursor, or any coding agent that reads the web:
+Start with the [agent development guide](https://github.com/fastagent-sh/fastagent/blob/main/docs/ai-start.md), the authoring entry point for both humans and coding agents. It covers responsibilities, TypeScript tools, verification, channels, scheduling, and deployment. FastAgent's repository `AGENTS.md` is for maintainers.
+
+To work with Claude Code, Codex, Cursor, or another coding agent, paste:
 
 > Read https://fastagent.sh/start.md and build an agent in this project.
 
@@ -138,6 +141,7 @@ const agent = createPiAgent({
 
 | Document | Purpose |
 |---|---|
+| [Agent development guide](https://github.com/fastagent-sh/fastagent/blob/main/docs/ai-start.md) | Canonical authoring path for humans and coding agents |
 | [Documentation index](https://fastagent.sh/docs/) | Documentation map |
 | [Quickstart](https://fastagent.sh/docs/quickstart/) | Scaffold, run, add a tool, and start |
 | [Configuration](https://fastagent.sh/docs/configuration/) | Configure model, auth, ports, sessions, tools, and channels |

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

@@ -0,0 +1,112 @@
+/**
+ * The wire between the forwarder Lambda and the container, in ONE place: the envelope every
+ * trigger arrives as, the reply a webhook rides back in, the presigned-URL pair the state snapshot
+ * uses, the wake-alarm request, and the forwarder's reserved paths. The forwarder itself is JavaScript
+ * (`deploy/agentcore/forwarder.js`) and cannot import this, so `agentcore-forwarder.test.ts` pins its
+ * literals to these — a rename here fails there, not on a live box.
+ *
+ * Pure types and constants: the adapter, the state sync, the wake sink and the deploy driver all
+ * read it, and none of them may pull the others in for it.
+ */
+/** Paths the forwarder answers ITSELF — never forwarded to a channel route. */
+export declare const RESERVED_PATHS: {
+    /** The deploy driver's post-deploy verification (ingress secret). */
+    readonly probe: "/__fastagent/probe";
+    /** The container's wake-alarm mirror callback (wake secret). */
+    readonly wakeAlarm: "/__fastagent/wake-alarm";
+    /** Re-mint the state snapshot's presigned URLs with current Lambda credentials (ingress secret). */
+    readonly stateUrls: "/__fastagent/state-urls";
+};
+/** Presigned S3 URLs for the one snapshot object, minted per envelope by the forwarder. */
+export interface StateUrls {
+    getUrl: string;
+    putUrl: string;
+    /** Authenticated forwarder callback that re-mints URLs with current Lambda credentials. */
+    refresh?: {
+        url: string;
+        auth: string;
+    };
+}
+/** Every kind the container's `POST /invocations` dispatches on. Listed as a value so the forwarder
+ *  pin test can check each one is spelled the same on the other side. */
+export declare const ENVELOPE_KINDS: readonly ["webhook", "schedule-fire", "invoke", "wake-poke", "checkpoint", "probe"];
+/** 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. */
+export type AgentcoreEnvelope = {
+    /** Shared secret proving this envelope came from the forwarder (FASTAGENT_INGRESS_SECRET). The
+     *  public `invoke` data plane neither has nor needs it — and may not carry the fields below. */
+    auth?: string;
+    wake?: {
+        url: string;
+    };
+    state?: StateUrls;
+} & ({
+    kind: "webhook";
+    /** Original webhook request line, verbatim. `path` must be absolute ("/telegram"). */
+    method: string;
+    path: string;
+    /** Original raw query string (no leading `?`) — "verbatim" includes it; a channel reading
+     *  `request.url.searchParams` must see what the webhook sender sent. */
+    query?: string;
+    /** Original headers — signature material (secret tokens, Feishu signatures) rides here. */
+    headers?: Record<string, string>;
+    /** Original body, base64 (webhook bodies are JSON but the tunnel must be byte-exact). */
+    bodyB64?: string;
+} | {
+    kind: "schedule-fire";
+    name: string;
+    /** The cron instant this fire is FOR (ISO) — the slot-idempotency key. */
+    slot: string;
+} | {
+    kind: "invoke";
+    session: string;
+    text: string;
+}
+/** An EventBridge wake-up poke: the invocation ITSELF is the payload — it wakes the container,
+ *  whose boot drain / 30s wake pump then fires whatever is due. The handler only acks. */
+ | {
+    kind: "wake-poke";
+}
+/** Pre-stop checkpoint (`--run`, right before stop-runtime-session): push the state snapshot NOW.
+ *  A stop cuts an in-flight turn, and its durable turn intent — written pre-ACK by every replaying
+ *  channel — lives on a mount the version update is about to erase. Flushing first is what makes
+ *  "channels with replay re-run it" true rather than aspirational. */
+ | {
+    kind: "checkpoint";
+}
+/** The deploy driver's post-deploy verification (relayed by the forwarder's reserved probe path,
+ *  which answers on EVERY forwarder topology — schedule-only URLs refuse ordinary public traffic).
+ *  Runs restore + channel construction end to end and answers a TRANSPORT-200 structured verdict
+ *  `{ ok, error? }`: the ordinary webhook path folds a non-200 transport into an opaque 502 at the
+ *  forwarder, which would strip exactly the diagnostics this probe exists to carry. */
+ | {
+    kind: "probe";
+});
+/** The webhook envelope's reply: the channel's real HTTP response, ridden inside a transport-200
+ *  body so the forwarder can re-emit it verbatim (AgentCore folds a container non-2xx into its own
+ *  424 RuntimeClientError). */
+export interface WebhookReply {
+    status: number;
+    headers: Record<string, string>;
+    bodyB64: string;
+}
+/** One desired alarm: mirror of a pending wake-up (id names the EventBridge schedule; at = fireAt). */
+export interface WakeAlarm {
+    id: string;
+    at: string;
+}
+/** The wire shape the wake sink POSTs to {@link RESERVED_PATHS.wakeAlarm} (the forwarder validates `secret`). */
+export interface WakeAlarmRequest {
+    secret: string;
+    alarms: WakeAlarm[];
+}
+/** What EventBridge hands the forwarder for a cron slot; `slot` is `<aws.scheduler.scheduled-time>`.
+ *  Its sibling, the wake-alarm poke `{ wakePoke: true }`, is minted and read inside the forwarder
+ *  alone (`syncAlarms` writes it, the handler reads it), so it has no type here. */
+export interface ScheduleFireEvent {
+    scheduleFire: {
+        name: string;
+        slot: string;
+    };
+}

package/dist/channels/agentcore-protocol.js

@@ -0,0 +1,22 @@
+/**
+ * The wire between the forwarder Lambda and the container, in ONE place: the envelope every
+ * trigger arrives as, the reply a webhook rides back in, the presigned-URL pair the state snapshot
+ * uses, the wake-alarm request, and the forwarder's reserved paths. The forwarder itself is JavaScript
+ * (`deploy/agentcore/forwarder.js`) and cannot import this, so `agentcore-forwarder.test.ts` pins its
+ * literals to these — a rename here fails there, not on a live box.
+ *
+ * Pure types and constants: the adapter, the state sync, the wake sink and the deploy driver all
+ * read it, and none of them may pull the others in for it.
+ */
+/** Paths the forwarder answers ITSELF — never forwarded to a channel route. */
+export const RESERVED_PATHS = {
+    /** The deploy driver's post-deploy verification (ingress secret). */
+    probe: "/__fastagent/probe",
+    /** The container's wake-alarm mirror callback (wake secret). */
+    wakeAlarm: "/__fastagent/wake-alarm",
+    /** Re-mint the state snapshot's presigned URLs with current Lambda credentials (ingress secret). */
+    stateUrls: "/__fastagent/state-urls",
+};
+/** Every kind the container's `POST /invocations` dispatches on. Listed as a value so the forwarder
+ *  pin test can check each one is spelled the same on the other side. */
+export const ENVELOPE_KINDS = ["webhook", "schedule-fire", "invoke", "wake-poke", "checkpoint", "probe"];

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

@@ -25,10 +25,6 @@ export interface MountAgentcoreServiceOptions {
     /** 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;

package/dist/channels/agentcore-service.js

@@ -14,7 +14,7 @@ export async function mountAgentcoreService(opened, options = {}) {
     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 withControl = mountSessionControl({}, sessionControl, { agent });
     const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule, {
         externalClock: true,
     });
@@ -42,7 +42,6 @@ export async function mountAgentcoreService(opened, options = {}) {
     });
     const handler = router(adapterRoutes, withControl.mounts);
     log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
-    let unannounce;
     return {
         handler,
         agent,
@@ -56,16 +55,12 @@ export async function mountAgentcoreService(opened, options = {}) {
         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
         },
     };
 }

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

@@ -19,21 +19,15 @@
  * half-applied state root is far worse than a slightly stale one.
  */
 import { Buffer } from "node:buffer";
+import type { StateUrls } from "./agentcore-protocol.ts";
 /** Snapshot envelope version — an unknown version fails the restore loudly (never a silent skip). */
 export declare const SNAPSHOT_VERSION = 1;
 /** Refuse to pack beyond this (before gzip): a runaway state root would OOM the microVM silently. */
 export declare const MAX_SNAPSHOT_BYTES: number;
-/** Presigned S3 URLs for the one snapshot object, minted per envelope by the forwarder. */
-export interface StateUrls {
-    getUrl: string;
-    putUrl: string;
-    /** Authenticated forwarder callback that re-mints URLs with current Lambda credentials. */
-    refresh?: {
-        url: string;
-        auth: string;
-    };
-}
-/** Pack the whole state root into one gzipped snapshot object. */
+/** Pack the whole state root into one gzipped snapshot object.
+ *  ponytail: the WHOLE root, every idle edge — O(state size) per settled turn, and session jsonl
+ *  grows without bound. Upgrade path when the 16 MiB warning is real for someone: a per-file
+ *  manifest with content hashes, uploading only what changed. */
 export declare function packStateRoot(stateRoot: string, maxBytes?: number): Promise<Buffer>;
 /** Apply a snapshot over the state root. Returns how many files were written. */
 export declare function unpackIntoStateRoot(stateRoot: string, packed: Buffer): Promise<number>;

package/dist/channels/agentcore-state.js

@@ -72,7 +72,10 @@ async function walk(root, dir = root, out = []) {
     }
     return out;
 }
-/** Pack the whole state root into one gzipped snapshot object. */
+/** Pack the whole state root into one gzipped snapshot object.
+ *  ponytail: the WHOLE root, every idle edge — O(state size) per settled turn, and session jsonl
+ *  grows without bound. Upgrade path when the 16 MiB warning is real for someone: a per-file
+ *  manifest with content hashes, uploading only what changed. */
 export async function packStateRoot(stateRoot, maxBytes = MAX_SNAPSHOT_BYTES) {
     const files = {};
     let raw = 0;

package/dist/channels/agentcore.d.ts

@@ -1,69 +1,8 @@
 import type { Agent } from "../agent.ts";
-import type { StateSync, StateUrls } from "./agentcore-state.ts";
+import type { StateSync } from "./agentcore-state.ts";
 import type { Routes } from "../channel.ts";
 import { type PrefixMount } from "../channels/serve.ts";
 import type { ScheduleFireOutcome } from "../schedule/scheduler.ts";
-/** 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. */
-export type AgentcoreEnvelope = {
-    /** Shared secret proving this envelope came from the forwarder (FASTAGENT_INGRESS_SECRET). The
-     *  public `invoke` data plane neither has nor needs it — and may not carry the fields below. */
-    auth?: string;
-    wake?: {
-        url: string;
-    };
-    state?: StateUrls;
-} & ({
-    kind: "webhook";
-    /** Original webhook request line, verbatim. `path` must be absolute ("/telegram"). */
-    method: string;
-    path: string;
-    /** Original raw query string (no leading `?`) — "verbatim" includes it; a channel reading
-     *  `request.url.searchParams` must see what the webhook sender sent. */
-    query?: string;
-    /** Original headers — signature material (secret tokens, Feishu signatures) rides here. */
-    headers?: Record<string, string>;
-    /** Original body, base64 (webhook bodies are JSON but the tunnel must be byte-exact). */
-    bodyB64?: string;
-} | {
-    kind: "schedule-fire";
-    name: string;
-    /** The cron instant this fire is FOR (ISO) — the slot-idempotency key. */
-    slot: string;
-} | {
-    kind: "invoke";
-    session: string;
-    text: string;
-}
-/** An EventBridge wake-up poke: the invocation ITSELF is the payload — it wakes the container,
- *  whose boot drain / 30s wake pump then fires whatever is due. The handler only acks. */
- | {
-    kind: "wake-poke";
-}
-/** Pre-stop checkpoint (`--run`, right before stop-runtime-session): push the state snapshot NOW.
- *  A stop cuts an in-flight turn, and its durable turn intent — written pre-ACK by every replaying
- *  channel — lives on a mount the version update is about to erase. Flushing first is what makes
- *  "channels with replay re-run it" true rather than aspirational. */
- | {
-    kind: "checkpoint";
-}
-/** The deploy driver's post-deploy verification (relayed by the forwarder's reserved
- *  `/__fastagent/probe` path, which answers on EVERY forwarder topology — schedule-only URLs
- *  refuse ordinary public traffic). Runs restore + channel construction end to end and answers a
- *  TRANSPORT-200 structured verdict `{ ok, error? }`: the ordinary webhook path folds a non-200
- *  transport into an opaque 502 at the forwarder, which would strip exactly the diagnostics this
- *  probe exists to carry. */
- | {
-    kind: "probe";
-});
-/** The webhook envelope's reply: the channel's real HTTP response, ridden inside a transport-200
- *  body so the forwarder can re-emit it verbatim (see the module header on AgentCore's 424 folding). */
-export interface WebhookReply {
-    status: number;
-    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 {
@@ -101,11 +40,6 @@ export interface AgentcoreAdapterOptions {
      *  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 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
  *  not have — the adapter maps it to 404 (deploy drift stays visible in the external clock's logs). */

package/dist/channels/agentcore.js

@@ -26,7 +26,7 @@
  * the platform reclaim the microVM (that idle-to-zero IS the point of this deployment).
  */
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { ENVELOPE_KINDS } from "./agentcore-protocol.js";
 import { beginWork, onIdle } from "./busy.js";
 import { router } from "../channels/serve.js";
 import { log } from "../log.js";
@@ -34,48 +34,84 @@ import { rememberWakeAlarmUrl } from "../schedule/wake-alarm.js";
 import { readBodyCapped } from "./body.js";
 import { createInvokeHandler } from "./http.js";
 import { text } from "./respond.js";
+import { secretEquals } from "./secret.js";
 import { MAX_ENVELOPE_BYTES, MAX_WEBHOOK_BODY_BYTES } from "./agentcore-limits.js";
 const unsnapshottedWarning = "[agentcore] this envelope carried no state-snapshot URLs — the state root is LOCAL ONLY and the " +
     "platform erases it on the next deploy (redeploy with a current fastagent to restore durability)";
 const jsonHeaders = { "content-type": "application/json" };
 const json = (body, status) => new Response(`${JSON.stringify(body)}\n`, { status, headers: jsonHeaders });
-/** Compare an untrusted envelope secret without leaking a matching-prefix timing signal. */
-function secretMatches(actual, expected) {
-    if (typeof actual !== "string" || expected === undefined)
-        return false;
-    const actualBytes = Buffer.from(actual);
-    const expectedBytes = Buffer.from(expected);
-    return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
-}
 /**
  * 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 { 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
-    // queues and replaying durable turn intent) before reporting another module's failure — and there
-    // is no cleanup contract to unwind it, so re-running it per envelope could replay the same
-    // recovered turn concurrently. The first rejection is therefore the process's answer: every later
-    // envelope fails with the same message (visible each time), the retry boundary is a fresh session
-    // (which scale-to-zero provides naturally), and the deploy driver's probe catches deterministic
-    // failures at deploy time.
+/**
+ * The process's BOOT, deferred to ingress. A resident host restores its state, wires its sinks and
+ * constructs its channels at start-up; here nothing before the first trusted envelope is
+ * authoritative (the mount is pre-restore, and the snapshot URLs only an envelope carries), so those
+ * steps run against the first one and are asserted again on every later one. Two things happen ONCE
+ * per process, in this order: the post-restore hook (the wake-alarm reconcile, which at boot would
+ * read the mount the platform just wiped), and channel construction — whose 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 queues and
+ * replaying durable turn intent) before reporting another module's failure — and there is no cleanup
+ * contract to unwind it, so re-running it per envelope could replay the same recovered turn
+ * concurrently. The first rejection is the process's answer: every later envelope fails with the same
+ * message (visible each time), the retry boundary is a fresh session (which scale-to-zero provides
+ * naturally), and the deploy driver's probe catches deterministic failures at deploy time.
+ */
+function createActivation(deps) {
+    const { stateSync, stateRoot, onStateReady } = deps;
+    let warnedUnsnapshotted = false;
+    let stateReadyFired = false;
     let dispatchP;
-    const resolveDispatch = () => {
-        if (!dispatchP) {
-            // 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(channels)
-                .then((surface) => router(surface.routes, surface.mounts));
-            dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
-        }
-        return dispatchP;
+    return {
+        async restore(envelope) {
+            if (stateSync) {
+                if (envelope.state && typeof envelope.state.getUrl === "string" && typeof envelope.state.putUrl === "string") {
+                    stateSync.use(envelope.state);
+                }
+                else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
+                    // webhook/schedule-fire/wake-poke/probe reach us ONLY through the forwarder, which mints the
+                    // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
+                    // once per process (a direct `invoke` legitimately has none — its session storage is its own).
+                    warnedUnsnapshotted = true;
+                    log.warn(unsnapshottedWarning);
+                }
+                await stateSync.ready();
+            }
+            // The forwarder rides its public URL along on every envelope — persist it (write-if-changed) so
+            // the wake-alarm sink can call back. AFTER the restore: a stale snapshot copy must not win over
+            // the URL this deployment is actually reachable at. A bad persist must not fail the turn.
+            if (typeof envelope.wake?.url === "string") {
+                try {
+                    rememberWakeAlarmUrl(stateRoot, envelope.wake.url);
+                }
+                catch (e) {
+                    log.error(`[agentcore] could not persist the wake-alarm URL: ${String(e)}`);
+                }
+            }
+            if (onStateReady && !stateReadyFired) {
+                stateReadyFired = true;
+                onStateReady();
+            }
+        },
+        channels() {
+            if (!dispatchP) {
+                // 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(deps.channels)
+                    .then((surface) => router(surface.routes, surface.mounts));
+                dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
+            }
+            return dispatchP;
+        },
     };
+}
+export function agentcoreRoutes(options) {
+    const { channels, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
+    const activation = createActivation({ stateSync, stateRoot, onStateReady, channels });
     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.
@@ -83,8 +119,6 @@ export function agentcoreRoutes(options) {
         const off = onIdle(() => stateSync.save());
         options.signal?.addEventListener("abort", off, { once: true });
     }
-    let warnedUnsnapshotted = false;
-    let stateReadyFired = false;
     const handleInvocation = async (req) => {
         const body = await readBodyCapped(req, MAX_ENVELOPE_BYTES);
         if ("tooLarge" in body)
@@ -97,7 +131,7 @@ export function agentcoreRoutes(options) {
             return text("invalid json\n", 400);
         }
         if (envelope === null || typeof envelope !== "object" || typeof envelope.kind !== "string") {
-            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint" | "probe", ... }\n', 400);
+            return text(`need { "kind": ${ENVELOPE_KINDS.map((k) => `"${k}"`).join(" | ")}, ... }\n`, 400);
         }
         // AUTHENTICATION BOUNDARY. `InvokeAgentRuntime` is an ordinary IAM action, so "reached this
         // handler" proves nothing about the sender. Only an envelope carrying the shared secret is the
@@ -105,7 +139,7 @@ export function agentcoreRoutes(options) {
         // and may NOT carry internal fields — riding a `state` or `wake` URL on a public invoke would
         // redirect the state snapshot (auth.json) or the alarm callback (the wake secret) to the caller.
         // Internal fields are DROPPED rather than rejected: a public caller has no business knowing them.
-        const trusted = secretMatches(envelope.auth, ingressSecret);
+        const trusted = secretEquals(envelope.auth, ingressSecret);
         if (!trusted) {
             if (envelope.kind !== "invoke") {
                 log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
@@ -114,67 +148,34 @@ export function agentcoreRoutes(options) {
             envelope.wake = undefined;
             envelope.state = undefined;
         }
-        // The forwarder rides its public URL along on every envelope — persist it (write-if-changed) so
-        // the wake-alarm sink can call back. Written AFTER the restore below: a stale snapshot copy must
-        // not win over the URL this deployment is actually reachable at. A bad persist must not fail the turn.
-        const rememberUrl = () => {
-            if (typeof envelope.wake?.url !== "string")
-                return;
-            try {
-                rememberWakeAlarmUrl(stateRoot, envelope.wake.url);
-            }
-            catch (e) {
-                log.error(`[agentcore] could not persist the wake-alarm URL: ${String(e)}`);
-            }
-        };
         // Cross-deploy state: the platform wipes /mnt/state on every version update, so the durable copy
-        // must be pulled back BEFORE anything reads it. A failed restore fails the request — serving an
-        // empty agent (and then snapshotting that emptiness over the good copy) is the worse outcome.
-        if (stateSync) {
-            if (envelope.state && typeof envelope.state.getUrl === "string" && typeof envelope.state.putUrl === "string") {
-                stateSync.use(envelope.state);
-            }
-            else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
-                // webhook/schedule-fire/wake-poke/probe reach us ONLY through the forwarder, which mints the
-                // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
-                // once per process (a direct `invoke` legitimately has none — its session storage is its own).
-                warnedUnsnapshotted = true;
-                log.warn(unsnapshottedWarning);
-            }
-            try {
-                await stateSync.ready();
-            }
-            catch (e) {
-                log.error(`[agentcore] state restore failed: ${String(e)}`);
-                // The probe is the deploy driver's verification channel: its diagnostics must survive the
-                // forwarder, which folds a non-200 transport into an opaque 502 — so for it the failure
-                // rides a transport-200 structured verdict; every other kind keeps the plain 503.
-                if (envelope.kind === "probe")
-                    return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
-                return text(`state restore failed: ${String(e)}\n`, 503);
-            }
+        // must be pulled back BEFORE anything reads it.
+        try {
+            await activation.restore(envelope);
         }
-        rememberUrl();
-        // The state root is authoritative only now — anything that must READ it at startup (the wake-alarm
-        // reconcile) runs here, once, rather than at boot against a mount the platform just wiped.
-        if (onStateReady && !stateReadyFired) {
-            stateReadyFired = true;
-            onStateReady();
+        catch (e) {
+            log.error(`[agentcore] state restore failed: ${String(e)}`);
+            // The probe is the deploy driver's verification channel: its diagnostics must survive the
+            // forwarder, which folds a non-200 transport into an opaque 502 — so for it the failure
+            // rides a transport-200 structured verdict; every other kind keeps the plain 503.
+            if (envelope.kind === "probe")
+                return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
+            return text(`state restore failed: ${String(e)}\n`, 503);
         }
-        // PROCESS INITIALIZATION, kind-independent: the (lazy) channels are constructed on the first
-        // trusted ingress after the state root became authoritative — whichever kind carries it, so a
-        // cold start woken by a schedule fire or an alarm poke still replays checkpointed turn intent.
-        // Two deliberate exceptions: `checkpoint` must push state even when a channel is broken, and a
-        // public `invoke` runs in its own isolated storage — constructing against THAT root would cache
-        // pre-restore emptiness for the ingress session. Failure policy is per kind below: webhook and
-        // wake-poke fail their request (503), the probe reports it structurally, and a schedule fire
-        // proceeds — cron does not consume channels, and letting an unrelated channel misconfiguration
-        // silence the clock would turn one fault into two (the error is logged here either way).
+        // The channels come up on the first trusted ingress after the state root became authoritative —
+        // whichever kind carries it, so a cold start woken by a schedule fire or an alarm poke still
+        // replays checkpointed turn intent. Two deliberate exceptions: `checkpoint` must push state even
+        // when a channel is broken, and a public `invoke` runs in its own isolated storage — constructing
+        // against THAT root would cache pre-restore emptiness for the ingress session. Failure policy is
+        // per kind below: webhook and wake-poke fail their request (503), the probe reports it
+        // structurally, and a schedule fire proceeds — cron does not consume channels, and letting an
+        // unrelated channel misconfiguration silence the clock would turn one fault into two (the error
+        // is logged here either way).
         let constructionError;
         let dispatch;
         if (trusted && envelope.kind !== "checkpoint" && envelope.kind !== "invoke") {
             try {
-                dispatch = await resolveDispatch();
+                dispatch = await activation.channels();
             }
             catch (e) {
                 constructionError = String(e);

package/dist/channels/control.d.ts

@@ -1,5 +1,5 @@
 /**
- * The session control plane over HTTP + SSE — the Phase 3 transport (design §13). Engine-neutral:
+ * The session control plane over HTTP + SSE (docs/design/session-control.md §13). Engine-neutral:
  * consumes only the `SessionControl` contract. One transport serves every remote consumer (Web
  * panel, desktop app, `fastagent attach`); the embedded API stays semantic-only and the ENVELOPE
  * lives here: `id` (request correlation — implicit in HTTP), `epoch` (serving-process incarnation