@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/channels/agentcore-service.js

@@ -1,13 +1,15 @@
 import { fromForwarder } from "./agentcore-protocol.js";
 import { log } from "../log.js";
-import { loadServingRoutines, routesFor, startSchedules } from "../service.js";
+import { routesFor, serviceOver, 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 { fireScheduleOnce } from "../schedule/scheduler.js";
+import { nextRun } from "../schedule/cron.js";
+import { createWakeAlarmSink } from "../schedule/wake-alarm.js";
+import { setWakeupsSink } from "../schedule/wakeups.js";
 import { text } from "./respond.js";
 import { activeWork, beginWork } from "./busy.js";
-import { router } from "./serve.js";
+import { router } from "./router.js";
 import { readBodyCapped } from "./body.js";
 import { MAX_ENVELOPE_BYTES } from "./agentcore-limits.js";
 /**
@@ -29,7 +31,7 @@ export function deferAgentcoreService(stages) {
                 throw error;
             });
             const taken = await prepared;
-            // Shutdown may have arrived while the workspace was being taken.
+            // Shutdown may have arrived while the storage was being taken.
             if (closed)
                 throw new Error("service closed during initialization");
             assembling ??= stages.assemble(taken);
@@ -40,128 +42,92 @@ export function deferAgentcoreService(stages) {
             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 });
-                    }
+    const handler = async (request) => {
+        if (closed)
+            return new Response("service closed\n", { status: 503 });
+        if (service)
+            return service.fetch(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;
-        },
+            return new Response(`${message}\n`, { status: 503 });
+        }
+        if (closed)
+            return new Response("service closed\n", { status: 503 });
+        return ready.fetch(request);
     };
+    // Nothing to wait for before the first envelope: the definition opens on it.
+    return serviceOver(handler, Promise.resolve(), () => {
+        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;
-    // 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 and attaches the
-    // ingress secret ITSELF (deploy/agentcore/forwarder.js), so every anonymous caller arrives as trusted ingress. A
-    // channel route survives that because it checks its platform's signature; `/control/*` has no such check.
-    //
-    // The recipe if it is ever wanted: a `kind: "control"` envelope on the IAM-gated `InvokeAgentRuntime`, which the
-    // forwarder never emits (the way `kind: "invoke"` runs a turn without the ingress secret). The envelope is
-    // request/response with a buffered body, so the long-lived `GET /control/sessions/{id}/events` stream a client
-    // renders from could not ride it.
+export async function mountAgentcoreService(opened) {
+    const { agent, agentDir, stateRoot, schedules } = opened;
+    // The only public way in is the forwarder's Function URL, which relays an arbitrary `rawPath` verbatim as a webhook
+    // envelope and attaches the ingress secret ITSELF (deploy/agentcore/forwarder.js), so every anonymous caller arrives
+    // as trusted ingress. A channel route survives that because it checks its platform's signature.
     //
-    // Every config key that cannot mean anything on this host says so: silence is how an operator concludes a setting
-    // took effect.
-    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 });
+    // Started here, not deferred to an envelope. No resident timers: each instant arrives as its own fire from the
+    // recurring schedule the container sets (`armAlarms`), ONE path per instant, so the reply to that delivery says
+    // whether it ran. The clock still pumps wake-ups; a redelivered fire claims its slot once.
+    const mirror = armAlarms(stateRoot, () => schedules);
+    const scheduled = startSchedules(agent, stateRoot, schedules, { localClock: false });
     const lazyChannels = async () => {
-        const lazy = await routesFor(agentDir, agent, stateRoot, sessionControl, { http: { invoke: false } });
+        const lazy = routesFor(agent, stateRoot, opened.channels);
         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`);
         }
-        // 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 };
+        return { routes: lazy.routes };
     };
     const adapterRoutes = mountAgentcore({
         agent,
         stateRoot,
-        routines: scheduled.routines,
-        onStateReady: options.onStateReady,
+        schedules: () => schedules,
+        ...(mirror ? { onStateReady: mirror } : {}),
         channels: lazyChannels,
     });
-    // 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 });
+    const handler = router(adapterRoutes);
     log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     return {
-        handler,
-        agent,
+        // Nothing to open: no port of its own, no resident connections.
+        ...serviceOver(handler, Promise.resolve(), async () => scheduled.stop()),
         // The adapter IS the surface here; the channel routes arrive lazily BEHIND it.
         routes: adapterRoutes,
         agentDir,
-        workspace,
         // 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
-        async close() {
-            scheduled.stop();
-        },
+        schedules,
+        // Reached only through /invocations here (SPEC.md §9.5).
+        api: false,
     };
 }
 /**
@@ -169,43 +135,58 @@ export async function mountAgentcoreService(opened, options = {}) {
  * surface (channels/agentcore.ts).
  */
 export function mountAgentcore(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
+    const { agent, stateRoot, schedules, onStateReady, channels } = options;
+    // OCCURRENCE SEMANTICS, because this host's clock is ours: the container set the recurring schedule that names this
+    // instant and the forwarder relays it behind the ingress secret, so a claim means something (dedup across
+    // EventBridge's redeliveries, a fire history, the overlap policy).
+    const fireSchedule = async (name, occurrence) => {
+        const schedule = schedules().find((s) => s.name === name);
+        // EventBridge can fire what a release has not reached yet (a mirror still in flight, or one that failed): a fire
+        // for a schedule since removed, or for an instant its cron no longer has, is answered as skipped, not run — and not
+        // as an error the forwarder would make EventBridge retry.
+        const skip = (why) => {
+            log.info(`[schedule] ${name}: alarm for ${occurrence.toISOString()} skipped — ${why}`);
+            return Response.json({ slot: occurrence.toISOString(), fired: false, skippedReason: why, ms: 0 });
+        };
+        if (!schedule)
+            return skip("no such schedule any more");
+        if (nextRun(schedule.cron, schedule.tz, new Date(occurrence.getTime() - 1))?.getTime() !== occurrence.getTime()) {
+            return skip(`not an instant of its cron "${schedule.cron}" any more`);
+        }
+        const outcome = await Effect.runPromise(fireScheduleOnce({ agent, stateRoot, schedule, slot: occurrence }).pipe(Effect.mapError((e) => e.cause))).catch((cause) => {
+            // `fireScheduleOnce`'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 text(`schedule "${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,
         // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call.
         ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
         onStateReady,
-        ...(routines.length > 0 ? { fireRoutine, runRoutine } : {}),
+        fireSchedule,
     });
 }
+/**
+ * The alarm mirror: each schedule as a recurring EventBridge schedule and each pending wake-up as a one-shot one, set
+ * by the forwarder (schedule/wake-alarm.ts), so a container AgentCore reclaimed is woken for them. Installed BEFORE the
+ * clock starts: the first wake poll may advance a recurring entry, and that save must already re-arm its alarm.
+ * Without the wake secret there is no way to set one, which is said.
+ */
+function armAlarms(stateRoot, schedules) {
+    const secret = process.env.FASTAGENT_WAKE_SECRET;
+    if (!secret) {
+        log.warn("[fastagent] FASTAGENT_WAKE_SECRET is missing; wake-ups and schedules cannot wake a reclaimed container");
+        return undefined;
+    }
+    const sink = Effect.runSync(createWakeAlarmSink({ secret, schedules }));
+    setWakeupsSink(sink);
+    return () => sink(stateRoot);
+}

package/dist/channels/agentcore.d.ts

@@ -1,4 +1,3 @@
-import type { Agent } from "../agent.ts";
 import type { ChannelHandler, Routes } from "../channel.ts";
 /**
  * What the lazy factory hands back: the CHANNELS' routes, and nothing else.
@@ -8,10 +7,8 @@ import type { ChannelHandler, Routes } from "../channel.ts";
  * so behind THIS door an anonymous caller and an IAM one are the same thing. A channel route survives that because
  * it verifies the platform's signature inside itself; nothing fastagent serves does.
  *
- * The other door is the Runtime's own, IAM-gated: the forwarder emits only `webhook`, `routine-fire`, `wake-poke`
- * and `probe`, so any other KIND can only come from a direct `InvokeAgentRuntime` call. That is what lets
- * `kind: "invoke"` run a turn here with no ingress secret, and it is where anything else that needs a real caller
- * identity belongs.
+ * The other door is the Runtime's own, IAM-gated: a direct `InvokeAgentRuntime` call, which carries no ingress
+ * secret, and which this container answers only with a `probe`.
  */
 export interface RouteSurface {
     routes: Routes;
@@ -19,32 +16,19 @@ export interface RouteSurface {
 export interface AgentcoreAdapterOptions {
     /** The channel surface. */
     channels: () => Promise<RouteSurface> | RouteSurface;
-    agent: Agent;
     /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
     stateRoot: string;
     /** Process-wide background-work signal (busy.ts `activeWork() > 0`) — injected for tests. */
     isBusy: () => boolean;
     /**
-     * Fire ONE declared schedule for the occurrence EventBridge named — the claim/run/settle the resident clock uses,
-     * not the `POST /run` API.
+     * Fire ONE declared schedule for the occurrence EventBridge named — the claim/run/settle the resident clock uses.
      *
-     * THIS IS WHERE OCCURRENCE SEMANTICS LIVE ON THIS HOST, and it is separate from that route on purpose. `deploy`
-     * wrote the rule, injected `<aws.scheduler.scheduled-time>` and the forwarder relays it behind the ingress
-     * secret, so this caller is one we produced and authenticated: the instant it names really is a grid point of
-     * that schedule, which is what makes a claim (and therefore dedup across EventBridge's redeliveries, a fire
-     * history and the overlap policy) mean anything. `POST /run` has none of that — it is an unauthenticated API
-     * whose caller cannot be told which occurrence it means, so it does not pretend to (schedule/run.ts).
-     *
-     * Undefined when the definition declares no schedules.
-     */
-    fireRoutine?: (name: string, occurrence: Date) => Promise<Response>;
-    /**
-     * Run a declared routine BY NAME — the `POST /run` contract, for the host that publishes no routes.
-     *
-     * Undefined when the definition declares none. Note what this does NOT do: no occurrence, no claim, no fire
-     * history. Those belong to {@link fireRoutine}, whose caller is a clock we wrote.
+     * The container set the recurring schedule that names this instant and the forwarder relays it behind the ingress
+     * secret, so this caller is one we produced and authenticated, which is what makes a claim (and therefore dedup
+     * across EventBridge's redeliveries, a fire history and the overlap policy) mean anything. Always present: a
+     * schedule can be added while the container runs, and a fire for one since removed is answered by it, as skipped.
      */
-    runRoutine?: (name: string) => Promise<Response>;
+    fireSchedule: (name: string, occurrence: Date) => Promise<Response>;
     /** FASTAGENT_INGRESS_SECRET: what makes an envelope the FORWARDER's rather than any IAM principal's. */
     ingressSecret?: string;
     /** Runs once on activation, after accepting the current forwarder callback URL. */

package/dist/channels/agentcore.js

@@ -1,14 +1,14 @@
-/** AWS AgentCore Runtime adapter: serve fastagent's whole HTTP surface through the Runtime's service contract. */
+/** AWS AgentCore Runtime adapter: serve the channels, the schedules' fires and the wake pokes through the Runtime's service contract. */
 import { Buffer } from "node:buffer";
 import * as Effect from "effect/Effect";
 import { PortFailure, portJoin } from "../effect-port.js";
-import { ENVELOPE_KINDS, fromForwarder } from "./agentcore-protocol.js";
+import { ENVELOPE_KINDS, fromForwarder, } from "./agentcore-protocol.js";
 import { beginWork } from "./busy.js";
-import { router } from "../channels/serve.js";
+import { router } from "../channels/router.js";
 import { log } from "../log.js";
+import { once } from "../once.js";
 import { rememberWakeAlarmUrl } from "../schedule/wake-alarm.js";
 import { readBodyCapped } from "./body.js";
-import { createInvokeHandler } from "./http.js";
 import { text } from "./respond.js";
 import { MAX_ENVELOPE_BYTES, MAX_WEBHOOK_BODY_BYTES } from "./agentcore-limits.js";
 const jsonHeaders = { "content-type": "application/json" };
@@ -18,18 +18,13 @@ const json = (body, status) => new Response(`${JSON.stringify(body)}\n`, { statu
  */
 function createActivation(deps) {
     const { stateRoot, onStateReady } = deps;
-    // UNINTERRUPTIBLE, because the outcome is CACHED: `Effect.cached` memoizes whatever exit it sees,
-    // interruption included. A once-per-process activation that remembered "interrupted" would answer
-    // every later envelope with an empty cause instead of the success or the diagnosable failure this
-    // block promises. Both are already unreachable (no caller passes a signal), which is exactly why
-    // the invariant has to be written down rather than relied on.
-    const stateReady = Effect.runSync(Effect.cached(portJoin(async () => {
+    const stateReady = once(portJoin(async () => {
         onStateReady?.();
-    }).pipe(Effect.uninterruptible)));
-    const channels = Effect.runSync(Effect.cached(portJoin(async () => {
+    }));
+    const channels = once(portJoin(async () => {
         const surface = await deps.channels();
-        return router({ selfVerifying: surface.routes });
-    }).pipe(Effect.uninterruptible)));
+        return router(surface.routes);
+    }));
     return {
         prepare: (envelope) => Effect.gen(function* () {
             // Use the current callback URL rather than the one persisted by an earlier deployment.
@@ -46,9 +41,19 @@ function createActivation(deps) {
     };
 }
 export function agentcoreRoutes(options) {
-    const { channels, agent, stateRoot, isBusy, fireRoutine, runRoutine, ingressSecret, onStateReady } = options;
+    const { channels, stateRoot, isBusy, fireSchedule, ingressSecret, onStateReady } = options;
     const activation = createActivation({ stateRoot, onStateReady, channels });
-    const invokeHandler = createInvokeHandler(agent);
+    const carried = (request) => {
+        const { method, path, query, headers, bodyB64 } = request;
+        return new Request(`http://agentcore.local${path}${typeof query === "string" && query !== "" ? `?${query}` : ""}`, {
+            method,
+            headers: headers ?? {},
+            body: typeof bodyB64 === "string" && method !== "GET" && method !== "HEAD"
+                ? Buffer.from(bodyB64, "base64")
+                : undefined,
+        });
+    };
+    const malformed = (request) => typeof request.method !== "string" || typeof request.path !== "string" || !request.path.startsWith("/");
     const handleInvocation = async (req) => {
         const body = await readBodyCapped(req, MAX_ENVELOPE_BYTES);
         if ("tooLarge" in body)
@@ -66,10 +71,10 @@ export function agentcoreRoutes(options) {
         // The forwarder, or another IAM principal? See `fromForwarder` for what that actually decides.
         const trusted = fromForwarder(envelope, ingressSecret);
         if (!trusted) {
-            // The IAM door's kinds: AWS authenticated this caller, so no ingress secret is expected or wanted. A `probe`
-            // here only opens the workspace (the deferred wrapper did that before this line) and says so: it is how
-            // `login --deployment` gets a workspace to log in, after a reset, on a runtime nothing has invoked yet.
-            if (envelope.kind !== "invoke" && envelope.kind !== "routine-run" && envelope.kind !== "probe") {
+            // The IAM door's one kind: AWS authenticated this caller, so no ingress secret is expected or wanted. A `probe`
+            // here only opens the deployed definition (the deferred wrapper did that before this line) and says so: it is
+            // how `login --deployment` gets a definition to log in, after a reset, on a runtime nothing has invoked yet.
+            if (envelope.kind !== "probe") {
                 log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
                 return text("forbidden\n", 403);
             }
@@ -87,10 +92,9 @@ export function agentcoreRoutes(options) {
                 return json({ ok: false, error: `activation failed: ${String(e)}` }, 200);
             return text(`activation failed: ${String(e)}\n`, 503);
         }
-        // Public invokes do not activate channels.
         let constructionError;
         let dispatch;
-        if (trusted && envelope.kind !== "invoke") {
+        if (trusted) {
             try {
                 dispatch = await Effect.runPromise(activation.channels.pipe(Effect.mapError((error) => error.cause)));
             }
@@ -101,10 +105,9 @@ export function agentcoreRoutes(options) {
         }
         switch (envelope.kind) {
             case "webhook": {
-                const { method, path, query, headers, bodyB64 } = envelope;
-                if (typeof method !== "string" || typeof path !== "string" || !path.startsWith("/")) {
+                const { bodyB64 } = envelope;
+                if (malformed(envelope))
                     return text('webhook envelope needs { "method": string, "path": "/..." }\n', 400);
-                }
                 if (typeof bodyB64 === "string" && Buffer.byteLength(bodyB64, "base64") > MAX_WEBHOOK_BODY_BYTES) {
                     return json({
                         status: 413,
@@ -112,13 +115,7 @@ export function agentcoreRoutes(options) {
                         bodyB64: Buffer.from("payload too large\n").toString("base64"),
                     }, 200);
                 }
-                const inner = new Request(`http://agentcore.local${path}${typeof query === "string" && query !== "" ? `?${query}` : ""}`, {
-                    method,
-                    headers: headers ?? {},
-                    body: typeof bodyB64 === "string" && method !== "GET" && method !== "HEAD"
-                        ? Buffer.from(bodyB64, "base64")
-                        : undefined,
-                });
+                const inner = carried(envelope);
                 // A construction failure is the request's failure (503 through the forwarder, so the platform retries and the
                 // operator sees the message), never a silently-empty channel.
                 if (!dispatch)
@@ -138,36 +135,16 @@ export function agentcoreRoutes(options) {
                 };
                 return json(reply, 200);
             }
-            case "routine-fire": {
+            case "schedule-fire": {
                 const { name, occurrence } = envelope;
                 if (typeof name !== "string" || typeof occurrence !== "string" || Number.isNaN(Date.parse(occurrence))) {
-                    return text('routine-fire envelope needs { "name": string, "occurrence": ISO-date }\n', 400);
+                    return text('schedule-fire envelope needs { "name": string, "occurrence": ISO-date }\n', 400);
                 }
-                // No schedules in this definition: nothing to fire, and no rule should have survived a deploy that removed
-                // them either.
-                if (!fireRoutine)
-                    return text(`no routines in this deployment (routine-fire "${name}")\n`, 404);
                 // The whole agent turn runs inside this request — but the CALLER (the forwarder Lambda) may time out and drop
                 // the connection while the turn keeps running server-side.
                 const workDone = beginWork();
                 try {
-                    return await fireRoutine(name, new Date(occurrence));
-                }
-                finally {
-                    workDone();
-                }
-            }
-            case "routine-run": {
-                const { name } = envelope;
-                if (typeof name !== "string" || name === "") {
-                    return text('routine-run envelope needs { "name": string }\n', 400);
-                }
-                if (!runRoutine)
-                    return text(`no routines in this deployment (routine-run "${name}")\n`, 404);
-                // The whole agent turn runs inside this request; the caller may time out while it keeps running.
-                const workDone = beginWork();
-                try {
-                    return await runRoutine(name);
+                    return await fireSchedule(name, new Date(occurrence));
                 }
                 finally {
                     workDone();
@@ -187,16 +164,6 @@ export function agentcoreRoutes(options) {
                     ? { ok: true }
                     : { ok: false, error: `channel construction failed: ${constructionError}` }, 200);
             }
-            case "invoke": {
-                // Reuse the HTTP channel's handler wholesale (SSE, cancellation, backpressure) by handing it the shape it
-                // already validates — one protocol, one implementation.
-                const inner = new Request("http://agentcore.local/invoke", {
-                    method: "POST",
-                    headers: jsonHeaders,
-                    body: JSON.stringify({ session: envelope.session, text: envelope.text }),
-                });
-                return invokeHandler(inner);
-            }
             default:
                 return text(`unknown envelope kind "${envelope.kind}"\n`, 400);
         }

package/dist/channels/body.d.ts

@@ -1,19 +1,3 @@
-/**
- * Refuse a request to one of OUR routes that does not declare a JSON body — `undefined` when it does.
- *
- * This is what makes "a foreign origin simply gets no CORS headers" safe. Withholding the headers stops a page from
- * READING the reply; it does not stop the request. A cross-origin POST carrying `text/plain` (or a form's
- * `multipart/form-data`) is a CORS *simple request*: no preflight, sent regardless, and the turn it asks for runs.
- * Demanding `application/json` takes the request out of that class, so the browser must preflight it — and a
- * preflight we do not answer is a request that is never sent.
- *
- * Asked of the ROUTE, never of "does this have a body": the control plane reads an empty body as `{}`, so a
- * body-less POST would otherwise walk straight through the gate.
- *
- * NOT applied to channel routes. Their caller is a platform's server with its own content types (Slack posts
- * `application/x-www-form-urlencoded` for some payloads) and its own signature check, and a page cannot forge that.
- */
-export declare function refuseNonJsonBody(req: Request): Response | undefined;
 /** Read a request body with a hard byte cap (real bytes). */
 export declare function readBodyCapped(req: Request, max: number): Promise<{
     text: string;

package/dist/channels/body.js

@@ -1,28 +1,3 @@
-import { text } from "./respond.js";
-/**
- * Refuse a request to one of OUR routes that does not declare a JSON body — `undefined` when it does.
- *
- * This is what makes "a foreign origin simply gets no CORS headers" safe. Withholding the headers stops a page from
- * READING the reply; it does not stop the request. A cross-origin POST carrying `text/plain` (or a form's
- * `multipart/form-data`) is a CORS *simple request*: no preflight, sent regardless, and the turn it asks for runs.
- * Demanding `application/json` takes the request out of that class, so the browser must preflight it — and a
- * preflight we do not answer is a request that is never sent.
- *
- * Asked of the ROUTE, never of "does this have a body": the control plane reads an empty body as `{}`, so a
- * body-less POST would otherwise walk straight through the gate.
- *
- * NOT applied to channel routes. Their caller is a platform's server with its own content types (Slack posts
- * `application/x-www-form-urlencoded` for some payloads) and its own signature check, and a page cannot forge that.
- */
-export function refuseNonJsonBody(req) {
-    // Parameters are part of the header (`application/json; charset=utf-8`), so compare the media type alone.
-    const mediaType = (req.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
-    if (mediaType === "application/json")
-        return undefined;
-    // Says what is required, and does not echo what arrived: reflecting a request header into a response body is a
-    // habit worth not having, and the sender already knows what they sent.
-    return text("content-type must be application/json\n", 415);
-}
 /** Read a request body with a hard byte cap (real bytes). */
 export async function readBodyCapped(req, max) {
     if (!req.body)

package/dist/channels/busy.js

@@ -1,4 +1,9 @@
-/** Webhooks ACK before background turns finish, so open requests cannot determine runtime idleness. */
+/**
+ * The process's work in flight: every message not yet settled (counted by the Agent, pi-durable/agent.ts), and the
+ * channel, schedule and AgentCore work that has not reached an accepted message yet. Webhooks ACK before their turns
+ * finish, so open requests cannot tell whether the process is idle; this can. Read by AgentCore's `/ping` and by
+ * `dev`'s restart.
+ */
 let inFlight = 0;
 /** Mark background work as started. */
 export function beginWork() {

package/dist/channels/context.d.ts

@@ -0,0 +1,4 @@
+import type { Agent } from "../agent-api.ts";
+import type { ChannelContext } from "../channel.ts";
+/** The context of the channel `name` (its file's name under `src/channels/`), its state under `stateRoot`. */
+export declare function channelContext(agent: Agent, stateRoot: string, name: string): ChannelContext;