@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/cli/serve.js

@@ -1,61 +1,17 @@
 /**
- * The serving spine shared by `dev` (its worker) and `start`: channel assembly, Node HTTP binding,
- * long-connection lifecycle, scheduler lifecycle, and the optional Cloudflare quick tunnel.
+ * What `dev` (its worker) and `start` need beyond the service itself: binding a port, the shutdown
+ * order, the startup report, and the optional Cloudflare quick tunnel.
+ *
+ * The ASSEMBLY is not here — it lives in `src/service.ts`, which a public entry may import and this
+ * directory may not be (it decides process-level things: `fail.ts` calls `process.exit`).
  */
-import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { createStateSync } from "../channels/agentcore-state.js";
-import { agentcoreRoutes, UnknownScheduleError } from "../channels/agentcore.js";
-import { activeWork } from "../channels/busy.js";
-import { controlRoutes } from "../channels/control.js";
-import { INVOKE_EXAMPLE_BODY, createInvokeHandler } from "../channels/http.js";
-import { text } from "../channels/respond.js";
-import { loadChannels } from "../engines/pi/channel.js";
-import { reportModuleLoadFailures } from "../engines/pi/report.js";
+import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
 import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
-import { parseRouteKey, router, serveNode } from "../host/node.js";
+import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
-import { loadSchedules } from "../schedule/discover.js";
-import { createScheduler, fireScheduleOnce } from "../schedule/scheduler.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup, failUsage } from "./fail.js";
-/**
- * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
- * POST `/invoke` only when neither a route nor a long-connection channel was declared.
- */
-export async function routesFor(agentDir, agent, stateRoot, control, options = {}) {
-    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
-        agent,
-        stateRoot,
-        control,
-    });
-    for (const c of collisions) {
-        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
-    }
-    reportModuleLoadFailures(failures);
-    if (failures.length > 0 || collisions.length > 0) {
-        throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
-            `fix it, or rename an intentionally disabled file to *.disabled`);
-    }
-    const builtinInvoke = options.builtinInvoke !== false && Object.keys(routes).length === 0 && longConnections.length === 0;
-    const channels = builtinInvoke ? { "POST /invoke": createInvokeHandler(agent) } : routes;
-    const healthCovered = Object.keys(channels).some((key) => {
-        const entry = parseRouteKey(key);
-        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
-    });
-    let ready = longConnections.length === 0;
-    const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
-    return {
-        routes: healthCovered ? channels : { "GET /health": health, ...channels },
-        longConnections,
-        routeChannels,
-        builtinInvoke,
-        markReady() {
-            ready = true;
-        },
-    };
-}
 /**
  * Mount the session control plane (`/control/*`) when the agent enabled it
  * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
@@ -66,123 +22,6 @@ export async function routesFor(agentDir, agent, stateRoot, control, options = {
  * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
  * and silently shadowing either side would serve a surface the author didn't write.
  */
