@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/cli/serve.js

@@ -1,27 +1,22 @@
 /**
  * What `dev` (its worker) and `start` need beyond the service itself: binding a port, the shutdown
- * order, the startup report, and the optional Cloudflare quick tunnel.
+ * order, the startup report, the optional Cloudflare quick tunnel, and the options the CLI hands the
+ * assembly (`cliMountOptions`, `resolveBindHost` — policy ABOUT the assembly, decided per command).
  *
- * The ASSEMBLY is not here — it lives in `src/service.ts`, which a public entry may import and this
- * directory may not be (it decides process-level things: `fail.ts` calls `process.exit`).
+ * The ASSEMBLY itself is not here — it lives in `src/service.ts`, which a public entry may import and
+ * this directory may not be (it decides process-level things: `fail.ts` calls `process.exit`).
  */
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
-import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
+import { answersLocalhost, bindAddress, bindLabel, classifyBind, clientHost } from "../bind.js";
+import { writeFileAtomic } from "../atomic-write.js";
 import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
+import { declaredChannels } from "../channels/discover.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup, failUsage } from "./fail.js";
-/**
- * Mount the session control plane (`/control/*`) when the agent enabled it
- * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
- * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
- * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
- * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
- * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
- * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
- * and silently shadowing either side would serve a surface the author didn't write.
- */
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
  * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
@@ -45,14 +40,44 @@ export function assertTunnelBindable(host, tunnel, source) {
     failStartup(new Error(message));
 }
 /**
- * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
- * ONE function because they are one message — they were two, and `--bind` updated the first while the
- * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
- * neither can be changed without the other in view, and the address has a single derivation.
- *
- * A wildcard bind is every interface, and naming one address there would understate it — but the curl
- * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ * The bind address a serve uses: the flag, else `http.host` from the config — through `bindAddress`,
+ * so a configured `localhost` is an ADDRESS by the time anything binds, renders or dials it — checked
+ * against `--tunnel` with the exit code the SOURCE of the value earns (serve.ts assertTunnelBindable).
  */
