@fastagent-sh/fastagent 0.19.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/atomic-write.d.ts

@@ -1,12 +1,16 @@
 /**
  * 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.
+ * 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.
  *
@@ -16,4 +20,4 @@
  * 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;
+export declare function writeFileAtomic(path: string, data: string | Buffer, mode?: number): void;

package/dist/atomic-write.js

@@ -1,22 +1,27 @@
 /**
- * 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.
+ * 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.
  *
- * 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.
+ * 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`). 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.
+ * 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.
  *

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-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

@@ -18,37 +18,34 @@ 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";
+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`) 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.
+ * 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(routes: Routes, options: {
+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 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>;
+    /** 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

@@ -4,7 +4,7 @@ import { assertNoControlPlaneCollision, mountSessionControl, routesFor, startSch
 import { UnknownScheduleError, agentcoreRoutes } from "./agentcore.js";
 import { createStateSync } from "./agentcore-state.js";
 import { activeWork } from "./busy.js";
-import { routeKeysConflict, router } from "./serve.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";
@@ -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,
     });
@@ -32,17 +32,16 @@ export async function mountAgentcoreService(opened, options = {}) {
     };
     // The adapter registers process-global listeners; this is what takes them down on close.
     const closed = new AbortController();
-    const adapterRoutes = mountAgentcore({}, {
+    const adapterRoutes = mountAgentcore({
         signal: closed.signal,
         agent,
         stateRoot,
         schedules: scheduled.schedules,
         onStateReady: options.onStateReady,
-        lazyChannels,
+        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,
@@ -56,30 +55,28 @@ 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
         },
     };
 }
 /**
- * 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.
+ * 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(routes, options) {
-    const { agent, stateRoot, schedules, onStateReady, lazyChannels, signal } = options;
-    const mounted = agentcoreRoutes({
-        routes: lazyChannels ?? { routes },
+export function mountAgentcore(options) {
+    const { agent, stateRoot, schedules, onStateReady, channels, signal } = options;
+    return agentcoreRoutes({
+        channels,
         agent,
         stateRoot,
         isBusy: () => activeWork() > 0,
@@ -102,10 +99,4 @@ export function mountAgentcore(routes, options) {
                 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-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,77 +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";
-/**
- * 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. */
-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 {
@@ -79,13 +10,14 @@ export interface RouteSurface {
     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: RouteSurface | (() => Promise<RouteSurface> | RouteSurface);
+    /** 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;
@@ -108,12 +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 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.
- */
 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). */