-export function mountSessionControl(routes, control, stateRoot, options = {}) {
-    if (!control)
-        return { routes, announce: () => { } };
-    const token = crypto.randomUUID();
-    const mounted = controlRoutes(control, { token, agent: options.agent });
-    // PATH-level collision, matching the router's semantics (an any-method "/control/dispatch"
-    // channel key would dodge an exact-key check yet still shadow the method-qualified control
-    // route at match time — the router matches by path first).
-    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
-    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
-    if (collisions.length > 0) {
-        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control plane — ` +
-            `rename the channel route or disable sessionControl in fastagent.config`);
-    }
-    return {
-        routes: { ...routes, ...mounted },
-        announce: (boundPort) => {
-            // The state root normally exists (the opener mkdirs the sessions dir under it), but an
-            // external --sessions-dir leaves it uncreated — and announce runs inside serve's listening
-            // callback, where a throw is an unhandled rejection, not a one-line startup diagnostic.
-            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
-            const path = join(stateRoot, "control.json");
-            // Atomic (tmp+rename, the state.ts pattern): attach re-reads this file exactly during the
-            // restart window — a torn read would be misdiagnosed as "serve gone".
-            const tmp = `${path}.tmp`;
-            writeFileSync(tmp, `${JSON.stringify({ url: `http://${clientHost(options.host)}:${boundPort}`, token })}\n`, {
-                mode: 0o600,
-            });
-            chmodSync(tmp, 0o600); // an existing file keeps its old mode on rewrite — pin it
-            renameSync(tmp, path);
-            log.info(`[fastagent] session control on /control/* (token in ${path})`);
-            // The serve binds ALL interfaces by DEFAULT (containers require it), so /control/* is
-            // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths warn
-            // loudly, and the LAN path must not be the silent third way past the local trust story. A
-            // loopback bind closes exactly that reach, so it earns silence.
-            const bind = classifyBind(options.host);
-            if (bind !== "loopback") {
-                log.warn(`[fastagent] the port binds ${bind === "wildcard" ? "all interfaces" : `${options.host} (off this machine)`}: ` +
-                    "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
-                    "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs: design §14)");
-            }
-            if (options.tunnel) {
-                // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC
-                // (beyond even the LAN reach the mount already warned about). The operator asked for the tunnel (webhooks), but must not DISCOVER the control
-                // plane went public with it — say it loudly.
-                log.warn("[fastagent] --tunnel exposes /control/* (steer/abort/set_model) at the public tunnel URL, " +
-                    "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs: design §14)");
-            }
-            // Best-effort lifecycle end: a clean exit removes the discovery file so a later `attach`
-            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
-            const unlink = () => {
-                try {
-                    rmSync(path, { force: true });
-                }
-                catch {
-                    /* the file is advisory — exit must not fail on it */
-                }
-            };
-            // Signal handlers MUST NOT absorb termination: registering any listener disables Node's
-            // default kill, so clean up and RE-RAISE. The mechanism: `process.kill` delivery is ASYNC —
-            // it lands after the current emit completes, so every listener of this same emit (scheduler
-            // stop, tunnel close — regardless of registration order) runs first, and the re-raised
-            // signal then hits the default action because each `once` handler is already consumed. When
-            // some listener exits the process itself (the tunnel path calls process.exit(0)), the
-            // re-raise is harmless redundancy. Without this, the first Ctrl+C would leave the serve
-            // alive minus its control.json, and dev's watch restart (SIGTERM → wait for exit → respawn)
-            // would hang on a worker that never exits.
-            const unlinkAndReraise = (signal) => () => {
-                unlink();
-                process.kill(process.pid, signal);
-            };
-            process.once("SIGINT", unlinkAndReraise("SIGINT"));
-            process.once("SIGTERM", unlinkAndReraise("SIGTERM"));
-            process.once("exit", unlink);
-        },
-    };
-}
-/**
- * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
- * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
- * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
- * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
- * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
- */
-export function mountAgentcore(routes, options) {
-    const { agent, stateRoot, schedules, onStateReady, lazyChannels } = options;
-    const mounted = agentcoreRoutes({
-        routes: lazyChannels ?? routes,
-        agent,
-        stateRoot,
-        isBusy: () => activeWork() > 0,
-        // Cross-deploy durability: AgentCore wipes the state mount on every runtime version update, so
-        // the state root is restored from (and pushed to) an S3 snapshot through presigned URLs the
-        // forwarder mints per envelope. Always wired on this path — the platform gives no other way to
-        // keep an agent's memory across a deploy.
-        stateSync: createStateSync({ stateRoot }),
-        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call. Absent =
-        // no forwarder in this topology, so only the public `invoke` kind is servable.
-        ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
-        onStateReady,
-        fire: schedules.length === 0
-            ? undefined
-            : (name, slot) => {
-                const schedule = schedules.find((s) => s.name === name);
-                if (!schedule)
-                    throw new UnknownScheduleError(name);
-                return fireScheduleOnce({ agent, stateRoot, schedule, slot });
-            },
-    });
-    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
-    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
-    if (collisions.length > 0) {
-        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the AgentCore adapter ` +
-            `(/invocations, /ping) — rename the channel route`);
-    }
-    return { ...routes, ...mounted };
-}
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
  * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
@@ -214,6 +53,20 @@ export function assertTunnelBindable(host, tunnel, source) {
  * A wildcard bind is every interface, and naming one address there would understate it — but the curl
  * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
  */
+/**
+ * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
+ * what mounted. One function because both commands must say the same thing at the same moment —
+ * after readiness, never at socket bind.
+ */
+export function reportServing(service, host, boundPort) {
+    process.send?.({ type: "ready", port: boundPort, routeChannels: service.channels.routes });
+    for (const line of readyAddressLines(host, boundPort, service.channels.builtinInvoke))
+        log.info(line);
+    log.info(`[fastagent] routes: ${Object.keys(service.routes).join(", ") || "(none)"}`);
+    if (service.channels.longConnections.length > 0) {
+        log.info(`[fastagent] long connections: ${service.channels.longConnections.join(", ")}`);
+    }
+}
 export function readyAddressLines(host, boundPort, builtinInvoke) {
     const dial = `${clientHost(host)}:${boundPort}`;
     const lines = [
@@ -229,76 +82,58 @@ export function readyAddressLines(host, boundPort, builtinInvoke) {
  * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
  * the sole clean-shutdown command. `host` unset binds all interfaces.
  */
-export function serve(surface, bind, onListening) {
+/** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
+ *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
+export const SHUTDOWN_GRACE_MS = 800;
+const FORCED_EXIT_MS = 1_500;
+export function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
-    const hosted = serveNode(router(surface.routes), { port, host });
-    const abort = new AbortController();
+    const hosted = serveNode(handler, { port, host });
     let stopping = false;
     const stop = (exitCode) => {
         if (stopping)
             return;
         stopping = true;
-        abort.abort();
-        const deadline = setTimeout(() => process.exit(exitCode), 1_000);
-        void hosted
-            .close()
-            .catch(() => { })
-            .finally(() => {
+        // Bounded: shutdown must not hang on a channel that will not close, so the deadline fires
+        // regardless. No drain — an in-flight turn is cut, which is the existing contract.
+        // Later than the service's own close deadline (SHUTDOWN_GRACE_MS below), or the process leaves
+        // at 0 before `close()` has said a channel would not stop.
+        const deadline = setTimeout(() => {
+            log.error(`[fastagent] shutdown did not finish within ${FORCED_EXIT_MS}ms; exiting`);
+            process.exit(1);
+        }, FORCED_EXIT_MS);
+        // Stop accepting FIRST, before anything is awaited. `onShutdown` waits for long connections to
+        // close, and a socket still listening through that wait would dispatch new work into channels
+        // and a scheduler that are already shutting down.
+        const closingServer = hosted.close();
+        hosted.closeAllConnections();
+        // A cleanup that failed is not a clean exit: `close()` reports a channel that would not stop,
+        // and swallowing it here would end the process at 0 over a resource still holding on.
+        void Promise.allSettled([closingServer, Promise.resolve(hooks.onShutdown?.())]).then((outcomes) => {
+            let code = exitCode;
+            for (const outcome of outcomes) {
+                if (outcome.status === "rejected") {
+                    log.error(`[fastagent] shutdown failed: ${String(outcome.reason)}`);
+                    code = 1;
+                }
+            }
             clearTimeout(deadline);
-            process.exit(exitCode);
+            process.exit(code);
         });
-        // Preserve the existing no-drain shutdown contract: stop accepting first, then cut active streams.
-        hosted.closeAllConnections();
     };
     process.once("SIGINT", () => stop(0));
     process.once("SIGTERM", () => stop(0));
     hosted.listening.then(async (boundPort) => {
         try {
-            const runs = surface.longConnections.map((connection) => {
-                const run = connection.connect(abort.signal);
-                if (run === null ||
-                    typeof run !== "object" ||
-                    typeof run.ready?.then !== "function" ||
-                    typeof run.closed?.then !== "function") {
-                    throw new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`);
-                }
-                void run.closed.then(() => {
-                    if (!abort.signal.aborted)
-                        failStartup(new Error(`${connection.name} closed unexpectedly`));
-                }, (error) => {
-                    if (!abort.signal.aborted)
-                        failStartup(new Error(`${connection.name} failed: ${String(error)}`));
-                });
-                return { connection, run };
-            });
-            await Promise.all(runs.map(async ({ connection, run }) => {
-                await run.ready;
-                if (!abort.signal.aborted)
-                    log.info(`[fastagent] long connection ready: ${connection.name}`);
-            }));
-            // Shutdown raced startup: a pre-ready abort settles `ready` as cancellation, not readiness —
-            // stop() already owns the exit; don't mark ready or report a surface being torn down.
-            if (abort.signal.aborted)
+            // A bound socket is NOT a serving agent: a declared socket-mode channel still has to come
+            // up, and reporting ready before it does tells the supervisor (and --tunnel, and the
+            // operator) that a surface is live while a channel is dead.
+            await hooks.ready;
+            if (stopping)
                 return;