+export function resolveBindHost(bindFlag, configured, tunnel) {
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, tunnel, bindFlag ? "flag" : "config");
+    return host;
+}
+/** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
+export function cliMountOptions(wrapAgent) {
+    return {
+        wrapAgent,
+        closeTimeoutMs: SHUTDOWN_GRACE_MS,
+        onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
+    };
+}
+/**
+ * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the
+ * tail dev's worker and start share once the service is assembled.
+ */
+export function serveService(service, bind, posture) {
+    const { host } = bind;
+    const { tunnel, agentDir, stateRoot } = posture;
+    let unannounce = () => { };
+    serve(service.handler, bind, {
+        ready: service.ready,
+        onListening: (p) => {
+            reportServing(service, host, p);
+            unannounce = announceControl(service.control, stateRoot, { host, tunnel }, p);
+            maybeTunnel(agentDir, service.channels.routes, p, tunnel, stateRoot);
+        },
+        onShutdown: () => {
+            unannounce();
+            return service.close();
+        },
+    });
+}
 /**
  * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
  * what mounted. One function because both commands must say the same thing at the same moment —
@@ -67,6 +92,15 @@ export function reportServing(service, host, boundPort) {
         log.info(`[fastagent] long connections: ${service.channels.longConnections.join(", ")}`);
     }
 }
+/**
+ * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
+ * ONE function because they are one message — they were two, and `--bind` updated the first while the
+ * second went on dialing `localhost`, which is precisely what a non-wildcard bind stops answering. Now
+ * neither can be changed without the other in view, and the address has a single derivation.
+ *
+ * A wildcard bind is every interface, and naming one address there would understate it — but the curl
+ * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
+ */
 export function readyAddressLines(host, boundPort, builtinInvoke) {
     const dial = `${clientHost(host)}:${boundPort}`;
     const lines = [
@@ -78,15 +112,57 @@ export function readyAddressLines(host, boundPort, builtinInvoke) {
     return lines;
 }
 /**
- * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
- * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command. `host` unset binds all interfaces.
+ * Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the control plane
+ * once the port is known, and say what reaches it. Returns the file's removal — wired into the
+ * shutdown so a stale file cannot point a client at a dead port (`attach` then fails with "cannot
+ * read", accurate, instead of a stale token's misleading 401/ECONNREFUSED). A hard exit leaves the
+ * file behind: advisory, overwritten by the next boot.
+ *
+ * Here and not in the assembly: the file, its permissions and the warnings are how THIS process's
+ * operator finds and protects the plane. An embedder distributes `service.control` itself.
  */
+export function announceControl(control, stateRoot, bind, boundPort) {
+    if (!control)
+        return () => { };
+    mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+    const path = join(stateRoot, "control.json");
+    const url = `http://${clientHost(bind.host)}:${boundPort}`;
+    writeFileAtomic(path, `${JSON.stringify({ url, token: control.token })}\n`, 0o600);
+    log.info(`[fastagent] session control on ${control.prefix}/* (token in ${path})`);
+    // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths warn
+    // loudly, and the LAN path must not be the silent third way past the local trust story. A
+    // loopback bind closes exactly that reach, so it earns silence.
+    const reach = classifyBind(bind.host);
+    if (reach !== "loopback") {
+        log.warn(`[fastagent] the port binds ${reach === "wildcard" ? "all interfaces" : `${bind.host} (off this machine)`}: ` +
+            "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
+            "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs/design/session-control.md §14)");
+    }
+    if (bind.tunnel) {
+        // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC.
+        log.warn("[fastagent] --tunnel exposes /control/* (steer, stop, rewrite or delete a session) at the public tunnel URL, " +
+            "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs/design/session-control.md §14)");
+    }
+    return () => {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            /* the file is advisory — shutdown must not fail on it */
+        }
+    };
+}
 /** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
  *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
-export const SHUTDOWN_GRACE_MS = 800;
+const SHUTDOWN_GRACE_MS = 800;
 const FORCED_EXIT_MS = 1_500;
-export function serve(handler, bind, hooks = {}) {
+/**
+ * Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment: a bound
+ * socket is not a serving agent while a declared long-connection channel is still dialling, so this
+ * awaits `hooks.ready` (mountAgentService owns the connections themselves) before announcing
+ * anything. Signals are the sole clean-shutdown command; `host` unset binds all interfaces.
+ */
+function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
     const hosted = serveNode(handler, { port, host });
     let stopping = false;
@@ -149,13 +225,16 @@ export function serve(handler, bind, hooks = {}) {
     });
 }
 /** Start a Cloudflare tunnel for route channels only. */
