@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/deploy/preflight.js

@@ -11,8 +11,8 @@
  */
 import { readFile } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
-import { defaultAuthPath, resolveStateRoot } from "../engines/pi/config.js";
-import { discoverChannelFiles } from "../engines/pi/channel.js";
+import { resolveAuthPath } from "../engines/pi/config.js";
+import { inspectChannels } from "../engines/pi/channel.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
@@ -25,7 +25,7 @@ import { isGeneratedDockerfile } from "./container.js";
  * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
  */
 export async function preflightDeploy(input) {
-    const { target, agentDir, config, modelSpec, run, force, authPathOverride } = input;
+    const { target, agentDir, config, modelSpec, run, force, authPathFlag } = input;
     const messages = [];
     // The deployed box resolves the model from fastagent.config.ts ONLY (in the image); a model set via
     // env/flag/.env doesn't travel. `--run` would ship a known crash-loop — hard gate; generate-only warns.
@@ -35,20 +35,52 @@ export async function preflightDeploy(input) {
             return { ok: false, gate: modelIssue };
         messages.push({ level: "warn", text: modelIssue });
     }
+    // The control plane on a deployed box: `start` honors `sessionControl: true`, so `/control/*`
+    // (steer/abort/set_model) rides the PUBLIC host URL — protected only by a per-boot bearer token
+    // minted INSIDE the container (`<stateRoot>/control.json`), which external consumers cannot read.
+    // Publicly reachable yet unusable is the worst of both; the tunnel path warns loudly and deploy
+    // must not be the silent second way to break the loopback trust story.
+    if (config.sessionControl === true) {
+        messages.push({
+            level: "warn",
+            text: `sessionControl: true — the deployed box serves /control/* (steer/abort/set_model) at its public URL, ` +
+                `protected only by a per-boot token written inside the container. Read the TOKEN from ` +
+                `<stateRoot>/control.json on the box (its url field is container-loopback — pair the token with the ` +
+                `public host URL: attach --url <public-url> --token …), or front the endpoint with real auth (design §14)`,
+        });
+    }
     // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
     // author wire them.
-    const discovered = await discoverChannelFiles(agentDir);
+    const inspected = await inspectChannels(agentDir);
+    if (inspected.failures.length > 0) {
+        throw new Error(`cannot inspect channel modules: ${inspected.failures.map((failure) => `${failure.label}: ${failure.message}`).join("; ")}`);
+    }
+    const discovered = inspected.channels;
     const channels = discovered.filter((c) => CHANNEL_KINDS.includes(c));
+    const routeChannels = inspected.routeChannels;
+    const longConnectionChannels = inspected.longConnectionChannels;
     for (const c of discovered) {
-        if (!channels.includes(c)) {
-            messages.push({ level: "note", text: `channel "${c}" is custom — set its secrets and webhook yourself` });
-        }
+        if (channels.includes(c))
+            continue;
+        messages.push({
+            level: "note",
+            text: longConnectionChannels.includes(c)
+                ? `long-connection channel "${c}" is custom — configure its secrets yourself; generated deploy plans keep the process running and skip webhook registration`
+                : `route channel "${c}" is custom — configure its secrets and webhook yourself`,
+        });
     }
     // Time triggers (static schedules or self-scheduling) need a machine kept running — unlike a webhook,
     // nothing external wakes a scale-to-zero box for a cron instant or a wake-up. The note is CONDITIONAL
     // ("the generated plan…"): in KEEP mode an existing fly.toml is not rewritten — the CLI warns separately
     // when a kept fly.toml still scales to zero.
     const hasTimeTriggers = (await discoverScheduleFiles(agentDir)).length > 0 || !!config.selfSchedule;
+    if (longConnectionChannels.length > 0) {
+        messages.push({
+            level: "note",
+            text: `long-connection channel present (${longConnectionChannels.join(", ")}) — a GENERATED plan keeps one machine running ` +
+                `(an outbound connection cannot wake a scaled-to-zero service).`,
+        });
+    }
     if (hasTimeTriggers) {
         messages.push({
             level: "note",
@@ -58,7 +90,7 @@ export async function preflightDeploy(input) {
     }
     // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
     // miss a `fastagent login` credential and falsely report "none configured".
-    const authPath = authPathOverride ?? defaultAuthPath(resolveStateRoot(target));
+    const authPath = resolveAuthPath(target, authPathFlag);
     const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
     // Container facts (shared by every host) + the warnings that follow. Repo-as-workspace layout
     // (agentDir ≠ target): the facts describe the KIT — its package.json/runtime/lockfile drive the
@@ -173,7 +205,19 @@ export async function preflightDeploy(input) {
             });
         }
     }
-    return { ok: true, messages, channels, hasTimeTriggers, modelAuth, authPath, container, port, extraSecrets };
+    return {
+        ok: true,
+        messages,
+        channels,
+        routeChannels,
+        longConnectionChannels,
+        hasTimeTriggers,
+        modelAuth,
+        authPath,
+        container,
+        port,
+        extraSecrets,
+    };
 }
 /**
  * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`

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

@@ -29,8 +29,10 @@ export interface RailwayPlanInput extends ContainerInput {
     serviceName: string;
     /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
     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 — no App Sleeping. */