-            surface.markReady();
-            process.send?.({
-                type: "ready",
-                port: boundPort,
-                routeChannels: surface.routeChannels,
-            });
-            for (const line of readyAddressLines(host, boundPort, surface.builtinInvoke))
-                log.info(line);
-            log.info(`[fastagent] routes: ${Object.keys(surface.routes).join(", ") || "(none)"}`);
-            if (surface.longConnections.length > 0) {
-                log.info(`[fastagent] long connections: ${surface.longConnections.map((connection) => connection.name).join(", ")}`);
-            }
-            onListening?.(boundPort);
+            hooks.onListening?.(boundPort);
         }
         catch (error) {
-            abort.abort();
-            const closing = hosted.close().catch(() => { });
-            hosted.closeAllConnections();
-            await closing;
             failStartup(error);
         }
     }, (error) => {
@@ -326,24 +161,3 @@ export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoo
         process.once("SIGTERM", cleanup);
     });
 }
-/**
- * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals. Returns the
- * loaded schedules so a serving surface that needs them (the AgentCore adapter's fire binding) shares
- * ONE load instead of re-discovering. `externalClock` (AgentCore) arms no resident cron timers.
- */
-export async function startSchedules(agentDir, agent, stateRoot, selfSchedule, options = {}) {
-    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
-    reportModuleLoadFailures(failures);
-    if (schedules.length === 0 && !selfSchedule)
-        return schedules;
-    const scheduler = createScheduler({ agent, stateRoot, schedules, externalClock: options.externalClock });
-    scheduler.start();
-    if (schedules.length > 0) {
-        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
-    }
-    const stop = () => scheduler.stop();
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
-    return schedules;
-}

