@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/schedule/wake-alarm.js

@@ -1,16 +1,22 @@
 /**
- * Wake ALARMS for the AgentCore deployment: the piece that makes the agent's self-scheduled wake-ups (`wake`) reliable
- * on a host with NO resident process.
+ * ALARMS for the AgentCore deployment: what makes the agent's self-scheduled wake-ups (`wake`) and its schedules fire
+ * on a host with NO resident process. The container mirrors both through the forwarder into EventBridge Scheduler:
+ * - each schedule as a RECURRING cron schedule, which EventBridge fires on its own clock, the way AWS runs any
+ *   recurring job. Mirroring only creates, changes or deletes it; nothing has to happen after a fire for the next
+ *   one, so a failed mirror delays an edit, never stops a schedule. Because the container sets it, a schedule written
+ *   or edited while it runs takes effect without a deploy.
+ * - each pending wake-up as a one-shot schedule that deletes itself once it has poked the container.
  */
 import { readFileSync } from "node:fs";
 import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
 import { PortFailure, portError, portJoin, portRequest } from "../effect-port.js";
-import { RESERVED_PATHS } from "../channels/agentcore-protocol.js";
+import { RESERVED_PATHS, } from "../channels/agentcore-protocol.js";
 import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
 import { scheduleFile, writeScheduleFile } from "./state.js";
 import { listWakeups } from "./wakeups.js";
+import { toEventBridgeCron } from "./eventbridge-cron.js";
 const URL_FILE = "wake-alarm-url";
 /**
  * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on every turn, the
@@ -41,14 +47,39 @@ export function readWakeAlarmUrl(stateRoot) {
  */
 export const MAX_SYNC_ATTEMPTS = 5;
 const RETRY_BASE_MS = 2_000;
+/**
+ * After a whole sync gives up, how long until it is tried again, for as long as this process lives. Outside the busy
+ * count, so a container that is only waiting to retry can still be reclaimed; its next start mirrors again.
+ */
+export const HEAL_MS = 5 * 60_000;
 const SYNC_TIMEOUT_MS = 10_000;
 /** Alarms due within this margin are NOT mirrored. */
 const DUE_MARGIN_MS = 5_000;
