@fastagent-sh/fastagent 0.13.0 → 0.15.0

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

@@ -0,0 +1,45 @@
+/**
+ * `fastagent deploy docker` — the local-Docker plan. The application image stays ingress-neutral:
+ * this target generates only the shared Dockerfile plus a small Compose service for the FastAgent
+ * process, its loopback port, exact environment-variable names, and one persistent state volume.
+ * `--tunnel` can add an ephemeral Cloudflare Quick Tunnel service; durable ingress remains operator-owned.
+ */
+import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Artifact, type ContainerInput } from "../container.ts";
+export interface DockerPlanInput extends ContainerInput {
+    /** Stable Compose project name, sanitized by {@link toDockerProjectName}. */
+    projectName: string;
+    /** Container + default host port. The host binding is loopback-only by default. */
+    port: number;
+    /** What satisfies model auth locally: an env-var name, an OAuth/stored label, or undefined. */
+    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. */
+    extraSecrets?: string[];
+}
+export interface DockerPlan {
+    /** fastagent.compose.yml + the shared Dockerfile/ignore artifacts. */
+    artifacts: Artifact[];
+    /** Compose file path relative to the workspace root (namespaced for agentDir layouts). */
+    composePath: string;
+    /** Ordered local build/run/operate instructions. */
+    runbook: string[];
+}
+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";
+/** Whether a Compose file still opts into generated-drift warnings (drop the marker after taking ownership). */
+export declare function isGeneratedCompose(content: string): boolean;
+/** Whether an authoritative Compose file already carries the generated tunnel service contract. */
+export declare function composeHasTunnelService(content: string): boolean;
+/** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
+export declare function toDockerProjectName(directoryName: string): string;
+/** Default first-party webhook paths. Workspace glue may remap them, so guidance labels them defaults. */
+export declare function dockerWebhookPaths(channels: ChannelKind[]): string[];
+/** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
+export declare function planDockerDeploy(input: DockerPlanInput): DockerPlan;

package/dist/deploy/docker/plan.js

@@ -0,0 +1,141 @@
+import { containerArtifacts } from "../container.js";
+import { deploymentSecrets, isEnvKey } from "../secrets.js";
+const MOUNT = "/data";
+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";
+/** Whether a Compose file still opts into generated-drift warnings (drop the marker after taking ownership). */
+export function isGeneratedCompose(content) {
+    return content.startsWith(GENERATED_COMPOSE_MARKER);
+}
+/** Whether an authoritative Compose file already carries the generated tunnel service contract. */
+export function composeHasTunnelService(content) {
+    return /^[ \t]+tunnel:\s*(?:#.*)?$/m.test(content);
+}
+/** Compose project names are lowercase [a-z0-9_-] and must start with an alphanumeric character. */
+export function toDockerProjectName(directoryName) {
+    const slug = directoryName
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "")
+        .slice(0, 54)
+        .replace(/[-_]+$/g, "");
+    return `fastagent-${slug || "agent"}`;
+}
+/** Default first-party webhook paths. Workspace glue may remap them, so guidance labels them defaults. */
+export function dockerWebhookPaths(channels) {
+    const path = {
+        github: "/webhook",
+        telegram: "/telegram",
+        slack: "/slack",
+        feishu: "/feishu",
+        lark: "/lark",
+    };
+    return channels.map((kind) => path[kind]);
+}
+/** `${NAME:-}` without making JavaScript treat it as interpolation. */
+function composeInterpolation(name) {
+    return `\${${name}:-}`;
+}
+/** Relative path from the namespaced Compose file's directory back to the workspace/build root. */
+function buildContext(kitDir) {
+    if (!kitDir)
+        return ".";
+    return kitDir
+        .split("/")
+        .map(() => "..")
+        .join("/");
+}
+function composeYaml(input) {
+    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"])];
+    const secretEnv = envNames.map((name) => `      ${name}: "${composeInterpolation(name)}"`).join("\n");
+    const context = buildContext(input.kitDir);
+    const dockerfile = input.kitDir ? `${input.kitDir}/Dockerfile` : "Dockerfile";
+    const tunnelService = input.tunnel
+        ? `
+  # Cloudflare Quick Tunnel: ephemeral URL, generated only with \`deploy docker --tunnel\`.
+  # No restart policy on purpose: a new process gets a new URL and needs webhook re-registration.
+  tunnel:
+    image: ${CLOUDFLARED_IMAGE}
+    command:
+      - tunnel
+      - --no-autoupdate
+      - --url
+      - http://agent:${input.port}
+    depends_on:
+      - agent
+    environment:
+      # Docker Desktop may inject HTTP(S)_PROXY into containers. The origin is Docker-internal and must
+      # bypass it; preserve any operator NO_PROXY entries after the required service/loopback names.
+      NO_PROXY: "agent,localhost,127.0.0.1,${composeInterpolation("NO_PROXY")}"
+      no_proxy: "agent,localhost,127.0.0.1,${composeInterpolation("no_proxy")}"
+    restart: "no"
+`
+        : "";
+    return `${GENERATED_COMPOSE_MARKER}. Edit freely — it is kept unless you pass --force.
+# Durable/public ingress remains yours; --tunnel optionally adds an ephemeral Quick Tunnel service.
+name: ${input.projectName}
+
+services:
+  agent:
+    build:
+      context: ${context}
+      dockerfile: ${dockerfile}
+    ports:
+      - "127.0.0.1:${input.port}:${input.port}"
+    environment:
+      PORT: "${input.port}"
+      FASTAGENT_STATE_DIR: "${MOUNT}"
+${secretEnv}
+    volumes:
+      - state:${MOUNT}
+    restart: unless-stopped
+${tunnelService}
+volumes:
+  state:
+`;
+}
+/** Compute local-Docker artifacts + the runbook; no Docker process is touched here. */
+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, input.longConnectionChannels);
+    const required = secrets.filter((secret) => secret.required);
+    const optional = secrets.filter((secret) => !secret.required);
+    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.`,
+        `# Prereqs: Docker Engine/Desktop with Compose >= ${MIN_DOCKER_COMPOSE_VERSION} (\`docker compose version\`).`,
+    ];
+    if (required.length > 0) {
+        runbook.push(`# Required environment values (put them in the workspace .env or export them):`, ...required.map((secret) => `#   ${secret.name}: ${secret.hint}`));
+    }
+    if (optional.length > 0) {
+        runbook.push(`# Optional environment values:`, ...optional.map((secret) => `#   ${secret.name}: ${secret.hint}`));
+    }
+    if (!isEnvKey(input.modelAuth)) {
+        runbook.push(input.modelAuth === undefined
+            ? `# Model auth: none found locally — run \`fastagent login\` or set a provider API key before --run.`
+            : `# Model auth: local source is "${input.modelAuth}" — \`--run\` carries auth.json as FASTAGENT_AUTH_SEED.`, `# For a manual Compose run, provide a provider API key or set FASTAGENT_AUTH_SEED yourself.`);
+    }
+    if (input.kitDir) {
+        runbook.push(`# Repo-as-workspace: run from the REPO ROOT. Compose lives under ${input.kitDir}/ but builds`, `# the whole repository; only the kit's dependencies are installed by ${input.kitDir}/Dockerfile.`);
+    }
+    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.`, `# 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.`);
+    }
+    runbook.push(`# Keep one agent replica: the local state volume is single-process; multiple replicas split/corrupt state.`);
+    return { artifacts, composePath, runbook };
+}

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

