@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/cli/commands/deploy.js

@@ -10,6 +10,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { registerFeishuWebhook } from "../../channels/feishu/register-webhook.js";
+import { readSlackBotAuthEnv } from "../../channels/slack/bot-auth.js";
+import { registerSlackWebhook } from "../../channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "../../channels/telegram/register-webhook.js";
 import { isGeneratedDockerfile } from "../../deploy/container.js";
 import { composeHasTunnelService, dockerWebhookPaths, isGeneratedCompose, planDockerDeploy, toDockerProjectName, } from "../../deploy/docker/plan.js";
@@ -22,12 +24,13 @@ import { deployRailwayRun } from "../../deploy/railway/run.js";
 import { spawnRunner } from "../../deploy/runner.js";
 import { assembleSecrets } from "../../deploy/secrets.js";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir, resolveAuthPathOverride, resolveModelSpec } from "../../engines/pi/config.js";
+import { loadConfig, resolveAgentDir, resolveModelSpec, resolveStateRoot } from "../../engines/pi/config.js";
 import { installProxyFetch } from "../../proxy.js";
 import { openExternalUrl } from "../../open-url.js";
 import { exists } from "../../scaffold/init.js";
 import { announceWebhooks } from "../../tunnel.js";
 import { failStartup, failUsage } from "../fail.js";