-/** Pending wake-ups → the desired alarm set, minus already-due entries (see {@link DUE_MARGIN_MS}). */
+/**
+ * Pending wake-ups → the desired one-shot alarms. A wake-up already due is left out (see {@link DUE_MARGIN_MS}): the
+ * container is awake for it, and its wake pump fires it.
+ *
+ * ONE ID PER INSTANT, never per wake-up. An alarm deletes itself once it has fired, and a recurring wake-up's claim
+ * mirrors its next instant right after: an id reused for it would update the alarm EventBridge is about to delete,
+ * and the next instant would be deleted with it. With one id per instant, mirroring again is idempotent.
+ */
 export function toAlarms(pending, now) {
+    const earliest = now.getTime() + DUE_MARGIN_MS;
     return pending
-        .filter((w) => Date.parse(w.fireAt) > now.getTime() + DUE_MARGIN_MS)
-        .map((w) => ({ id: w.id, at: w.fireAt }));
+        .filter((w) => Date.parse(w.fireAt) > earliest)
+        .map((w) => ({ id: `${w.id}@${w.fireAt}`, at: w.fireAt }));
+}
+/**
+ * Each armed schedule → the recurring EventBridge schedule that fires it. Discovery admits only a cron that
+ * translates (schedule/discover.ts), so one that does not here is a defect, and throws.
+ */
+export function toRecurring(schedules) {
+    return schedules.map((s) => {
+        const translated = toEventBridgeCron(s.cron);
+        if ("error" in translated)
+            throw new Error(`schedule "${s.name}" has no EventBridge form: ${translated.error}`);
+        return { name: s.name, expression: translated.expression, tz: s.tz ?? "UTC" };
+    });
 }
 /**
  * Build the wakeups sink for an AgentCore deployment (registered via `setWakeupsSink` by `start` when
@@ -58,7 +89,7 @@ export function createWakeAlarmSink(options) {
     return Effect.gen(function* () {
         const clock = yield* Clock.Clock;
         const fork = Effect.runForkWith(yield* Effect.context());
-        const { secret, fetchImpl = fetch, now = () => new Date(clock.currentTimeMillisUnsafe()), delay: pause } = options;
+        const { secret, schedules = () => [], fetchImpl = fetch, now = () => new Date(clock.currentTimeMillisUnsafe()), delay: pause, } = options;
         const delay = (ms) => (pause ? portJoin(() => pause(ms)) : Effect.sleep(ms));
         let running = false;
         let dirty = false;
@@ -68,18 +99,20 @@ export function createWakeAlarmSink(options) {
                 try: () => toAlarms(listWakeups(stateRoot), now()),
                 catch: (cause) => new PortFailure(cause),
             });
-            // Nothing future to mirror: converged.
-            if (alarms.length === 0)
-                return true;
+            const recurring = toRecurring(schedules());
             const url = yield* Effect.try({
                 try: () => readWakeAlarmUrl(stateRoot),
                 catch: (cause) => new PortFailure(cause),
             });
             if (!url) {
-                log.warn("[schedule] wake alarm skipped — forwarder URL not seen yet");
+                // Nothing to set, before the forwarder was ever seen: nothing can be pending there either.
+                if (alarms.length > 0 || recurring.length > 0) {
+                    log.warn("[schedule] alarm sync skipped — forwarder URL not seen yet");
+                }
                 return true;
             }
-            const body = { secret, alarms };
+            // Sent EMPTY too: the schedules are the whole set, and the forwarder deletes one this set no longer has.
+            const body = { secret, alarms, schedules: recurring };
             return yield* portRequest(async (signal) => {
                 const res = await fetchImpl(`${url.replace(/\/$/, "")}${RESERVED_PATHS.wakeAlarm}`, {
                     method: "POST",
@@ -121,14 +154,18 @@ export function createWakeAlarmSink(options) {
                         break;
                 }
             }
-            if (failures >= MAX_SYNC_ATTEMPTS) {
-                log.error(`[schedule] wake alarm sync FAILED after ${MAX_SYNC_ATTEMPTS} attempts — pending wake-ups have no ` +
-                    `external alarm until the next store change or boot re-mirrors them`);
-            }
+            if (failures < MAX_SYNC_ATTEMPTS)
+                return true;
+            log.error(`[schedule] alarm sync FAILED after ${MAX_SYNC_ATTEMPTS} attempts — new wake-ups have no alarm, and ` +
+                `schedule edits since the last sync have not reached EventBridge (schedules it already holds keep ` +
+                `firing). It is tried again every ${HEAL_MS / 60_000} minutes while this container runs, and at its next start`);
+            return false;
         });
+        /** One retry pending at a time, however many syncs gave up meanwhile. */
+        let healing = false;
         // Single-flight: a save arriving while the loop runs only marks it dirty, so a burst coalesces into one more pass
         // instead of one concurrent loop each.
-        return (stateRoot) => {
+        const sink = (stateRoot) => {
             dirty = true;
             if (running)
                 return;
@@ -136,12 +173,21 @@ export function createWakeAlarmSink(options) {
             fork(Effect.acquireUseRelease(Effect.sync(beginWork), () => 
             // Claim notification precedes scheduler admission; retain busy ownership through that handoff.
             Effect.yieldNow.pipe(Effect.andThen(reconcile(stateRoot)), Effect.catchCause((cause) => Effect.sync(() => {
-                // Store/clock faults cannot be repaired by another POST. A new mutation may retry the mirror.
-                log.error(`[schedule] wake alarm reconcile failed (alarms are stale until the next store change): ${String(portError(cause))}`);
+                log.error(`[schedule] alarm reconcile failed (tried again in ${HEAL_MS / 60_000} minutes while this ` +
+                    `container runs): ${String(portError(cause))}`);
+                return false;
             }))), (done) => Effect.sync(() => {
                 running = false;
                 done();
-            })));
+            })).pipe(Effect.flatMap((converged) => converged || healing
+                ? Effect.void
+                : Effect.sync(() => {
+                    healing = true;
+                }).pipe(Effect.andThen(delay(HEAL_MS)), Effect.andThen(Effect.sync(() => {
+                    healing = false;
+                    sink(stateRoot);
+                }))))));
         };
