@fastagent-sh/fastagent 0.21.0 → 0.22.0

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

@@ -1,91 +1,98 @@
-/**
- * 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. */
+/** Every kind the container's `POST /invocations` dispatches on. */
+export declare const ENVELOPE_KINDS: readonly ["webhook", "routine-fire", "routine-run", "invoke", "wake-poke", "probe"];
+/**
+ * Did this envelope come from the FORWARDER, rather than from some other principal holding
+ * `bedrock-agentcore:InvokeAgentRuntime`?
+ *
+ * WHAT IT ACTUALLY GUARDS, in one line: only the forwarder may tell the container where the forwarder is. That URL
+ * (`envelope.wake.url`) is where the container later POSTs its wake alarms, carrying `FASTAGENT_WAKE_SECRET` — so a
+ * principal who could set it would redirect that callback and collect the secret along with every pending wake-up.
+ *
+ * The other thing it gates — the non-`invoke` kinds — is DEPTH, not a boundary. Every one of them is weaker than
+ * the `invoke` the same caller may already send: `routine-fire` runs a prompt the definition wrote down,
+ * `webhook` reaches only channel routes that verify their own platform's signature, `wake-poke` wakes, `probe`
+ * reports. IAM is what decides who gets to ask at all.
+ *
+ * ONE reading, because the deferred wrapper answers a probe before the adapter exists and would otherwise spell the
+ * same rule twice (channels/agentcore-service.ts).
+ */
+export declare function fromForwarder(envelope: {
+    auth?: unknown;
+} | undefined, expected: string | undefined): boolean;
+/** What the forwarder Lambda / EventBridge deliver in the `/invocations` payload. */
 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. */
+    /** Shared secret proving this envelope came from the forwarder (FASTAGENT_INGRESS_SECRET). */
     auth?: string;
     wake?: {
         url: string;
     };
