@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/cli/shared.js

@@ -1,16 +1,20 @@
 /**
  * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report,
- * and first-run model resolution. Bodies moved verbatim from cli.ts; the module-scoped flag access
- * (`values.*`) became parameters.
+ * first-run model resolution, and the login terminal IO. Bodies moved verbatim from cli.ts; the
+ * module-scoped flag access (`values.*`) became parameters.
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { relative } from "node:path";
-import { autocomplete, isCancel, select } from "@clack/prompts";
+import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
+import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
-import { isValidPort, loadConfig, resolveAuthPath, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
-import { configuredModelSpecs, createPiModels, probeAuthSource } from "../engines/pi/models.js";
-import { formatAuthReport } from "../cli-auth.js";
+import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, resolveStateRoot, rewriteConfigModel, } from "../engines/pi/config.js";
+import { ensureStateRootSelfIgnored, isUnderDir } from "../engines/pi/definition.js";
+import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
+import { 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";
 import { failStartup, failUsage } from "./fail.js";
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
 export function isInteractive() {
@@ -38,7 +42,7 @@ export function parsePort(value, source, from) {
 }
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
 export async function reportAuth(modelSpec, authPath) {
-    const provider = modelSpec.slice(0, modelSpec.indexOf("/"));
+    const provider = providerOf(modelSpec);
     const source = await probeAuthSource(createPiModels({ authPath }), 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.
@@ -53,12 +57,15 @@ export async function reportAuth(modelSpec, authPath) {
         log.warn(`[fastagent] ${report.warn}`);
 }
 /**
- * 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 async function resolveFirstRunModel(workspaceDir, options = {}) {
     const { config, path: configPath } = await loadConfig(workspaceDir).catch(failStartup);
@@ -69,38 +76,161 @@ export async function resolveFirstRunModel(workspaceDir, options = {}) {
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
     const authPath = resolveAuthPath(workspaceDir, options.authPath);
-    let specs;
+    const models = createPiModels({ authPath });
+    const chosen = await pickWithCredentials(workspaceDir, models, authPath);
+    if (chosen === undefined)
+        return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
+    process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
+    await persistModelChoice(workspaceDir, configPath, chosen);
+}
+/**
+ * The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy —
+ * remedy warnings for providers no login flow can fix (the choice is KEPT: model validity is
+ * independent of credentials), or the inline login for the rest. Returns the chosen spec, or
+ * undefined when the pick should be discarded (picker cancel, login cancel, a failed auth probe).
+ */
+async function pickWithCredentials(workspaceDir, models, authPath) {
+    let statuses;
     try {
-        specs = await configuredModelSpecs(createPiModels({ authPath }));
+        statuses = await providerAuthStatuses(models);
     }
     catch (error) {
-        // Enumerating providers/auth threw — a system fault (a corrupt auth store, a throwing provider),
-        // NOT "not logged in". Surface it instead of masking it as the login hint; the opener then still
-        // raises the clear missing-model error.
-        log.warn(`[fastagent] could not list configured models: ${error.message}`);
-        return;
-    }
-    if (specs.length === 0) {
-        log.warn(`[fastagent] no model set and no authenticated provider — run \`fastagent login\`, then \`fastagent dev\``);
-        return;
+        // Per-provider auth throws are captured as `broken` INSIDE providerAuthStatuses; reaching here
+        // means the enumeration itself failed (getProviders / a provider with no probe-able surface) — a
+        // system fault. Surface it; the opener then still raises the clear missing-model error.
+        log.warn(`[fastagent] could not probe provider auth: ${error.message}`);
+        return undefined;
     }
-    const r = await (specs.length > 7 ? autocomplete : select)({
+    const r = await autocomplete({
         message: "Choose a model for this agent",
-        options: specs.map((s) => ({ value: s, label: s })),
+        options: buildModelPickerOptions(listModels(models), statuses),
     });
     if (isCancel(r))
-        return; // cancelled: let the opener report the missing model
+        return undefined; // cancelled: the caller raises its clear missing-model error
     const chosen = r;
-    process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
-    await persistModelChoice(workspaceDir, configPath, chosen);
+    const provider = providerOf(chosen);
+    const status = statuses.get(provider);
+    if (status?.state === "ready")
+        return chosen; // usable now — nothing to fix
+    if (status && status.login === "none") {
+        // No login flow exists for this provider — KEEP the choice and name the remedy. The remedy depends
+        // on WHY it is not ready: a BROKEN stored credential still owns the provider (env is consulted
+        // only when nothing is stored — createPiModels), so "set the env var" would not help there.
+        if (status.state === "broken") {
+            log.warn(`[fastagent] stored auth for "${provider}" is unusable: ${status.message} — fix or remove it in ${authPath}; invokes fail until then`);
+        }
+        else {
+            log.warn(`[fastagent] "${provider}" has no interactive login — set its API key env var; invokes fail until then`);
+        }
+        return chosen;
+    }
+    // Inline login. Same leak guard as `login`: self-ignore the state root BEFORE a credential
+    // can land in-tree, so the secret is never untracked-but-committable.
+    const stateRoot = resolveStateRoot(workspaceDir);
+    if (isUnderDir(authPath, stateRoot))
+        await ensureStateRootSelfIgnored(workspaceDir, stateRoot);
+    try {
+        // Verified against the CHOSEN model — the exact request the agent is about to make; a rejected
+        // key re-prompts inside the loop, so reaching here means a usable (or at worst unverifiable) key.
+        await loginWithKeyCheck(provider, authPath, chosen);
+        console.error(`[fastagent] logged in to ${provider} — saved to ${authPath}`);
+    }
+    catch (error) {
+        if (error instanceof LoginCancelled)
+            return undefined; // user backed out — discard the choice, like a picker cancel
+        // A FAILED login keeps the choice: the pick persists, the startup auth report names the remedy,
+        // and a later `fastagent login` fixes auth without re-picking the model.
+        log.warn(`[fastagent] login for "${provider}" failed: ${error.message} — model saved; run \`fastagent login\` to fix auth`);
+    }
+    return chosen;
+}
+/**
+ * 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 async function loginWithKeyCheck(provider, authPath, spec, 
+// Test seams: this loop DESTROYS credential state on `rejected`, so its policy (rejected → delete →
+// re-ask ONLY the key) is pinned by a test through fake flow/verify; production callers omit both.
+seams = {}) {
+    const flow = seams.flow ?? loginFlow;
+    const verify = seams.verify ?? verifyApiKeyLogin;
+    const io = terminalLoginIO();
+    let method;
+    for (;;) {
+        const result = await flow(io, { provider, authPath, method });
+        if (result.method !== "api_key")
+            return result;
+        const verdict = await verify(result.provider, authPath, spec);
+        if (verdict !== "rejected")
+            return result;
+        // Retry re-asks ONLY the key: the provider/method choices weren't the mistake, the keystrokes were.
+        provider = result.provider;
+        method = "api_key";
+    }
+}
+/**
+ * Quick-fail check after an api_key login (OAuth needs none — completing the flow already proved the
+ * credential): probe the stored key with one minimal request against `spec`, or the provider's first
+ * model. Policy over {@link probeApiKey}'s verdict: `rejected` (definitive HTTP 401) DELETES the
+ * just-stored credential — a mistyped key must not persist as plausible state — and the caller
+ * ({@link loginWithKeyCheck}) re-prompts; `unknown` (network, quota, permissions) keeps it and prints
+ * the provider's message: the key may still be right, and wrongly destroying a good credential costs
+ * more than keeping a doubtful one.
+ */
+async function verifyApiKeyLogin(provider, authPath, spec) {
+    const models = createPiModels({ authPath });
+    const model = spec ? resolveModel(models, spec) : models.getProvider(provider)?.getModels()[0];
+    if (!model) {
+        console.error(`[fastagent] cannot verify the key: provider "${provider}" lists no models — kept as stored`);
+        return "unknown";
+    }
+    const label = `${model.provider}/${model.id}`;
+    console.error(`[fastagent] verifying the key with ${label}…`);
+    const probe = await probeApiKey(models, model);
+    if (probe.state === "ok") {
+        console.error(`[fastagent] key verified — ${label} responded`);
+    }
+    else if (probe.state === "rejected") {
+        await fastagentCredentialStore(authPath).delete(provider);
+        console.error(`[fastagent] ${provider} rejected the API key (HTTP 401): ${probe.message} — enter it again (or cancel)`);
+    }
+    else {
+        console.error(`[fastagent] could not verify the key with ${label}: ${probe.message} — kept; invokes surface the provider's error`);
+    }
+    return probe.state;
+}
+/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. Shared
+ *  by the `login` command and the first-run picker's inline login. */
+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,
+    };
 }
 /**
- * Best-effort persist the picked model so the next run does not prompt. Only rewrites the commented
- * `model:` placeholder the scaffold writes (or an existing `model:` line); anything else (zero-config,
- * a hand-shaped config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ * Best-effort persist the picked model so the next run does not prompt. Rewrites the commented
+ * `model:` placeholder the scaffold writes / an existing `model:` line, or re-inserts the line into a
+ * scaffold-shaped config (the hand-deleted-to-reset case); anything else (zero-config, a hand-shaped
+ * config) is left untouched with a printed hint. Never throws — persistence is a convenience.
  */
 async function persistModelChoice(workspaceDir, configPath, spec) {
-    const hint = () => console.error(`[fastagent] using ${spec} for this run; set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
+    const hint = () => console.error(
+    // No "using it for this run" promise: deploy's model-travel gate rightly ignores the un-persisted pick.
+    `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
     if (!configPath)
         return hint();
     try {

package/dist/collect.d.ts

@@ -1,9 +1,20 @@
 /**
- * Buffered consumption helper (caller-side, SPEC §7): reduce an AgentEvent stream to a final value,
- * encoding the terminal discipline (failed → throw, missing terminal → error). Streaming consumers
- * for-await themselves.
+ * 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.
  */
 import type { AgentEvent, Json } from "./agent.ts";
+/**
+ * The abort-first cancellation protocol, ONCE: an async generator suspended on a quiet await (a
+ * tool mid-execution, a silent SSE read) parks inside that await, and `gen.return()`/`gen.throw()`
+ * queue behind the pending `next()` FOREVER (async-generator semantics) — a consumer's cancel
+ * would deadlock. The wrapper's `return()` first runs `cancel` (abort the underlying work, which
+ * 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.
+ */
+export declare function abortFirstIterator<T>(gen: AsyncGenerator<T>, cancel: () => void): AsyncIterator<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

@@ -1,3 +1,27 @@
+/**
+ * The abort-first cancellation protocol, ONCE: an async generator suspended on a quiet await (a
+ * tool mid-execution, a silent SSE read) parks inside that await, and `gen.return()`/`gen.throw()`
+ * queue behind the pending `next()` FOREVER (async-generator semantics) — a consumer's cancel
+ * would deadlock. The wrapper's `return()` first runs `cancel` (abort the underlying work, which
+ * 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.
+ */
+export function abortFirstIterator(gen, cancel) {
+    return {
+        next: () => gen.next(),
+        async return(value) {
+            cancel();
+            await gen.return(value).catch(() => { });
+            return { done: true, value: undefined };
+        },
+        async throw(error) {
+            cancel();
+            await gen.return(undefined).catch(() => { });
+            throw error;
+        },
+    };
+}
 /** Exception form of a failed event (thrown by collect). Carries the failed event's fields verbatim, so
  *  a buffered consumer can branch on `code` (SPEC §8 failure subdivision) just like a streaming one. */
 export class AgentFailure extends Error {

package/dist/core.d.ts

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

package/dist/core.js

@@ -1,5 +1,7 @@
 export { collect, AgentFailure } from "./collect.js";
 export { createInvokeHandler, nodeListener } from "./channels/http.js";
+export { controlRoutes } from "./channels/control.js";
+export { ControlRequestError, connectAgent, connectSessionControl, } from "./session-remote.js";
 export { readBodyCapped } from "./channels/body.js";
 export { text, textHeaders } from "./channels/respond.js";
 export { router, serveNode, } from "./host/node.js";

package/dist/deploy/docker/plan.d.ts

@@ -15,6 +15,8 @@ export interface DockerPlanInput extends ContainerInput {
     modelAuth: string | undefined;
     /** Known channels contribute their environment-variable names and webhook registration. */
     channels: ChannelKind[];
+    /** All long-connection channel basenames, including custom channels. */
+    longConnectionChannels?: string[];
     /** Generate an optional Cloudflare Quick Tunnel service in Compose. Generation only; `--run` starts it. */
     tunnel: boolean;
     /** Extra environment-variable names declared in config.deploy.secrets. */
@@ -28,8 +30,6 @@ export interface DockerPlan {
     /** Ordered local build/run/operate instructions. */
     runbook: string[];
 }
-export declare const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
-export declare const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
 export declare const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
 /** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
 export declare const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";

package/dist/deploy/docker/plan.js

@@ -1,8 +1,8 @@
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
 const MOUNT = "/data";
-export const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
-export const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
+const DOCKER_COMPOSE_FILE = "fastagent.compose.yml";
+const GENERATED_COMPOSE_MARKER = "# Generated by `fastagent deploy docker`";
 export const MIN_DOCKER_COMPOSE_VERSION = "2.3.3";
 /** Pinned: generated deployment artifacts must not silently move when Cloudflare publishes `latest`. */
 export const CLOUDFLARED_IMAGE = "cloudflare/cloudflared:2026.7.1";
@@ -29,6 +29,7 @@ export function dockerWebhookPaths(channels) {
     const path = {
         github: "/webhook",
         telegram: "/telegram",
+        slack: "/slack",
         feishu: "/feishu",
         lark: "/lark",
     };
@@ -48,7 +49,7 @@ function buildContext(kitDir) {
         .join("/");
 }
 function composeYaml(input) {
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
+    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets, input.longConnectionChannels);
     // Always leave the auth-seed seam in the committed topology. `--run` uses it for OAuth/stored auth;
     // it is empty otherwise. Values never land in this file — Compose interpolates them at invocation.
     const envNames = [...new Set([...secrets.map((secret) => secret.name), "FASTAGENT_AUTH_SEED"])];
@@ -104,10 +105,11 @@ export function planDockerDeploy(input) {
     const composePath = input.kitDir ? `${input.kitDir}/${DOCKER_COMPOSE_FILE}` : DOCKER_COMPOSE_FILE;
     const artifacts = [{ path: composePath, content: composeYaml(input) }, ...containerArtifacts(input)];
     const compose = `docker compose -f ${composePath}`;
-    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets);
+    const secrets = deploymentSecrets(input.modelAuth, input.channels, input.extraSecrets, input.longConnectionChannels);
     const required = secrets.filter((secret) => secret.required);
     const optional = secrets.filter((secret) => !secret.required);
-    const paths = dockerWebhookPaths(input.channels);
+    const routeChannels = input.channels.filter((kind) => !input.longConnectionChannels?.includes(kind));
+    const paths = dockerWebhookPaths(routeChannels);
     const runbook = [
         `# Run FastAgent in local Docker. ${composePath} / Dockerfile(.dockerignore) are generated above.`,
         `# Existing artifacts are authoritative and kept; edit Dockerfile or ${composePath} freely.`,
@@ -129,7 +131,7 @@ export function planDockerDeploy(input) {
     }
     runbook.push(``, `# Build/create/reconcile the service. Re-running this is the complete local redeploy; state stays`, `# in the Compose volume mounted at ${MOUNT}.`, `${compose} up -d --build`, `curl --fail http://127.0.0.1:${input.port}/health`, ``, `# Operate it:`, `${compose} logs -f agent`, `${compose} ps`, `${compose} down        # stops containers; keeps the state volume`, `# ${compose} down -v   # DESTRUCTIVE: also deletes auth, sessions, and channel state`);
     if (input.tunnel) {
-        runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Detected Telegram/Feishu/Lark channels auto-register; GitHub prints the URL. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);
+        runbook.push(``, `# Quick Tunnel: \`--run\` starts the Compose tunnel service and reads its ephemeral public URL.`, `# Telegram/Feishu/Lark and locally onboarded Slack auto-register; GitHub/manual Slack print console URLs. Re-run after the`, `# tunnel container/Docker daemon restarts: a new Quick Tunnel URL must replace the old webhook URL.`, `${compose} logs -f tunnel`);
     }
     else if (paths.length > 0) {
         runbook.push(``, `# Public ingress is operator-owned: add your tunnel/proxy/DNS/TLS, then configure the`, `# detected default endpoint(s): ${paths.map((path) => `https://<your-domain>${path}`).join(", ")}.`, `# If your channels/*.ts glue remaps a route, use that path instead.`);

package/dist/deploy/fly/plan.d.ts

@@ -28,8 +28,10 @@ export interface FlyPlanInput extends ContainerInput {
      * `"OAuth"`/`"stored credential"` (a local login the server can't use), or undefined (unconfigured).
      */
     modelAuth: string | undefined;
-    /** Channels discovered in the workspace — each contributes its secret metadata + webhook step. */
+    /** Known first-party channels — each contributes its secret metadata + webhook step. */
     channels: ChannelKind[];
+    /** All long-connection channel basenames, including custom channels — require one running machine. */
+    longConnectionChannels?: string[];
     /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
     extraSecrets?: string[];
     /** `auto_stop_machines` — `"suspend"` (default, fast resume) or `"stop"` (cold start). CLI `--stop`. */

package/dist/deploy/fly/plan.js

@@ -1,6 +1,6 @@
 import { containerArtifacts } from "../container.js";
 import { deploymentSecrets, isEnvKey } from "../secrets.js";
-function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTriggers) {
+function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTriggers, hasLongConnectionChannel) {
     // min_machines_running: 1 (keep one up) when a github channel is present, TIME triggers exist, OR the
     // operator opted out of scale-to-zero. GitHub's is a SAFETY default — its fire-and-forget turns have no
     // replay, so scaling to zero could drop an in-flight review. Time triggers (schedules/wake) have no
@@ -10,9 +10,11 @@ function flyToml(appName, port, hasGithub, autostop, scaleToZero, hasTimeTrigger
         ? `  min_machines_running = 1         # github turns have no replay — don't scale to zero (an in-flight review would be lost)`
         : hasTimeTriggers
             ? `  min_machines_running = 1         # schedules/wake-ups need a running machine (no external wake-up for a cron instant)`
-            : !scaleToZero
-                ? `  min_machines_running = 1         # kept running (--no-scale-to-zero)`
-                : `  min_machines_running = 0         # scale to zero`;
+            : hasLongConnectionChannel
+                ? `  min_machines_running = 1         # long-connection channel needs a running machine (cannot wake from zero)`
+                : !scaleToZero
+                    ? `  min_machines_running = 1         # kept running (--no-scale-to-zero)`
+                    : `  min_machines_running = 0         # scale to zero`;
     const stopLine = autostop === "stop"
         ? `  auto_stop_machines = "stop"      # stop on idle (cold start on the next webhook)`
         : `  auto_stop_machines = "suspend"   # suspend on idle (fast resume on the next webhook)`;
@@ -52,7 +54,7 @@ export function planFlyDeploy(input) {
     const artifacts = [
         {
             path: flyTomlPath,
-            content: flyToml(appName, port, channels.includes("github"), input.autostop, input.scaleToZero, input.hasTimeTriggers),
+            content: flyToml(appName, port, channels.includes("github"), input.autostop, input.scaleToZero, input.hasTimeTriggers, (input.longConnectionChannels?.length ?? 0) > 0),
         },
         ...containerArtifacts(input),
     ];
@@ -60,7 +62,7 @@ export function planFlyDeploy(input) {
     // model key (when local auth is an env key) + every discovered channel's secrets. Names + hints as
     // COMMENT lines (a `#` inside a `\`-continued command would break the shell), then one flat, executable
     // `fly secrets set` the coding agent fills — `<value>` placeholders, never inline comments.
-    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets);
+    const secrets = deploymentSecrets(modelAuth, channels, input.extraSecrets, input.longConnectionChannels);
     const requiredSecrets = secrets.filter((secret) => secret.required);
     const optionalSecrets = secrets.filter((secret) => !secret.required);
     const deployCmd = kitDir
@@ -111,8 +113,11 @@ export function planFlyDeploy(input) {
     if (channels.includes("github")) {
         post.push(`# After deploy — set the GitHub webhook (repo Settings → Webhooks). Path assumes the default route`, `# (POST /webhook); if you remapped it in channels/github.ts, use your path:`, `#   Payload URL = https://${appName}.fly.dev/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
     }
+    if (channels.includes("slack")) {
+        post.push(`# After deploy — set Slack Event Subscriptions → Request URL. Path assumes POST /slack;`, `# Slack verifies the running endpoint with a challenge:`, `#   Request URL = https://${appName}.fly.dev/slack`, `# Ensure OAuth scopes + message.* subscriptions match the groupBehavior in channels/slack.ts.`);
+    }
     for (const kind of ["feishu", "lark"]) {
-        if (!channels.includes(kind))
+        if (!channels.includes(kind) || input.longConnectionChannels?.includes(kind))
             continue;
         const label = kind === "feishu" ? "Feishu" : "Lark";
         post.push(`# After deploy — set the ${label} event Request URL (developer console → Events & Callbacks).`, `# Path assumes the default route (POST /${kind}); the app must be RUNNING when you save (the console`, `# verifies the URL with a challenge):`, `#   Request URL = https://${appName}.fly.dev/${kind}`);

package/dist/deploy/fly/run.d.ts

@@ -35,6 +35,7 @@ export interface FlyRunPlan {
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** fly.toml path passed to `fly deploy -c` (relative to the run cwd = the workspace dir). */
     flyConfig: string;
 }
@@ -46,9 +47,9 @@ export type FlyRunOutcome = {
     gate: string;
 };
 /**
- * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` /
- * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
- * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * Run the deploy through `fly`. `log` reports progress; the injected Telegram/Feishu/Slack registrars
+ * perform post-deploy webhook steps from the builder machine (Slack's control credential never travels
+ * to the host). Absent, the manual console
  * instruction is printed. Every gate is fail-visible.
  */
-export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>): Promise<FlyRunOutcome>;
+export declare function deployFlyRun(plan: FlyRunPlan, fly: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<FlyRunOutcome>;

package/dist/deploy/fly/run.js

@@ -19,12 +19,12 @@ function listHasName(stdout, name) {
     }
 }
 /**
- * Run the deploy through `fly`. `log` reports progress; `registerTelegram(baseUrl)` /
- * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
- * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * Run the deploy through `fly`. `log` reports progress; the injected Telegram/Feishu/Slack registrars
+ * perform post-deploy webhook steps from the builder machine (Slack's control credential never travels
+ * to the host). Absent, the manual console
  * instruction is printed. Every gate is fail-visible.
  */
-export async function deployFlyRun(plan, fly, log, registerTelegram, registerFeishu) {
+export async function deployFlyRun(plan, fly, log, registerTelegram, registerFeishu, registerSlack) {
     const gate = (g) => ({ ok: false, gate: g });
     // 1. Auth is the one gate a coding agent can't clear itself (browser OAuth). `whoami` succeeds with
     //    either an interactive login or FLY_API_TOKEN, so one check covers both.
@@ -91,8 +91,19 @@ export async function deployFlyRun(plan, fly, log, registerTelegram, registerFei
         log(`github: set the webhook in the repo (Settings → Webhooks) → https://${plan.appName}.fly.dev/webhook`);
         reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
     }
+    if (plan.channels.includes("slack")) {
+        const baseUrl = `https://${plan.appName}.fly.dev`;
+        if (registerSlack) {
+            log("registering slack event URL…");
+            reg.track("slack", await registerSlack(baseUrl));
+        }
+        else {
+            log(`slack: set Event Subscriptions → Request URL → ${baseUrl}/slack`);
+            reg.track("slack", "manual");
+        }
+    }
     for (const kind of ["feishu", "lark"]) {
-        if (!plan.channels.includes(kind))
+        if (!plan.channels.includes(kind) || plan.longConnectionChannels?.includes(kind))
             continue;
         if (registerFeishu) {
             log(`registering ${kind} event URL…`);

package/dist/deploy/preflight.d.ts

@@ -2,14 +2,18 @@ import type { FastagentConfig } from "../engines/pi/config.ts";
 import { type ChannelKind } from "../scaffold/add-channel.ts";
 import { type ContainerInput } from "./container.ts";
 /** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). Host-neutral advisories. */
-export interface DeployMessage {
+interface DeployMessage {
     level: "warn" | "note";
     text: string;
 }
 /** The resolved facts every host plan needs (the container shape, channels, model auth, ports/secrets). */
-export interface DeployFacts {
+interface DeployFacts {
     messages: DeployMessage[];
     channels: ChannelKind[];
+    /** Every structurally detected HTTP-route channel basename, including custom channels. */
+    routeChannels: string[];
+    /** Every structurally detected long-connection channel basename, including custom channels. */
+    longConnectionChannels: string[];
     /** Whether the agent has TIME triggers — `schedules/` files or `selfSchedule` (the wake tool). Cron/wake
      *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
      *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */
@@ -46,8 +50,9 @@ export declare function preflightDeploy(input: {
     run: boolean;
     /** `--force` regenerates artifacts, so the kept-hand-written-Dockerfile apt warning does not apply. */
     force: boolean;
-    /** `--auth-path` / `FASTAGENT_AUTH_PATH`; falls back to the project default `<state root>/auth.json`. */
-    authPathOverride: string | undefined;
+    /** The raw `--auth-path` flag; the chain (flag > FASTAGENT_AUTH_PATH > `<state root>/auth.json`)
+     *  is resolved HERE via {@link resolveAuthPath} — the one owner, same as every serving command. */
+    authPathFlag: string | undefined;
 }): Promise<DeployPreflight>;
 /**
  * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`
@@ -57,3 +62,4 @@ export declare function preflightDeploy(input: {
  * (`--run`). Single source on purpose — a host env block (fly.toml `[env]`) is NOT advertised as a second home.
  */
 export declare function modelTravelIssue(configModel: string | undefined, modelSpec: string | undefined): string | undefined;
+export {};