@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/agentcore.js

@@ -26,7 +26,7 @@
  * the platform reclaim the microVM (that idle-to-zero IS the point of this deployment).
  */
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { ENVELOPE_KINDS } from "./agentcore-protocol.js";
 import { beginWork, onIdle } from "./busy.js";
 import { router } from "../channels/serve.js";
 import { log } from "../log.js";
@@ -34,49 +34,84 @@ import { rememberWakeAlarmUrl } from "../schedule/wake-alarm.js";
 import { readBodyCapped } from "./body.js";
 import { createInvokeHandler } from "./http.js";
 import { text } from "./respond.js";
+import { secretEquals } from "./secret.js";
 import { MAX_ENVELOPE_BYTES, MAX_WEBHOOK_BODY_BYTES } from "./agentcore-limits.js";
 const unsnapshottedWarning = "[agentcore] this envelope carried no state-snapshot URLs — the state root is LOCAL ONLY and the " +
     "platform erases it on the next deploy (redeploy with a current fastagent to restore durability)";
 const jsonHeaders = { "content-type": "application/json" };
 const json = (body, status) => new Response(`${JSON.stringify(body)}\n`, { status, headers: jsonHeaders });
-/** Compare an untrusted envelope secret without leaking a matching-prefix timing signal. */
-function secretMatches(actual, expected) {
-    if (typeof actual !== "string" || expected === undefined)
-        return false;
-    const actualBytes = Buffer.from(actual);
-    const expectedBytes = Buffer.from(expected);
-    return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
-}
 /**
- * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }`. The caller merges it
- * over its routes (collision-checked at the mount site, serve.ts) — the inner routes stay mounted
- * too, which is harmless (AgentCore routes only /invocations and /ping into the container) and keeps
- * a local `curl` debug surface.
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }` — the whole of what the
+ * platform routes into the container. The agent's own channels are not beside these: they are a table
+ * inside the envelope dispatch below, reached only by unwrapping a forwarder envelope.
  */
