@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/channels/agentcore.d.ts

@@ -1,48 +1,54 @@
 import type { Agent } from "../agent.ts";
-import type { StateSync } from "./agentcore-state.ts";
-import type { Routes } from "../channel.ts";
-import { type PrefixMount } from "../channels/serve.ts";
-import type { ScheduleFireOutcome } from "../schedule/scheduler.ts";
-/** What the lazy factory hands back: literal routes plus any prefix-owning mounts (the control
- *  plane), so the adapter's INNER dispatch is assembled exactly like a direct host's. */
+import type { ChannelHandler, Routes } from "../channel.ts";
+/**
+ * What the lazy factory hands back: the CHANNELS' routes, and nothing else.
+ *
+ * Deliberately not "the whole inner surface". Every request that reaches this dispatcher arrived through the
+ * forwarder's public Function URL, which relays an arbitrary path verbatim and supplies the ingress secret itself —
+ * 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.
+ */
 export interface RouteSurface {
     routes: Routes;
-    mounts?: readonly PrefixMount[];
 }
 export interface AgentcoreAdapterOptions {
-    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health),
-     *  built LAZILY: channel construction loads channel state and replays durable turn intent, so on
-     *  AgentCore it must not run until the state root is authoritative — which happens at the first
-     *  envelope's `stateSync.ready()` (the restore URLs only an envelope carries), never at boot, where
-     *  the mount is pre-restore (empty after every version update). A factory, not a value: there is no
-     *  moment during construction at which the right answer is knowable. May answer synchronously — the
-     *  resolution chain normalizes it either way. */
+    /** 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;
-    /** Slot-idempotent schedule fire ({@link fireScheduleOnce} bound to this workspace's schedules);
-     *  undefined when the workspace has none — a schedule-fire envelope then 404s (deploy drift: an
-     *  external clock still firing for a schedule this definition no longer has). */
-    fire?: (name: string, slot: Date) => Promise<ScheduleFireOutcome>;
-    /** Cross-deploy state durability (agentcore-state.ts). Absent = the state root is local-only,
-     *  which on AgentCore means it is erased by the next deploy — the serving path always wires it. */
-    stateSync?: StateSync;
-    /** FASTAGENT_INGRESS_SECRET: what makes an envelope the FORWARDER's rather than any IAM principal's.
-     *  Undefined = nothing can be trusted, so only the public `invoke` kind is served. */
+    /**
+     * Fire ONE declared schedule for the occurrence EventBridge named — the claim/run/settle the resident clock uses,
+     * not the `POST /run` API.
+     *
+     * 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.
+     */
+    runRoutine?: (name: string) => Promise<Response>;
+    /** FASTAGENT_INGRESS_SECRET: what makes an envelope the FORWARDER's rather than any IAM principal's. */
     ingressSecret?: string;
-    /** Cancels the adapter's process-global registrations. Without it a closed adapter keeps saving
-     *  state on every later idle edge — including work belonging to whatever mounted after it. */
-    signal?: AbortSignal;
-    /** Runs ONCE, after the state root is authoritative (post-restore) — the wake-alarm reconcile, which
-     *  at boot would see the mount the platform just wiped and conclude there is nothing pending. */
+    /** Runs once on activation, after accepting the current forwarder callback URL. */
     onStateReady?: () => void;
 }
 export declare function agentcoreRoutes(options: AgentcoreAdapterOptions): Routes;
-/** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does
- *  not have — the adapter maps it to 404 (deploy drift stays visible in the external clock's logs). */
-export declare class UnknownScheduleError extends Error {
-    constructor(name: string);
-}
+export declare function agentcorePing(isBusy: () => boolean): ChannelHandler;

package/dist/channels/agentcore.js