+        return sink;
     });
 }

package/dist/schedule/wakeups.d.ts

@@ -10,9 +10,12 @@ export interface Wakeup {
     cron?: string;
     /** IANA timezone for `cron` (default UTC). */
     tz?: string;
-    /** ONE-SHOT ONLY: consecutive busy-defer attempts. */
-    attempts?: number;
 }
+/**
+ * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"` ("30m", "2h",
+ * "1d").
+ */
+export declare function parseDelayMs(input: string | number): number | undefined;
 /** The minimum delay a wake-up may be scheduled for — rejects a busy-loop (`wake in 1s`, then again…). */
 export declare const MIN_WAKE_MS = 60000;
 /**
@@ -21,8 +24,6 @@ export declare const MIN_WAKE_MS = 60000;
  * deploy is one session per chat).
  */
 export declare const MAX_PENDING_WAKEUPS = 20;
-/** How many times a busy/transient wake is retried (deferred) before being dropped. */
-export declare const MAX_WAKE_ATTEMPTS = 120;
 export declare function setWakeupsSink(sink: ((stateRoot: string) => void) | undefined): void;
 /** The current pending wake-ups — read by the wake-alarm sink, which mirrors them into an external clock. */
 export declare function listWakeups(stateRoot: string): Wakeup[];
@@ -43,22 +44,22 @@ export declare function addWakeup(stateRoot: string, input: {
     tz?: string;
 }, now?: Date): AddWakeupResult;
 /**
- * Remove ONE pending wake-up, and only from the session that made it.
- *
- * SESSION-SCOPED WITH NO WAY AROUND IT, because `unwake` is the only caller: an agent cancels its own alarm, and
- * cancelling another conversation's silently is a cost with no matching benefit. There is no operator command: a
- * wake-up only fires while a serve is running, and a running serve is one whose
- * session can be spoken to (`POST /invoke`, the control plane's `follow_up`, or the chat thread it lives in), so
- * "the alarm is loose" and "the agent is unreachable" cannot both be true. The last resort is editing
- * `<stateRoot>/schedule/wakeups.json`, which needs no command.
+ * Remove ONE pending wake-up, and only from the session that made it: `unwake`, an agent cancelling its own alarm.
+ * Cancelling another conversation's silently is a cost with no matching benefit.
  */
 export declare function removeWakeup(stateRoot: string, id: string, session: string): boolean;
+/**
+ * Remove ONE pending wake-up whatever session set it: the operator's `fastagent schedules unwake`, the one way out of a
+ * wake-up set in a session nobody can message (a schedule's own). Its caller holds the instance, so no serve's poll
+ * writes the store between this read and its write.
+ */
+export declare function removeAnyWakeup(stateRoot: string, id: string): Wakeup | undefined;
 /**
  * CLAIM the FIRST due wake-up (at or before `now`) in stored order, remove + return it, or undefined if none is due.
  */
 export declare function takeFirstDueWakeup(stateRoot: string, now?: Date): Wakeup | undefined;
 /**
- * Re-schedule a ONE-SHOT wake whose fire failed TRANSIENTLY (its session was busy — a channel is mid-turn on it),
- * deferred to `fireAt`.
+ * Put back a ONE-SHOT wake-up its session refused for now (the process or the session's queue was full), to fire at
+ * `fireAt`. It was taken out of the store to fire, so it does not count against the session's cap again.
  */
-export declare function deferWakeup(stateRoot: string, w: Wakeup, fireAt: Date): boolean;
+export declare function requeueWakeup(stateRoot: string, w: Wakeup, fireAt: Date): void;

package/dist/schedule/wakeups.js

@@ -1,11 +1,24 @@
 /**
  * The agent's self-scheduled wake-ups — the SECOND producer of scheduled invocations (the first is the author's
- * `routines/` files).
+ * `schedules/` files).
  */
 import { randomUUID } from "node:crypto";
 import { log } from "../log.js";
-import { cronError, nextRun } from "./cron.js";
+import { cronError, nextRun, recurringCronError } from "./cron.js";
 import { readScheduleFile, scheduleFile, writeScheduleFile } from "./state.js";