+import { resolveFirstRunModel } from "../shared.js";
 export async function runDeploy(host, dirArg, opts) {
     const target = resolve(dirArg);
     if (opts.tunnel && host !== "docker") {
@@ -36,6 +39,11 @@ export async function runDeploy(host, dirArg, opts) {
     }
     loadDotEnv(target); // a custom provider/tool may read a key at config load
     installProxyFetch(); // post-deploy channel API calls must honor HTTP(S)_PROXY under Node
+    // First-run funnel, FULL picker: the write-back lands the model in fastagent.config.* — exactly what
+    // the model-travel gate below requires (--model/env don't reach the deployed box) — and an inline
+    // login stores the credential `--run` then carries. Runs BEFORE loadConfig; the read-back sees the
+    // rewritten file because loadConfig cache-busts on mtime (a failed write-back still gates, correctly).
+    await resolveFirstRunModel(target, { model: opts.model, authPath: opts.authPath, input: opts.input });
     const { config } = await loadConfig(target).catch(failStartup);
     const agentDir = resolveAgentDir(target, config);
     const modelSpec = resolveModelSpec(opts.model, config);
@@ -49,13 +57,14 @@ export async function runDeploy(host, dirArg, opts) {
         modelSpec,
         run: !!opts.run,
         force: !!opts.force,
-        authPathOverride: resolveAuthPathOverride(opts.authPath),
+        authPathFlag: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by preflight (one owner)
     }).catch(failStartup);
     if (!pre.ok)
         failStartup(new Error(`deploy stopped: ${pre.gate}`));
     for (const m of pre.messages)
         console.error(`[fastagent] ${m.level}: ${m.text}`);
-    const { channels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets } = pre;
+    const { channels, routeChannels, longConnectionChannels, hasTimeTriggers, modelAuth, 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.
     if (host === "docker") {
@@ -66,8 +75,20 @@ export async function runDeploy(host, dirArg, opts) {
             console.error(`[fastagent] warn: --into-linked is Railway-only — ignored for local Docker`);
         }
         const projectName = toDockerProjectName(basename(target));
-        const dockerPlan = (tunnel) => planDockerDeploy({ projectName, port, modelAuth, channels, tunnel, extraSecrets, ...container });
-        const requestedTunnel = !!opts.tunnel;
+        const dockerPlan = (tunnel) => planDockerDeploy({
+            projectName,
+            port,
+            modelAuth,
+            channels,
+            longConnectionChannels,
+            tunnel,
+            extraSecrets,
+            ...container,
+        });
+        const requestedTunnel = !!opts.tunnel && (!hasDeclaredChannels || routeChannels.length > 0);
+        if (opts.tunnel && hasDeclaredChannels && routeChannels.length === 0) {
+            console.error(`[fastagent] note: --tunnel skipped — every channel uses a long connection`);
+        }
         let plan = dockerPlan(requestedTunnel);
         // An existing Compose file is authoritative: shape its comparison/runbook from the topology on disk,
         // regardless of the current flag. `--force` is the explicit reset to the requested generated shape.
@@ -85,13 +106,13 @@ export async function runDeploy(host, dirArg, opts) {
         if (opts.run) {
             return runDeployDocker({
                 target,
-                agentDir,
                 composeFile: plan.composePath,
                 port,
                 requireTunnel: requestedTunnel,
                 modelAuth,
                 authPath,
                 channels,
+                longConnectionChannels,
                 extraSecrets,
             });
         }
@@ -114,7 +135,15 @@ export async function runDeploy(host, dirArg, opts) {
         const serviceName = basename(target)
             .replace(/[^a-zA-Z0-9-]+/g, "-")
             .replace(/^-+|-+$/g, "") || "agent";
-        const plan = planRailwayDeploy({ serviceName, modelAuth, channels, extraSecrets, hasTimeTriggers, ...container });
+        const plan = planRailwayDeploy({
+            serviceName,
+            modelAuth,
+            channels,
+            longConnectionChannels,
+            extraSecrets,
+            hasTimeTriggers,
+            ...container,
+        });
         await writeArtifacts(target, plan.artifacts, {
             force: !!opts.force,
             neverForce: container.kitDir ? [".dockerignore"] : [],
@@ -126,6 +155,7 @@ export async function runDeploy(host, dirArg, opts) {
                 modelAuth,
                 authPath,
                 channels,
+                longConnectionChannels,
                 extraSecrets,
                 intoLinked: !!opts.intoLinked,
             });
@@ -171,14 +201,16 @@ export async function runDeploy(host, dirArg, opts) {
     // Under `--run` this is a GATE (same discipline as the model-travel gate): a full deploy whose schedules
     // silently never fire is worse than a crash-loop — nothing fails visibly when a cron instant passes on a
     // sleeping machine, and unlike github's min=0 there is no legitimate trade to accept here.
-    if (flyTomlExists && !opts.force && hasTimeTriggers) {
+    if (flyTomlExists && !opts.force && (hasTimeTriggers || longConnectionChannels.length > 0)) {
         const min = parseFlyMinMachines(await readFile(flyTomlPath, "utf8"));
         if ((min ?? 0) === 0) {
             // undefined = the line is absent — Fly's platform default for min_machines_running is 0, so a
             // hand-written fly.toml without the line scales to zero exactly like an explicit 0.
+            const reason = hasTimeTriggers
+                ? `schedules/self-scheduling need a running machine (no external wake-up)`
+                : `long-connection channel (${longConnectionChannels.join(", ")}) needs an always-on outbound connection`;
             const msg = `your kept fly.toml scales to zero (min_machines_running = ${min ?? "absent → platform default 0"}), but ` +
-                `schedules/self-scheduling need a running machine (no external wake-up). Set min_machines_running = 1, ` +
-                `or pass --force to regenerate.`;
+                `${reason}. Set min_machines_running = 1, or pass --force to regenerate.`;
             if (opts.run)
                 failStartup(new Error(`deploy stopped: ${msg}`));
             console.error(`[fastagent] warn: ${msg}`);
@@ -189,6 +221,7 @@ export async function runDeploy(host, dirArg, opts) {
         port,
         modelAuth,
         channels,
+        longConnectionChannels,
         extraSecrets,
         hasTimeTriggers,
         ...container,
@@ -199,8 +232,18 @@ export async function runDeploy(host, dirArg, opts) {
         force: !!opts.force,
         neverForce: container.kitDir ? [".dockerignore"] : [],
     });
-    if (opts.run)
-        return runDeployFly({ target, appName, modelAuth, authPath, channels, flyTomlPath, extraSecrets });
+    if (opts.run) {
+        return runDeployFly({
+            target,
+            appName,
+            modelAuth,
+            authPath,
+            channels,
+            longConnectionChannels,
+            flyTomlPath,
+            extraSecrets,
+        });
+    }
     console.log(plan.runbook.join("\n"));
 }
 /**
@@ -238,19 +281,26 @@ async function writeArtifacts(target, artifacts, options) {
         console.error(`[fastagent] wrote ${a.path}`);
     }
 }
+function deployEnvironment(target, channels) {
+    if (!channels.includes("slack"))
+        return process.env;
+    const latest = readSlackBotAuthEnv(join(resolveStateRoot(target), "channels", "slack", "bot-auth.json"));
+    return { ...process.env, ...latest };
+}
 /**
  * `deploy docker --run`: carry local credentials into Compose's child environment, then reconcile the
  * user-owned local topology. Docker owns container/network/volume lifecycle. A Compose tunnel service,
  * when present, yields an ephemeral URL that reuses the same webhook announcer as `dev --tunnel`.
  */
 async function runDeployDocker(params) {
-    const { target, agentDir, composeFile, port, requireTunnel, modelAuth, authPath, channels, extraSecrets } = params;
+    const { target, composeFile, port, requireTunnel, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, } = params;
     const { secrets, missingSecrets, needsModelCredential } = assembleSecrets({
         modelAuth,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
+        longConnectionChannels,
         extraSecrets,
-        env: process.env,
+        env: deployEnvironment(target, channels),
     });
     const outcome = await deployDockerRun({ composeFile, port, secrets, missingSecrets, needsModelCredential, requireTunnel }, spawnRunner("docker", target), (message) => console.error(`[fastagent] ${message}`));
     if (!outcome.ok)
@@ -263,12 +313,16 @@ async function runDeployDocker(params) {
         // Docker Desktop commonly injects a host proxy. The Quick Tunnel hostname may be resolvable only
         // through it, exactly like provider/channel APIs; use the same Node dispatcher as dev/start/login.
         installProxyFetch();
-        await announceWebhooks(agentDir, outcome.tunnelUrl, { openUrl: openExternalUrl });
+        await announceWebhooks(target, outcome.tunnelUrl, {
+            openUrl: openExternalUrl,
+            routeChannels: channels.filter((kind) => !longConnectionChannels.includes(kind)),
+            stateRoot: resolveStateRoot(target),
+        });
         console.error(`[fastagent] note: Quick Tunnel URLs are ephemeral — after the tunnel container/Docker daemon ` +
             `restarts, re-run this deploy so webhooks receive the new URL`);
         return;
     }
-    const paths = dockerWebhookPaths(channels);
+    const paths = dockerWebhookPaths(channels.filter((kind) => !longConnectionChannels.includes(kind)));
     if (paths.length > 0) {
         console.error(`[fastagent] note: public ingress is operator-owned — configure your tunnel/proxy, then wire the ` +
             `default webhook path(s): ${paths.join(", ")} (or your remapped channel routes)`);
@@ -282,7 +336,7 @@ async function runDeployDocker(params) {
  * behind the shared {@link spawnRunner} seam (spawned `fly`, cwd = the workspace so the build context is the agent).
  */
 async function runDeployFly(params) {
-    const { target, appName, modelAuth, authPath, channels, flyTomlPath, extraSecrets } = params;
+    const { target, appName, modelAuth, authPath, channels, longConnectionChannels, flyTomlPath, extraSecrets } = params;
     const fly = spawnRunner("fly", target);
     // 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) {
@@ -293,15 +347,16 @@ async function runDeployFly(params) {
         modelAuth,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
+        longConnectionChannels,
         extraSecrets,
-        env: process.env,
+        env: deployEnvironment(target, channels),
     });
     // Model credential has its OWN remediation (login), distinct from a missing secret's (.env) — gate it
     // here, not through missingSecrets, so the message isn't a contradictory mash of both.
     if (needsModelCredential) {
         failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
     }
-    const outcome = await deployFlyRun({ appName, region, secrets, missingSecrets, channels, flyConfig: "fly.toml" }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind));
+    const outcome = await deployFlyRun({ appName, region, secrets, missingSecrets, channels, longConnectionChannels, flyConfig: "fly.toml" }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(target) }));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → https://${appName}.fly.dev`);
@@ -314,7 +369,7 @@ async function runDeployFly(params) {
  * webhook) lives in {@link deployRailwayRun}; see there for why Railway differs from Fly.
  */
 async function runDeployRailway(params) {
-    const { target, name, modelAuth, authPath, channels, extraSecrets, intoLinked } = params;
+    const { target, name, modelAuth, authPath, channels, longConnectionChannels, extraSecrets, intoLinked } = params;
     const railway = spawnRunner("railway", target);
     // Fail fast if the railway CLI is absent (spawn ENOENT → 127), with the install link.
     if ((await railway(["--version"], { capture: true })).code === 127) {
@@ -324,14 +379,15 @@ async function runDeployRailway(params) {
         modelAuth,
         authFile: (await exists(authPath)) ? await readFile(authPath) : undefined,
         channels,
+        longConnectionChannels,
         extraSecrets,
-        env: process.env,
+        env: deployEnvironment(target, channels),
     });
     // Model credential has its OWN remediation (login), distinct from a missing secret's (.env).
     if (needsModelCredential) {
         failStartup(new Error(`deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`));
     }
-    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, intoLinked }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind));
+    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, longConnectionChannels, intoLinked }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind), (baseUrl) => registerSlackWebhook(baseUrl, { stateRoot: resolveStateRoot(target) }));
     if (!outcome.ok)
         failStartup(new Error(`deploy stopped: ${outcome.gate}`));
     console.error(`[fastagent] deployed → ${outcome.url}`);

package/dist/cli/commands/dev.js

@@ -6,14 +6,13 @@
 import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
 import { loadDotEnv } from "../../env.js";
-import { resolveAuthPathOverride } from "../../engines/pi/config.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
 import { log, setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { failStartup } from "../fail.js";
-import { maybeTunnel, routesFor, serve, startSchedules } from "../serve.js";
+import { maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
 import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
 export async function runDev(dirArg, opts) {
     const dir = resolve(dirArg);
@@ -42,7 +41,7 @@ async function serveOnce(dir, opts) {
     installProxyFetch();
     const a = await createPiAgentFromWorkspace(dir, {
         model: opts.model,
-        authPath: resolveAuthPathOverride(opts.authPath),
+        authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
     log.info(`[fastagent] dir:    ${dir}`);
@@ -55,9 +54,16 @@ async function serveOnce(dir, opts) {
     // 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.
     const traced = logAgentLoop(a.agent);
-    const routes = await routesFor(a.agentDir, traced, a.stateRoot).catch(failStartup);
+    const routed = await routesFor(a.agentDir, traced, a.stateRoot, a.sessionControl).catch(failStartup);
+    const withControl = mountSessionControl(routed.routes, a.sessionControl, a.stateRoot, {
+        tunnel: opts.tunnel ?? false,
+        agent: traced, // the remote data plane (POST /control/invoke) drives the SAME traced agent
+    });
     await startSchedules(a.agentDir, traced, a.stateRoot, a.config.selfSchedule ?? false);
-    serve(routes, portFlag ?? a.config.http?.port ?? 8787, (p) => maybeTunnel(a.agentDir, p, opts.tunnel ?? false));
+    serve({ ...routed, routes: withControl.routes }, portFlag ?? a.config.http?.port ?? 8787, (p) => {
+        withControl.announce(p);
+        maybeTunnel(dir, routed.routeChannels, p, opts.tunnel ?? false, a.stateRoot);
+    });
 }
 /** The agents/skills/tools/collisions report lines. */
 function reportAgentsSkillsTools(a) {

package/dist/cli/commands/fire.js

@@ -6,10 +6,10 @@
  */
 import { relative, resolve, sep } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { loadConfig, resolveAgentDir, resolveAuthPathOverride } from "../../engines/pi/config.js";
+import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
 import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
-import { runInvokeStream } from "../../invoke-stream.js";
+import { runInvokeStream } from "../invoke-stream.js";
 import { installProxyFetch } from "../../proxy.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { scheduleSession } from "../../schedule/scheduler.js";
@@ -35,7 +35,7 @@ export async function runFire(name, dirArg, opts) {
     }
     const { agent, modelSpec, authPath } = await createPiAgentFromWorkspace(fireDir, {
         model: opts.model,
-        authPath: resolveAuthPathOverride(opts.authPath),
+        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);

package/dist/cli/commands/info.js

@@ -2,7 +2,7 @@
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { discoverChannelFiles } from "../../engines/pi/channel.js";
-import { defaultAuthPath, defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPathOverride, resolveModelSpec, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
+import { defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPath, resolveModelSpec, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
 import { resolveWorkspaceTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
@@ -52,7 +52,7 @@ export async function runInfo(dirArg, opts) {
     // create them, info must not).
     const stateRoot = resolveStateRoot(dir);
     const sessionsDir = resolveSessionsDirOverride(opts.sessionsDir) ?? defaultSessionsDir(stateRoot);
-    const authPath = resolveAuthPathOverride(opts.authPath) ?? defaultAuthPath(stateRoot);
+    const authPath = resolveAuthPath(dir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
     if (opts.json) {
         console.log(JSON.stringify({
             dir,

package/dist/cli/commands/invoke.js

@@ -2,9 +2,8 @@
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { resolveAuthPathOverride } from "../../engines/pi/config.js";
 import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
-import { runInvokeStream } from "../../invoke-stream.js";
+import { runInvokeStream } from "../invoke-stream.js";
 import { installProxyFetch } from "../../proxy.js";
 import { failStartup } from "../fail.js";
 import { reportAuth, resolveFirstRunModel } from "../shared.js";
@@ -15,7 +14,7 @@ export async function runInvoke(message, dirArg, opts) {
     await resolveFirstRunModel(invokeDir, opts);
     const { agent, modelSpec, authPath } = await createPiAgentFromWorkspace(invokeDir, {
         model: opts.model,
-        authPath: resolveAuthPathOverride(opts.authPath),
+        authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);
     console.error(`[fastagent] invoke: ${invokeDir} (${modelSpec})`);
     await reportAuth(modelSpec, authPath);

package/dist/cli/commands/login.js

@@ -8,21 +8,19 @@
  * so the secret can never land untracked — a flow that then fails (bad provider, abort) leaves that
  * empty state dir behind, by design (no secret without its `.gitignore`). Skipped for the HOME-global dir.
  */
-import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { loadDotEnv } from "../../env.js";
-import { defaultAuthPath, resolveAuthPathOverride, resolveStateRoot } from "../../engines/pi/config.js";
+import { resolveAuthPath, resolveStateRoot } from "../../engines/pi/config.js";
 import { ensureStateRootSelfIgnored, isUnderDir } from "../../engines/pi/definition.js";
-import { loginFlow } from "../../engines/pi/login.js";
-import { openExternalUrl } from "../../open-url.js";
+import { LoginCancelled } from "../../engines/pi/login.js";
 import { installProxyFetch } from "../../proxy.js";
 import { failStartup } from "../fail.js";
-import { isInteractive } from "../shared.js";
+import { isInteractive, loginWithKeyCheck } from "../shared.js";
 export async function runLogin(provider, opts) {
     const loginDir = process.cwd();
     loadDotEnv(loginDir); // FASTAGENT_AUTH_PATH / a proxy (HTTPS_PROXY) may be configured in the project .env
     installProxyFetch(); // the OAuth token exchange must go through HTTPS_PROXY (region-locked providers)
     const stateRoot = resolveStateRoot(loginDir);
-    const authPath = resolveAuthPathOverride(opts.authPath) ?? defaultAuthPath(stateRoot);
+    const authPath = resolveAuthPath(loginDir, opts.authPath); // flag > FASTAGENT_AUTH_PATH > default — the one owner
     // login is the command that CREATES the credential file, so the leak guard binds HERE too (not only
     // in the opener): on an adapted project dir, a `login` before the first dev/start would otherwise
     // leave the secret untracked-but-committable. Unlike the opener (which populates the WHOLE root, so
@@ -39,25 +37,16 @@ export async function runLogin(provider, opts) {
     if (opts.input === false || !isInteractive()) {
         failStartup(new Error(`login is interactive (it shows a menu and opens a browser) — run it in a terminal, not a pipe/CI`));
     }
-    const io = terminalLoginIO();
-    const result = await loginFlow(io, { provider, authPath }).catch(failStartup);
+    // loginWithKeyCheck: an entered API key is verified with one minimal request; a rejected key (401)
+    // re-prompts in place, so a returned result is always a stored-and-not-definitively-bad credential.
+    const result = await loginWithKeyCheck(provider, authPath).catch((error) => {
+        if (error instanceof LoginCancelled) {
+            // A decision, not a failure — neutral wording; non-zero exit because no credential was stored.
+            console.error(`[fastagent] login cancelled`);
+            process.exit(1);
+        }
+        failStartup(error);
+    });
     console.error(`[fastagent] logged in to ${result.provider} (${result.method}) — saved to ${authPath}`);
     process.exit(0); // the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
 }
-/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
-function terminalLoginIO() {
-    return {
-        async select(message, options) {
-            const r = await (options.length > 7 ? autocomplete : select)({ message, options });
-            return isCancel(r) ? undefined : r;
-        },
-        async prompt(message, opts) {
-            const r = opts?.hidden
-                ? await password({ message, signal: opts.signal })
-                : await clackText({ message, signal: opts?.signal });
-            return isCancel(r) ? undefined : r;
-        },
-        note: (message) => clackLog.info(message),
-        openUrl: openExternalUrl,
-    };
-}

package/dist/cli/commands/models.js

@@ -3,7 +3,7 @@
  * substring. This module pulls the pi model catalog (heavy) — it is lazy-imported by the spec, so
  * only an actual `models` invocation pays for it.
  */
-import { formatModelsCommand } from "../../cli-models.js";
+import { formatModelsCommand } from "../models-view.js";
 import { listModels } from "../../engines/pi/config.js";
 import { createPiModels } from "../../engines/pi/models.js";
 export function runModels(search) {

package/dist/cli/commands/start.js

@@ -6,7 +6,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { authSeedBytes } from "../../deploy/fly/run.js";
 import { loadDotEnv } from "../../env.js";
-import { defaultAuthPath, resolveAuthPathOverride, resolveSessionsDirOverride, resolveStateRoot, } from "../../engines/pi/config.js";
+import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
 import { isUnderDir } from "../../engines/pi/definition.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { createPiAgentFromWorkspace } from "../../engines/pi/workspace.js";
@@ -15,7 +15,7 @@ import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { exists } from "../../scaffold/init.js";
 import { failStartup } from "../fail.js";
-import { maybeTunnel, routesFor, serve, startSchedules } from "../serve.js";
+import { maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
 import { parsePort, reportAuth, resolveFirstRunModel } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
@@ -26,14 +26,14 @@ export async function runStart(dirArg, opts) {
     await resolveFirstRunModel(dir, opts);
     // A `deploy --run` may carry the operator's local credential as FASTAGENT_AUTH_SEED —
     // materialize it onto the writable state root BEFORE the opener resolves auth (once, absent-only).
-    const authPathOverride = resolveAuthPathOverride(opts.authPath);
-    await maybeSeedAuth(authPathOverride ?? defaultAuthPath(resolveStateRoot(dir)));
+    // Same resolveAuthPath the opener uses — ONE owner of the flag > env > default chain.
+    await maybeSeedAuth(resolveAuthPath(dir, opts.authPath));
     // The same opener dev uses (single assembly source), just no watch.
     const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
-    const { agent, definition, agentDir, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await createPiAgentFromWorkspace(dir, {
+    const { agent, definition, agentDir, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, sessionControl, } = await createPiAgentFromWorkspace(dir, {
         model: opts.model,
         sessionsDir: sessionsDirOverride,
-        authPath: authPathOverride,
+        authPath: opts.authPath,
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
     log.info(`[fastagent] start:  ${dir}`);
@@ -66,9 +66,16 @@ export async function runStart(dirArg, opts) {
     reportDefinitionWarnings(definition.collisions, definition.diagnostics);
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
-    const routes = await routesFor(agentDir, traced, stateRoot).catch(failStartup);
+    const routed = await routesFor(agentDir, traced, stateRoot, sessionControl).catch(failStartup);
+    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
+        tunnel: opts.tunnel ?? false,
+        agent: traced,
+    });
     await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false);
-    serve(routes, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => maybeTunnel(agentDir, p, opts.tunnel ?? false));
+    serve({ ...routed, routes: withControl.routes }, portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, (p) => {
+        withControl.announce(p);
+        maybeTunnel(dir, 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
     // and replays it next start (turn-store.ts, L1 durable execution, at-least-once); HTTP and other

package/dist/cli/commands/tool.js

@@ -4,6 +4,7 @@ import { loadDotEnv } from "../../env.js";
 import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
 import { resolveWorkspaceTools } from "../../engines/pi/create.js";
 import { reportModuleLoadFailures } from "../../engines/pi/report.js";
+import { turnContext } from "../../engines/pi/tool-context.js";
 import { failStartup, failUsage } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
     const toolDir = resolve(dirArg);
@@ -29,7 +30,7 @@ export async function runTool(name, argsJson, dirArg) {
     catch {
         failUsage(`invalid JSON args: ${argsJson}`); // malformed input syntax = usage error, exit 2
     }
-    const result = await tool.execute(`cli-${name}`, args).catch(failStartup);
+    const result = await turnContext.run({ cwd: toolDir }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");

package/dist/cli/fail.d.ts

@@ -1,5 +1,3 @@
-/** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
-export declare function stderrHasColors(): boolean;
 /**
  * The ONE error prefix every error message carries — bold red when stderr renders color, plain
  * otherwise. Errors are the only place the CLI uses color at all.

package/dist/cli/fail.js

@@ -1,5 +1,5 @@
 /** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
-export function stderrHasColors() {
+function stderrHasColors() {
     return process.stderr.isTTY === true && (process.stderr.hasColors?.() ?? false);
 }
 /**

package/dist/{invoke-stream.d.ts → cli/invoke-stream.d.ts}

@@ -6,5 +6,5 @@
  * An errored tool inside an otherwise-completed turn still surfaces (the diagnostic the operator
  * needs); tool_ended carries no name, so it is remembered from the matching tool_started.
  */
-import type { AgentEvent } from "./agent.ts";
+import type { AgentEvent } from "../agent.ts";
 export declare function runInvokeStream(events: AsyncIterable<AgentEvent>, out: (text: string) => void, err: (line: string) => void): Promise<number>;

package/dist/{invoke-stream.js → cli/invoke-stream.js}

@@ -14,6 +14,10 @@ export async function runInvokeStream(events, out, err) {
                 if (event.isError)
                     err(`[tool] ${toolName.get(event.id) ?? event.id} failed`);
                 break;
+            case "retrying":
+                // Operator-facing: include the reason (channels show a neutral customer line instead).
+                err(`[fastagent] transient failure — retrying (${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms): ${event.reason}`);
+                break;
             case "failed":
                 err(`[fastagent] failed: ${event.details}${event.retryable ? " (retryable)" : ""}`);
                 exitCode = 1;

package/dist/cli/kernel.d.ts

@@ -13,7 +13,7 @@
  */
 import { Command } from "commander";
 /** One positional argument, in commander syntax: `<name>` required, `[dir]` optional. */
-export interface ArgSpec {
+interface ArgSpec {
     name: string;
     description: string;
     default?: string;
@@ -29,7 +29,7 @@ export interface FlagSpec {
     /** Mutually exclusive with these {@link optionKey} values — validated at build time. */
     conflicts?: string[];
 }
-export interface ExampleSpec {
+interface ExampleSpec {
     cmd: string;
     note?: string;
 }
@@ -87,3 +87,4 @@ export interface ProgramOptions {
 export declare function optionKey(flags: string): string;
 /** Build the commander program for `specs`. The CLI entry parses with it; tests inject the IO seams. */
 export declare function buildProgram(specs: readonly CommandSpec[], options?: ProgramOptions): Command;
+export {};

package/dist/cli/models-view.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderAuthStatus } from "../engines/pi/models.ts";
+/** One first-run picker entry (@clack/prompts option shape). */
+export interface ModelPickerOption {
+    value: string;
+    label: string;
+    hint: string;
+}
+/**
+ * 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 declare function buildModelPickerOptions(specs: string[], statuses: Map<string, ProviderAuthStatus>): ModelPickerOption[];
+/** 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 declare function formatModelsCommand(specs: string[], search?: string): {
+    lines: string[];
+    error?: string;
+};