-    state?: StateUrls;
 } & ({
     kind: "webhook";
-    /** Original webhook request line, verbatim. `path` must be absolute ("/telegram"). */
+    /** Original webhook request line, verbatim. */
     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. */
+    /**
+     * 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";
+    kind: "routine-fire";
+    name: string;
+    /**
+     * The instant EventBridge scheduled this fire for — the clock's NAME for the occurrence, stable across its
+     * redeliveries (measured: 3 attempts of one fire, byte-identical payload). The container dedupes on it and
+     * never recomputes it.
+     */
+    occurrence: string;
+} | {
+    /**
+     * Run a declared routine BY NAME — the `POST /run` contract on the host that publishes no routes.
+     *
+     * On the IAM door, like `invoke`, and for the same reason: the forwarder never emits this, so it can only
+     * come from a direct `InvokeAgentRuntime` call, where AWS has already said who the caller is. That makes
+     * by-name running STRICTER here than on a host with a public URL, where the same route is anonymous.
+     *
+     * Separate from `routine-fire` because they are different contracts, not two spellings: a fire names an
+     * OCCURRENCE our own clock produced and claims it (dedup across redeliveries, a fire history, the overlap
+     * policy); this names only the work (schedule/run.ts).
+     */
+    kind: "routine-run";
     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. */
+/**
+ * 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.
+ */
  | {
     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. */
+/**
+ * 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).
+ */
  | {
     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). */
+/**
+ * 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>;
@@ -101,12 +108,14 @@ 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. */
+/**
+ * What EventBridge hands the forwarder when a cron rule fires: which schedule, and which occurrence of it.
+ * `occurrence` is `<aws.scheduler.scheduled-time>` — the clock names its own fire, which is the only thing that
+ * survives a retry (schedule/run.ts).
+ */
 export interface ScheduleFireEvent {
     scheduleFire: {
         name: string;
-        slot: string;
+        occurrence: string;
     };
 }

package/dist/channels/agentcore-protocol.js

@@ -1,22 +1,30 @@
-/**
- * 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.
- */
+/** The wire between the forwarder Lambda and the container, in ONE place. */
+import { secretEquals } from "./secret.js";
 /** 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"];
+/** Every kind the container's `POST /invocations` dispatches on. */
+export const ENVELOPE_KINDS = ["webhook", "routine-fire", "routine-run", "invoke", "wake-poke", "probe"];
+/**
+ * Did this envelope come from the FORWARDER, rather than from some other principal holding
+ * `bedrock-agentcore:InvokeAgentRuntime`?
+ *
+ * WHAT IT ACTUALLY GUARDS, in one line: only the forwarder may tell the container where the forwarder is. That URL
+ * (`envelope.wake.url`) is where the container later POSTs its wake alarms, carrying `FASTAGENT_WAKE_SECRET` — so a
+ * principal who could set it would redirect that callback and collect the secret along with every pending wake-up.
+ *
+ * The other thing it gates — the non-`invoke` kinds — is DEPTH, not a boundary. Every one of them is weaker than
+ * the `invoke` the same caller may already send: `routine-fire` runs a prompt the definition wrote down,
+ * `webhook` reaches only channel routes that verify their own platform's signature, `wake-poke` wakes, `probe`
+ * reports. IAM is what decides who gets to ask at all.
+ *
+ * ONE reading, because the deferred wrapper answers a probe before the adapter exists and would otherwise spell the
+ * same rule twice (channels/agentcore-service.ts).
+ */
+export function fromForwarder(envelope, expected) {
+    return secretEquals(envelope?.auth, expected);
+}

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

@@ -1,51 +1,37 @@
-/**
- * The AgentCore serving assembly — the same product as `mountAgentService`, built differently
- * because the host is.
- *
- * Two facts drive every difference. There is no public URL (the adapter's `POST /invocations` is the
- * only ingress, and cron slots arrive through it from an external clock, so no resident timers), and
- * **the state mount at boot is PRE-RESTORE** — empty after every version update. Discovering channels
- * eagerly would therefore cache that emptiness (thread participation, delivery dedup, pending turns)
- * and then clobber the restored files with it, so channels are constructed lazily on the first
- * envelope. Everywhere else the state root is durable at boot and a broken channel fails startup.
- *
- * That is a different assembly, not a flag on the shared one: handler shape, discovery timing, clock
- * source, long-connection support and shutdown all differ. What it is NOT is a different product —
- * it returns the same {@link AgentService}, so `start` picks an assembly once and everything after
- * that point is common.
- */
+/** The AgentCore serving assembly — the same product as `mountAgentService`, built differently because the host is. */
 import type { Agent } from "../agent.ts";
 import type { Routes } from "../channel.ts";
-import type { LoadedSchedule } from "../schedule/schedule.ts";
+import type { LoadedRoutine } from "../schedule/routine.ts";
 import { type AgentService, type MountableAgent } from "../service.ts";
 import { type AgentcoreAdapterOptions } from "./agentcore.ts";
+import type { ChannelHandler } from "../channel.ts";
+/**
+ * Runtime filesystems appear on invocation, so even opening the definition must be deferred — in the TWO stages that
+ * differ in what a retry would cost.
+ */
+export declare function deferAgentcoreService<T>(stages: {
+    prepare: () => Promise<T>;
+    assemble: (prepared: T) => Promise<AgentService>;
+}): {
+    handler: ChannelHandler;
+    close: () => Promise<void>;
+};
 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. */
+    /** The process entry owns the global wake-alarm sink; activation reconciles it once. */
     onStateReady?: () => void;
 }
-/** 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`) — 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.
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) — the deployed container's ONLY reachable
+ * surface (channels/agentcore.ts).
  */
 export declare function mountAgentcore(options: {
     agent: Agent;
     stateRoot: string;
-    schedules: readonly LoadedSchedule[];
+    routines: readonly LoadedRoutine[];
     onStateReady?: () => void;
-    /** Cancels the adapter's process-global registrations on close. */
-    signal?: AbortSignal;
-    /** 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). */
+    /** The channel surface, initialized once by the adapter on trusted ingress. */
     channels: AgentcoreAdapterOptions["channels"];
 }): Routes;

package/dist/channels/agentcore-service.js

@@ -1,102 +1,219 @@
+import { fromForwarder } from "./agentcore-protocol.js";
 import { log } from "../log.js";
-import { fireScheduleOnce } from "../schedule/scheduler.js";
-import { assertNoControlPlaneCollision, mountSessionControl, routesFor, startSchedules, } from "../service.js";
-import { UnknownScheduleError, agentcoreRoutes } from "./agentcore.js";
-import { createStateSync } from "./agentcore-state.js";
-import { activeWork } from "./busy.js";
+import { loadServingRoutines, routesFor, startSchedules } from "../service.js";
+import { agentcoreRoutes, agentcorePing } from "./agentcore.js";
+import * as Effect from "effect/Effect";
+import { runRoutineByName, unknownRoutine } from "../schedule/run.js";
+import { fireRoutineOnce } from "../schedule/scheduler.js";
+import { text } from "./respond.js";
+import { activeWork, beginWork } from "./busy.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";
+import { readBodyCapped } from "./body.js";
+import { MAX_ENVELOPE_BYTES } from "./agentcore-limits.js";
+/**
+ * Runtime filesystems appear on invocation, so even opening the definition must be deferred — in the TWO stages that
+ * differ in what a retry would cost.
+ */
+export function deferAgentcoreService(stages) {
+    let service;
+    let prepared;
+    let assembling;
+    let closed = false;
+    let closing;
+    const ping = agentcorePing(() => activeWork() > 0);
+    const initialize = async () => {
+        const done = beginWork();
+        try {
+            prepared ??= stages.prepare().catch((error) => {
+                prepared = undefined; // nothing was taken, so the next envelope may ask again
+                throw error;
+            });
+            const taken = await prepared;
+            // Shutdown may have arrived while the workspace was being taken.
+            if (closed)
+                throw new Error("service closed during initialization");
+            assembling ??= stages.assemble(taken);
+            service = await assembling;
+            return service;
+        }
+        finally {
+            done();
+        }
+    };
+    return {
+        handler: async (request) => {
+            if (closed)
+                return new Response("service closed\n", { status: 503 });
+            if (service)
+                return service.handler(request);
+            const path = new URL(request.url).pathname;
+            if (path === "/ping" && request.method === "GET")
+                return ping(request);
+            if (path !== "/invocations" || request.method !== "POST")
+                return new Response("not found\n", { status: 404 });
+            let ready;
+            // Only the INITIALIZATION is caught here.
+            try {
+                ready = await initialize();
+            }
+            catch (error) {
+                const message = `initialization failed: ${String(error)}`;
+                log.error(`[agentcore] ${message}`);
+                const body = await readBodyCapped(request, MAX_ENVELOPE_BYTES);
+                if (!("tooLarge" in body)) {
+                    let envelope;
+                    try {
+                        envelope = JSON.parse(body.text);
+                    }
+                    catch {
+                        // Invalid envelopes retain the initialization error.
+                    }
+                    if (envelope?.kind === "probe" && fromForwarder(envelope, process.env.FASTAGENT_INGRESS_SECRET)) {
+                        return Response.json({ ok: false, error: message });
+                    }
+                }
+                return new Response(`${message}\n`, { status: 503 });
+            }
+            if (closed)
+                return new Response("service closed\n", { status: 503 });
+            return ready.handler(request);
+        },
+        close() {
+            closed = true;
+            closing ??= (async () => {
+                // A failed assembly already reached its caller.
+                await (await assembling?.catch(() => undefined))?.close();
+            })();
+            return closing;
+        },
+    };
 }
 export async function mountAgentcoreService(opened, options = {}) {
     const { agentDir, workspace, stateRoot, sessionControl } = opened;
     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, { agent });
-    const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule, {
-        externalClock: true,
-    });
+    // NO control plane on this host, and `sessionControl: true` cannot change that.
+    //
+    // The only public way in is the forwarder's Function URL, which relays an arbitrary `rawPath` verbatim as a
+    // webhook envelope (deploy/agentcore/forwarder.js) and attaches the ingress secret ITSELF — so every anonymous
+    // caller arrives as trusted ingress. A channel route survives that because the platform's signature is checked
+    // inside it; `/control/*` has no such check, and mounting it here made `GET /control/sessions` and
+    // `DELETE /control/sessions/{id}` answerable from the public URL with no credential at all.
+    //
+    // It is NOT that the two callers cannot be told apart. AWS already separates them and we already use that:
+    // `InvokeAgentRuntime` is IAM-gated, the forwarder builds its own envelopes and emits exactly four kinds, so a
+    // kind it never sends can only have come from a direct IAM call — which is how `kind: "invoke"` runs a turn here
+    // without the ingress secret. Adding `kind: "control"` on the same footing is small, and is the recipe if this is
+    // ever wanted.
+    //
+    // It is not built because nothing asks for it: `connectSessionControl` has no caller in this repo, and the
+    // envelope is request/response with a buffered body (see the webhook reply), so the one route a GUI actually
+    // renders from — the long-lived `GET /control/sessions/{id}/events` stream — could not ride it anyway. Half a
+    // control plane, for nobody, on a third transport.
+    // Every config key that cannot mean anything on this host says so. Silence here is how an operator concludes a
+    // setting took effect — `sessionControl` was the one that already warned, and the other two were just as inert.
+    if (opened.http?.cors) {
+        log.warn("[fastagent] agentcore: http.cors has no effect here — no browser reaches this container. Its ingress is the " +
+            "forwarder's Function URL (webhooks) and the Runtime's IAM-gated API, neither of which is a page.");
+    }
+    if (opened.http?.invoke !== undefined) {
+        log.warn("[fastagent] agentcore: http.invoke has no effect here — this host serves the Runtime's POST /invocations " +
+            "contract instead of our own /invoke, and reaching it already requires bedrock-agentcore:InvokeAgentRuntime.");
+    }
+    if (opened.http?.run !== undefined) {
+        log.warn("[fastagent] agentcore: http.run has no effect here — routines fire through the forwarder's " +
+            "routine-fire envelope, which is gated by the ingress secret rather than served as an anonymous route.");
+    }
+    if (opened.publishControl) {
+        log.warn("[fastagent] agentcore: sessionControl is ON but /control/* is NOT served here — this host's only public " +
+            "ingress relays anonymous traffic as trusted, so the plane is not assembled behind it " +
+            "(docs/design/session-control.md §14)");
+    }
+    // Started here, not deferred to an envelope.
+    const routines = await loadServingRoutines(agentDir);
+    const scheduled = startSchedules(agent, stateRoot, routines, { externalClock: true });
     const lazyChannels = async () => {
-        const lazy = await routesFor(agentDir, agent, stateRoot, sessionControl, { builtinInvoke: false });
+        const lazy = await routesFor(agentDir, agent, stateRoot, sessionControl, { http: { invoke: false } });
         if (lazy.longConnections.length > 0) {
             throw new Error(`long-connection channel(s) ${lazy.longConnections.map((c) => c.name).join(", ")} cannot serve on ` +
                 `AgentCore (scale-to-zero severs resident connections) — use the channel's webhook form`);
         }
-        // The SAME rule mountSessionControl applies, through the same function: its check ran against an
-        // empty base at boot, so it has to run again once the channels are real.
-        for (const plane of withControl.mounts)
-            assertNoControlPlaneCollision(lazy.routes, plane);
-        return { routes: lazy.routes, mounts: withControl.mounts };
+        // CHANNELS ONLY — nothing unverified rides the public relay. `lazy.unverified` (here just `GET /health`) is dropped
+        // with the control plane, for the same reason: what arrives through that URL is anonymous.
+        return { routes: lazy.selfVerifying };
     };
-    // The adapter registers process-global listeners; this is what takes them down on close.
-    const closed = new AbortController();
     const adapterRoutes = mountAgentcore({
-        signal: closed.signal,
         agent,
         stateRoot,
-        schedules: scheduled.schedules,
+        routines: scheduled.routines,
         onStateReady: options.onStateReady,
         channels: lazyChannels,
     });
-    const handler = router(adapterRoutes, withControl.mounts);
+    // SELF-VERIFYING, not unverified: both paths are reached only through `InvokeAgentRuntime`, which AWS gates with
+    // IAM. Putting them in the other table applied our JSON body gate to `POST /invocations` (whose content type is
+    // AWS's to set) and reported two IAM-protected paths as authenticating nobody.
+    const handler = router({ selfVerifying: adapterRoutes });
     log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     return {
         handler,
         agent,
-        // The adapter IS the surface here; the channel routes arrive lazily BEHIND it. Reporting `{}`
-        // would make the startup line claim nothing is served.
+        // The adapter IS the surface here; the channel routes arrive lazily BEHIND it.
         routes: adapterRoutes,
         agentDir,
         workspace,
-        // Unknown at boot by design — a channel list here would be the pre-restore emptiness.
-        channels: { routes: [], longConnections: [], builtinInvoke: false },
-        schedules: scheduled.schedules,
+        // Channels remain lazy until the adapter receives trusted ingress.
+        channels: { routes: [], longConnections: [] },
+        // NONE: the adapter's two paths are IAM-gated and the channels behind them verify their own platform.
+        unverifiedRoutes: [],
+        // No `controlPrefix`: it is not served here, so nothing may report a prefix a caller could dial.
+        routines: scheduled.routines,
         ready: Promise.resolve(), // nothing to open: no port of our own, no resident connections
-        ...(withControl.control ? { control: withControl.control } : {}),
         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();
         },
     };
 }
 /**
- * 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.
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) — the deployed container's ONLY reachable
+ * surface (channels/agentcore.ts).
  */
 export function mountAgentcore(options) {
-    const { agent, stateRoot, schedules, onStateReady, channels, signal } = options;
+    const { agent, stateRoot, routines, onStateReady, channels } = options;
+    // OCCURRENCE SEMANTICS, because this host's clock is ours: `deploy` wrote the EventBridge rule and the forwarder
+    // relays its instant behind the ingress secret, so the slot is a real grid point of that schedule and a claim
+    // means something (dedup across redeliveries, a fire history, the overlap policy). `POST /run` — the
+    // unauthenticated API — is NOT this and is not served here at all.
+    const fireRoutine = async (name, occurrence) => {
+        const routine = routines.find((r) => r.name === name);
+        if (!routine)
+            return unknownRoutine(name, routines);
+        const outcome = await Effect.runPromise(fireRoutineOnce({ agent, stateRoot, routine, slot: occurrence }).pipe(Effect.mapError((e) => e.cause))).catch((cause) => {
+            // `fireRoutineOnce`'s only failure is a claim-state fault, which happens BEFORE any claim exists — the
+            // occurrence is unburned, so the forwarder's throw makes EventBridge retry it, which is the right answer.
+            log.error(`[schedule] firing "${name}" for ${occurrence.toISOString()} failed: ${String(cause)}`);
+            return undefined;
+        });
+        if (outcome === undefined) {
+            return text(`routine "${name}": claim state unavailable, nothing was claimed — retry\n`, 500);
+        }
+        return Response.json({ slot: occurrence.toISOString(), ...outcome });
+    };
+    // BY NAME, on the IAM door. `POST /run`'s contract, through the only ingress this host has for a caller AWS has
+    // already identified — which makes it stricter here than the anonymous route other hosts publish. A routine
+    // without a cron is reachable ONLY this way on this host, and that is the point: nothing is unreachable.
+    const runRoutine = async (name) => {
+        const routine = routines.find((r) => r.name === name);
+        if (!routine)
+            return unknownRoutine(name, routines);
+        return Response.json(await runRoutineByName(agent, routine));
+    };
     return agentcoreRoutes({
         channels,
         agent,
         stateRoot,
         isBusy: () => activeWork() > 0,
-        // Cross-deploy durability: AgentCore wipes the state mount on every runtime version update, so
-        // the state root is restored from (and pushed to) an S3 snapshot through presigned URLs the
-        // forwarder mints per envelope. Always wired on this path — the platform gives no other way to
-        // keep an agent's memory across a deploy.
-        stateSync: createStateSync({ stateRoot }),
-        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call. Absent =
-        // no forwarder in this topology, so only the public `invoke` kind is servable.
+        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call.
         ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
         onStateReady,
-        ...(signal ? { signal } : {}),
-        fire: schedules.length === 0
-            ? undefined
-            : (name, slot) => {
-                const schedule = schedules.find((s) => s.name === name);
-                if (!schedule)
-                    throw new UnknownScheduleError(name);
-                return fireScheduleOnce({ agent, stateRoot, schedule, slot });
-            },
+        ...(routines.length > 0 ? { fireRoutine, runRoutine } : {}),
     });
 }