@@ -1,124 +1,54 @@
-/**
- * AWS AgentCore Runtime adapter: serve fastagent's whole HTTP surface through the Runtime's service
- * contract. AgentCore gives a container exactly TWO paths — `POST /invocations` (the only ingress,
- * reached via the SigV4 `InvokeAgentRuntime` API) and `GET /ping` (health) — and no public URL, so
- * the deployment fronts webhooks with a thin forwarder Lambda and delivers cron slots from
- * EventBridge Scheduler; both arrive here as an ENVELOPE in the /invocations payload:
- *
- *  - `{ kind: "webhook", method, path, headers?, bodyB64? }` — a verbatim webhook request captured
- *    by the forwarder. Reconstructed into a real `Request` and dispatched to the SAME channel routes
- *    a direct deployment serves — signature verification (Telegram secret token, Feishu signatures)
- *    runs unchanged inside the channel. The channel's HTTP response travels back INSIDE the
- *    transport reply (`{ status, headers, bodyB64 }`, transport always 200): AgentCore folds a
- *    container non-2xx into its own 424 RuntimeClientError, so riding the real status inside the
- *    envelope is the only way the forwarder can re-emit it verbatim (a Feishu URL-verification
- *    challenge needs the exact body + content-type back).
- *  - `{ kind: "schedule-fire", name, slot }` — one cron instant from the external clock. Dispatched
- *    to {@link fireScheduleOnce}-shaped `fire` with the slot as the idempotency key (EventBridge
- *    delivery is at-least-once; a duplicate slot must not double-fire).
- *  - `{ kind: "invoke", session, text }` — the programmatic data plane; streams the invoke back as
- *    SSE (AgentCore's streaming response form), reusing the HTTP channel's handler wholesale.
- *
- * `/ping` reports `HealthyBusy` (+ `time_of_last_update`, required — see the handler) while
- * process-wide background work is in flight (busy.ts) — webhook
- * channels ACK fast and run turns fire-and-forget, and AgentCore ends an idle session, so without
- * this signal a long turn would be killed mid-flight right after its ACK. `Healthy` when idle lets
- * the platform reclaim the microVM (that idle-to-zero IS the point of this deployment).
- */
+/** AWS AgentCore Runtime adapter: serve fastagent's whole HTTP surface through the Runtime's service contract. */
 import { Buffer } from "node:buffer";
-import { ENVELOPE_KINDS } from "./agentcore-protocol.js";
-import { beginWork, onIdle } from "./busy.js";
+import * as Effect from "effect/Effect";
+import { PortFailure, portJoin } from "../effect-port.js";
+import { ENVELOPE_KINDS, fromForwarder } from "./agentcore-protocol.js";
+import { beginWork } from "./busy.js";
 import { router } from "../channels/serve.js";
 import { log } from "../log.js";
 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 });
 /**
- * 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.
- */
-/**
- * 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.
+ * Channel construction may already have replayed work before failing; cache either outcome to avoid replaying twice.
  */
 function createActivation(deps) {
-    const { stateSync, stateRoot, onStateReady } = deps;
-    let warnedUnsnapshotted = false;
-    let stateReadyFired = false;
-    let dispatchP;
+    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 () => {
+        onStateReady?.();
+    }).pipe(Effect.uninterruptible)));
+    const channels = Effect.runSync(Effect.cached(portJoin(async () => {
+        const surface = await deps.channels();
+        return router({ selfVerifying: surface.routes });
+    }).pipe(Effect.uninterruptible)));
     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.