+/**
+ * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"` ("30m", "2h",
+ * "1d").
+ */
+export function parseDelayMs(input) {
+    if (typeof input === "number")
+        return Number.isFinite(input) && input > 0 ? input * 1000 : undefined;
+    const m = input.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i); // unit REQUIRED on a string
+    if (!m)
+        return undefined;
+    const mult = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2].toLowerCase()];
+    return Number(m[1]) * mult;
+}
 /** The minimum delay a wake-up may be scheduled for — rejects a busy-loop (`wake in 1s`, then again…). */
 export const MIN_WAKE_MS = 60_000; // 1 minute
 /**
@@ -14,10 +27,6 @@ export const MIN_WAKE_MS = 60_000; // 1 minute
  * deploy is one session per chat).
  */
 export const MAX_PENDING_WAKEUPS = 20;
-/** How many times a busy/transient wake is retried (deferred) before being dropped. */
-export const MAX_WAKE_ATTEMPTS = 120;
-/** The minimum gap between two consecutive fires of a RECURRING wake. */
-const MIN_RECURRING_GAP_MS = 10 * 60_000; // 10 minutes
 /** A stored entry is a real Wakeup: the fields are present and `fireAt` is a parseable date. */
 function isWakeup(e) {
     if (!e || typeof e !== "object")
@@ -28,7 +37,6 @@ function isWakeup(e) {
         typeof w.prompt === "string" &&
         typeof w.fireAt === "string" &&
         !Number.isNaN(Date.parse(w.fireAt)) &&
-        (w.attempts === undefined || typeof w.attempts === "number") && // a non-number would make deferWakeup's count NaN
         (w.tz === undefined || typeof w.tz === "string") &&
         // A stored cron must PARSE: a bad one would throw inside the claim's nextRun.
         (w.cron === undefined ||
@@ -74,22 +82,15 @@ export function listWakeups(stateRoot) {
 export function addWakeup(stateRoot, input, now = new Date()) {
     let fireAtDate;
     if (input.cron !== undefined) {
-        const err = cronError(input.cron, input.tz);
+        // A recurring wake runs FOREVER — gated harder than a one-shot, by the rule every recurring producer shares.
+        const err = recurringCronError(input.cron, input.tz);
         if (err)
-            return { ok: false, error: `invalid cron/tz: ${err}` };
-        // A recurring wake runs FOREVER — gate its frequency harder than a one-shot: the gap between the next two
-        // instants must be ≥ the recurring floor.
+            return { ok: false, error: `${err}${err.startsWith("this cron never") ? " — use `in` for a one-shot" : ""}.` };
+        // DERIVED from the cron — a caller-passed fireAt can't disagree with the schedule.
         const first = nextRun(input.cron, input.tz, now);
-        const second = first && nextRun(input.cron, input.tz, first);
-        if (!first || !second)
-            return { ok: false, error: "this cron never fires (or fires only once) — use `in` for a one-shot." };
-        if (second.getTime() - first.getTime() < MIN_RECURRING_GAP_MS) {
-            return {
-                ok: false,
-                error: `too frequent — a recurring wake must fire at most every ${MIN_RECURRING_GAP_MS / 60_000} minutes.`,
-            };
-        }
-        fireAtDate = first; // DERIVED from the cron — a caller-passed fireAt can't disagree with the schedule
+        if (!first)
+            return { ok: false, error: "this cron never fires again — use `in` for a one-shot." };
+        fireAtDate = first;
     }
     else {
         if (!input.fireAt)
@@ -121,22 +122,28 @@ export function addWakeup(stateRoot, input, now = new Date()) {
     return { ok: true, id, fireAt };
 }
 /**
- * Remove ONE pending wake-up, and only from the session that made it.
- *
- * SESSION-SCOPED WITH NO WAY AROUND IT, because `unwake` is the only caller: an agent cancels its own alarm, and
- * cancelling another conversation's silently is a cost with no matching benefit. There is no operator command: a
- * wake-up only fires while a serve is running, and a running serve is one whose
- * session can be spoken to (`POST /invoke`, the control plane's `follow_up`, or the chat thread it lives in), so
- * "the alarm is loose" and "the agent is unreachable" cannot both be true. The last resort is editing
- * `<stateRoot>/schedule/wakeups.json`, which needs no command.
+ * Remove ONE pending wake-up, and only from the session that made it: `unwake`, an agent cancelling its own alarm.
+ * Cancelling another conversation's silently is a cost with no matching benefit.
  */
 export function removeWakeup(stateRoot, id, session) {
+    return removeWhere(stateRoot, (w) => w.id === id && w.session === session) !== undefined;
+}
+/**
+ * Remove ONE pending wake-up whatever session set it: the operator's `fastagent schedules unwake`, the one way out of a
+ * wake-up set in a session nobody can message (a schedule's own). Its caller holds the instance, so no serve's poll
+ * writes the store between this read and its write.
+ */
+export function removeAnyWakeup(stateRoot, id) {
+    return removeWhere(stateRoot, (w) => w.id === id);
+}
+function removeWhere(stateRoot, match) {
     const all = load(stateRoot);
-    const kept = all.filter((w) => !(w.id === id && w.session === session));
-    if (kept.length === all.length)
-        return false;
-    save(stateRoot, kept);
-    return true;
+    const index = all.findIndex(match);
+    if (index === -1)
+        return undefined;
+    const [removed] = all.splice(index, 1);
+    save(stateRoot, all);
+    return removed;
 }
 /**
  * CLAIM the FIRST due wake-up (at or before `now`) in stored order, remove + return it, or undefined if none is due.
@@ -148,11 +155,10 @@ export function takeFirstDueWakeup(stateRoot, now = new Date()) {
         return undefined;
     const w = all[idx];
     if (w.cron !== undefined) {
-        // RECURRING claim = ADVANCE IN PLACE: the entry STAYS in the store with fireAt pushed to the next cron instant
-        // (attempts cleared).
+        // RECURRING claim = ADVANCE IN PLACE: the entry STAYS in the store with fireAt pushed to the next cron instant.
         const next = nextRun(w.cron, w.tz, now);
         if (next)
-            all[idx] = { ...w, fireAt: next.toISOString(), attempts: undefined };
+            all[idx] = { ...w, fireAt: next.toISOString() };
         else
             all.splice(idx, 1); // the cron has no next instant — this is its final occurrence
         save(stateRoot, all);
@@ -163,13 +169,9 @@ export function takeFirstDueWakeup(stateRoot, now = new Date()) {
     return w;
 }
 /**
- * Re-schedule a ONE-SHOT wake whose fire failed TRANSIENTLY (its session was busy — a channel is mid-turn on it),
- * deferred to `fireAt`.
+ * Put back a ONE-SHOT wake-up its session refused for now (the process or the session's queue was full), to fire at
+ * `fireAt`. It was taken out of the store to fire, so it does not count against the session's cap again.
  */
-export function deferWakeup(stateRoot, w, fireAt) {
-    const attempts = (w.attempts ?? 0) + 1;
-    if (attempts > MAX_WAKE_ATTEMPTS)
-        return false;
-    save(stateRoot, [...load(stateRoot), { ...w, fireAt: fireAt.toISOString(), attempts }]);
-    return true;
+export function requeueWakeup(stateRoot, w, fireAt) {
+    save(stateRoot, [...load(stateRoot), { ...w, fireAt: fireAt.toISOString() }]);
 }

package/dist/service.d.ts

@@ -1,194 +1,81 @@
-import type { Agent } from "./agent.ts";
-import { type PrefixMount } from "./channels/serve.ts";
-import { type LoadedLongConnectionChannel } from "./channels/discover.ts";
-import type { SessionControl } from "./session.ts";
+import type { Agent } from "./agent-api.ts";
 import type { ChannelHandler, Routes } from "./channel.ts";
-import type { LoadedRoutine } from "./schedule/routine.ts";
-export interface ServingSurface {
-    /**
-     * The routes that AUTHENTICATE NOBODY — `GET /health`, `POST /invoke`, and `POST /run` where the definition
-     * declares routines, minus what a channel took over or `http.invoke: false` withheld. Kept APART from the
-     * channels' table rather than derived from it, because three decisions read it (browser reachability, the JSON
-     * body gate, what the startup line calls unauthenticated) and must give the same answer.
-     */
-    unverified: Routes;
-    /**
-     * What the `channels/` files serve. Exempt from both guards because a channel checks its platform's signature
-     * inside itself — an assumption about the author for a CUSTOM channel, not a property we enforce (§14).
-     */
-    selfVerifying: Routes;
-    /** Prefix-owning handlers mounted beside the routes (the session control plane). */
-    mounts?: readonly PrefixMount[];
+import { type AnyChannelModule, type LoadedLongConnectionChannel } from "./channels/discover.ts";
+import { type Scheduler } from "./schedule/scheduler.ts";
+import type { Schedule } from "./schedule/schedule.ts";
+/** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
+export declare const DEFAULT_HTTP_PORT = 8787;
+/** What a serve answers: its channels' routes, and `GET /health` unless a channel serves it. */
+interface ServingSurface {
+    routes: Routes;
     longConnections: LoadedLongConnectionChannel[];
-    /** Route-channel basenames; the tunnel registers only this subset. */
+    /** Route-channel names; the tunnel registers only this subset. */
     routeChannels: string[];
     /** Flip health between 200 and 503. */
     setReady(value: boolean): void;
 }
-/** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
-export declare const DEFAULT_HTTP_PORT = 8787;
-/**
- * What a serve publishes on its port, and to which browsers — the config file's `http` block minus `port`, carried
- * as-is into the assembly so every reader (the routes, the startup report, deploy's pre-flight, AgentCore's inert-key
- * warnings) reads ONE value. The port is not here: the assembly binds nothing, so only the CLI reads it.
- */
-export interface HttpSurface {
-    /**
-     * The origins a BROWSER may call this serve from. The default, with this unset, answers EVERY origin: any page your
-     * users visit can call this port and read the reply, and every route here is unauthenticated. Set it to your front
-     * end's real domain to take that back (`["*"]` is the default said out loud; an empty list is refused, because it
-     * reads as "nobody" and would mean the opposite).
-     */
-    cors?: readonly string[];
-    /**
-     * Serve the data plane, `POST /invoke`. On by default: it is the framework's interface, and a deployment that can
-     * only be reached through a chat channel is still worth curling. Set it `false` when this port is public and the
-     * channels' own signature checks are meant to be the only way in — the route is unauthenticated and runs a turn
-     * with the agent's full tool authority.
-     */
-    invoke?: boolean;
+/** Mount the channels and the health check. */
+export declare function routesFor(agent: Agent, stateRoot: string, channels: ReadonlyMap<string, AnyChannelModule>): ServingSurface;
+/** Start the clock: the definition's schedules, and the wake-ups the agent sets for itself, on every serve. */
+export declare function startSchedules(agent: Agent, stateRoot: string, schedules: readonly Schedule[], options?: {
+    localClock?: boolean;
+}): Pick<Scheduler, "stop">;
+/** What `serve()` answers (SPEC.md §8): the agent's channels, schedules and wake-ups, and `GET /health`. */
+export interface Service {
+    /** For an app's own server to route to. */
+    fetch(request: Request): Promise<Response>;
+    /** Or a server of its own, on this runtime's server: the one way to start one. Answers the port it bound. */
+    listen(port: number, host?: string): Promise<number>;
+    /** Settles when every long connection is up: immediately when there are none. */
+    ready: Promise<void>;
     /**
-     * Serve `POST /run` (and `GET /routines`), which run a routine this definition declares by name. It follows
-     * `invoke` unless set: turning the anonymous turn endpoint off must not leave a second one open behind it. Set it
-     * `true` for the one combination that gets wrong — no `/invoke`, but an external clock (a crontab, a CI job) driving
-     * the routines. It has no effect where `routines/` declares nothing; there is no route then.
+     * Stop the server, giving the requests in flight a moment before ending them, then long connections and schedules.
+     * It does NOT drain the agent's messages: one takes seconds to minutes, and the deployment wants the old process gone
+     * in under a second. What makes that safe is that they are durable: an accepted message is answered after the
+     * restart, and a chat turn's intent is durable before it is accepted (`channels/kit/turn-store.ts`). A schedule
+     * fire's claim is written before its message: the next boot writes back the end of a message the agent took, and
+     * records one it never took as `interrupted`.
      */
-    run?: boolean;
+    close(): Promise<void>;
 }
-/**
- * Does this surface serve `POST /run`, given a routine to run? It FOLLOWS `invoke` unless `run` says otherwise (see
- * {@link HttpSurface.run}). ONE function because the assembly mounts the route and `preflightDeploy` names it; a
- * default spelled twice is a default that moves once.
- */
-export declare function shouldServeRun(http: HttpSurface | undefined): boolean;
-/**
- * What an anonymous caller of a port can do, worst first — the ONE wording the startup report and deploy's pre-flight
- * both print, each from its own facts (what mounted vs what will mount).
- */
-export declare function describeAnonymousSurface(open: {
-    invoke: boolean;
-    run: boolean;
-    controlPrefix?: string;
-}): string[];
-/**
- * The surface this deployment serves: the DATA plane (`POST /invoke`), `GET /health`, and the discovered channels.
- *
- * `/invoke` is the framework's interface, so it is served whatever channels a definition declares (unless
- * `http.invoke: false`). It is RESERVED for the same reason `/control/*` is: a channel taking that path would silently replace the one route every client,
- * every doc and the startup line all name. `/health` stays overridable — a probe is the deployment's to shape.
- */
-export declare function routesFor(agentDir: string, agent: Agent, stateRoot: string, control: SessionControl | undefined, 
-/**
- * `http.invoke: false` withholds the data plane. Two callers, two reasons: the AgentCore adapter serves the
- * Runtime's `/invocations` contract instead, and an author sets it to leave the channels' signature checks as the
- * only way into a public port.
- *
- * `routines` mounts `POST /run` and `GET /routines` (per {@link shouldServeRun}). Passed in rather than loaded here
- * so the routes and the resident clock cannot disagree about which routines exist (`loadServingRoutines`).
- */
-options?: {
-    http?: HttpSurface;
-    routines?: readonly LoadedRoutine[];
-}): Promise<ServingSurface>;
-/** Refuse channel routes the control plane would swallow. */
-export declare function assertNoControlPlaneCollision(channelRoutes: Routes, plane: PrefixMount): void;
-export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined): {
-    routes: Routes;
-    mounts: PrefixMount[];
-    /** The prefix the plane owns, when it is published — what a startup line names. */
-    controlPrefix?: string;
-};
-/**
- * Load the agent's `routines/`, gated.
- *
- * Separate from {@link startSchedules} because two things need the SAME list and one of them runs first: the
- * `POST /run` route is built with the routes (so a channel cannot take that path unnoticed), and the resident
- * clock starts later, inside the service's scope. Loading twice would let them disagree about which routines exist.
- */
-export declare function loadServingRoutines(agentDir: string): Promise<LoadedRoutine[]>;
-/**
- * Start the clock over routines {@link loadServingRoutines} already gated — on every serve, routines or not: the
- * agent's own wake-ups are a default capability, and this is what fires them.
- */
-export declare function startSchedules(agent: Agent, stateRoot: string, routines: LoadedRoutine[], options?: {
-    externalClock?: boolean;
-}): {
-    routines: LoadedRoutine[];
-    stop: () => void;
-};
-export interface AgentService {
-    /** The assembled Fetch handler: channel routes, the control plane, and health. */
-    handler: ChannelHandler;
-    /** The agent behind it — invoke it directly when you also want a programmatic path. */
-    agent: Agent;
-    /** The literal routes `handler` was composed from — for a startup line naming what is served. */
+/** A serve as the CLI reports it: what it serves, beside the Service itself. */
+export interface ServedAgent extends Service {
+    /** The literal routes the service answers, for a startup line naming them. */
     routes: Routes;
     agentDir: string;
-    workspace: string;
-    /**
-     * What actually mounted, for a startup line: channel files serving routes, and long connections.
-     */
+    /** What actually mounted: channels serving routes, and long connections. */
     channels: {
         routes: string[];
         longConnections: string[];
     };
-    /**
-     * The keys of {@link ServingSurface.unverified}: what a caller reads to describe this surface. Not derivable from
-     * `routes`, where a channel may serve one of those paths behind its own signature check.
-     */
-    unverifiedRoutes: readonly string[];
-    /**
-     * The cross-origin allow-list this service was assembled with (`http.cors`), or `undefined` for the `*` default.
-     * Read by the startup report for the same reason as {@link AgentService.unverifiedRoutes}: what a caller says
-     * about this surface must come from what was actually assembled, not from re-deriving it.
-     */
-    corsOrigins?: readonly string[];
-    routines: readonly LoadedRoutine[];
-    /** Settles when every long connection is up — immediately when there are none. */
-    ready: Promise<void>;
-    /** The control plane's prefix, when `sessionControl` is on. */
-    controlPrefix?: string;
-    /**
-     * Stop long connections and routines. It does NOT drain agent turns: a turn takes seconds to minutes, and the
-     * deployment wants the old process gone in under a second (`SHUTDOWN_GRACE_MS` in `src/cli/serve.ts`). What makes
-     * that safe is replay, not waiting — a chat turn's intent is durable before it is accepted and its channel
-     * replays it on the next boot (`channels/kit/turn-store.ts`), and an in-flight HTTP/SSE caller sees the stream
-     * drop and retries. The one path with neither is a routine fire, whose claim is written before the turn: it
-     * stays skipped, and the next boot records it as `interrupted` rather than losing it silently.
-     */
-    close(): Promise<void>;
+    schedules: readonly Schedule[];
+    /** Whether the Agent API is served, under `/v1`: only with a key (SPEC.md §9.1). */
+    api: boolean;
 }
-/** What {@link mountAgentService} needs beyond an opened directory. */
-export interface MountAgentServiceOptions {
-    /** Wrap the agent before anything consumes it. */
-    wrapAgent?: (agent: Agent) => Agent;
-    /** Aborting this closes the service, exactly like calling {@link AgentService.close}. */
-    signal?: AbortSignal;
+/**
+ * A Service over `handler`: answered in process, or served on a server of its own. `endStreams` ends what would hold
+ * the server's close open (a Caller watching events), and `shutdown` stops the rest once the server has.
+ */
+export declare function serviceOver(handler: ChannelHandler, ready: Promise<void>, shutdown: () => Promise<void>, endStreams?: () => Promise<void>): Service;
+/** What {@link serveAgent} needs beyond an opened agent. */
+export interface ServeOptions {
     /** Called when a long connection ends on its own — a dropped socket-mode channel, say. */
     onChannelClosed?: (name: string, error?: unknown) => void;
     /** How long `close()` waits for a channel to stop before reporting it stuck (default 5s). */
     closeTimeoutMs?: number;
+    /** The keys the Agent API takes; without one it is not served (SPEC.md §9.1). */
+    apiKeys?: readonly string[];
 }
-/** What the assembly needs from an opened agent directory — the whole of it. */
-export interface MountableAgent {
+/** What the assembly serves. */
+export interface ServableAgent {
     agent: Agent;
-    /** The definition dir: where channels/, tools/ and routines/ are read from. */
+    /** The definition's directory: the agent's working directory. */
     agentDir: string;
-    /** The agent's cwd. */
-    workspace: string;
-    /** Where durable state lives (channel state, sessions, routine fires). */
+    /** Where durable state lives (channel state, schedule fires, wake-ups). */
     stateRoot: string;
-    /** The session-control hub, when the opener built one. A serve has it whether or not `/control/*` is published:
-     *  a chat channel's stop command reaches the running turn through it. */
-    sessionControl?: SessionControl;
-    /** Whether that hub is ALSO served as `/control/*` (`config.sessionControl`). Required, not defaulted: an
-     *  embedder assembling this by hand would otherwise lose the plane to a 404 with nothing said anywhere. */
-    publishControl: boolean;
-    /** What the port publishes, and to which browsers — the config's `http` block ({@link HttpSurface}). */
-    http?: HttpSurface;
+    channels: ReadonlyMap<string, AnyChannelModule>;
+    schedules: readonly Schedule[];
 }
-/**
- * The assembly itself, over an already-opened directory: channels, the control plane, routines and long connections,
- * composed into one handler.
- */
-export declare function mountAgentService(opened: MountableAgent, options?: MountAgentServiceOptions): Promise<AgentService>;
+/** The assembly itself: channels, schedules and long connections, composed into one handler. */
+export declare function serveAgent(opened: ServableAgent, options?: ServeOptions): Promise<ServedAgent>;
+export {};