+    longConnectionChannels?: string[];
     /** Extra secret env-var names (fastagent.config deploy.secrets) — added to the runbook's secret list. */
     extraSecrets?: string[];
     /** Time triggers present (schedules/ or selfSchedule) — the runbook forbids App Sleeping: cron/wake has

package/dist/deploy/railway/plan.js

@@ -23,7 +23,7 @@ export function planRailwayDeploy(input) {
         { path: configPath, content: railwayJson(input.kitDir) },
         ...containerArtifacts(input),
     ];
-    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);
     // Order matters, not cosmetics: `railway init` creates a PROJECT with no service, but the volume and
@@ -76,7 +76,10 @@ export function planRailwayDeploy(input) {
     // The public URL is minted, not deterministic (unlike Fly's <app>.fly.dev) — ONE mint step, then each
     // channel's webhook uses that domain (mint once even when both channels are present).
     const hasFeishuCloudChannel = ["feishu", "lark"].some((kind) => channels.includes(kind));
-    if (channels.includes("telegram") || channels.includes("github") || hasFeishuCloudChannel) {
+    if (channels.includes("telegram") ||
+        channels.includes("github") ||
+        channels.includes("slack") ||
+        hasFeishuCloudChannel) {
         runbook.push(``, `# Public URL — Railway mints a *.up.railway.app domain (NOT deterministic). Generate it, then read`, `# the printed https URL and use it as <your-domain> in the webhook step(s) below:`, `railway domain`);
     }
     if (channels.includes("telegram")) {
@@ -85,8 +88,11 @@ export function planRailwayDeploy(input) {
     if (channels.includes("github")) {
         runbook.push(`# Set the GitHub webhook (repo Settings → Webhooks). Default route POST /webhook; if you remapped it`, `# in channels/github.ts, use your path:`, `#   Payload URL = https://<your-domain>/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
     }
+    if (channels.includes("slack")) {
+        runbook.push(`# Set Slack Event Subscriptions → Request URL (default route POST /slack; the running service`, `# answers Slack's challenge), and match scopes/subscriptions to channels/slack.ts groupBehavior:`, `#   Request URL = https://<your-domain>/slack`);
+    }
     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";
         runbook.push(`# Set the ${label} event Request URL (developer console → Events & Callbacks). Default route`, `# POST /${kind}; the service must be RUNNING when you save (the console verifies with a challenge):`, `#   Request URL = https://<your-domain>/${kind}`);
@@ -98,6 +104,8 @@ export function planRailwayDeploy(input) {
         ? `# Scale-to-zero: do NOT enable App Sleeping — github turns have no replay, a sleep mid-review is lost.`
         : input.hasTimeTriggers
             ? `# Scale-to-zero: do NOT enable App Sleeping — schedules/wake-ups have no external wake-up; a sleeping service sleeps through them.`
-            : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
+            : (input.longConnectionChannels?.length ?? 0) > 0
+                ? `# Scale-to-zero: do NOT enable App Sleeping — a long-connection channel must remain connected.`
+                : `# Scale-to-zero (optional, dashboard-only — no CLI/API): Settings → Deploy → Serverless → App Sleeping.`, `# Keep this a SINGLE service: the ${MOUNT} volume is tied to one service; extra replicas split state.`);
     return { artifacts, runbook };
 }

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

@@ -38,6 +38,7 @@ export interface RailwayRunPlan {
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. Off
      *  by default so `--run` only creates on an unlinked dir and never deploys into a pre-existing (possibly
      *  unrelated/production) project; the flag is the operator's explicit "yes, this project". */