package/dist/cli/shared.d.ts

@@ -2,7 +2,7 @@ import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/
 /**
  * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
  * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
- * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
  * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
  * policy (pad, never hand-space), not a constant.
  */
@@ -26,8 +26,10 @@ export declare function parsePort(value: string | undefined, source: string, fro
  * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
  */
 export declare function parseBind(value: string | undefined): string | undefined;
-/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
-export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking.
+ *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
+ *  reported like any built-in rather than as an unknown provider. */
+export declare function reportAuth(agentDir: string, modelSpec: string, authPath: string): Promise<void>;
 /**
  * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
  * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL

package/dist/cli/shared.js

@@ -10,7 +10,7 @@ import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
 import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
-import { createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
+import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
@@ -19,12 +19,12 @@ import { failStartup, failUsage } from "./fail.js";
 /**
  * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
  * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
- * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
  * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
  * policy (pad, never hand-space), not a constant.
  */
 export function reportLine(label, value) {
-    log.info(`[fastagent] ${`${label}:`.padEnd(11)}${value}`);
+    log.info(`[fastagent] ${`${label}:`.padEnd(13)}${value}`);
 }
 /** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
  *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders
@@ -70,10 +70,13 @@ export function parseBind(value) {
         failUsage(`invalid --bind "${value}": must be an IP address or "localhost"`);
     return bindAddress(trimmed); // a name never travels past this point — see bind.ts
 }
-/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
-export async function reportAuth(modelSpec, authPath) {
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking.
+ *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
+ *  reported like any built-in rather than as an unknown provider. */
+export async function reportAuth(agentDir, modelSpec, authPath) {
     const provider = providerOf(modelSpec);
-    const source = await probeAuthSource(createPiModels({ authPath }), modelSpec);
+    const models = await createPiModelRuntime({ agentDir, authPath }).catch(failStartup);
+    const source = await probeAuthSource(models, modelSpec);
     // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
     // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
     const stored = source === undefined
@@ -107,7 +110,9 @@ export async function resolveFirstRunModel(agentDir, options = {}) {
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
     const authPath = resolveAuthPath(agentDir, options.authPath);
-    const models = createPiModels({ authPath });
+    // The picker lists the AGENT's surface: built-ins plus whatever its models.json declares, so a
+    // self-hosted endpoint is pickable on first run instead of being invisible until hand-set.
+    const models = await createPiModelRuntime({ agentDir, authPath }).catch(failStartup);
     const chosen = await pickWithCredentials(models, authPath);
     if (chosen === undefined)
         return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
@@ -208,6 +213,8 @@ seams = {}) {
  * more than keeping a doubtful one.
  */
 async function verifyApiKeyLogin(provider, authPath, spec) {
+    // Built-ins only: `login` itself offers built-in providers (login.ts), and a models.json endpoint
+    // authenticates from its own `apiKey` (env/command), so there is no stored credential to verify here.
     const models = createPiModels({ authPath });
     const model = spec ? resolveModel(models, spec) : models.getProvider(provider)?.getModels()[0];
     if (!model) {

package/dist/collect.d.ts

@@ -1,8 +1,13 @@
 /**
- * Caller-side stream helpers: `collect` (buffered consumption, SPEC §7) reduces an AgentEvent
- * stream to a final value, encoding the terminal discipline (failed → throw, missing terminal →
- * error) — streaming consumers for-await themselves. `abortFirstIterator` is the shared
- * cancellation protocol for generator-backed streams.
+ * Stream helpers around the SPEC's two stream disciplines.
+ *
+ * Caller side: `collect` (buffered consumption, SPEC §7) reduces an AgentEvent stream to a final
+ * value, encoding the terminal discipline (failed → throw, missing terminal → error) — streaming
+ * consumers for-await themselves.
+ *
+ * Agent side: the cancellation protocol (SPEC MUST 3), in two halves that only work together —
+ * `abortFirstIterator` delivers the consumer's knock, `cancellableStream` is what an engine wraps
+ * its turn in to receive it.
  */
 import type { AgentEvent, Json } from "./agent.ts";
 /**
@@ -13,8 +18,29 @@ import type { AgentEvent, Json } from "./agent.ts";
  * settles the suspension), then delegates to `gen.return`, swallowing its rejection (the
  * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
  * and rethrows the caller's error deterministically instead of poking a completed generator.
+ *
+ * Cancellation also SILENCES the stream, and that belongs here rather than in each producer: a
+ * generator parked in an await can still reach a `yield` on its way out (an error path that
+ * yields a terminal, say), and that yield satisfies the pending `next()` — handing a terminal
+ * event to a consumer that already walked away, which SPEC MUST 3 forbids. Deciding it once, at
+ * the protocol boundary, is what keeps every producer from having to re-ask "is anyone still
+ * listening?" before each yield.
  */
 export declare function abortFirstIterator<T>(gen: AsyncGenerator<T>, cancel: () => void): AsyncIterator<T>;
+/** What a turn generator gets so a consumer walking away can stop it. */
+export interface CancelHooks {
+    /** Publish the door: how to abort the engine work, once there is engine work to abort. */
+    onCancelReady: (cancel: () => void) => void;
+    /** The latch, for the window where the door is armed but the engine is still idle — knocking then
+     *  does nothing, so a turn must read this before committing to work no one is waiting for. */
+    wasCancelled: () => boolean;
+}
+/**
+ * Wrap a turn generator in the cancellation protocol: cancelling the returned stream latches the
+ * intent AND knocks on whatever door the generator published, in that order (the latch must be set
+ * before the knock, or a turn checking it mid-flight could miss the cancel it just received).
+ */
+export declare function cancellableStream<T>(start: (hooks: CancelHooks) => AsyncGenerator<T>): AsyncIterable<T>;
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export declare class AgentFailure extends Error {

package/dist/collect.js

@@ -6,22 +6,55 @@
  * settles the suspension), then delegates to `gen.return`, swallowing its rejection (the
  * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
  * and rethrows the caller's error deterministically instead of poking a completed generator.
+ *
+ * Cancellation also SILENCES the stream, and that belongs here rather than in each producer: a
+ * generator parked in an await can still reach a `yield` on its way out (an error path that
+ * yields a terminal, say), and that yield satisfies the pending `next()` — handing a terminal
+ * event to a consumer that already walked away, which SPEC MUST 3 forbids. Deciding it once, at
+ * the protocol boundary, is what keeps every producer from having to re-ask "is anyone still
+ * listening?" before each yield.
  */
 export function abortFirstIterator(gen, cancel) {
+    let cancelled = false;
+    const teardown = async () => {
+        cancelled = true;
+        cancel();
+        await gen.return(undefined).catch(() => { });
+    };
     return {
-        next: () => gen.next(),
-        async return(value) {
-            cancel();
-            await gen.return(value).catch(() => { });
+        async next() {
+            const result = await gen.next();
+            return cancelled ? { done: true, value: undefined } : result;
+        },
+        async return() {
+            await teardown();
             return { done: true, value: undefined };
         },
         async throw(error) {
-            cancel();
-            await gen.return(undefined).catch(() => { });
+            await teardown();
             throw error;
         },
     };
 }
+/**
+ * Wrap a turn generator in the cancellation protocol: cancelling the returned stream latches the
+ * intent AND knocks on whatever door the generator published, in that order (the latch must be set
+ * before the knock, or a turn checking it mid-flight could miss the cancel it just received).
+ */
+export function cancellableStream(start) {
+    let door;
+    let cancelled = false;
+    const iterator = abortFirstIterator(start({
+        onCancelReady: (cancel) => {
+            door = cancel;
+        },
+        wasCancelled: () => cancelled,
+    }), () => {
+        cancelled = true;
+        door?.();
+    });
+    return { [Symbol.asyncIterator]: () => iterator };
+}
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export class AgentFailure extends Error {

package/dist/core.d.ts

@@ -1,12 +1,10 @@
 export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.ts";
 export { collect, AgentFailure, type CollectResult } from "./collect.ts";
 export type { ModuleLoadFailure } from "./loader.ts";
-export { createInvokeHandler, nodeListener } from "./channels/http.ts";
-export { controlRoutes, type ControlRoutesOptions, type WireEvent } from "./channels/control.ts";
+export { createInvokeHandler } from "./channels/http.ts";
+export type { WireEvent } from "./channels/control.ts";
 export { ControlRequestError, connectAgent, connectSessionControl, type RemoteEndpointOptions, } from "./session-remote.ts";
 export { readBodyCapped } from "./channels/body.ts";
 export { text, textHeaders } from "./channels/respond.ts";
-export { type ChannelContext, type ChannelHandler, type ChannelModule, type LongConnection, type LongConnectionChannelModule, type Routes, router, serveNode, } from "./host/node.ts";
+export type { ChannelContext, ChannelHandler, ChannelModule, LongConnection, LongConnectionChannelModule, Routes, } from "./channel.ts";
 export { defineSchedule, type LoadedSchedule, type Schedule } from "./schedule/schedule.ts";
-export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.ts";
-export { createScheduler, scheduleSession, type Scheduler, type SchedulerOptions } from "./schedule/scheduler.ts";

package/dist/core.js

@@ -1,10 +1,12 @@
 export { collect, AgentFailure } from "./collect.js";
-export { createInvokeHandler, nodeListener } from "./channels/http.js";
-export { controlRoutes } from "./channels/control.js";
+export { createInvokeHandler } from "./channels/http.js";
 export { ControlRequestError, connectAgent, connectSessionControl, } from "./session-remote.js";
 export { readBodyCapped } from "./channels/body.js";
 export { text, textHeaders } from "./channels/respond.js";
-export { router, serveNode, } from "./host/node.js";
+// Mounting only. Composing a route table (`router`) and owning a prefix (`PrefixMount`) are how
+// `createAgentService` assembles a service — not something a caller has to reproduce.
+// Binding to a Node server lives at `/node`: it is the only runtime-specific piece here, and the
+// only one that costs a third-party package.
+// `defineSchedule` is what a `schedules/*.ts` file is written against. Discovering those files and
+// running the clock is what `createAgentService` does with them — parts a caller does not reproduce.
 export { defineSchedule } from "./schedule/schedule.js";
-export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.js";
-export { createScheduler, scheduleSession } from "./schedule/scheduler.js";

package/dist/deploy/preflight.d.ts

@@ -19,9 +19,15 @@ interface DeployFacts {
      *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
      *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */
     hasTimeTriggers: boolean;
-    /** What satisfies model auth locally ({@link probeAuthSource}) — an env-var name, an OAuth/stored label,
-     *  or undefined. Drives the runbook's secret guidance and `--run`'s credential carry. */
+    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. Drives the
+     *  runbook's secret guidance and `--run`'s credential carry. For a models.json endpoint keyed from the
+     *  environment this is the VARIABLE NAME (see {@link modelCredentialCarry}), not the display label, so
+     *  the value carries like any provider key. */
     modelAuth: string | undefined;
+    /** The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on
+     *  the host), so there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot
+     *  serve a custom provider, so gating on it would strand a correctly configured agent. */
+    modelKeyInDefinition: boolean;
     /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
     authPath: string;
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */