@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/cli/models-view.js

@@ -0,0 +1,66 @@
+/**
+ * CLI presenter for the model-facing commands: `fastagent models [search]` output and the first-run
+ * picker's option list. Output DECISIONS live here, out of the engine config layer (config.ts owns
+ * model resolution / listModels), so this process-boundary behavior is unit-testable without
+ * spawning the CLI.
+ */
+import { providerOf } from "../engines/pi/config.js";
+/** The remedy hint for a non-ready provider, by what picking it actually does: an OAuth flow →
+ *  "login required"; an interactive key prompt → "API key required"; no flow at all → the env var. */
+function remedy(login) {
+    if (login === "oauth")
+        return "login required";
+    return login === "api_key" ? "API key required" : "API key required — set the provider's env var";
+}
+/**
+ * The first-run picker menu: the FULL model catalog, each spec annotated with its provider's auth
+ * status — ready first (usable now, with the credential source so "which account pays" is visible at
+ * the decision point), then the rest with their remedy. Order within each group preserves `specs`
+ * (sorted by the caller). A broken provider (expired/corrupt credential) is annotated, not dropped —
+ * fail visibly.
+ */
+export function buildModelPickerOptions(specs, statuses) {
+    const ready = [];
+    const rest = [];
+    for (const spec of specs) {
+        const status = statuses.get(providerOf(spec));
+        if (status?.state === "ready") {
+            ready.push({ value: spec, label: spec, hint: status.source ? `ready — ${status.source}` : "ready" });
+        }
+        else if (status?.state === "broken") {
+            // A broken stored credential OWNS the provider (env is consulted only when nothing is stored),
+            // so with no login flow the remedy is fixing the store — not the env var (which can't win here).
+            rest.push({
+                value: spec,
+                label: spec,
+                hint: status.login === "none"
+                    ? `stored auth unusable: ${status.message} — fix or remove the stored credential`
+                    : `${remedy(status.login)} — stored auth unusable: ${status.message}`,
+            });
+        }
+        else if (status) {
+            rest.push({ value: spec, label: spec, hint: remedy(status.login) });
+        }
+        else {
+            // Unreachable when `specs` and `statuses` come from the same Models (every listed provider is
+            // probed); if a caller ever mixes sources, promise nothing — neutral wording, no login claim.
+            rest.push({ value: spec, label: spec, hint: "auth required" });
+        }
+    }
+    return [...ready, ...rest];
+}
+/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
+ *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
+export function formatModelsCommand(specs, search) {
+    if (!search)
+        return { lines: specs };
+    const q = search.toLowerCase();
+    const matches = specs.filter((spec) => spec.toLowerCase().includes(q));
+    if (matches.length === 0)
+        return { lines: matches, error: `no model matches "${search}"` };
+    // Rank a PROVIDER-name match (query in the part before "/") above an incidental model-id match, so
+    // `models anthropic` leads with anthropic/* rather than burying it under amazon-bedrock/anthropic.*
+    // and google-vertex/…-anthropic-… (which only match in the model id). Order within each group is kept.
+    const providerMatch = (spec) => providerOf(spec).toLowerCase().includes(q);
+    return { lines: [...matches.filter(providerMatch), ...matches.filter((s) => !providerMatch(s))] };
+}

package/dist/cli/program.js