-export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
+function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
     void startCloudflareTunnel(boundPort).then((instance) => {
         if (!instance)
             return;
-        void announceWebhooks(agentDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        void announceWebhooks(agentDir, instance.url, declaredChannels(routeChannels), {
+            openUrl: openExternalUrl,
+            stateRoot,
+        });
         const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);

package/dist/cli/shared.d.ts

@@ -1,16 +1,58 @@
 import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
+import type { LoadedDefinition } from "../engines/pi/definition.ts";
+import { type ModuleLoadFailure } from "../loader.ts";
+import type { ToolCollision } from "../engines/pi/tool.ts";
+import { type ResolvedPlacement } from "../paths.ts";
 /**
- * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
- * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
- * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
- * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
- * policy (pad, never hand-space), not a constant.
+ * How every command that runs the model enters its agent directory, in the one order that works:
+ * placement decides whose `.env` to read; `.env` may carry the proxy and the provider keys the
+ * picker's auth probe needs; the picker runs last. Six commands wrote these steps out by hand, and
+ * one carried the order as a comment. The result is the placement every later step reads.
  */
-export declare function reportLine(label: string, value: string): void;
-/** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
- *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
- *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
-export declare function reportWorkspaceHint(hint: string | undefined): void;
+export declare function enterAgentCommand(dirArg: string, opts: {
+    model?: string;
+    authPath?: string;
+    input?: boolean;
+}): Promise<ResolvedPlacement>;
+/** What the startup report reads off an opened directory — a structural subset of the opener's return,
+ *  spelled out so this module does not depend on that function's whole shape. */
+export interface ReportableAssembly {
+    agentDir: string;
+    workspace: string;
+    modelSpec: string;
+    authPath: string;
+    config: {
+        thinkingLevel?: string;
+    };
+    definition: LoadedDefinition;
+    toolNames: string[];
+    deferredToolNames: string[];
+    toolCollisions: ToolCollision[];
+    toolFailures: ModuleLoadFailure[];
+}
+/**
+ * What `dev` and `start` say about the directory they just opened, in the order they say it.
+ *
+ * ONE function because it is one report: the two commands wrote it out line by line, and the copies
+ * had already diverged over which lines exist at all — `dev` naming the config file, `start` naming
+ * state and sessions. A line added to one of two hand-written copies is invisible in the other.
+ *
+ * The divergence itself is PRESERVED, not resolved: `start`'s `state:`/`sessions:` pair introduces the
+ * persistence warnings that follow it in production posture, and `dev`'s `config:` has no counterpart
+ * there. Both are passed as explicit extras by the caller, so the asymmetry is visible at the call
+ * site rather than buried in two copies of a list. Whether it is RIGHT is a separate question from
+ * whether it has one owner.
+ *
+ * Findings (skill collisions, definition diagnostics) CLOSE the report — they are about the assembly
+ * just printed. What a command says next is its own posture talk, not report: `start`'s persistence
+ * notes now follow them rather than precede them.
+ */
+export declare function reportAssembly(a: ReportableAssembly, extras?: {
+    /** Printed between `workspace:`/`hint:` and `model:` (`dev` names the config file here). */
+    beforeModel?: [label: string, value: string][];
+    /** Printed after the tool lines, before findings (`start` names state + sessions here). */
+    afterTools?: [label: string, value: string][];
+}): Promise<void>;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
 /**
@@ -30,23 +72,6 @@ export declare function parseBind(value: string | undefined): string | undefined
  *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
  *  reported like any built-in rather than as an unknown provider. */
 export declare function reportAuth(agentDir: string, modelSpec: string, authPath: string): Promise<void>;
-/**
- * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
- * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL
- * catalog annotated per provider — ready (with the credential source, so which account pays is
- * visible at the decision point) or login-required — and, when the choice needs auth, run the login
- * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
- * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
- * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
- * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
- * and best-effort written back to the config so the next run is quiet. `agentDir` is the resolved
- * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
- */
-export declare function resolveFirstRunModel(agentDir: string, options?: {
-    model?: string;
-    authPath?: string;
-    input?: boolean;
-}): Promise<void>;
 /**
  * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
  * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the

package/dist/cli/shared.js

@@ -4,7 +4,7 @@
  * module-scoped flag access (`values.*`) became parameters.
  */
 import { readFile, writeFile } from "node:fs/promises";
-import { relative } from "node:path";
+import { relative, resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
@@ -12,27 +12,90 @@ import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resol
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
+import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
+import { reportModuleLoadFailures } from "../loader.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
+import { workspaceHint } from "../paths.js";
 import { log } from "../log.js";
+import { loadDotEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
+import { installProxyFetch } from "../proxy.js";
 import { bindAddress, isBindAddress } from "../bind.js";
-import { failStartup, failUsage } from "./fail.js";
+import { failStartup, failUsage, placementOrExit } from "./fail.js";
+/**
+ * How every command that runs the model enters its agent directory, in the one order that works:
+ * placement decides whose `.env` to read; `.env` may carry the proxy and the provider keys the
+ * picker's auth probe needs; the picker runs last. Six commands wrote these steps out by hand, and
+ * one carried the order as a comment. The result is the placement every later step reads.
+ */
+export async function enterAgentCommand(dirArg, opts) {
+    const placement = placementOrExit(resolve(dirArg));
+    loadDotEnv(placement.agentDir);
+    installProxyFetch();
+    await resolveFirstRunModel(placement.agentDir, opts);
+    return placement;
+}
 /**
  * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
  * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
  * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
  * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
  * policy (pad, never hand-space), not a constant.
+ *
+ * Private to this module: {@link reportAssembly} is the report, and a command reaching past it for a
+ * line of its own is how the two copies of that report came to differ.
  */
-export function reportLine(label, value) {
+function reportLine(label, value) {
     log.info(`[fastagent] ${`${label}:`.padEnd(13)}${value}`);
 }
 /** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
  *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
- *  as one and is silent otherwise — `dev` and `start` both print the pair, so both ask for it. */
-export function reportWorkspaceHint(hint) {
+ *  as one and is silent otherwise. */
+function reportWorkspaceHint(hint) {
     if (hint)
         reportLine("hint", hint);
 }
+/**
+ * What `dev` and `start` say about the directory they just opened, in the order they say it.
+ *
+ * ONE function because it is one report: the two commands wrote it out line by line, and the copies
+ * had already diverged over which lines exist at all — `dev` naming the config file, `start` naming
+ * state and sessions. A line added to one of two hand-written copies is invisible in the other.
+ *
+ * The divergence itself is PRESERVED, not resolved: `start`'s `state:`/`sessions:` pair introduces the
+ * persistence warnings that follow it in production posture, and `dev`'s `config:` has no counterpart
+ * there. Both are passed as explicit extras by the caller, so the asymmetry is visible at the call
+ * site rather than buried in two copies of a list. Whether it is RIGHT is a separate question from
+ * whether it has one owner.
+ *
+ * Findings (skill collisions, definition diagnostics) CLOSE the report — they are about the assembly
+ * just printed. What a command says next is its own posture talk, not report: `start`'s persistence
+ * notes now follow them rather than precede them.
+ */
+export async function reportAssembly(a, extras = {}) {
+    reportLine("agent", a.agentDir);
+    reportLine("workspace", a.workspace);
+    reportWorkspaceHint(workspaceHint(a));
+    for (const [label, value] of extras.beforeModel ?? [])
+        reportLine(label, value);
+    reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
+    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
+    reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
+    if (a.definition.persona)
+        reportLine("persona", "persona.md");
+    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
+    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
+    if (a.toolNames.length > 0)
+        reportLine("tools", a.toolNames.join(", "));
+    if (a.deferredToolNames.length > 0) {
+        reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
+    }
+    reportToolCollisions(a.toolCollisions);
+    reportModuleLoadFailures(a.toolFailures);
+    for (const [label, value] of extras.afterTools ?? [])
+        reportLine(label, value);
+    reportFindingsIfChanged(a.definition.dir, a.definition);
+}
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -101,7 +164,7 @@ export async function reportAuth(agentDir, modelSpec, authPath) {
  * and best-effort written back to the config so the next run is quiet. `agentDir` is the resolved
  * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
  */
-export async function resolveFirstRunModel(agentDir, options = {}) {
+async function resolveFirstRunModel(agentDir, options = {}) {
     const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
     if (resolveModelSpec(options.model, config))
         return; // already set (flag > FASTAGENT_MODEL > config)

package/dist/deploy/agentcore/forwarder.js

@@ -0,0 +1,250 @@
+// Generated by `fastagent deploy agentcore` — the deployment's only ingress.
+// (Inside fastagent this file IS the source; the sentence below applies to the copy it is emitted as,
+// the workspace's `lambda/index.js`.)
+// REGENERATED ON EVERY DEPLOY; edits here are overwritten and never deployed. `--run` builds the
+// Lambda package from fastagent's own copy of this source, so this file is the readable MIRROR of
+// what runs (and what the manual runbook zips) — not an input you can change.
+// Webhooks (Function URL) and EventBridge Scheduler fires are forwarded as envelopes to the
+// AgentCore Runtime over SigV4 InvokeAgentRuntime, all on ONE fixed ingress session (fastagent
+// channel state is single-writer; one session = at most one microVM). With selfSchedule, this
+// Lambda also OWNS the wake alarms: the container POSTs its pending wake-ups to /__fastagent/
+// wake-alarm (shared secret) and each becomes a self-deleting one-shot EventBridge schedule that
+// pokes this Lambda — which wakes the container, whose wake pump fires the due entry.
+// CommonJS on purpose: the deployment package's entry lands as index.js, where ESM import is invalid.
+"use strict";
+const crypto = require("node:crypto");
+const { BedrockAgentCoreClient, InvokeAgentRuntimeCommand } = require("@aws-sdk/client-bedrock-agentcore");
+const client = new BedrockAgentCoreClient({});
+let ownUrl; // self-resolved once per cold start; rides on every envelope for the wake-alarm callback
+
+// Presigned S3 URLs for the container's state snapshot. AgentCore wipes the /mnt/state mount on
+// every runtime version update (= every deploy), so the durable copy lives in S3 — but the
+// container is given NO AWS credentials by the platform, so the only reachable form is a URL that
+// carries its own authorization. SigV4 query signing, node:crypto only (no SDK, nothing to install).
+const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+const hmac = (key, data) => crypto.createHmac("sha256", key).update(data).digest();
+
+// Every shared-secret gate on this public URL goes through here. Constant-time, and an unset
+// expected secret NEVER matches — otherwise a topology that did not configure one would accept a
+// request that sent none. Non-string input is coerced to "" first: Buffer.from(8) allocates eight
+// bytes rather than throwing, which would compare a number against a secret by length alone.
+const secretEq = (given, expected) => {
+  const a = Buffer.from(typeof given === "string" ? given : ""),
+    b = Buffer.from(expected || "");
+  return b.length > 0 && a.length === b.length && crypto.timingSafeEqual(a, b);
+};
+
+function presign(method, seconds) {
+  const bucket = process.env.STATE_BUCKET,
+    key = process.env.STATE_KEY,
+    region = process.env.AWS_REGION;
+  const host = `${bucket}.s3.${region}.amazonaws.com`;
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+/, "");
+  const scope = `${stamp.slice(0, 8)}/${region}/s3/aws4_request`;
+  const pairs = [
+    ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
+    ["X-Amz-Credential", `${process.env.AWS_ACCESS_KEY_ID}/${scope}`],
+    ["X-Amz-Date", stamp],
+    ["X-Amz-Expires", String(seconds)],
+    ["X-Amz-SignedHeaders", "host"],
+  ];
+  if (process.env.AWS_SESSION_TOKEN) pairs.push(["X-Amz-Security-Token", process.env.AWS_SESSION_TOKEN]);
+  // The canonical query must be byte-identical to the one on the wire — build it ONCE, reuse below.
+  const query = pairs
+    .map(([k, v]) => [enc(k), enc(v)])
+    .sort((a, b) => (a[0] < b[0] ? -1 : 1))
+    .map((p) => p.join("="))
+    .join("&");
+  const path = `/${key.split("/").map(enc).join("/")}`;
+  const canonical = [method, path, query, `host:${host}\n`, "host", "UNSIGNED-PAYLOAD"].join("\n");
+  const sts = ["AWS4-HMAC-SHA256", stamp, scope, crypto.createHash("sha256").update(canonical).digest("hex")].join(
+    "\n",
+  );
+  let k = hmac(`AWS4${process.env.AWS_SECRET_ACCESS_KEY}`, stamp.slice(0, 8));
+  for (const part of [region, "s3", "aws4_request"]) k = hmac(k, part);
+  return `https://${host}${path}?${query}&X-Amz-Signature=${hmac(k, sts).toString("hex")}`;
+}
+
+async function invoke(envelope) {
+  if ((process.env.WAKE_SECRET || process.env.STATE_REFRESH_SECRET) && !ownUrl) {
+    const { LambdaClient, GetFunctionUrlConfigCommand } = require("@aws-sdk/client-lambda");
+    ownUrl = (
+      await new LambdaClient({}).send(
+        new GetFunctionUrlConfigCommand({ FunctionName: process.env.AWS_LAMBDA_FUNCTION_NAME }),
+      )
+    ).FunctionUrl;
+  }
+  if (ownUrl) envelope.wake = { url: ownUrl };
+  // Authenticates this envelope as coming from the forwarder (see the template's FastagentIngressSecret).
+  envelope.auth = process.env.INGRESS_SECRET;
+  // Keep each capability short-lived. Function-URL deployments also carry an authenticated refresh
+  // endpoint, so a background turn settling hours after its webhook never depends on the temporary
+  // Lambda credentials that signed the original pair still being alive.
+  if (process.env.STATE_BUCKET)
+    envelope.state = {
+      getUrl: presign("GET", 3600),
+      putUrl: presign("PUT", 3600),
+      ...(ownUrl && process.env.STATE_REFRESH_SECRET
+        ? {
+            refresh: {
+              url: `${ownUrl.replace(/\/$/, "")}/__fastagent/state-urls`,
+              auth: process.env.STATE_REFRESH_SECRET,
+            },
+          }
+        : {}),
+    };
+  const res = await client.send(
+    new InvokeAgentRuntimeCommand({
+      agentRuntimeArn: process.env.RUNTIME_ARN,
+      runtimeSessionId: process.env.INGRESS_SESSION_ID,
+      contentType: "application/json",
+      accept: "application/json",
+      payload: new TextEncoder().encode(JSON.stringify(envelope)),
+    }),
+  );
+  const body = Buffer.from(await res.response.transformToByteArray());
+  return { status: res.statusCode ?? 200, body };
+}
+
+// Mirror the container's pending wake-ups into one-shot schedules: at(fireAt), poke me, delete
+// after firing. Upsert (create → conflict → update). The container pre-filters DUE alarms (it is
+// awake handling those), so every failure here is REAL — counted and propagated: a swallowed error
+// would leave a pending wake with no alarm, exactly the reliability hole this mechanism closes.
+// Cancelled wakes are NOT deleted here: their poke fires, finds nothing due, and the schedule
+// self-deletes (lazy cleanup by design).
+async function syncAlarms(alarms, ctx) {
+  const { SchedulerClient, CreateScheduleCommand, UpdateScheduleCommand } = require("@aws-sdk/client-scheduler");
+  const sch = new SchedulerClient({});
+  let failed = 0;
+  // Alarm name = a stable hash of the WHOLE wake id. A prefix of the id would collide (two wakes
+  // sharing 8 hex chars), and a collision is INDISTINGUISHABLE from the legitimate re-arm below:
+  // the second wake would "update" the first's alarm and silently steal its fire time.
+  const names = new Map();
+  for (const a of alarms) {
+    const name = process.env.WAKE_PREFIX + crypto.createHash("sha256").update(a.id).digest("hex").slice(0, 16);
+    if (names.has(name)) {
+      failed += 1;
+      console.log(`alarm name collision ${name}: ${names.get(name)} vs ${a.id}`);
+      continue;
+    }
+    names.set(name, a.id);
+    const p = {
+      Name: name,
+      ScheduleExpression: `at(${a.at.slice(0, 19)})`,
+      ScheduleExpressionTimezone: "UTC",
+      FlexibleTimeWindow: { Mode: "OFF" },
+      ActionAfterCompletion: "DELETE",
+      Target: { Arn: ctx.invokedFunctionArn, RoleArn: process.env.WAKE_ROLE_ARN, Input: '{"wakePoke":true}' },
+    };
+    try {
+      await sch.send(new CreateScheduleCommand(p));
+    } catch (e) {
+      try {
+        if (e.name !== "ConflictException") throw e;
+        await sch.send(new UpdateScheduleCommand(p));
+      } catch (u) {
+        failed += 1;
+        console.log(`alarm ${p.Name}: ${u}`);
+      }
+    }
+  }
+  return failed;
+}
+
+exports.handler = async (event, ctx) => {
+  // EventBridge wake-up poke: the invocation itself wakes the container; its pump does the rest.
+  if (event?.wakePoke) {
+    const r = await invoke({ kind: "wake-poke" });
+    console.log(`wake-poke: ${r.status}`);
+    return { status: r.status };
+  }
+  // EventBridge Scheduler fire — throw on failure so the miss lands in CloudWatch, never silently.
+  if (event?.scheduleFire) {
+    const { name, slot } = event.scheduleFire;
+    const r = await invoke({ kind: "schedule-fire", name, slot });
+    const out = r.body.toString();
+    console.log(`schedule-fire ${name} (${slot}): ${r.status} ${out}`);
+    if (r.status >= 400) throw new Error(`schedule-fire ${name} failed: ${r.status} ${out}`);
+    return { status: r.status };
+  }
+  const http = event?.requestContext?.http;
+  if (!http) throw new Error("unrecognized event shape");
+  // Refresh the snapshot capabilities with THIS Lambda invocation's current temporary credentials.
+  // The container may settle long after the webhook Lambda (and its credentials) expired.
+  if (event.rawPath === "/__fastagent/state-urls") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!secretEq(req.auth, process.env.STATE_REFRESH_SECRET)) return { statusCode: 403, body: "forbidden\n" };
+    return {
+      statusCode: 200,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ getUrl: presign("GET", 3600), putUrl: presign("PUT", 3600) }),
+    };
+  }
+  // The container's wake-alarm callback (reserved path, shared secret) — handled HERE, never forwarded.
+  if (event.rawPath === "/__fastagent/wake-alarm") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!secretEq(req.secret, process.env.WAKE_SECRET)) return { statusCode: 403, body: "forbidden\n" };
+    const failed = await syncAlarms(req.alarms || [], ctx);
+    // Partial failure IS failure: the container retries the whole (idempotent) set until every
+    // pending wake really has its alarm.
+    if (failed > 0) return { statusCode: 500, body: `${failed} alarm(s) failed\n` };
+    return { statusCode: 200, body: "ok\n" };
+  }
+  // The deploy driver's probe (reserved path, ingress secret): wake the runtime through the SAME
+  // trusted envelope pipeline (state URLs included — a direct InvokeAgentRuntime call could not mint
+  // them, and would make the runtime construct against a pre-restore mount) and pass its structured
+  // transport-200 verdict back VERBATIM. The ordinary webhook path below folds a non-200 transport
+  // into an opaque 502, which would strip exactly the diagnostics the probe exists to carry — and it
+  // sits BEFORE the WEBHOOKS_ENABLED gate so schedule-only topologies (whose URLs refuse ordinary
+  // public traffic) are probeable too.
+  if (event.rawPath === "/__fastagent/probe") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!secretEq(req.auth, process.env.INGRESS_SECRET)) return { statusCode: 403, body: "forbidden\n" };
+    const r = await invoke({ kind: "probe" });
+    if (r.status !== 200) {
+      console.log(`probe transport error ${r.status}: ${r.body}`);
+      return { statusCode: 502, body: "upstream error\n" };
+    }
+    return { statusCode: 200, headers: { "content-type": "application/json" }, body: r.body.toString() };
+  }
+  // Enforce the advertised ORIGINAL-body ceiling before base64 adds another 4/3 inside the runtime
+  // envelope. This also leaves deterministic room for headers/query/JSON under Lambda's 6 MB cap.
+  const webhookBytes =
+    event.body === undefined
+      ? 0
+      : event.isBase64Encoded
+        ? Buffer.byteLength(event.body, "base64")
+        : Buffer.byteLength(event.body);
+  // The ceiling rides in as an env var (the template's MAX_WEBHOOK_BODY_BYTES), so a stack whose
+  // template predates it would compare against NaN — every comparison false, the limit silently gone.
+  const maxWebhookBytes = Number(process.env.MAX_WEBHOOK_BODY_BYTES);
+  if (!(maxWebhookBytes > 0))
+    throw new Error("MAX_WEBHOOK_BODY_BYTES is missing or invalid — redeploy to regenerate the stack template");
+  if (webhookBytes > maxWebhookBytes) return { statusCode: 413, body: "payload too large\n" };
+  // A schedule-only deployment has a Function URL solely for the authenticated refresh callback.
+  // Reject arbitrary public traffic BEFORE it can wake AgentCore (cost/DoS) or reach an inner route.
+  if (process.env.WEBHOOKS_ENABLED !== "1") return { statusCode: 404, body: "not found\n" };
+  // Function URL webhook — forward the original request verbatim (signature material included).
+  const r = await invoke({
+    kind: "webhook",
+    method: http.method,
+    path: event.rawPath || "/",
+    query: event.rawQueryString || undefined,
+    headers: event.headers || {},
+    bodyB64:
+      event.body === undefined
+        ? undefined
+        : event.isBase64Encoded
+          ? event.body
+          : Buffer.from(event.body).toString("base64"),
+  });
+  if (r.status !== 200) {
+    console.log(`transport error ${r.status}: ${r.body}`);
+    return { statusCode: 502, body: "upstream error\n" };
+  }
+  const reply = JSON.parse(r.body.toString()); // { status, headers, bodyB64 } from the adapter
+  for (const k of Object.keys(reply.headers)) {
+    if (/^(content-length|transfer-encoding|connection)$/i.test(k)) delete reply.headers[k];
+  }
+  return { statusCode: reply.status, headers: reply.headers, body: reply.bodyB64, isBase64Encoded: true };
+};