@@ -76,9 +77,9 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  */
 export declare function parseHasVolume(stdout: string, mountPath: string): boolean;
 /**
- * Run the deploy through `railway`. `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 `railway`. `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 deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -62,12 +62,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `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 `railway`. `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 deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu) {
+export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu, registerSlack) {
     const gate = (g) => ({ ok: false, gate: g });
     // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
     // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
@@ -179,8 +179,18 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
         log(`github: set the webhook in the repo (Settings → Webhooks) → ${url}/webhook`);
         reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
     }
+    if (plan.channels.includes("slack")) {
+        if (registerSlack) {
+            log("registering slack event URL…");
+            reg.track("slack", await registerSlack(url));
+        }
+        else {
+            log(`slack: set Event Subscriptions → Request URL → ${url}/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/runner.d.ts

@@ -1,4 +1,4 @@
-export interface RunResult {
+interface RunResult {
     code: number;
     /** Captured stdout (for `--json` queries); empty when the command streamed to the terminal. The CLI's
      *  stderr is always inherited straight to the terminal, so it is not a field here. */
@@ -19,3 +19,4 @@ export type CliRunner = (args: string[], opts?: {
  * ENOENT (the CLI not on PATH) resolves to code 127 so the caller can gate with an install hint.
  */
 export declare function spawnRunner(bin: string, cwd: string): CliRunner;
+export {};

package/dist/deploy/secrets.d.ts

@@ -17,7 +17,7 @@ export declare function isEnvKey(source: string | undefined): source is string;
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
+export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[], longConnectionChannels?: string[]): {
     name: string;
     hint: string;
     required: boolean;
@@ -40,6 +40,7 @@ export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
     authFile: Buffer | undefined;
     channels: ChannelKind[];
+    longConnectionChannels?: string[];
     /** Extra secret env-var names from `fastagent.config` deploy.secrets — carried like channel secrets. */
     extraSecrets?: string[];
     env: NodeJS.ProcessEnv;

package/dist/deploy/secrets.js

@@ -19,13 +19,15 @@ export function isEnvKey(source) {
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
+export function deploymentSecrets(modelAuth, channels, extraSecrets = [], longConnectionChannels = []) {
     const secrets = [];
     if (isEnvKey(modelAuth))
         secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
     for (const kind of channels) {
-        for (const e of channelSetup(kind).env)
+        const setupMode = longConnectionChannels.includes(kind) ? "websocket" : "webhook";
+        for (const e of channelSetup(kind, setupMode).env) {
             secrets.push({ name: e.name, hint: e.hint, required: e.required });
+        }
     }
     // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
     for (const name of extraSecrets) {
@@ -67,7 +69,8 @@ export function assembleSecrets(input) {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }
     for (const kind of input.channels) {
-        for (const e of channelSetup(kind).env) {
+        const setupMode = input.longConnectionChannels?.includes(kind) ? "websocket" : "webhook";
+        for (const e of channelSetup(kind, setupMode).env) {
             const v = input.env[e.name];
             if (v)
                 secrets[e.name] = v; // optional channel values travel when configured
@@ -76,6 +79,23 @@ export function assembleSecrets(input) {
             }
         }
     }
+    // Slack bot-token rotation is an all-or-nothing credential bundle. Its fields remain optional so a
+    // manually configured long-lived token works, but a partial bundle must gate before the container
+    // reaches slackChannel construction.
+    if (input.channels.includes("slack")) {
+        const rotation = [
+            "SLACK_BOT_REFRESH_TOKEN",
+            "SLACK_BOT_TOKEN_EXPIRES_AT",
+            "SLACK_CLIENT_ID",
+            "SLACK_CLIENT_SECRET",
+        ];
+        if (rotation.some((name) => !!input.env[name])) {
+            for (const name of rotation) {
+                if (!input.env[name] && !missingSecrets.includes(name))
+                    missingSecrets.push(name);
+            }
+        }
+    }
     for (const name of input.extraSecrets ?? []) {
         if (name in secrets || missingSecrets.includes(name))
             continue; // already covered by model/channel — no dup

package/dist/dev-supervisor.d.ts

@@ -1,5 +1,3 @@
-/** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
-export declare const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
  * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and

package/dist/dev-supervisor.js

@@ -13,13 +13,13 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { loadConfig, resolveAgentDir } from "./engines/pi/config.js";
+import { loadConfig, resolveAgentDir, resolveStateRoot } from "./engines/pi/config.js";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (workspace-relative): the process-bound code inputs only. */
-export const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
+const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore). Ignoring a directory prunes
  * the whole subtree, so everything outside the allowlist — .fastagent state, node_modules, .git, and
@@ -100,7 +100,11 @@ export async function runDevSupervisor(dir, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(agentDir, t.url, { openUrl: openExternalUrl });
+                        void announceWebhooks(dir, t.url, {
+                            openUrl: openExternalUrl,
+                            routeChannels: m.routeChannels,
+                            stateRoot: resolveStateRoot(dir),
+                        });
                     }
                 });
             }

package/dist/engines/pi/channel.d.ts

@@ -1,31 +1,37 @@
-import { type ChannelContext, type Routes } from "../../host/node.ts";
+import { type ChannelContext, type LongConnection, type Routes } from "../../host/node.ts";
 import { type ModuleLoadFailure } from "../../loader.ts";
 /** A dropped route: two channels claim the same key. Surfaced, never silent. */
 export interface ChannelCollision {
     route: string;
     source: string;
 }
+/** A long-connection module bound to the same context route factories receive. Internal serving shape. */
+export interface LoadedLongConnectionChannel {
+    name: string;
+    connect(signal: AbortSignal): LongConnection;
+}
 /**
- * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing, unlike {@link loadChannels}. It enforces the SAME containment guard so info reports
- * exactly the surface dev/start would accept: a channels/ symlink escaping the workspace is rejected
- * here too. This path is independent of loadChannels', so it must guard the boundary on its own.
+ * Import channel files without mounting route factories or opening connections. Deployment needs only
+ * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
  */
-export declare function discoverChannelFiles(dir: string): Promise<string[]>;
+export declare function inspectChannels(dir: string): Promise<{
+    channels: string[];
+    routeChannels: string[];
+    longConnectionChannels: string[];
+    failures: ModuleLoadFailure[];
+}>;
 /**
- * Discover channels in `<dir>/channels/`: each `*.ts|.js|.mjs` default-exports a `(ctx) => Routes`
- * factory ({@link ChannelModule}), called here with the mount context; the returned route maps are
- * merged (first file wins a route-key clash, the dropped route surfaced).
- *
- * A channel file broken for ANY reason — a failed import, a factory that throws when called (a missing
- * env var is the common deploy case), or a malformed shape (not a function, not a Routes object, a bad
- * handler/route key) — is collected in `failures` without preventing validation of sibling files. The
- * serving CLI treats any such failure as fatal: a declared channel must not silently disappear or cause
- * the default `/invoke` route to mount. Programmatic callers can inspect the returned data themselves.
- * Routes are validated fully before any merge, so a throw mounts no partial routes.
+ * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
+ * WITHOUT importing. A symlinked channels directory must remain inside the workspace.
  */
+export declare function discoverChannelFiles(dir: string): Promise<string[]>;
+/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
 export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<{
     routes: Routes;
+    longConnections: LoadedLongConnectionChannel[];
+    routeChannels: string[];
+    longConnectionChannels: string[];
     collisions: ChannelCollision[];
     failures: ModuleLoadFailure[];
 }>;

package/dist/engines/pi/channel.js

@@ -1,19 +1,55 @@
 /**
- * Channel discovery (the N axis, filesystem form): a workspace declares its inbound surface by
- * dropping files in `channels/`, mirroring `tools/`. Each file wires a third-party adapter to the
- * app's `on()` glue and returns the routes it mounts. There is no config-level channel list — a
- * channel always needs glue, so it is always a file.
+ * Channel discovery (the N axis, filesystem form). A channel file default-exports either the existing
+ * route factory `(ctx) => Routes`, or an explicit long-connection module `{ name, connect(ctx, signal) }`.
  */
 import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { parseRouteKey } from "../../host/node.js";
-import { assertInsideWorkspace } from "../../workspace.js";
+import { parseRouteKey, } from "../../host/node.js";
 import { isModuleFile, loadModuleDir } from "../../loader.js";
+import { assertInsideWorkspace } from "../../workspace.js";
+function longConnectionModule(value) {
+    return value !== null && typeof value === "object" && typeof value.connect === "function";
+}
+function validateLongConnectionModule(value, label) {
+    if (typeof value.name !== "string" || value.name.trim() === "") {
+        throw new Error(`${label}: long-connection channel name must be a non-empty string`);
+    }
+}
+/**
+ * Import channel files without mounting route factories or opening connections. Deployment needs only
+ * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
+ */
+export async function inspectChannels(dir) {
+    await assertInsideWorkspace(dir, "channels");
+    const { modules, failures } = await loadModuleDir(join(dir, "channels"));
+    const channels = [];
+    const routeChannels = [];
+    const longConnectionChannels = [];
+    for (const { name, label, file, mod } of modules) {
+        try {
+            if (typeof mod.default === "function") {
+                channels.push(name);
+                routeChannels.push(name);
+                continue;
+            }
+            if (longConnectionModule(mod.default)) {
+                validateLongConnectionModule(mod.default, label);
+                channels.push(name);
+                longConnectionChannels.push(name);
+                continue;
+            }
+            throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
+        }
+        catch (error) {
+            failures.push({ label, file, message: error.message });
+        }
+    }
+    return { channels, routeChannels, longConnectionChannels, failures };
+}
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing, unlike {@link loadChannels}. It enforces the SAME containment guard so info reports
- * exactly the surface dev/start would accept: a channels/ symlink escaping the workspace is rejected
- * here too. This path is independent of loadChannels', so it must guard the boundary on its own.
+ * WITHOUT importing. A symlinked channels directory must remain inside the workspace.
  */
 export async function discoverChannelFiles(dir) {
     await assertInsideWorkspace(dir, "channels");
@@ -28,75 +64,68 @@ export async function discoverChannelFiles(dir) {
     }
     return names
         .filter(isModuleFile)
-        .map((n) => n.replace(/\.(ts|js|mjs)$/, ""))
+        .map((name) => name.replace(/\.(ts|js|mjs)$/, ""))
         .sort();
 }
-/**
- * Discover channels in `<dir>/channels/`: each `*.ts|.js|.mjs` default-exports a `(ctx) => Routes`
- * factory ({@link ChannelModule}), called here with the mount context; the returned route maps are
- * merged (first file wins a route-key clash, the dropped route surfaced).
- *
- * A channel file broken for ANY reason — a failed import, a factory that throws when called (a missing
- * env var is the common deploy case), or a malformed shape (not a function, not a Routes object, a bad
- * handler/route key) — is collected in `failures` without preventing validation of sibling files. The
- * serving CLI treats any such failure as fatal: a declared channel must not silently disappear or cause
- * the default `/invoke` route to mount. Programmatic callers can inspect the returned data themselves.
- * Routes are validated fully before any merge, so a throw mounts no partial routes.
- */
+function validateRoutes(value, label) {
+    if (value === null || typeof value !== "object" || value instanceof Map) {
+        throw new Error(`${label} must return a Routes object`);
+    }
+    const routes = Object.entries(value);
+    if (routes.length === 0) {
+        throw new Error(`${label} declared no routes — return a non-empty { "METHOD /path": handler } object`);
+    }
+    for (const [route, handler] of routes) {
+        if (typeof handler !== "function") {
+            throw new Error(`${label}: route "${route}" must map to a handler function, got ${typeof handler}`);
+        }
+        if (!parseRouteKey(route).path.startsWith("/")) {
+            throw new Error(`${label}: route "${route}" is not a valid route key (expected "METHOD /path" or "/path")`);
+        }
+    }
+    return routes;
+}
+/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
 export async function loadChannels(dir, ctx) {
-    // The contract says stateRoot is absolute; enforce it at the mount boundary so a relative root fails
-    // fast HERE instead of silently re-anchoring some channel's state on the process cwd.
     if (!isAbsolute(ctx.stateRoot)) {
         throw new Error(`ChannelContext.stateRoot must be absolute, got "${ctx.stateRoot}"`);
     }
-    // A symlinked channels/ is followed only if it stays inside the workspace, so a deploy that copies
-    // the dir includes it (the directory is the agent).
     await assertInsideWorkspace(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const routes = {};
+    const longConnections = [];
+    const routeChannels = [];
+    const longConnectionChannels = [];
     const collisions = [];
-    for (const { label, file, mod } of modules) {
-        // Collect every per-file failure so the caller can report all broken channels in one pass. The CLI
-        // then fails startup rather than silently dropping a declared route; direct callers own their policy.
-        // Routes are VALIDATED fully before any are merged, so a throw mid-validation mounts NO partial routes.
+    for (const { name, label, file, mod } of modules) {
         try {
-            const factory = mod.default;
-            if (typeof factory !== "function") {
-                throw new Error(`${label} must default-export (ctx) => Routes`);
+            if (longConnectionModule(mod.default)) {
+                validateLongConnectionModule(mod.default, label);
+                const channel = mod.default;
+                longConnections.push({
+                    name: channel.name,
+                    connect: (signal) => channel.connect(ctx, signal),
+                });
+                longConnectionChannels.push(name);
+                continue;
+            }
+            if (typeof mod.default !== "function") {
+                throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
             }
-            const declared = factory(ctx);
-            // A Promise needs its own branch before the object check: mark it handled (a rejected async setup
-            // must not go unhandled) and reject it with a precise message rather than the zero-routes one.
+            const declared = mod.default(ctx);
             if (declared !== null &&
                 typeof declared === "object" &&
                 typeof declared.then === "function") {
                 declared.catch(() => { });
-                throw new Error(`${label} must return Routes synchronously, not a Promise (an async factory is not supported)`);
-            }
-            if (declared === null || typeof declared !== "object") {
-                throw new Error(`${label} must return a Routes object, got ${declared === null ? "null" : typeof declared}`);
-            }
-            const declaredRoutes = Object.entries(declared);
-            if (declaredRoutes.length === 0) {
-                throw new Error(`${label} declared no routes — return a non-empty { "METHOD /path": handler } object (a Promise, Map, array, or {} yields none)`);
-            }
-            // Validate every route BEFORE merging any (no partial mount on a later throw).
-            for (const [route, handler] of declaredRoutes) {
-                if (typeof handler !== "function") {
-                    throw new Error(`${label}: route "${route}" must map to a handler function, got ${typeof handler}`);
-                }
-                if (!parseRouteKey(route).path.startsWith("/")) {
-                    throw new Error(`${label}: route "${route}" is not a valid route key (expected "METHOD /path" or "/path")`);
-                }
+                throw new Error(`${label} must return Routes synchronously, not a Promise`);
             }
+            const declaredRoutes = validateRoutes(declared, label);
             for (const [route, handler] of declaredRoutes) {
                 const parsed = parseRouteKey(route);
-                // Overlap, not literal-key, equality: the router treats a bare `/path` as any-method, so
-                // `/webhook` and `POST /webhook` clash. `GET /x` vs `POST /x` is fine.
-                const clash = Object.keys(routes).some((k) => {
-                    const e = parseRouteKey(k);
-                    return (e.path === parsed.path &&
-                        (e.method === undefined || parsed.method === undefined || e.method === parsed.method));
+                const clash = Object.keys(routes).some((key) => {
+                    const existing = parseRouteKey(key);
+                    return (existing.path === parsed.path &&
+                        (existing.method === undefined || parsed.method === undefined || existing.method === parsed.method));
                 });
                 if (clash) {
                     collisions.push({ route, source: label });
@@ -104,10 +133,11 @@ export async function loadChannels(dir, ctx) {
                 }
                 routes[route] = handler;
             }
+            routeChannels.push(name);
         }
         catch (error) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { routes, collisions, failures };
+    return { routes, longConnections, routeChannels, longConnectionChannels, collisions, failures };
 }

package/dist/engines/pi/chat.d.ts

@@ -1,19 +1,7 @@
-import { type AgentSessionRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
-export interface RunPiChatOptions {
-    /** Model spec override (the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
-    model?: string;
-}
-/**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
- * skills resolved exactly as the dev opener does). Split from {@link runPiChat} so the assembly —
- * the fidelity-critical part — is inspectable without launching the TUI.
- */
-export declare function buildChatRuntime(dir: string, options?: RunPiChatOptions, 
-/** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
-sessionManager?: SessionManager): Promise<AgentSessionRuntime>;
+import { type BuildSessionRuntimeOptions } from "./session-builder.ts";
 /**
  * Open the workspace's agent in pi's interactive TUI and run until the user exits. The agent is
- * fastagent's assembled agent (same model/tools/skills/prompt as dev/start serve); pi's TUI handles
- * login, rendering, and same-workspace sessions natively.
+ * fastagent's assembled agent (same model/tools/skills/prompt/auth as dev/start serve); pi's TUI
+ * handles login, rendering, and same-workspace sessions natively.
  */
-export declare function runPiChat(dir: string, options?: RunPiChatOptions): Promise<void>;
+export declare function runPiChat(dir: string, options?: BuildSessionRuntimeOptions): Promise<void>;