@@ -0,0 +1,40 @@
+import type { CliRunner } from "../runner.ts";
+export interface DockerRunPlan {
+    /** Compose file relative to the runner cwd (the workspace root). */
+    composeFile: string;
+    /** Container port from config; used to ask Compose for the effective published host port. */
+    port: number;
+    /** Values interpolated by Compose. Keys/values are passed in the child environment, never argv. */
+    secrets: Record<string, string>;
+    /** Required names with no local value; gate before build/create. */
+    missingSecrets: string[];
+    /** Neither an env-key credential nor a readable auth.json is available. */
+    needsModelCredential: boolean;
+    /** `--tunnel` was requested for this run; a kept Compose file must actually contain that service. */
+    requireTunnel: boolean;
+}
+export type DockerRunOutcome = {
+    ok: true;
+    url?: string;
+    tunnelUrl?: string;
+} | {
+    ok: false;
+    gate: string;
+};
+export type DockerHealthProbe = (healthUrl: string) => Promise<boolean>;
+export type DockerTunnelUrlProbe = (docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv) => Promise<string | undefined>;
+/** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
+export declare function localUrlFromComposePort(stdout: string): string | undefined;
+/** Poll the detached cloudflared service's logs until its assigned Quick Tunnel URL appears. */
+export declare function waitForComposeTunnelUrl(docker: CliRunner, composeFile: string, env: NodeJS.ProcessEnv, options?: {
+    attempts?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<string | undefined>;
+/**
+ * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
+ * only assumes the generated service contract (`agent`, config's container port) for optional URL/
+ * readiness reporting. If the service intentionally has no host-published port, a successful running
+ * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
+ */
+export declare function deployDockerRun(plan: DockerRunPlan, docker: CliRunner, log: (message: string) => void, healthProbe?: DockerHealthProbe, tunnelUrlProbe?: DockerTunnelUrlProbe): Promise<DockerRunOutcome>;

package/dist/deploy/docker/run.js

@@ -0,0 +1,126 @@
+/**
+ * `fastagent deploy docker --run` — reconcile the generated/user-owned Compose application locally.
+ * Compose owns container/network/volume lifecycle; this driver owns only actionable gates, secret/auth
+ * carry through the child environment (never argv), and a readiness check on the published loopback port.
+ */
+import { waitForHealth } from "../../channels/wait-health.js";
+import { parseTunnelUrl } from "../../tunnel.js";
+import { MIN_DOCKER_COMPOSE_VERSION } from "./plan.js";
+/** Resolve Docker Compose's `host:port` output to a loopback URL (safe for 0.0.0.0/[::] bindings too). */
+export function localUrlFromComposePort(stdout) {
+    const line = stdout
+        .split("\n")
+        .map((value) => value.trim())
+        .find(Boolean);
+    const port = line?.match(/:(\d+)$/)?.[1];
+    return port ? `http://127.0.0.1:${port}` : undefined;
+}
+const defaultHealthProbe = (healthUrl) => waitForHealth(healthUrl, 30_000, 500);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Poll the detached cloudflared service's logs until its assigned Quick Tunnel URL appears. */
+export async function waitForComposeTunnelUrl(docker, composeFile, env, options = {}) {
+    const compose = ["compose", "-f", composeFile];
+    const attempts = options.attempts ?? 60;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const logs = await docker([...compose, "logs", "--no-color", "tunnel"], { capture: true, env });
+        const url = logs.code === 0 ? parseTunnelUrl(logs.stdout) : undefined;
+        if (url)
+            return url;
+        if (attempt + 1 < attempts)
+            await (options.sleep ?? sleep)(options.intervalMs ?? 500);
+    }
+    return undefined;
+}
+const defaultTunnelUrlProbe = (docker, composeFile, env) => waitForComposeTunnelUrl(docker, composeFile, env);
+/**
+ * Drive Docker Compose. A custom Compose file remains authoritative: the driver invokes it as-is and
+ * only assumes the generated service contract (`agent`, config's container port) for optional URL/
+ * readiness reporting. If the service intentionally has no host-published port, a successful running
+ * service is still success (an operator-owned sidecar/reverse proxy may be its only ingress).
+ */
+export async function deployDockerRun(plan, docker, log, healthProbe = defaultHealthProbe, tunnelUrlProbe = defaultTunnelUrlProbe) {
+    const gate = (message) => ({ ok: false, gate: message });
+    const compose = ["compose", "-f", plan.composeFile];
+    const env = plan.secrets;
+    // CLI/plugin gate first: unlike a daemon error, spawn ENOENT becomes 127 at the shared runner seam.
+    const version = await docker(["compose", "version"], { capture: true });
+    if (version.code === 127) {
+        return gate("Docker CLI not found — install Docker Engine/Desktop, then re-run");
+    }
+    if (version.code !== 0) {
+        return gate("Docker Compose plugin is unavailable — install/enable `docker compose`, then re-run");
+    }
+    // Credential gates precede the first side effect (build/create), with distinct remediation.
+    if (plan.needsModelCredential) {
+        return gate("no model credential — run `fastagent login`, or set a provider API key in .env, then re-run");
+    }
+    if (plan.missingSecrets.length > 0) {
+        return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
+    }
+    if ((await docker(["info"], { capture: true })).code !== 0) {
+        return gate("Docker daemon is unavailable — start Docker Engine/Desktop, then re-run");
+    }
+    // The file on disk is authoritative. Inspect its actual services before any build/create side effect,
+    // both to protect the `agent` run contract and to catch `--tunnel` against a kept non-tunnel topology.
+    const configured = await docker([...compose, "config", "--services"], { capture: true, env });
+    if (configured.code !== 0) {
+        return gate(`could not load ${plan.composeFile} — generated files require Docker Compose >= ` +
+            `${MIN_DOCKER_COMPOSE_VERSION}; upgrade Compose or fix the file, then re-run`);
+    }
+    const services = configured.stdout.split(/\s+/).filter(Boolean);
+    if (!services.includes("agent")) {
+        return gate(`Compose file must keep the "agent" service for \`fastagent deploy docker --run\``);
+    }
+    const hasTunnel = services.includes("tunnel");
+    if (plan.requireTunnel && !hasTunnel) {
+        return gate(`--tunnel was requested but the kept ${plan.composeFile} has no "tunnel" service — ` +
+            `edit it, delete it and regenerate, or pass --force`);
+    }
+    // Quick Tunnel logs are the control-plane output (the assigned URL). Remove its old container first so
+    // a rerun cannot read a stale URL from accumulated logs; `up` below creates one fresh tunnel, then the
+    // CLI registers that URL. The app container/volume are untouched.
+    if (hasTunnel) {
+        log("recreating the ephemeral tunnel service…");
+        if ((await docker([...compose, "rm", "-s", "-f", "tunnel"], { env })).code !== 0) {
+            return gate(`could not recreate the tunnel service — inspect \`docker compose -f ${plan.composeFile} ps\``);
+        }
+    }
+    log(`building and reconciling ${plan.composeFile}…`);
+    if ((await docker([...compose, "up", "-d", "--build"], { env })).code !== 0) {
+        return gate(`\`docker compose up\` failed — see the Docker output above; fix ${plan.composeFile} and re-run`);
+    }
+    // Detached `up` can return 0 just before a bad command exits. Verify the expected service is actually
+    // running so a broken custom Dockerfile/CMD cannot look deployed. Compose restart loops are excluded.
+    const running = await docker([...compose, "ps", "--status", "running", "--services"], {
+        capture: true,
+        env,
+    });
+    const runningServices = running.stdout.split(/\s+/).filter(Boolean);
+    if (running.code !== 0 || !runningServices.includes("agent")) {
+        return gate(`the Compose service "agent" is not running — inspect with \`docker compose -f ${plan.composeFile} logs agent\``);
+    }
+    if (hasTunnel && !runningServices.includes("tunnel")) {
+        return gate(`the Compose service "tunnel" is not running — inspect with \`docker compose -f ${plan.composeFile} logs tunnel\``);
+    }
+    // A user-owned topology may deliberately remove the host port and expose only through its own ingress.
+    // In that case Compose `port` is absent/non-zero: service-running is the available readiness floor.
+    const published = await docker([...compose, "port", "agent", String(plan.port)], { capture: true, env });
+    const url = published.code === 0 ? localUrlFromComposePort(published.stdout) : undefined;
+    if (!url) {
+        log("agent is running (no host-published port found; using the Compose ingress readiness floor)");
+    }
+    else {
+        const healthUrl = `${url}/health`;
+        if (!(await healthProbe(healthUrl))) {
+            return gate(`agent did not become healthy at ${healthUrl} — inspect \`docker compose -f ${plan.composeFile} logs agent\``);
+        }
+    }
+    if (!hasTunnel)
+        return { ok: true, url };
+    log("waiting for the Compose tunnel service to publish its Quick Tunnel URL…");
+    const tunnelUrl = await tunnelUrlProbe(docker, plan.composeFile, env);
+    if (!tunnelUrl) {
+        return gate(`tunnel did not publish a Quick Tunnel URL — inspect \`docker compose -f ${plan.composeFile} logs tunnel\``);
+    }
+    return { ok: true, url, tunnelUrl };
+}

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 {};