-export function agentcoreRoutes(options) {
-    const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
-    // Lazy channel construction (see AgentcoreAdapterOptions.routes) — resolved ONCE per process, on
-    // the first trusted envelope after the state root is authoritative, and the outcome is cached
-    // EITHER WAY. Success: the same resident channels a direct host keeps. Failure too: construction
-    // is an ACTIVATION with side effects — loadChannels builds every healthy channel (starting its
-    // queues and replaying durable turn intent) before reporting another module's failure — and there
-    // is no cleanup contract to unwind it, so re-running it per envelope could replay the same
-    // recovered turn concurrently. The first rejection is therefore the process's answer: every later
-    // envelope fails with the same message (visible each time), the retry boundary is a fresh session
-    // (which scale-to-zero provides naturally), and the deploy driver's probe catches deterministic
-    // failures at deploy time.
+/**
+ * The process's BOOT, deferred to ingress. A resident host restores its state, wires its sinks and
+ * constructs its channels at start-up; here nothing before the first trusted envelope is
+ * authoritative (the mount is pre-restore, and the snapshot URLs only an envelope carries), so those
+ * steps run against the first one and are asserted again on every later one. Two things happen ONCE
+ * per process, in this order: the post-restore hook (the wake-alarm reconcile, which at boot would
+ * read the mount the platform just wiped), and channel construction — whose outcome is cached EITHER
+ * WAY. Success: the same resident channels a direct host keeps. Failure too: construction is an
+ * ACTIVATION with side effects — loadChannels builds every healthy channel (starting its queues and
+ * replaying durable turn intent) before reporting another module's failure — and there is no cleanup
+ * contract to unwind it, so re-running it per envelope could replay the same recovered turn
+ * concurrently. The first rejection is the process's answer: every later envelope fails with the same
+ * message (visible each time), the retry boundary is a fresh session (which scale-to-zero provides
+ * naturally), and the deploy driver's probe catches deterministic failures at deploy time.
+ */
+function createActivation(deps) {
+    const { stateSync, stateRoot, onStateReady } = deps;
+    let warnedUnsnapshotted = false;
+    let stateReadyFired = false;
     let dispatchP;
-    const resolveDispatch = () => {
-        if (!dispatchP) {
-            // The factory runs INSIDE the chain: a synchronous throw must land in the cached rejection,
-            // not escape before `dispatchP` is assigned (which would silently re-run the activation).
-            dispatchP = Promise.resolve()
-                .then(() => (typeof routes === "function" ? routes() : routes))
-                .then((surface) => router(surface.routes, surface.mounts));
-            dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
-        }
-        return dispatchP;
+    return {
+        async restore(envelope) {
+            if (stateSync) {
+                if (envelope.state && typeof envelope.state.getUrl === "string" && typeof envelope.state.putUrl === "string") {
+                    stateSync.use(envelope.state);
+                }
+                else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
+                    // webhook/schedule-fire/wake-poke/probe reach us ONLY through the forwarder, which mints the
+                    // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
+                    // once per process (a direct `invoke` legitimately has none — its session storage is its own).
+                    warnedUnsnapshotted = true;
+                    log.warn(unsnapshottedWarning);
+                }
+                await stateSync.ready();
+            }
+            // The forwarder rides its public URL along on every envelope — persist it (write-if-changed) so
+            // the wake-alarm sink can call back. AFTER the restore: a stale snapshot copy must not win over
+            // the URL this deployment is actually reachable at. A bad persist must not fail the turn.
+            if (typeof envelope.wake?.url === "string") {
+                try {
+                    rememberWakeAlarmUrl(stateRoot, envelope.wake.url);
+                }
+                catch (e) {
+                    log.error(`[agentcore] could not persist the wake-alarm URL: ${String(e)}`);
+                }
+            }
+            if (onStateReady && !stateReadyFired) {
+                stateReadyFired = true;
+                onStateReady();
+            }
+        },
+        channels() {
+            if (!dispatchP) {
+                // The factory runs INSIDE the chain: a synchronous throw must land in the cached rejection,
+                // not escape before `dispatchP` is assigned (which would silently re-run the activation).
+                dispatchP = Promise.resolve()
+                    .then(deps.channels)
+                    .then((surface) => router(surface.routes, surface.mounts));
+                dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
+            }
+            return dispatchP;
+        },
     };
+}
+export function agentcoreRoutes(options) {
+    const { channels, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
+    const activation = createActivation({ stateSync, stateRoot, onStateReady, channels });
     const invokeHandler = createInvokeHandler(agent);
     // Snapshot on the 0-in-flight edge: webhook channels ACK fast and finish the turn in the
     // background, so "the request returned" is NOT when the state root settles.
@@ -84,8 +119,6 @@ export function agentcoreRoutes(options) {
         const off = onIdle(() => stateSync.save());
         options.signal?.addEventListener("abort", off, { once: true });
     }
-    let warnedUnsnapshotted = false;
-    let stateReadyFired = false;
     const handleInvocation = async (req) => {
         const body = await readBodyCapped(req, MAX_ENVELOPE_BYTES);
         if ("tooLarge" in body)
@@ -98,7 +131,7 @@ export function agentcoreRoutes(options) {
             return text("invalid json\n", 400);
         }
         if (envelope === null || typeof envelope !== "object" || typeof envelope.kind !== "string") {
-            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint" | "probe", ... }\n', 400);
+            return text(`need { "kind": ${ENVELOPE_KINDS.map((k) => `"${k}"`).join(" | ")}, ... }\n`, 400);
         }
         // AUTHENTICATION BOUNDARY. `InvokeAgentRuntime` is an ordinary IAM action, so "reached this
         // handler" proves nothing about the sender. Only an envelope carrying the shared secret is the
@@ -106,7 +139,7 @@ export function agentcoreRoutes(options) {
         // and may NOT carry internal fields — riding a `state` or `wake` URL on a public invoke would
         // redirect the state snapshot (auth.json) or the alarm callback (the wake secret) to the caller.
         // Internal fields are DROPPED rather than rejected: a public caller has no business knowing them.
-        const trusted = secretMatches(envelope.auth, ingressSecret);
+        const trusted = secretEquals(envelope.auth, ingressSecret);
         if (!trusted) {
             if (envelope.kind !== "invoke") {
                 log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
@@ -115,67 +148,34 @@ export function agentcoreRoutes(options) {
             envelope.wake = undefined;
             envelope.state = undefined;
         }
-        // The forwarder rides its public URL along on every envelope — persist it (write-if-changed) so
-        // the wake-alarm sink can call back. Written AFTER the restore below: a stale snapshot copy must
-        // not win over the URL this deployment is actually reachable at. A bad persist must not fail the turn.
-        const rememberUrl = () => {
-            if (typeof envelope.wake?.url !== "string")
-                return;
-            try {
-                rememberWakeAlarmUrl(stateRoot, envelope.wake.url);
-            }
-            catch (e) {
-                log.error(`[agentcore] could not persist the wake-alarm URL: ${String(e)}`);
-            }
-        };
         // Cross-deploy state: the platform wipes /mnt/state on every version update, so the durable copy
-        // must be pulled back BEFORE anything reads it. A failed restore fails the request — serving an
-        // empty agent (and then snapshotting that emptiness over the good copy) is the worse outcome.
-        if (stateSync) {
-            if (envelope.state && typeof envelope.state.getUrl === "string" && typeof envelope.state.putUrl === "string") {
-                stateSync.use(envelope.state);
-            }
-            else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
-                // webhook/schedule-fire/wake-poke/probe reach us ONLY through the forwarder, which mints the
-                // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
-                // once per process (a direct `invoke` legitimately has none — its session storage is its own).
-                warnedUnsnapshotted = true;
-                log.warn(unsnapshottedWarning);
-            }
-            try {
-                await stateSync.ready();
-            }
-            catch (e) {
-                log.error(`[agentcore] state restore failed: ${String(e)}`);
-                // The probe is the deploy driver's verification channel: its diagnostics must survive the
-                // forwarder, which folds a non-200 transport into an opaque 502 — so for it the failure
-                // rides a transport-200 structured verdict; every other kind keeps the plain 503.
-                if (envelope.kind === "probe")
-                    return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
-                return text(`state restore failed: ${String(e)}\n`, 503);
-            }
+        // must be pulled back BEFORE anything reads it.
+        try {
+            await activation.restore(envelope);
         }
-        rememberUrl();
-        // The state root is authoritative only now — anything that must READ it at startup (the wake-alarm
-        // reconcile) runs here, once, rather than at boot against a mount the platform just wiped.
-        if (onStateReady && !stateReadyFired) {
-            stateReadyFired = true;
-            onStateReady();
+        catch (e) {
+            log.error(`[agentcore] state restore failed: ${String(e)}`);
+            // The probe is the deploy driver's verification channel: its diagnostics must survive the
+            // forwarder, which folds a non-200 transport into an opaque 502 — so for it the failure
+            // rides a transport-200 structured verdict; every other kind keeps the plain 503.
+            if (envelope.kind === "probe")
+                return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
+            return text(`state restore failed: ${String(e)}\n`, 503);
         }
-        // PROCESS INITIALIZATION, kind-independent: the (lazy) channels are constructed on the first
-        // trusted ingress after the state root became authoritative — whichever kind carries it, so a
-        // cold start woken by a schedule fire or an alarm poke still replays checkpointed turn intent.
-        // Two deliberate exceptions: `checkpoint` must push state even when a channel is broken, and a
-        // public `invoke` runs in its own isolated storage — constructing against THAT root would cache
-        // pre-restore emptiness for the ingress session. Failure policy is per kind below: webhook and
-        // wake-poke fail their request (503), the probe reports it structurally, and a schedule fire
-        // proceeds — cron does not consume channels, and letting an unrelated channel misconfiguration
-        // silence the clock would turn one fault into two (the error is logged here either way).
+        // The channels come up on the first trusted ingress after the state root became authoritative —
+        // whichever kind carries it, so a cold start woken by a schedule fire or an alarm poke still
+        // replays checkpointed turn intent. Two deliberate exceptions: `checkpoint` must push state even
+        // when a channel is broken, and a public `invoke` runs in its own isolated storage — constructing
+        // against THAT root would cache pre-restore emptiness for the ingress session. Failure policy is
+        // per kind below: webhook and wake-poke fail their request (503), the probe reports it
+        // structurally, and a schedule fire proceeds — cron does not consume channels, and letting an
+        // unrelated channel misconfiguration silence the clock would turn one fault into two (the error
+        // is logged here either way).
         let constructionError;
         let dispatch;
         if (trusted && envelope.kind !== "checkpoint" && envelope.kind !== "invoke") {
             try {
-                dispatch = await resolveDispatch();
+                dispatch = await activation.channels();
             }
             catch (e) {
                 constructionError = String(e);
@@ -301,6 +301,14 @@ export function agentcoreRoutes(options) {
     };
     // Settle-then-snapshot: when the envelope leaves nothing in flight, its writes are final now (a
     // background turn instead reports through the idle edge above).
+    //
+    // A public `invoke` is the one kind this MISSES, measurably: it answers with an unconsumed SSE
+    // stream, so the turn runs after this line and its records wait for the next envelope's snapshot.
+    // Counting it as in-flight work would close that and cost more than it buys — the stream drains at
+    // the CLIENT's pace, so one parked reader pins /ping at HealthyBusy and defeats the idle reclaim,
+    // which is the quota-exhaustion failure the ping contract below warns about. The kinds that carry
+    // conversations (webhook, schedule-fire, wake-poke) all run their turn inside the request or
+    // through `beginWork`, so they land on one of the two edges; `invoke` is the direct/debug door.
     const invocations = async (req) => {
         const response = await handleInvocation(req);
         if (stateSync && !isBusy())

package/dist/channels/control.d.ts

@@ -1,7 +1,36 @@
-import { type SessionControl, type SessionEvent } from "../session.ts";
+/**
+ * The session control plane over HTTP + SSE (docs/design/session-control.md §13). Engine-neutral:
+ * consumes only the `SessionControl` contract. One transport serves every remote consumer (Web
+ * panel, desktop app, `fastagent attach`); the embedded API stays semantic-only and the ENVELOPE
+ * lives here: `id` (request correlation — implicit in HTTP), `epoch` (serving-process incarnation
+ * — INFORMATIONAL, for consumers correlating across connections; a restart surfaces as its
+ * connections dropping, so no one fences on it), `seq` (per-connection monotonic, detects loss in
+ * transit).
+ *
+ * SECURITY: these routes steer and stop runs, rewrite session properties, and delete records — a
+ * remote-control surface. The bearer token is REQUIRED (there is no unauthenticated mode) and is the only auth the framework owns; anything
+ * beyond a shared secret (principals, per-permission split, audit) is the wrapping host's job
+ * (design §14). Locally the serving process generates a per-boot token and writes it to
+ * `<stateRoot>/control.json` for local discovery — filesystem permissions guard the token, and the
+ * token guards the routes. That premise is shared-filesystem: a deployment breaks it, so there the
+ * DEPLOYER supplies the token ({@link CONTROL_TOKEN_ENV}) and both sides know it. How far those routes REACH is the bind address: all interfaces by
+ * default (containers require it), so the port is LAN-reachable and the mount warns accordingly —
+ * `--bind 127.0.0.1` (or `http.host`) closes exactly that reach, and the warning goes quiet because
+ * there is none left to state.
+ */
 import type { Agent } from "../agent.ts";
-import type { ChannelHandler } from "../channel.ts";
+import { type SessionControl, type SessionEvent } from "../session.ts";
 import { type PrefixMount } from "./serve.ts";
+/** A plane handler: the request, plus the session id the path named (`""` where the path has none). */
+type PlaneHandler = (req: Request, session: string) => Response | Promise<Response>;
+/** The plane's route table: `"<METHOD> <path>"` → handler, where at most one path segment is
+ *  {@link SESSION_SEGMENT}. */
+export type PlaneRoutes = Record<string, PlaneHandler>;
+/** The token, when the DEPLOYER owns it rather than the box (`mountSessionControl` reads it, `deploy`
+ *  carries it). Declared here with the prefix because both are the plane's public names: the serving
+ *  side and the deploy side must spell it identically, and a rename that hits only one of them fails
+ *  silently — the box mints its own and every caller the runbook told gets a 401. */
+export declare const CONTROL_TOKEN_ENV = "FASTAGENT_CONTROL_TOKEN";
 /** The SSE payload: one control-plane event in its transport envelope. */
 export interface WireEvent {
     sessionId: string;
@@ -23,16 +52,25 @@ export interface ControlPlaneOptions {
     agent?: Agent;
 }
 /**
- * Create the control plane as a mountable prefix owner: `GET
- * /control/capabilities|commands|state|entries|events` + `POST /control/dispatch`, all
- * bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
- * The plane OWNS {@link CONTROL_PREFIX}: it is mounted as one sub-application, answers its own
- * 404/405/preflight, and puts CORS headers on every reply — see {@link planeApp}.
+ * Create the control plane as a mountable prefix owner — a RESTful surface over
+ * {@link CONTROL_PREFIX}: sessions are a collection, a session is a resource, its history and event
+ * stream are sub-resources, and the things that HAPPEN to a run are posted to `…/actions`.
+ * The plane OWNS the prefix: it answers its own 404/405/preflight and puts CORS headers on every
+ * reply — see {@link planeApp}.
  */
 export declare function createControlPlane(control: SessionControl, options: ControlPlaneOptions): PrefixMount;
 /** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
- *  table is a set of literal paths. */
-export declare function mountControlPlane(routes: Record<string, ChannelHandler>): PrefixMount;
-/** The plane's route table. Exported so the conformance sweeps derive their route list from what is
- *  actually mounted, rather than from a hand-kept copy that cannot notice a new route. */
-export declare function controlPlaneRoutes(control: SessionControl, options: ControlPlaneOptions): Record<string, ChannelHandler>;
+ *  table is a set of paths, at most one segment of which is a session id. */
+export declare function mountControlPlane(routes: PlaneRoutes): PrefixMount;
+/**
+ * The plane's route table. Exported so the conformance sweeps derive their route list from what is
+ * actually mounted, rather than from a hand-kept copy that cannot notice a new route.
+ *
+ * The shape mirrors the contract: a collection, a resource, its sub-resources, and one action
+ * endpoint. What a session IS gets `GET`; what a session HAS gets `PATCH` (properties, last-wins);
+ * what happens TO a run gets `POST …/actions` (not a property — an event in time). `PUT` on a
+ * session id is the fork, and it is a PUT because a fork is idempotent by construction: the id is
+ * the caller's, the body says where the history came from, and repeating it changes nothing.
+ */
+export declare function controlPlaneRoutes(control: SessionControl, options: ControlPlaneOptions): PlaneRoutes;
+export {};