@fastagent-sh/fastagent 0.17.0 → 0.18.0

package/dist/channels/invoke-turn-kit.js

@@ -33,13 +33,17 @@ export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
  * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
  * is ever re-run.
  */
-export async function* streamTurnWithBusyRetry(agent, session, prompt, options) {
+export async function* streamTurnWithBusyRetry(agent, 
+/** The full scope, not a session string — channels that set extension fields (lineage) pass them
+ *  through here; channels that don't pass `{ session }` and nothing changes. */
+scope, prompt, options) {
     const { label, onCompleted, busyRetry = DEFAULT_BUSY_RETRY } = options;
+    const session = scope.session;
     const deadline = Date.now() + busyRetry.maxWaitMs;
     for (;;) {
         let retryBusy = false;
         let first = true;
-        for await (const e of agent.invoke({ session }, prompt)) {
+        for await (const e of agent.invoke(scope, prompt)) {
             if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
                 retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
                 break;

package/dist/channels/lark/scaffold/lark-send.ts

@@ -56,12 +56,15 @@ async function tenantToken(): Promise<string> {
 
 export default defineTool({
   description:
-    "Send a message to a Lark chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
-    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
-    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
-    "answer (it would post the message twice). chatId comes from the [lark: chat …] context line in a " +
-    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
+    "Send a message to a Lark chat, OUTSIDE the normal reply path. Call it only for a turn NO " +
+    "channel is carrying — a scheduled or self-scheduled (wake) turn, whose plain reply goes " +
+    "nowhere — or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
+    "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
+    "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
+    "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
+    "or memory); the [lark: chat …] context line only identifies the chat you are answering — the " +
+    "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
+    "`markdown` (rendered as a card: headings, bold, code blocks, links).",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),

package/dist/channels/slack/invoke-turn.js

@@ -59,5 +59,5 @@ export async function* invokeSlackTurn(agent, session, text, transport, attachme
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
+    yield* streamTurnWithBusyRetry(agent, { session }, prompt, { label: transport.label, onCompleted, busyRetry });
 }

package/dist/channels/slack/slack.js

@@ -7,7 +7,7 @@ import { text } from "../respond.js";
 import { createSeenRing } from "../seen.js";
 import { createThreadParticipants } from "../thread-participants.js";
 import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome, removeRetiredStateFile } from "../state.js";
+import { ensureStateHome } from "../state.js";
 import { dispatchStop, isStopText } from "../stop-command.js";
 import { codePointPrefix } from "../text.js";
 import { createTurnQueue } from "../turn-queue.js";
@@ -141,10 +141,6 @@ export function slackChannel(options) {
          *  under a custom route is the `routed.session === undefined` condition on the write, not the
          *  absence of a route: a route that supplies its own session records nothing here. */
         const threadKey = (teamId, channelId, threadTs) => `slack:${teamId}:${channelId}:${threadTs}`;
-        // The participant model replaced the owned-thread index (a cache, so nothing is lost). REMOVE THIS
-        // after the release following the participant model ships — by then no live deployment can still
-        // be carrying the file. test/migration-deadline.test.ts fails when due.
-        removeRetiredStateFile(stateHome, "owned-threads.json", label);
         const welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
         const buffer = createSlackContextBuffer(join(stateHome, "buffers.json"), label);
         const store = createTurnStore(join(stateHome, "turns.json"), {

package/dist/channels/state.d.ts

@@ -4,13 +4,3 @@ export declare function ensureStateHome(dir: string): void;
  *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
 export declare function loadStateFile(path: string): unknown;
 export declare function saveStateFile(path: string, value: unknown): void;
-/**
- * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
- * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
- * whose loss changes behaviour needs a migration, not a delete.
- *
- * Shared because a retired file is usually retired in every channel at once: one best-effort
- * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
- * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
- */
-export declare function removeRetiredStateFile(stateHome: string, name: string, label: string): void;

package/dist/channels/state.js

@@ -12,8 +12,8 @@
  * is an ENVIRONMENT error the operator must fix: it throws, and construction fails loudly — booting
  * with silently-empty state would hide real data behind a config mistake.
  */
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { log } from "../log.js";
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
@@ -48,20 +48,3 @@ export function saveStateFile(path, value) {
     writeFileSync(tmp, JSON.stringify(value));
     renameSync(tmp, path);
 }
-/**
- * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
- * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
- * whose loss changes behaviour needs a migration, not a delete.
- *
- * Shared because a retired file is usually retired in every channel at once: one best-effort
- * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
- * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
- */
-export function removeRetiredStateFile(stateHome, name, label) {
-    try {
-        rmSync(join(stateHome, name), { force: true });
-    }
-    catch (error) {
-        log.debug(`${label} could not remove the obsolete ${name}: ${String(error)}`);
-    }
-}

package/dist/channels/telegram/invoke-turn.js

@@ -76,5 +76,5 @@ export async function* invokeTurn(agent, session, text, transport, attachments,
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, images: resolved.images };
-    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: "[telegram]", onCompleted, busyRetry });
+    yield* streamTurnWithBusyRetry(agent, { session }, prompt, { label: "[telegram]", onCompleted, busyRetry });
 }

package/dist/channels/thread-participants.d.ts

@@ -6,6 +6,13 @@ export interface ThreadParticipants {
      * get wrong twice, and "a second human restores the mention requirement" must have one place to change.
      */
     admitsBareMessage(key: string): boolean;
+    /**
+     * Has the agent answered into this thread before — the "first answered turn" fact
+     * (participant-model.md §8), unlike {@link ThreadParticipants.admitsBareMessage} which also weighs
+     * the second-human rule. An evicted record answers false (this store is a cache — see the header),
+     * so gate a repeatable read on it, never a durable claim.
+     */
+    agentSpokeIn(key: string): boolean;
     /**
      * Merge in what was just heard. Idempotent; a failed write is a warning, never a failed delivery.
      *

package/dist/channels/thread-participants.js

@@ -68,6 +68,9 @@ export function createThreadParticipants(path, label) {
             const heard = records.get(key);
             return heard?.agentSpoke === true && heard.humans.length <= 1;
         },
+        agentSpokeIn(key) {
+            return records.get(key)?.agentSpoke === true;
+        },
         merge(key, heard) {
             const previous = records.get(key);
             const humans = new Set(previous?.humans ?? []);

package/dist/cli/commands/deploy.js

@@ -76,7 +76,7 @@ export async function runDeploy(host, dirArg, opts) {
         failStartup(new Error(`deploy stopped: ${pre.gate}`));
     for (const m of pre.messages)
         console.error(`[fastagent] ${m.level}: ${m.text}`);
-    const { channels, routeChannels, longConnectionChannels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets, } = pre;
+    const { channels, routeChannels, longConnectionChannels, hasTimeTriggers, modelAuth, modelKeyInDefinition, authPath, container, port, extraSecrets, } = pre;
     const hasDeclaredChannels = routeChannels.length + longConnectionChannels.length > 0;
     // Docker: one app service + loopback port + state volume. `--tunnel` shapes the generated topology
     // with an optional Quick Tunnel service; `--run` alone decides whether Docker receives side effects.
@@ -126,6 +126,7 @@ export async function runDeploy(host, dirArg, opts) {
                 port,
                 requireTunnel: requestedTunnel,
                 modelAuth,
+                modelKeyInDefinition,
                 authPath,
                 channels,
                 longConnectionChannels,
@@ -176,6 +177,7 @@ export async function runDeploy(host, dirArg, opts) {
                 workspace,
                 name: serviceName,
                 modelAuth,
+                modelKeyInDefinition,
                 authPath,
                 channels,
                 longConnectionChannels,
@@ -278,6 +280,7 @@ export async function runDeploy(host, dirArg, opts) {
                 agentPrefix: container.agentPrefix,
                 name: acName,
                 modelAuth,
+                modelKeyInDefinition,
                 authPath,
                 channels,
                 extraSecrets,
@@ -371,6 +374,7 @@ export async function runDeploy(host, dirArg, opts) {
             agentPrefix: container.agentPrefix,
             appName,
             modelAuth,
+            modelKeyInDefinition,
             authPath,
             channels,
             longConnectionChannels,
@@ -468,9 +472,10 @@ function deployEnvironment(agentDir, channels) {
  * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
  */
 async function runDeployDocker(params) {
-    const { agentDir, workspace, composeFile, port, requireTunnel, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, } = params;
+    const { agentDir, workspace, composeFile, port, requireTunnel, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, extraSecrets, } = params;
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,
@@ -511,7 +516,7 @@ async function runDeployDocker(params) {
  * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the whole workspace).
  */
 async function runDeployFly(params) {
-    const { agentDir, workspace, agentPrefix, appName, modelAuth, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets, } = params;
+    const { agentDir, workspace, agentPrefix, appName, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets, } = params;
     const fly = spawnRunner("fly", workspace);
     // Fail fast if flyctl is absent (spawn ENOENT → 127), with the install link — not a confusing auth gate.
     if ((await fly(["version"], { capture: true })).code === 127) {
@@ -520,6 +525,7 @@ async function runDeployFly(params) {
     const region = parseFlyRegion(await readFile(flyTomlPath, "utf8")) ?? "iad";
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,
@@ -553,9 +559,10 @@ async function runDeployFly(params) {
  * file (secret values off argv) is created here — 0600, removed after the run either way.
  */
 async function runDeployAgentcore(params) {
-    const { agentDir, workspace, agentPrefix, name, modelAuth, authPath, channels, extraSecrets, selfSchedule } = params;
+    const { agentDir, workspace, agentPrefix, name, modelAuth, modelKeyInDefinition, authPath, channels, extraSecrets, selfSchedule, } = params;
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         extraSecrets,
@@ -627,7 +634,7 @@ async function runDeployAgentcore(params) {
  * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
  */
 async function runDeployRailway(params) {
-    const { agentDir, workspace, name, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, intoLinked, dockerfilePath, } = params;
+    const { agentDir, workspace, name, modelAuth, modelKeyInDefinition, authPath, channels, longConnectionChannels, extraSecrets, intoLinked, dockerfilePath, } = params;
     const railway = spawnRunner("railway", workspace);
     // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
     if ((await railway(["--version"], { capture: true })).code === 127) {
@@ -635,6 +642,7 @@ async function runDeployRailway(params) {
     }
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
+        modelKeyInDefinition,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
         longConnectionChannels,

package/dist/cli/commands/dev.js

@@ -56,7 +56,7 @@ async function serveOnce(dir, opts) {
     reportWorkspaceHint(workspaceHint(a));
     reportLine("config", a.configPath ?? "(none)");
     reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
-    await reportAuth(a.modelSpec, a.authPath);
+    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
     reportAgentsSkillsTools(a);
     // Trace each turn's agent loop (tool calls + reply) to the log at debug level — shown in dev, gated
     // out in start (level info), keeping end-user content out of production logs. Wired in both postures.

package/dist/cli/commands/fire.js

@@ -37,7 +37,7 @@ export async function runFire(name, dirArg, opts) {
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);
     console.error(`[fastagent] fire: ${name} (${modelSpec})`);
-    await reportAuth(modelSpec, authPath);
+    await reportAuth(placement.agentDir, modelSpec, authPath);
     const exitCode = await runInvokeStream(agent.invoke({ session: scheduleSession(name) }, { text: schedule.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));
     process.stdout.write("\n");
     process.exit(exitCode);

package/dist/cli/commands/info.js

@@ -2,7 +2,8 @@
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { discoverChannelFiles } from "../../engines/pi/channel.js";
-import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, resolveSessionsDirOverride, } from "../../engines/pi/config.js";
+import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModel, resolveModelSpec, resolveSessionsDirOverride, } from "../../engines/pi/config.js";
+import { createPiModelRuntime } from "../../engines/pi/models.js";
 import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
@@ -55,12 +56,27 @@ export async function runInfo(dirArg, opts) {
     const stateRoot = resolveStateRoot(agentDir);
     const sessionsDir = resolveSessionsDirOverride(opts.sessionsDir) ?? defaultSessionsDir(stateRoot);
     const authPath = resolveAuthPath(agentDir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
+    // RESOLVE the spec, do not just echo it: a spec is only real once its provider/model exist in the
+    // agent's own surface (built-ins + its models.json), which is exactly what a custom endpoint changes.
+    // Reporting a healthy-looking spec that `dev`/`start` then reject is the failure this pre-empts.
+    // Reported as DATA rather than thrown — a broken agent is what `info` is for — and read-only: the
+    // runtime reads models.json without creating anything (its catalog cache is written on refresh, and
+    // there is none here).
+    const modelError = modelSpec
+        ? await createPiModelRuntime({ agentDir, authPath })
+            .then((models) => {
+            resolveModel(models, modelSpec);
+            return undefined;
+        })
+            .catch((error) => error.message)
+        : undefined;
     if (opts.json) {
         console.log(JSON.stringify({
             agentDir,
             workspace,
             configPath: configPath ?? null,
             model: modelSpec ?? null,
+            modelError: modelError ?? null,
             thinkingLevel: config.thinkingLevel ?? null,
             context: definition.contextFiles.map((f) => f.path),
             persona: definition.persona !== undefined,
@@ -85,6 +101,8 @@ export async function runInfo(dirArg, opts) {
     // One padded label writer: hand-spaced labels drifted out of alignment the moment a longer one
     // (agent/workspace/selfSchedule) joined the report.
     const line = (label, value) => console.log(`${`${label}:`.padEnd(13)} ${value}`);
+    /** A continuation under the previous line, aligned to the same column (no label, so no bare colon). */
+    const cont = (value) => console.log(`${"".padEnd(13)} ${value}`);
     line("agent", agentDir);
     line("workspace", workspace);
     const hint = workspaceHint({ agentDir, workspace });
@@ -92,6 +110,8 @@ export async function runInfo(dirArg, opts) {
         line("hint", hint);
     line("config", configPath ?? "(none)");
     line("model", modelSpec ?? "(not set — pass --model, set FASTAGENT_MODEL, or config.model)");
+    if (modelError)
+        cont(`⚠ does not resolve: ${modelError}`);
     if (config.thinkingLevel)
         line("thinking", config.thinkingLevel);
     line("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");

package/dist/cli/commands/invoke.js

@@ -20,7 +20,7 @@ export async function runInvoke(message, dirArg, opts) {
     // BOTH directories, like dev/start: from the workspace, `placement.workspace` alone equals the dir you
     // typed, so it cannot tell you which agent actually ran.
     console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
-    await reportAuth(modelSpec, authPath);
+    await reportAuth(placement.agentDir, modelSpec, authPath);
     // Fresh session per invoke (one-shot, no resume). runInvokeStream maps events→IO: reply→stdout,
     // tool/failure→stderr, exit 1 iff the turn failed (so CI can gate on it).
     const exitCode = await runInvokeStream(agent.invoke({ session: randomUUID() }, { text: message }), (text) => process.stdout.write(text), (line) => console.error(line));

package/dist/cli/commands/start.js

@@ -18,6 +18,7 @@ import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { exists } from "../../paths.js";
 import { bindAddress } from "../../bind.js";
+import { parseRouteKey } from "../../host/node.js";
 import { failStartup, placementOrExit } from "../fail.js";
 import { assertTunnelBindable, maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules, } from "../serve.js";
 import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
@@ -48,7 +49,7 @@ export async function runStart(dirArg, opts) {
     reportLine("workspace", workspace);
     reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
     reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
-    await reportAuth(modelSpec, authPath);
+    await reportAuth(agentDir, modelSpec, authPath);
     reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (definition.persona)
         reportLine("persona", "persona.md");
@@ -89,13 +90,21 @@ export async function runStart(dirArg, opts) {
     const agentcore = process.env.FASTAGENT_AGENTCORE === "1";
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
-    const routed = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: !agentcore }).catch(failStartup);
+    // On AgentCore the channels are constructed LAZILY (mountAgentcore's lazyChannels, resolved on the
+    // first envelope after the state-snapshot restore): construction loads channel state and replays
+    // turn intent, and at boot the state mount is PRE-RESTORE — empty after every version update — so
+    // an eager build would cache that emptiness (thread participation, delivery dedup, pending turns)
+    // and then clobber the restored files with it. Everywhere else the state root is durable at boot,
+    // so channels mount eagerly and a broken channel fails startup.
+    const routed = agentcore
+        ? undefined
+        : await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: true }).catch(failStartup);
     // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
     // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
     const configured = config.http?.host;
     const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
     assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
-    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
+    const withControl = mountSessionControl(routed?.routes ?? {}, sessionControl, stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced,
         host,
@@ -126,17 +135,42 @@ export async function runStart(dirArg, opts) {
     });
     let routes = withControl.routes;
     if (agentcore) {
+        // The lazy channel surface the adapter resolves post-restore. Control routes ride along so a
+        // forwarder-relayed /control/* request dispatches the same as on a direct host. Long-connection
+        // channels cannot serve here — scale-to-zero severs a resident connection and nothing
+        // re-establishes it — so their presence is a configuration error, surfaced per envelope and by
+        // the deploy driver's health probe (there is no boot to fail on this host).
+        const lazyChannels = async () => {
+            const surface = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: false });
+            if (surface.longConnections.length > 0) {
+                throw new Error(`long-connection channel(s) ${surface.longConnections.map((c) => c.name).join(", ")} cannot serve on ` +
+                    `AgentCore (scale-to-zero severs resident connections) — use the channel's webhook form`);
+            }
+            // mountSessionControl's PATH-level collision rule, re-asserted here: with no channels at boot
+            // its own check ran against an empty base, and a spread merge would silently let control win —
+            // but a channel on /control/* is the same configuration error it is on every other host.
+            const controlPaths = new Set(Object.keys(withControl.routes).map((key) => parseRouteKey(key).path));
+            const collisions = Object.keys(surface.routes).filter((key) => controlPaths.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 { ...surface.routes, ...withControl.routes };
+        };
         try {
-            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady });
+            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady, lazyChannels });
         }
         catch (e) {
             failStartup(e);
         }
         log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     }
-    serve({ ...routed, routes }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
+    serve({
+        ...(routed ?? { longConnections: [], routeChannels: [], builtinInvoke: false, markReady() { } }),
+        routes,
+    }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
-        maybeTunnel(agentDir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
+        maybeTunnel(agentDir, routed?.routeChannels ?? [], p, opts.tunnel ?? false, stateRoot);
     });
     // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
     // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK

package/dist/cli/serve.d.ts

@@ -49,6 +49,10 @@ export declare function mountAgentcore(routes: Routes, options: {
     stateRoot: string;
     schedules: LoadedSchedule[];
     onStateReady?: () => void;
+    /** The serving path's LAZY channel surface: constructed by the adapter on the first envelope
+     *  AFTER the state-snapshot restore, never at boot (channels/agentcore.ts). When absent,
+     *  `routes` is the dispatch target — for wirings whose state root is already authoritative. */
+    lazyChannels?: () => Promise<Routes>;
 }): Routes;
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`

package/dist/cli/serve.js

@@ -151,9 +151,9 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
  * 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 } = options;
+    const { agent, stateRoot, schedules, onStateReady, lazyChannels } = options;
     const mounted = agentcoreRoutes({
-        routes,
+        routes: lazyChannels ?? routes,
         agent,
         stateRoot,
         isBusy: () => activeWork() > 0,

package/dist/cli/shared.d.ts

@@ -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";
@@ -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 {