+        prepare: (envelope) => Effect.gen(function* () {
+            // Use the current callback URL rather than the one persisted by an earlier deployment.
             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"
+                const url = envelope.wake.url;
+                yield* Effect.try({
+                    try: () => rememberWakeAlarmUrl(stateRoot, url),
+                    catch: (cause) => new PortFailure(cause),
+                });
             }
-            return dispatchP;
-        },
+            yield* stateReady;
+        }),
+        channels,
     };
 }
 export function agentcoreRoutes(options) {
-    const { channels, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
-    const activation = createActivation({ stateSync, stateRoot, onStateReady, channels });
+    const { channels, agent, stateRoot, isBusy, fireRoutine, runRoutine, ingressSecret, onStateReady } = options;
+    const activation = createActivation({ 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.
-    if (stateSync) {
-        const off = onIdle(() => stateSync.save());
-        options.signal?.addEventListener("abort", off, { once: true });
-    }
     const handleInvocation = async (req) => {
         const body = await readBodyCapped(req, MAX_ENVELOPE_BYTES);
         if ("tooLarge" in body)
@@ -133,49 +63,34 @@ export function agentcoreRoutes(options) {
         if (envelope === null || typeof envelope !== "object" || typeof envelope.kind !== "string") {
             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
-        // forwarder's; anything else is the PUBLIC data plane, which may run exactly one kind (`invoke`)
-        // 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 = secretEquals(envelope.auth, ingressSecret);
+        // The forwarder, or another IAM principal? See `fromForwarder` for what that actually decides.
+        const trusted = fromForwarder(envelope, ingressSecret);
         if (!trusted) {
-            if (envelope.kind !== "invoke") {
+            // The IAM door's kinds: AWS authenticated this caller, so no ingress secret is expected or wanted.
+            if (envelope.kind !== "invoke" && envelope.kind !== "routine-run") {
                 log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
                 return text("forbidden\n", 403);
             }
             envelope.wake = undefined;
-            envelope.state = undefined;
         }
-        // Cross-deploy state: the platform wipes /mnt/state on every version update, so the durable copy
-        // must be pulled back BEFORE anything reads it.
         try {
-            await activation.restore(envelope);
+            if (trusted)
+                await Effect.runPromise(activation.prepare(envelope).pipe(Effect.mapError((e) => e.cause)));
         }
         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.
+            log.error(`[agentcore] activation 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.
             if (envelope.kind === "probe")
-                return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
-            return text(`state restore failed: ${String(e)}\n`, 503);
+                return json({ ok: false, error: `activation failed: ${String(e)}` }, 200);
+            return text(`activation failed: ${String(e)}\n`, 503);
         }
-        // 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).
+        // Public invokes do not activate channels.
         let constructionError;
         let dispatch;
-        if (trusted && envelope.kind !== "checkpoint" && envelope.kind !== "invoke") {
+        if (trusted && envelope.kind !== "invoke") {
             try {
-                dispatch = await activation.channels();
+                dispatch = await Effect.runPromise(activation.channels.pipe(Effect.mapError((error) => error.cause)));
             }
             catch (e) {
                 constructionError = String(e);
@@ -202,13 +117,13 @@ export function agentcoreRoutes(options) {
                         ? Buffer.from(bodyB64, "base64")
                         : undefined,
                 });
-                // 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.
+                // 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)
                     return text(`channel construction failed: ${constructionError ?? "unavailable"}\n`, 503);
                 const response = await dispatch(inner);
-                // Buffer the channel's ACK (webhook ACKs are small by design — the turn itself runs
-                // fire-and-forget) and ride it inside the transport reply, byte-exact.
+                // Buffer the channel's ACK (webhook ACKs are small by design — the turn itself runs fire-and-forget) and ride
+                // it inside the transport reply, byte-exact.
                 const replyBody = Buffer.from(await response.arrayBuffer());
                 const replyHeaders = {};
                 response.headers.forEach((value, key) => {
@@ -221,73 +136,57 @@ export function agentcoreRoutes(options) {
                 };
                 return json(reply, 200);
             }
-            case "schedule-fire": {
-                const { name, slot } = envelope;
-                if (typeof name !== "string" || typeof slot !== "string" || Number.isNaN(Date.parse(slot))) {
-                    return text('schedule-fire envelope needs { "name": string, "slot": ISO-date }\n', 400);
+            case "routine-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);
                 }
-                // No fire capability (no schedules in this definition) or an unknown name is deploy drift —
-                // an external clock rule outliving the schedule it fired for. 404 keeps it VISIBLE in the
-                // clock's logs (a 200 would silently absorb every future fire).
-                if (!fire)
-                    return text(`no schedules in this deployment (schedule-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. Count it as
-                // in-flight work so /ping holds the session (HealthyBusy) for the remainder.
+                // 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 {
-                    const outcome = await fire(name, new Date(slot));
-                    return json(outcome, 200);
-                }
-                catch (e) {
-                    if (e instanceof UnknownScheduleError)
-                        return text(`${e.message}\n`, 404);
-                    // A claim-state fault (unreadable/unwritable fires.json) — surface it as the request's
-                    // failure so the external clock's logs carry it (fail visibly, never a silent absorb).
-                    log.error(`[agentcore] schedule-fire ${name} failed: ${String(e)}`);
-                    return text(`schedule-fire failed: ${String(e)}\n`, 500);
+                    return await fireRoutine(name, new Date(occurrence));
                 }
                 finally {
                     workDone();
                 }
             }
-            case "checkpoint": {
-                // Deliberately does NOT wait for idle: the durable turn intent is persisted BEFORE the
-                // webhook ACK (turn-store.ts), so a flush right now already carries the interrupted turn —
-                // and blocking a deploy on a turn that may run for minutes would be the worse trade.
-                if (!stateSync)
-                    return json({ written: false, reason: "no state sync in this deployment" }, 200);
+            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 {
-                    // The reply is the ONLY thing telling the operator whether an in-flight turn was
-                    // protected, so it reports what actually happened — `written: false` (nothing to write)
-                    // reads differently from `written: true`, and a failure is a failure.
-                    return json(await stateSync.checkpoint(), 200);
+                    return await runRoutine(name);
                 }
-                catch (e) {
-                    log.error(`[agentcore] checkpoint failed: ${String(e)}`);
-                    return text(`checkpoint failed: ${String(e)}\n`, 500);
+                finally {
+                    workDone();
                 }
             }
             case "wake-poke": {
-                // The poke's job is DONE by arriving: the invocation woke (or kept awake) the container, and
-                // the wake pump (boot drain + 30s poll) fires whatever is due. Nothing to dispatch — the
-                // initialization above already resolved construction (replaying checkpointed turn intent),
-                // and its failure is this request's failure so the alarm's log line names it.
+                // The poke's job is DONE by arriving: the invocation woke (or kept awake) the container, and the wake pump
+                // (boot drain + 30s poll) fires whatever is due.
                 if (constructionError !== undefined)
                     return text(`channel construction failed: ${constructionError}\n`, 503);
                 return json({ ok: true }, 200);
             }
             case "probe": {
-                // The structured verdict (transport-200 — see the envelope doc): the deploy driver reads it
-                // through the forwarder's reserved path, so the error text survives the hop that turns any
-                // non-200 transport into an opaque 502.
+                // The structured verdict (transport-200 — see the envelope doc).
                 return json(constructionError === undefined
                     ? { 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.
+                // 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,
@@ -299,53 +198,20 @@ export function agentcoreRoutes(options) {
                 return text(`unknown envelope kind "${envelope.kind}"\n`, 400);
         }
     };
-    // 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())
-            stateSync.save();
-        return response;
-    };
-    // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive
-    // (background turns in flight). `time_of_last_update` is REQUIRED for the keep-alive to work,
-    // despite the contract documenting it as optional ("If you omit the field, the platform tracks
-    // status changes on its own"): measured on a live Runtime (us-east-1, 2026-08-04), the platform's
-    // idle measurement reads ONLY this field — with it omitted, a session polling every ~2s and
-    // receiving HealthyBusy 200s was still reclaimed at exactly IdleRuntimeSessionTimeout after the
-    // last InvokeAgentRuntime, mid-turn, 2s after the last HealthyBusy answer; with the field present
-    // the same turn survived 3.5× the idle timeout with zero invocations and completed. The value
-    // updates ONLY on a real status change: a timestamp advancing on every ping declares a perpetual
-    // status change, so the idle timeout never fires and dead-idle sessions live to MaxLifetime
-    // (quota exhaustion — the failure mode the contract's warning describes).
+    return { "POST /invocations": handleInvocation, "GET /ping": agentcorePing(isBusy) };
+}
+export function agentcorePing(isBusy) {
+    // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive (background turns in
+    // flight).
     let lastStatus = "Healthy";
     let lastTransition = Math.floor(Date.now() / 1000);
-    return {
-        "POST /invocations": invocations,
-        "GET /ping": () => {
-            const status = isBusy() ? "HealthyBusy" : "Healthy";
-            if (status !== lastStatus) {
-                lastTransition = Math.floor(Date.now() / 1000);
-                log.debug(`[agentcore] ping status: ${lastStatus} → ${status}`);
-                lastStatus = status;
-            }
-            return json({ status, time_of_last_update: lastTransition }, 200);
-        },
+    return () => {
+        const status = isBusy() ? "HealthyBusy" : "Healthy";
+        if (status !== lastStatus) {
+            lastTransition = Math.floor(Date.now() / 1000);
+            log.debug(`[agentcore] ping status: ${lastStatus} → ${status}`);
+            lastStatus = status;
+        }
+        return json({ status, time_of_last_update: lastTransition }, 200);
     };
 }
-/** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does
- *  not have — the adapter maps it to 404 (deploy drift stays visible in the external clock's logs). */
-export class UnknownScheduleError extends Error {
-    constructor(name) {
-        super(`unknown schedule "${name}"`);
-        this.name = "UnknownScheduleError";
-    }
-}

package/dist/channels/body.d.ts

@@ -1,7 +1,20 @@
 /**
- * Read a request body with a hard byte cap (real bytes). A streaming cap is the only robust guard
- * against an unbounded body (Content-Length is bypassable with chunked encoding). Web-streams only.
+ * 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,7 +1,29 @@
+import { text } from "./respond.js";
 /**
- * Read a request body with a hard byte cap (real bytes). A streaming cap is the only robust guard
- * against an unbounded body (Content-Length is bypassable with chunked encoding). Web-streams only.
+ * 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)
         return { text: "" };

package/dist/channels/busy.d.ts

@@ -1,23 +1,3 @@
-/**
- * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
- * fire-and-forget on this process's event loop (serve.ts) — so "is this process busy?" is not
- * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
- * task-tracker side tasks) report here; a serving surface that must stay alive while background
- * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.
- *
- * Deliberately a counter, not a registry: consumers need only "any work in flight?"; keeping the
- * module dependency-free lets both channel primitives import it without cycles.
- */
-/**
- * Mark one unit of background work as started. Returns its completion callback — idempotent, so a
- * caller may safely settle it from multiple cleanup paths (finally + catch) without double-counting.
- */
+/** Mark background work as started. */
 export declare function beginWork(): () => void;
-/**
- * Subscribe to the 0-in-flight edge: the moment the process finishes its last background turn.
- * Returns an unsubscribe. Used by the AgentCore adapter to push its state snapshot exactly when the
- * state root has settled and before the platform may reclaim the idle microVM.
- */
-export declare function onIdle(listener: () => void): () => void;
-/** How many units of background work are currently in flight (0 = idle). */
 export declare function activeWork(): number;