@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/README.md

@@ -7,6 +7,7 @@
 [![license](https://img.shields.io/npm/l/@fastagent-sh/fastagent.svg)](https://github.com/fastagent-sh/fastagent/blob/main/LICENSE)
 [![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)
 
 <p align="center">
   <sub>Built on</sub>
@@ -39,7 +40,7 @@ FastAgent is the missing bridge from local agent directory to live service.
 - **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, a Feishu or Lark bot, an HTTP/SSE endpoint, or your own adapter: verified webhooks, streaming replies, group-aware.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
 - **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
-- **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels. Durable ingress remains yours.
+- **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway|agentcore` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels; AWS Bedrock AgentCore gets a one-stack CloudFormation topology (webhooks via a forwarder Lambda, schedules via EventBridge). Durable ingress remains yours.
 
 ## Design philosophy
 
@@ -160,7 +161,7 @@ The root export intentionally contains the supported surface only.
 |---|---|---|
 | Contract | `Agent`, `AgentEvent`, `collect` | Stable within SPEC v0.1 |
 | Channels/host | `createInvokeHandler`, `nodeListener`, `serveNode`, `router`, `Routes` | Reference implementation, pre-1.0 |
-| pi assembly | `createPiAgentFromWorkspace`, `createPiAgentFromDefinition`, `createPiAgent` | Usable now, may tighten before 1.0 |
+| 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 |
@@ -198,10 +199,12 @@ The neutral contract leaves room for capabilities that are not complete product
 - **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter 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, and Railway ship today; the generated container is the portable path for other hosts.
+- **More deploy targets** — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.
 
 See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
 
+> ☁️ **Prefer these managed?** FastAgent Cloud will run your agents with multi-instance durability, scale-to-zero, and observability built in — and self-hosting stays free forever. [Join the waitlist →](https://tally.so/r/44DVMB)
+
 ## Project
 
 - [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md)
@@ -215,6 +218,13 @@ It also depends on, and is grateful to, [zod](https://github.com/colinhacks/zod)
 
 The scaffolded `writing-great-skills` skill is vendored from [mattpocock/skills](https://github.com/mattpocock/skills), with its license included.
 
+---
+
+<p align="center">
+  <b>FastAgent is built in the open.</b><br/>
+  If it saves you from rewriting an agent into yet another framework, <a href="https://github.com/fastagent-sh/fastagent">give it a ⭐</a> — it's the fastest way to help other devs find it.
+</p>
+
 ## License
 
 [MIT](https://github.com/fastagent-sh/fastagent/blob/main/LICENSE). Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored `writing-great-skills` scaffold includes its own license.

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

@@ -0,0 +1,7 @@
+/**
+ * Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion.
+ * Enforced by both the public forwarder and the runtime adapter.
+ */
+export declare const MAX_WEBHOOK_BODY_BYTES: number;
+/** Largest complete AgentCore envelope accepted by the runtime adapter. */
+export declare const MAX_ENVELOPE_BYTES: number;

package/dist/channels/agentcore-limits.js

@@ -0,0 +1,9 @@
+/** AWS Lambda Function URLs accept request payloads up to 6 MB. */
+const FUNCTION_URL_REQUEST_LIMIT = 6 * 1000 * 1000;
+/**
+ * Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion.
+ * Enforced by both the public forwarder and the runtime adapter.
+ */
+export const MAX_WEBHOOK_BODY_BYTES = Math.floor((FUNCTION_URL_REQUEST_LIMIT * 3) / 4) - (64 << 10);
+/** Largest complete AgentCore envelope accepted by the runtime adapter. */
+export const MAX_ENVELOPE_BYTES = FUNCTION_URL_REQUEST_LIMIT;

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

@@ -0,0 +1,83 @@
+/**
+ * Cross-deploy durability for the state root on AgentCore.
+ *
+ * WHY THIS EXISTS: AgentCore's managed SessionStorage — the `/mnt/state` mount — is reset on every
+ * runtime VERSION UPDATE, i.e. on EVERY deploy ("On runtime version update: Data wiped — fresh file
+ * system on next invoke", AWS file-system configuration docs), and again after 14 idle days. The
+ * mount is therefore a fast LOCAL disk, not the source of truth. Without this module a deploy
+ * silently resurrects the agent with no sessions, no channel dedup, no pending wake-ups — and the
+ * wake ALARM, which lives in the operator's EventBridge and survives independently, still fires into
+ * that empty store: a miss with no error anywhere (exactly the silent-failure class the repo's
+ * fail-visibly rule exists to prevent).
+ *
+ * The durable copy is ONE S3 object reached through PRESIGNED URLS minted per-envelope by the
+ * forwarder Lambda. The container holds no AWS credentials (the platform injects none — verified on
+ * a live deployment) and stays AWS-SDK-free: a snapshot is one `fetch` GET and one `fetch` PUT.
+ *
+ * Format: gzip(JSON `{ v, files: { relPath: base64 } }`). Deliberately NOT tar — the state root is a
+ * handful of small JSON/JSONL files, and a single self-describing object makes restore ATOMIC: a
+ * half-applied state root is far worse than a slightly stale one.
+ */
+import { Buffer } from "node:buffer";
+/** 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. */
+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>;
+export interface StateSyncOptions {
+    stateRoot: string;
+    /** Injected in tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The per-process snapshot lifecycle: restore ONCE before anything reads the state root, then push a
+ * coalesced snapshot whenever work settles.
+ */
+export interface StateSync {
+    /** Remember the newest presigned URLs (each envelope carries a fresh pair). */
+    use(urls: StateUrls): void;
+    /** Resolve once the state root is authoritative. REJECTS if a snapshot exists but cannot be
+     *  restored — the caller must fail the request rather than serve from an empty state root (and a
+     *  failed restore also blocks {@link StateSync.save}, so bad state is never written back).
+     *  Resolves immediately while no URLs are known: a direct programmatic invoke runs in its OWN
+     *  isolated session/storage and must neither read nor overwrite the ingress snapshot. */
+    ready(): Promise<void>;
+    /** Whether snapshotting is active (URLs seen). Lets the caller flag a forwarder envelope that
+     *  arrived WITHOUT them — a topology fault that would otherwise lose state silently. */
+    configured(): boolean;
+    /** Request a snapshot upload; coalesces while one is in flight. Errors are logged, not thrown —
+     *  the next settle retries, and the local mount still holds the data until the version changes. */
+    save(): void;
+    /** Await the in-flight (and any queued) upload — the shutdown/test seam. */
+    flush(): Promise<void>;
+    /**
+     * Push a snapshot NOW and report whether one was actually written — the pre-stop checkpoint
+     * (`--run`, before `stop-runtime-session`). Distinct from {@link StateSync.save} on both counts:
+     * it forces a fresh round rather than joining a coalescing window (the caller is about to lose
+     * this process, so "an upload from a second ago" is not good enough), and it THROWS on failure
+     * instead of logging, because the whole point of the call is to know.
+     *
+     * `written: false` is a legitimate outcome, not an error: a session that never served a forwarder
+     * envelope has no URLs and nothing of the shared state to write. The caller must not report that
+     * as a successful checkpoint — it is exactly the case where an operator would otherwise believe an
+     * in-flight turn had been protected.
+     */
+    checkpoint(): Promise<{
+        written: boolean;
+        reason?: string;
+    }>;
+}
+export declare function createStateSync(options: StateSyncOptions): StateSync;

package/dist/channels/agentcore-state.js

@@ -0,0 +1,258 @@
+/**
+ * Cross-deploy durability for the state root on AgentCore.
+ *
+ * WHY THIS EXISTS: AgentCore's managed SessionStorage — the `/mnt/state` mount — is reset on every
+ * runtime VERSION UPDATE, i.e. on EVERY deploy ("On runtime version update: Data wiped — fresh file
+ * system on next invoke", AWS file-system configuration docs), and again after 14 idle days. The
+ * mount is therefore a fast LOCAL disk, not the source of truth. Without this module a deploy
+ * silently resurrects the agent with no sessions, no channel dedup, no pending wake-ups — and the
+ * wake ALARM, which lives in the operator's EventBridge and survives independently, still fires into
+ * that empty store: a miss with no error anywhere (exactly the silent-failure class the repo's
+ * fail-visibly rule exists to prevent).
+ *
+ * The durable copy is ONE S3 object reached through PRESIGNED URLS minted per-envelope by the
+ * forwarder Lambda. The container holds no AWS credentials (the platform injects none — verified on
+ * a live deployment) and stays AWS-SDK-free: a snapshot is one `fetch` GET and one `fetch` PUT.
+ *
+ * Format: gzip(JSON `{ v, files: { relPath: base64 } }`). Deliberately NOT tar — the state root is a
+ * handful of small JSON/JSONL files, and a single self-describing object makes restore ATOMIC: a
+ * half-applied state root is far worse than a slightly stale one.
+ */
+import { Buffer } from "node:buffer";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { gunzipSync, gzipSync } from "node:zlib";
+import { log } from "../log.js";
+import { beginWork } from "./busy.js";
+/** Snapshot envelope version — an unknown version fails the restore loudly (never a silent skip). */
+export const SNAPSHOT_VERSION = 1;
+/** Refuse to pack beyond this (before gzip): a runaway state root would OOM the microVM silently. */
+export const MAX_SNAPSHOT_BYTES = 64 << 20;
+/** Warn past this — the operator should know the snapshot is getting expensive to round-trip. */
+const WARN_SNAPSHOT_BYTES = 16 << 20;
+/** Upload deadline. Generous (a large snapshot on a cold network) but finite. */
+const PUT_TIMEOUT_MS = 60_000;
+/**
+ * Files the snapshot must NOT carry. `control.json` is a PER-BOOT artifact (this process's control
+ * URL + token, written once the port is known): snapshotting it would hand the next boot a file
+ * advertising a dead endpoint and a token that no longer matches the one in memory.
+ *
+ * Everything else is durable and restores VERBATIM — including `auth.json`. The deploy seeds that
+ * file from the builder machine, but the box's own copy is the one that has been REFRESHED, and this
+ * snapshot is its volume: the same rule every other host states ("a credential already refreshed on
+ * the volume is never overwritten"). The seed is bootstrap for a snapshot that has none.
+ */
+const EXCLUDED = new Set(["control.json"]);
+/** Every regular file under `root`, as root-relative POSIX paths (stable across platforms). */
+async function walk(root, dir = root, out = []) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return out;
+        throw e;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        // Symlinks/sockets/FIFOs are skipped on purpose: the state root holds plain files, and
+        // AgentCore's session storage does not support special files anyway.
+        if (entry.isDirectory())
+            await walk(root, full, out);
+        else if (entry.isFile())
+            out.push(relative(root, full).split(sep).join("/"));
+    }
+    return out;
+}
+/** Pack the whole state root into one gzipped snapshot object. */
+export async function packStateRoot(stateRoot, maxBytes = MAX_SNAPSHOT_BYTES) {
+    const files = {};
+    let raw = 0;
+    for (const rel of await walk(stateRoot)) {
+        if (EXCLUDED.has(rel))
+            continue;
+        const content = await readFile(join(stateRoot, rel));
+        raw += content.byteLength;
+        if (raw > maxBytes) {
+            throw new Error(`state root exceeds ${maxBytes} bytes — it cannot be snapshotted for cross-deploy durability`);
+        }
+        files[rel] = content.toString("base64");
+    }
+    if (raw > WARN_SNAPSHOT_BYTES) {
+        log.warn(`[agentcore] state snapshot is large (${Math.round(raw / (1 << 20))} MiB) — every turn round-trips it`);
+    }
+    return gzipSync(Buffer.from(JSON.stringify({ v: SNAPSHOT_VERSION, files })));
+}
+/** Apply a snapshot over the state root. Returns how many files were written. */
+export async function unpackIntoStateRoot(stateRoot, packed) {
+    let snapshot;
+    try {
+        snapshot = JSON.parse(gunzipSync(packed).toString());
+    }
+    catch (e) {
+        throw new Error(`state snapshot is unreadable (${String(e)})`);
+    }
+    if (snapshot?.v !== SNAPSHOT_VERSION || typeof snapshot.files !== "object" || snapshot.files === null) {
+        throw new Error(`state snapshot has an unsupported shape (v=${String(snapshot?.v)})`);
+    }
+    let written = 0;
+    for (const [rel, b64] of Object.entries(snapshot.files)) {
+        // A snapshot is written by this same code, but it arrives over the network: refuse anything
+        // that could escape the state root.
+        if (rel.startsWith("/") || rel.split("/").includes("..")) {
+            throw new Error(`state snapshot contains an unsafe path (${rel})`);
+        }
+        if (EXCLUDED.has(rel))
+            continue; // never write a per-boot artifact from an older boot
+        const target = join(stateRoot, rel);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, Buffer.from(b64, "base64"));
+        written += 1;
+    }
+    return written;
+}
+export function createStateSync(options) {
+    const { stateRoot } = options;
+    const doFetch = options.fetchImpl ?? fetch;
+    let urls;
+    let restore;
+    let restored = false;
+    let saving;
+    let queued = false;
+    // Whether the upload loop is still able to pick up another round. Counting the upload as in-flight
+    // work (below) means ITS completion is itself a 0-in-flight edge, which re-enters save() — without
+    // this the snapshot would queue a redundant follow-up after every single upload.
+    let looping = false;
+    const runRestore = async (urls) => {
+        const res = await doFetch(urls.getUrl, { method: "GET" });
+        // ONLY a proven 404 is "first deploy". The signer holds s3:GetObject on exactly this key, so a
+        // missing object answers NoSuchKey/404; a 403 means an expired or malformed signature, or a
+        // revoked permission — i.e. the snapshot may well exist. Reading 403 as "absent" would serve an
+        // empty agent and then overwrite the real snapshot with that emptiness.
+        if (res.status === 404) {
+            log.info("[agentcore] no state snapshot yet — starting from an empty state root (first deploy)");
+            restored = true;
+            return;
+        }
+        if (!res.ok)
+            throw new Error(`state snapshot GET failed: ${res.status}`);
+        const written = await unpackIntoStateRoot(stateRoot, Buffer.from(await res.arrayBuffer()));
+        log.info(`[agentcore] restored ${written} state file(s) from the snapshot`);
+        restored = true;
+    };
+    const refreshUrls = async () => {
+        if (!urls?.refresh)
+            return;
+        const res = await doFetch(urls.refresh.url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ auth: urls.refresh.auth }),
+            signal: AbortSignal.timeout(PUT_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`state snapshot URL refresh failed: ${res.status}`);
+        const fresh = (await res.json());
+        if (typeof fresh.getUrl !== "string" || typeof fresh.putUrl !== "string") {
+            throw new Error("state snapshot URL refresh returned an invalid response");
+        }
+        urls = { ...urls, getUrl: fresh.getUrl, putUrl: fresh.putUrl };
+    };
+    const runSave = async () => {
+        // Counted as in-flight work for its whole duration: `save()` fires on the 0-in-flight edge, the
+        // exact moment /ping starts answering Healthy — without this the platform may reclaim the microVM
+        // mid-upload and the turn that just finished is lost with only a log line. Bounded too: a hung
+        // PUT would otherwise pin `saving` forever and block every later snapshot.
+        const workDone = beginWork();
+        looping = true;
+        try {
+            do {
+                queued = false;
+                if (!restored || !urls)
+                    return;
+                // A webhook turn may settle hours after its envelope. Re-mint immediately before every PUT
+                // instead of assuming the Lambda credentials that signed the envelope outlive the turn.
+                await refreshUrls();
+                const body = await packStateRoot(stateRoot);
+                const res = await doFetch(urls.putUrl, {
+                    method: "PUT",
+                    body: new Uint8Array(body),
+                    signal: AbortSignal.timeout(PUT_TIMEOUT_MS),
+                });
+                if (!res.ok) {
+                    const hint = res.status === 403 ? " (presigned URL or its temporary signing credentials may have expired)" : "";
+                    throw new Error(`state snapshot PUT failed: ${res.status}${hint}`);
+                }
+            } while (queued);
+        }
+        finally {
+            looping = false;
+            workDone();
+        }
+    };
+    return {
+        use(next) {
+            urls = next;
+        },
+        configured() {
+            return urls !== undefined;
+        },
+        ready() {
+            // No URLs = not an ingress envelope (a direct invoke has its own isolated storage): nothing to
+            // restore, and deliberately NOT cached, so the first envelope that does carry them still runs
+            // the restore.
+            if (!urls)
+                return Promise.resolve();
+            // One attempt per process otherwise: a rejected restore stays rejected so every subsequent
+            // envelope fails the same visible way instead of quietly serving an empty agent.
+            restore ??= runRestore(urls);
+            return restore;
+        },
+        save() {
+            if (!restored)
+                return; // never overwrite a good snapshot with a state root we failed to fill
+            if (saving) {
+                if (looping)
+                    queued = true; // otherwise this is the upload's own completion edge, not new work
+                return;
+            }
+            saving = runSave()
+                .catch((e) => {
+                log.error(`[agentcore] could not save the state snapshot: ${String(e)} — retrying when work next settles`);
+            })
+                .finally(() => {
+                saving = undefined;
+            });
+        },
+        async flush() {
+            while (saving)
+                await saving;
+        },
+        async checkpoint() {
+            if (!urls) {
+                return { written: false, reason: "this session has never served a forwarder envelope" };
+            }
+            if (!restored) {
+                return { written: false, reason: "the state root is not authoritative here (nothing restored)" };
+            }
+            // Never overlap an in-flight upload, then run a FRESH one: joining the running round could
+            // return before the bytes written moments ago (the interrupted turn's intent) are included.
+            while (saving)
+                await saving;
+            const run = runSave();
+            // Stored form never rejects (an unawaited rejection would be an unhandled crash); the caller
+            // awaits `run` itself and gets the error.
+            saving = run.then(() => { }, () => { });
+            const settle = saving.finally(() => {
+                saving = undefined;
+            });
+            try {
+                await run;
+            }
+            finally {
+                await settle;
+            }
+            return { written: true };
+        },
+    };
+}

package/dist/channels/agentcore.d.ts

@@ -0,0 +1,98 @@
+import type { Agent } from "../agent.ts";
+import type { StateSync, StateUrls } from "./agentcore-state.ts";
+import type { Routes } from "../host/node.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 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;
+}
+export interface AgentcoreAdapterOptions {
+    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health). */
+    routes: Routes;
+    agent: Agent;
+    /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
+    stateRoot: string;
+    /** Process-wide background-work signal (busy.ts `activeWork() > 0`) — injected for tests. */
+    isBusy: () => boolean;
+    /** Slot-idempotent schedule fire ({@link fireScheduleOnce} bound to this workspace's schedules);
+     *  undefined when the workspace has none — a schedule-fire envelope then 404s (deploy drift: an
+     *  external clock still firing for a schedule this definition no longer has). */
+    fire?: (name: string, slot: Date) => Promise<ScheduleFireOutcome>;
+    /** Cross-deploy state durability (agentcore-state.ts). Absent = the state root is local-only,
+     *  which on AgentCore means it is erased by the next deploy — the serving path always wires it. */
+    stateSync?: StateSync;
+    /** 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;
+    /** 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.
+ */
+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). */
+export declare class UnknownScheduleError extends Error {
+    constructor(name: string);
+}