@@ -26,7 +26,7 @@ const PORT = { flags: "--port <n>", description: "HTTP port" };
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
-        "webhook channels (telegram, feishu, lark; github prints the URL) — for hosting a bot from your " +
+        "webhook channels (telegram, onboarded slack, feishu, lark; github/manual slack print the URL) — for hosting a bot from your " +
         "own box without deploying (the quick-tunnel URL is ephemeral, not for production)",
 };
 const init = {
@@ -77,7 +77,7 @@ const dev = {
     ],
     examples: [
         { cmd: "fastagent dev" },
-        { cmd: "fastagent dev --tunnel", note: "public URL + auto-registered webhooks" },
+        { cmd: "fastagent dev --tunnel", note: "public URL + registered/guided webhooks" },
     ],
     run: async (args, f) => (await import("./commands/dev.js")).runDev(args[0], {
         port: f.port,
@@ -88,16 +88,38 @@ const dev = {
         input: f.input !== false,
     }),
 };
+const attach = {
+    name: "attach",
+    summary: "watch a session's live events from a running serve and steer it",
+    description: "Attach to a session served by a running dev/start with `sessionControl: true` in the config: " +
+        "stream its live events (text, tools, run boundaries), steer the active run by typing — or, with " +
+        "no run active, start one (detaching cancels a run YOU started) — /abort to stop a run. Discovers " +
+        "the local endpoint from <stateRoot>/control.json; --url/--token reach a remote serve. The same " +
+        "wire protocol a Web panel or desktop app uses.",
+    args: [{ name: "<session>", description: "the session id to attach to" }, DIR_ARG],
+    flags: [
+        { flags: "--url <url>", description: "control endpoint (skip control.json discovery)" },
+        { flags: "--token <token>", description: "bearer token for --url" },
+    ],
+    examples: [{ cmd: "fastagent attach tg-chat-42" }],
+    run: async (args, f) => (await import("./commands/attach.js")).runAttach(args[0], args[1], {
+        url: f.url,
+        token: f.token,
+    }),
+};
 const chat = {
     name: "chat",
     summary: "open the SAME assembled agent in pi's interactive TUI",
     description: "Open the SAME assembled agent in pi's interactive TUI (the real harness, not a crude REPL) — to " +
-        "try it locally before serving. Same model/tool/skill resolution as dev; pi handles login, " +
-        "sessions, and /resume natively.",
+        "try it locally before serving. Same model/tool/skill/auth resolution as dev; pi handles " +
+        "rendering, sessions, and /resume natively (its /login writes to the same fastagent auth file).",
     args: [DIR_ARG],
-    flags: [MODEL],
+    flags: [MODEL, AUTH_PATH],
     examples: [{ cmd: "fastagent chat" }],
-    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], { model: f.model }),
+    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], {
+        model: f.model,
+        authPath: f.authPath,
+    }),
 };
 const info = {
     name: "info",
@@ -211,37 +233,70 @@ const start = {
 };
 /** The retired app-creation flag — parsed so it can explain itself, hidden from help. */
 const CREATE_APP = { flags: "--create-app", description: "(retired)", hidden: true };
+const INGRESS = {
+    flags: "--ingress <mode>",
+    description: "Feishu/Lark ingress: websocket or webhook (interactive when omitted)",
+};
+const GROUP_BEHAVIOR = {
+    flags: "--group-behavior <behavior>",
+    description: "Slack/Feishu/Lark groups: context (recommended) or mentions (least privilege)",
+};
+const NO_ONBOARD = {
+    flags: "--no-onboard",
+    description: "Slack: scaffold only; skip internal-app creation/OAuth",
+};
+const REPLACE_CONFIG = {
+    flags: "--replace-config",
+    description: "Slack: replace the local App Configuration token pair (repairs automatic dev/deploy Request URL " +
+        "updates after the tokens expire or are revoked; runs on the machine that onboarded the app)",
+};
 const channelSub = (kind, summary, description, notes) => ({
     name: kind,
     summary,
     description,
     args: [DIR_ARG],
-    flags: [CREATE_APP],
+    flags: [
+        CREATE_APP,
+        ...(kind === "feishu" || kind === "lark"
+            ? [INGRESS, GROUP_BEHAVIOR]
+            : kind === "slack"
+                ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
+                : []),
+    ],
     examples: [{ cmd: `fastagent add ${kind}` }],
     ...(notes ? { notes } : {}),
-    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], { createApp: f.createApp === true }),
+    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], {
+        createApp: f.createApp === true,
+        ingress: f.ingress,
+        groupBehavior: f.groupBehavior,
+        onboard: f.onboard !== false,
+        replaceConfig: f.replaceConfig === true,
+    }),
 });
 const add = {
     name: "add",
-    summary: "connect a channel (github, telegram, feishu, lark) or vendor a skill",
-    description: "Scaffold channels/<kind>.ts — third-party adapter glue with the policy to edit (github maps " +
-        "events in on(); telegram/feishu/lark route in the optional route()) — or vendor an Agent Skills " +
+    summary: "connect a channel (github, telegram, slack, feishu, lark) or vendor a skill",
+    description: "Scaffold channels/<kind>.ts — first-party adapter glue with the policy to edit (github maps " +
+        "events in on(); telegram/slack/feishu/lark route in the optional route()) — or vendor an Agent Skills " +
         "skill into skills/<name>/.",
     subcommands: [
         channelSub("github", "scaffold the GitHub webhook channel (issues/PRs → agent turns)", "Scaffold channels/github.ts — webhook adapter glue that maps repository events (issues, PRs, " +
             "comments) to agent turns in its on() policy."),
         channelSub("telegram", "scaffold the Telegram bot channel (durable turns, live preview)", "Scaffold channels/telegram.ts — the Telegram bot channel with durable turns, a live-preview " +
             "message pump, and an optional route() policy."),
-        channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Scaffold channels/feishu.ts AND create/configure the Feishu platform app (scan-to-create), " +
-            "writing credentials to .env.", "Feishu (open.feishu.cn) is the canonical implementation. `add feishu` also CREATES + " +
-            'configures the platform app (confirm a link in the app — the platform\'s "scan to create" ' +
-            "flow; one version-publish action remains) and writes credentials to .env; a persisted " +
-            "ID/Secret pair resumes missing-Token setup instead of creating another app."),
-        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Scaffold channels/lark.ts — the Lark international profile over the Feishu engine — and guide " +
-            "credential setup against the intl developer console.", "Lark international (open.larksuite.com) is Feishu's compatibility profile with degraded " +
-            "control-plane setup: opens the intl developer console only for a new/partial pair, validates " +
-            "App ID/Secret, then probes webhook-mode + Token automation; an explicit config-route 404 " +
-            "falls back to a hidden Token prompt + manual mode/URL setup."),
+        channelSub("slack", "scaffold the Slack Events API channel (files, threads, context, live preview)", "Choose group visibility, scaffold channels/slack.ts plus slack-send.ts, create a single-workspace " +
+            "internal Slack app from a manifest, and install it through OAuth. The channel provides signed " +
+            "Events API ingress, durable turns, files, managed threads, context, and an edited live preview.", "Automated onboarding requires Slack App Configuration access + refresh tokens and a temporary " +
+            "cloudflared tunnel. They stay in owner-readable local state and are never deployed; --no-onboard " +
+            "keeps the explicit manual/scaffold-only path."),
+        channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Choose WebSocket or webhook, scaffold channels/feishu.ts, and create/configure the Feishu app " +
+            "through scan-to-create, writing the matching credentials to .env.", "Feishu (open.feishu.cn) is the canonical implementation. WebSocket needs only App ID/Secret and " +
+            "no public URL; webhook additionally captures the Verification Token through a temporary tunnel. " +
+            "Context-aware groups (recommended) request admin approval for im:message.group_msg before publish."),
+        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Choose WebSocket or webhook, scaffold channels/lark.ts, and guide credential setup against the " +
+            "international developer console.", "Lark international (open.larksuite.com) is Feishu's compatibility profile. WebSocket stops after " +
+            "App ID/Secret validation; webhook and recommended context-aware group setup probe config " +
+            "automation and fall back to explicit manual steps on the international config-route 404."),
         {
             name: "skill",
             summary: "vendor an Agent Skills skill into skills/<name>/ (copied in, git-tracked)",
@@ -306,6 +361,7 @@ const deploy = {
         },
         MODEL,
         AUTH_PATH,
+        NO_INPUT,
     ],
     examples: [
         { cmd: "fastagent deploy fly --run", note: "provision + deploy + webhooks" },
@@ -324,6 +380,7 @@ const deploy = {
         intoLinked: f.intoLinked === true,
         model: f.model,
         authPath: f.authPath,
+        input: f.input !== false,
     }),
 };
 const schedule = {
@@ -395,6 +452,7 @@ export const specs = [
     schedule,
     dev,
     chat,
+    attach,
     start,
     add,
     deploy,

package/dist/cli/serve.d.ts

@@ -1,28 +1,48 @@
-/**
- * The serving spine shared by `dev` (its worker) and `start`: route assembly from discovered
- * channels/, the Node host binding, the scheduler lifecycle, and the optional Cloudflare quick
- * tunnel. Bodies moved verbatim from cli.ts; `values.tunnel` became a parameter.
- */
 import type { Agent } from "../agent.ts";
+import { type LoadedLongConnectionChannel } from "../engines/pi/channel.ts";
 import { type Routes } from "../host/node.ts";
+import type { SessionControl } from "../session.ts";
+export interface ServingSurface {
+    routes: Routes;
+    longConnections: LoadedLongConnectionChannel[];
+    /** Route-channel basenames; the tunnel registers only this subset. */
+    routeChannels: string[];
+    builtinInvoke: boolean;
+    /** Marks the built-in health route ready after every long-connection channel first connects. */
+    markReady(): void;
+}
+/**
+ * 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 declare function routesFor(workspaceDir: string, agent: Agent, stateRoot: string, control?: SessionControl): Promise<ServingSurface>;
 /**
- * The routes this deployment serves: a default `GET /health` plus the workspace's discovered
- * `channels/` — or the default invoke channel at POST /invoke when none are declared.
+ * Mount the session control plane (`/control/*`) when the workspace enabled it
+ * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
+ * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
+ * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
+ * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
+ * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
+ * (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 declare function routesFor(workspaceDir: string, agent: Agent, stateRoot: string): Promise<Routes>;
-/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
-export declare function serve(routes: Routes, port: number, onListening?: (boundPort: number) => void): void;
+export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
+    tunnel?: boolean;
+    agent?: Agent;
+}): {
+    routes: Routes;
+    announce: (boundPort: number) => void;
+};
 /**
- * Start a Cloudflare tunnel + announce/register webhooks once the server is bound — unless this is a
- * watch-supervisor worker, where the supervisor owns the long-lived tunnel so the public URL survives
- * reloads.
+ * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
+ * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
+ * the sole clean-shutdown command.
  */
-export declare function maybeTunnel(workspaceDir: string, boundPort: number, tunnel: boolean): void;
+export declare function serve(surface: ServingSurface, port: number, onListening?: (boundPort: number) => void): void;
+/** Start a Cloudflare tunnel for route channels only. */
+export declare function maybeTunnel(workspaceDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): void;
 /**
  * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on (the scheduler also polls the agent's self-scheduled
- * wake-ups, which the built-in `wake` tool creates only when opted in). Shares the SAME (trace-wrapped)
- * agent the routes serve, so a scheduled turn is observed like any other. Best-effort stop on exit; dev's
- * watch restart re-reads schedules with the worker (schedules are a code input). Single-process.
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals.
  */
 export declare function startSchedules(workspaceDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean): Promise<void>;

package/dist/cli/serve.js

@@ -1,4 +1,11 @@
-import { createInvokeHandler } from "../channels/http.js";
+/**
+ * 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.
+ */
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+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";
@@ -10,11 +17,15 @@ import { createScheduler } from "../schedule/scheduler.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup } from "./fail.js";
 /**
- * The routes this deployment serves: a default `GET /health` plus the workspace's discovered
- * `channels/` — or the default invoke channel at POST /invoke when none are declared.
+ * 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(workspaceDir, agent, stateRoot) {
-    const { routes, collisions, failures } = await loadChannels(workspaceDir, { agent, stateRoot });
+export async function routesFor(workspaceDir, agent, stateRoot, control) {
+    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(workspaceDir, {
+        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`);
     }
@@ -23,61 +34,208 @@ export async function routesFor(workspaceDir, agent, stateRoot) {
         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 channels = Object.keys(routes).length > 0 ? routes : { "POST /invoke": createInvokeHandler(agent) };
-    // Add a default GET /health unless a channel already covers it (overlap, not exact-key: an
-    // any-method `/health` also handles GET, so the built-in steps aside).
-    const healthCovered = Object.keys(channels).some((k) => {
-        const e = parseRouteKey(k);
-        return e.path === "/health" && (e.method === undefined || e.method === "GET");
+    const builtinInvoke = 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");
     });
-    return healthCovered ? channels : { "GET /health": () => text("ok\n", 200), ...channels };
+    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 workspace enabled it
+ * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
+ * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
+ * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
+ * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
+ * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
+ * (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://127.0.0.1:${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 (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.
+            log.warn("[fastagent] the port binds all interfaces: /control/* is reachable on your LAN, protected only by " +
+                "the bearer token — 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);
+        },
+    };
 }
-/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
-export function serve(routes, port, onListening) {
-    serveNode(router(routes), { port }).listening.then((boundPort) => {
-        process.send?.({ type: "ready", port: boundPort }); // tell the dev supervisor we bound + on which port
-        log.info(`[fastagent] http channel on :${boundPort}`);
-        log.info(`[fastagent] routes: ${Object.keys(routes).join(", ") || "(none)"}`);
-        onListening?.(boundPort);
+/**
+ * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
+ * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
+ * the sole clean-shutdown command.
+ */
+export function serve(surface, port, onListening) {
+    const hosted = serveNode(router(surface.routes), { port });
+    const abort = new AbortController();
+    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(() => {
+            clearTimeout(deadline);
+            process.exit(exitCode);
+        });
+        // 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)
+                return;
+            surface.markReady();
+            process.send?.({
+                type: "ready",
+                port: boundPort,
+                routeChannels: surface.routeChannels,
+            });
+            log.info(`[fastagent] http host on :${boundPort}`);
+            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(", ")}`);
+            }
+            if (surface.builtinInvoke) {
+                log.info(`[fastagent] try it: curl -s localhost:${boundPort}/invoke -X POST -H 'content-type: application/json' -d '${INVOKE_EXAMPLE_BODY}'`);
+            }
+            onListening?.(boundPort);
+        }
+        catch (error) {
+            abort.abort();
+            const closing = hosted.close().catch(() => { });
+            hosted.closeAllConnections();
+            await closing;
+            failStartup(error);
+        }
     }, (error) => {
         if (error.code === "EADDRINUSE")
             failStartup(new Error(`port ${port} is already in use; choose another with --port`));
         failStartup(new Error(`cannot bind http channel on :${port}: ${error.message}`));
     });
 }
-/**
- * Start a Cloudflare tunnel + announce/register webhooks once the server is bound — unless this is a
- * watch-supervisor worker, where the supervisor owns the long-lived tunnel so the public URL survives
- * reloads.
- */
-export function maybeTunnel(workspaceDir, boundPort, tunnel) {
+/** Start a Cloudflare tunnel for route channels only. */
+export function maybeTunnel(workspaceDir, routeChannels, boundPort, tunnel, stateRoot) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
-    void startCloudflareTunnel(boundPort).then((t) => {
-        if (!t)
+    void startCloudflareTunnel(boundPort).then((instance) => {
+        if (!instance)
             return;
-        void announceWebhooks(workspaceDir, t.url, { openUrl: openExternalUrl });
-        // Single-process (start / --no-watch): close the tunnel on exit (watch mode's supervisor owns its own).
-        const cleanup = () => {
-            t.close();
-            process.exit(0);
-        };
+        void announceWebhooks(workspaceDir, instance.url, { openUrl: openExternalUrl, routeChannels, stateRoot });
+        const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);
     });
 }
 /**
  * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on (the scheduler also polls the agent's self-scheduled
- * wake-ups, which the built-in `wake` tool creates only when opted in). Shares the SAME (trace-wrapped)
- * agent the routes serve, so a scheduled turn is observed like any other. Best-effort stop on exit; dev's
- * watch restart re-reads schedules with the worker (schedules are a code input). Single-process.
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals.
  */
 export async function startSchedules(workspaceDir, agent, stateRoot, selfSchedule) {
     const { schedules, failures } = await loadSchedules(workspaceDir).catch(failStartup);
     reportModuleLoadFailures(failures);
-    // Nothing to run when there are neither static `schedules/` nor self-scheduling (the `wake` tool, and
-    // thus any wake-up to poll, is mounted only when config.selfSchedule is on) — skip the poller entirely.
     if (schedules.length === 0 && !selfSchedule)
         return;
     const scheduler = createScheduler({ agent, stateRoot, schedules });

package/dist/cli/shared.d.ts

@@ -1,3 +1,4 @@
+import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/login.ts";
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export declare function isInteractive(): boolean;
 /**
@@ -10,15 +11,34 @@ export declare function parsePort(value: string | undefined, source: string, fro
 /** 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>;
 /**
- * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
- * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
- * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
- * configured it stays silent and lets the opener raise its clear "missing model" error. The pick is
- * exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it, and best-effort written back to
- * the config so the next run is quiet.
+ * 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
+ * catalog annotated per provider — ready (with the credential source, so which account pays is
+ * visible at the decision point) or login-required — and, when the choice needs auth, run the login
+ * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
+ * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
+ * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
+ * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
+ * and best-effort written back to the config so the next run is quiet.
  */
 export declare function resolveFirstRunModel(workspaceDir: string, options?: {
     model?: string;
     authPath?: string;
     input?: boolean;
 }): Promise<void>;
+/**
+ * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
+ * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the
+ * keyboard NOW; parking the failure for a later `fastagent login` would waste that. The loop exits on
+ * a verified/unverifiable key (kept), an OAuth login (completing the flow already proved the
+ * credential), or cancel (LoginCancelled propagates to the caller's cancel policy). Used by both the
+ * `login` command and the first-run picker's inline login.
+ */
+export declare function loginWithKeyCheck(provider: string | undefined, authPath: string, spec?: string, seams?: {
+    flow?: (io: LoginIO, options: {
+        provider?: string;
+        authPath?: string;
+        method?: LoginMethod;
+    }) => Promise<LoginResult>;
+    verify?: (provider: string, authPath: string, spec?: string) => Promise<"ok" | "rejected" | "unknown">;
+}): Promise<LoginResult>;