@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/service.d.ts

@@ -1,3 +1,19 @@
+/**
+ * The product, as one call: an agent directory becomes a live service.
+ *
+ * That phrase is the promise on the README, and until this existed only the CLI could keep it. The
+ * assembly parts live here too — `routesFor`, `mountSessionControl`, `startSchedules` — because a
+ * public entry may not reach into `cli/`: that directory decides process-level things (`fail.ts`
+ * calls `process.exit`) which a library mounted inside someone's app does not get to decide.
+ * Everything else was parts: assemble the agent, discover channels, mount the control plane, start
+ * schedules, open long connections, compose a router. An embedder had to know that list and get its
+ * order right, and getting it wrong is silent: a plane that 404s while advertising itself, a
+ * schedule that never fires.
+ *
+ * So the assembly lives here, and `dev`/`start` are callers. AgentCore is the one exception, and a
+ * substantive one: its channels load lazily after a state-snapshot restore, so it cannot use an
+ * assembly that discovers them eagerly (cli/commands/start.ts says so at the branch).
+ */
 import type { Agent } from "./agent.ts";
 import { type PrefixMount } from "./channels/serve.ts";
 import { type LoadedLongConnectionChannel } from "./channels/discover.ts";
@@ -35,20 +51,17 @@ export declare function routesFor(agentDir: string, agent: Agent, stateRoot: str
  * load after this ran against an empty base.
  */
 export declare function assertNoControlPlaneCollision(channelRoutes: Routes, plane: PrefixMount): void;
-export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
-    tunnel?: boolean;
+export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, options?: {
     agent?: Agent;
-    host?: string;
 }): {
     routes: Routes;
     mounts: PrefixMount[];
-    /** The plane's bearer token and prefix — how an embedder distributes access without a discovery file. */
+    /** The plane's bearer token and prefix — how a caller distributes access (the CLI writes it to
+     *  `<stateRoot>/control.json` for local discovery; an embedder hands it out itself). */
     control?: {
         token: string;
         prefix: string;
     };
-    /** Write the local discovery file; returns its removal. Installs no signal handlers. */
-    announce: (boundPort: number) => () => void;
 };
 /**
  * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
@@ -88,20 +101,14 @@ export interface AgentService {
      *  fails to come up, after closing the service: a host must not report itself serving while a
      *  declared channel is dead, and health answers 503 until this resolves. */
     ready: Promise<void>;
-    /** The control plane's bearer token and prefix, when `sessionControl` is on — how an embedder
-     *  hands access to a client without a discovery file. */
+    /** The control plane's bearer token and prefix, when `sessionControl` is on — how a caller hands
+     *  access to a client. The CLI writes it to `<stateRoot>/control.json` for `fastagent attach`; an
+     *  embedder mounted inside a larger app has no port of its own to describe and distributes it
+     *  itself. */
     control?: {
         token: string;
         prefix: string;
     };
-    /** Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the plane,
-     *  once the port is known. Optional: an embedder mounted inside a larger app has no port of its
-     *  own to describe and uses {@link AgentService.control} instead.
-     *
-     *  Removed by `close()`. Not by an `exit` handler: installing one is a decision about the whole
-     *  process, which a mounted library does not get to make. A hard exit therefore leaves the file
-     *  behind — advisory, overwritten by the next boot, and the client's own error stays honest. */
-    announce(boundPort: number): void;
     /** Stop long connections and schedules. Idempotent; also runs when `options.signal` aborts. */
     close(): Promise<void>;
 }
@@ -111,12 +118,6 @@ export interface MountAgentServiceOptions {
      *  must get the SAME one, which is why this is a hook rather than the caller's own call. `dev`
      *  passes `logAgentLoop`. */
     wrapAgent?: (agent: Agent) => Agent;
-    /** Passed through to the control plane mount: `--tunnel` widens its warning, `host` names the
-     *  bind address in the discovery file. */
-    control?: {
-        tunnel?: boolean;
-        host?: string;
-    };
     /** Aborting this closes the service, exactly like calling {@link AgentService.close}. */
     signal?: AbortSignal;
     /** Called when a long connection ends on its own — a dropped socket-mode channel, say. The CLI

package/dist/service.js

@@ -1,23 +1,3 @@
-/**
- * The product, as one call: an agent directory becomes a live service.
- *
- * That phrase is the promise on the README, and until this existed only the CLI could keep it. The
- * assembly parts live here too — `routesFor`, `mountSessionControl`, `startSchedules` — because a
- * public entry may not reach into `cli/`: that directory decides process-level things (`fail.ts`
- * calls `process.exit`) which a library mounted inside someone's app does not get to decide.
- * Everything else was parts: assemble the agent, discover channels, mount the control plane, start
- * schedules, open long connections, compose a router. An embedder had to know that list and get its
- * order right, and getting it wrong is silent: a plane that 404s while advertising itself, a
- * schedule that never fires.
- *
- * So the assembly lives here, and `dev`/`start` are callers. AgentCore is the one exception, and a
- * substantive one: its channels load lazily after a state-snapshot restore, so it cannot use an
- * assembly that discovers them eagerly (cli/commands/start.ts says so at the branch).
- */
-import { mkdirSync, rmSync } from "node:fs";
-import { writeFileAtomic } from "./atomic-write.js";
-import { join } from "node:path";
-import { classifyBind, clientHost } from "./bind.js";
 import { CONTROL_TOKEN_ENV, createControlPlane } from "./channels/control.js";
 import { createInvokeHandler } from "./channels/http.js";
 import { text } from "./channels/respond.js";
@@ -25,7 +5,8 @@ import { parseRouteKey, pathUnderPrefix, router } from "./channels/serve.js";
 import { loadChannels } from "./channels/discover.js";
 import { loadSchedules } from "./schedule/discover.js";
 import { createScheduler } from "./schedule/scheduler.js";
-import { log, reportModuleLoadFailures } from "./log.js";
+import { log } from "./log.js";
+import { reportModuleLoadFailures } from "./loader.js";
 /** Default wait for a channel's `closed` before reporting it stuck. A channel that ignores its
  *  abort signal must not hang a caller's teardown — or, during a failed start, keep the original
  *  error from arriving. The CLI passes a shorter one: its own forced exit must come AFTER this, or
@@ -70,7 +51,7 @@ export async function routesFor(agentDir, agent, stateRoot, control, options = {
         control,
     });
     for (const c of collisions) {
-        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
+        log.warn(`[fastagent] channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
     }
     reportModuleLoadFailures(failures);
     if (failures.length > 0 || collisions.length > 0) {
@@ -113,9 +94,9 @@ export function assertNoControlPlaneCollision(channelRoutes, plane) {
             `rename the channel route or disable sessionControl in fastagent.config`);
     }
 }
-export function mountSessionControl(routes, control, stateRoot, options = {}) {
+export function mountSessionControl(routes, control, options = {}) {
     if (!control)
-        return { routes, mounts: [], announce: () => () => { } };
+        return { routes, mounts: [] };
     // WHO OWNS the secret. Per-boot mint is right locally: discovery is `control.json` and its file
     // permissions, which works because both holders share a filesystem. A deployment removes that
     // premise — a token minted in the container is replaced every restart and reachable only by shelling
@@ -142,45 +123,7 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
     const token = injected || crypto.randomUUID();
     const plane = createControlPlane(control, { token, agent: options.agent });
     assertNoControlPlaneCollision(routes, plane);
-    return {
-        routes,
-        mounts: [plane],
-        control: { token, prefix: plane.prefix },
-        // Writes the discovery file and hands back its removal. It installs NO signal handlers: a
-        // library mounted inside someone's app must not change how that app exits — the CLI wires the
-        // returned cleanup into its own shutdown, an embedder into `close()`.
-        announce: (boundPort) => {
-            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
-            const path = join(stateRoot, "control.json");
-            const url = `http://${clientHost(options.host)}:${boundPort}`;
-            writeFileAtomic(path, `${JSON.stringify({ url, token })}\n`, 0o600);
-            log.info(`[fastagent] session control on /control/* (token in ${path})`);
-            // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths
-            // warn loudly, and the LAN path must not be the silent third way past the local trust story.
-            // A loopback bind closes exactly that reach, so it earns silence.
-            const bind = classifyBind(options.host);
-            if (bind !== "loopback") {
-                log.warn(`[fastagent] the port binds ${bind === "wildcard" ? "all interfaces" : `${options.host} (off this machine)`}: ` +
-                    "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
-                    "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs: design §14)");
-            }
-            if (options.tunnel) {
-                // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC.
-                log.warn("[fastagent] --tunnel exposes /control/* (steer, stop, rewrite or delete a session) at the public tunnel URL, " +
-                    "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs: design §14)");
-            }
-            // Removed on shutdown so a stale file cannot point a client at a dead port: `attach` then
-            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
-            return () => {
-                try {
-                    rmSync(path, { force: true });
-                }
-                catch {
-                    /* the file is advisory — shutdown must not fail on it */
-                }
-            };
-        },
-    };
+    return { routes, mounts: [plane], control: { token, prefix: plane.prefix } };
 }
 /**
  * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
@@ -221,11 +164,7 @@ export async function mountAgentService(opened, options = {}) {
     const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
     const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
     const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { builtinInvoke: true });
-    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
-        agent,
-        ...(options.control?.tunnel !== undefined ? { tunnel: options.control.tunnel } : {}),
-        ...(options.control?.host !== undefined ? { host: options.control.host } : {}),
-    });
+    const withControl = mountSessionControl(routed.routes, sessionControl, { agent });
     // Composed BEFORE anything starts. `router` re-validates what `loadChannels` and the control
     // mount already checked, so on THIS path it should not fail — but "should not" is not an ordering
     // guarantee, and a throw after the scheduler ticks and channels dial would leave both running
@@ -233,7 +172,6 @@ export async function mountAgentService(opened, options = {}) {
     const handler = router(withControl.routes, withControl.mounts);
     const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule);
     const abort = new AbortController();
-    let unannounce;
     // A connection that drops while others are still dialling must not be undone by their later
     // readiness: the service is missing a declared channel from that moment on, whatever else arrives.
     let dropped = false;
@@ -259,7 +197,6 @@ export async function mountAgentService(opened, options = {}) {
             abort.abort();
             scheduled.stop();
             options.signal?.removeEventListener("abort", onAbort);
-            unannounce?.(); // a stale discovery file would point a client at a dead port
             // A failure to stop is the caller's to know about — swallowing it would let `close()` report
             // success over a channel still holding on. Bounded, because a channel that ignores its abort
             // signal must not hang the teardown either.
@@ -368,9 +305,6 @@ export async function mountAgentService(opened, options = {}) {
         schedules: scheduled.schedules,
         ready,
         ...(withControl.control ? { control: withControl.control } : {}),
-        announce: (boundPort) => {
-            unannounce = withControl.announce(boundPort);
-        },
         close,
     };
 }

package/dist/session-remote.d.ts

@@ -1,9 +1,9 @@
 /**
- * The remote `SessionControl` — the client half of the Phase 3 transport (design §13). Engine- and
- * server-neutral: speaks only the wire protocol `createControlPlane` serves (HTTP JSON + SSE with the
- * {sessionId, epoch, seq, event} envelope) and re-exposes the SAME `SessionControl` interface, so
- * local and remote consumers are isomorphic — client code does not change when the agent moves out
- * of process.
+ * The remote `SessionControl` — the client half of the HTTP + SSE transport
+ * (docs/design/session-control.md §13). Engine- and server-neutral: speaks only the wire protocol
+ * `createControlPlane` serves (HTTP JSON + SSE with the {sessionId, epoch, seq, event} envelope) and
+ * re-exposes the SAME `SessionControl` interface, so local and remote consumers are isomorphic —
+ * client code does not change when the agent moves out of process.
  *
  * Envelope consumption is internal: a seq gap (loss in transit on this connection) — and any
  * mid-stream transport failure, a server restart included (its connections drop) — THROWS from

package/dist/session-remote.js

@@ -1,4 +1,4 @@
-import { SSE_HEARTBEAT_MS } from "./channels/http.js";
+import { SSE_HEARTBEAT_MS } from "./channels/sse.js";
 import { abortFirstIterator } from "./collect.js";
 import { isAddressableSession, } from "./session.js";
 /** Dead-connection watchdog for SSE reads: the server heartbeats every SSE_HEARTBEAT_MS, so a
@@ -58,7 +58,7 @@ async function controlError(res) {
         // status over: both travel in one error rather than a bare SyntaxError from a rejection path.
         return new ControlRequestError(res.status, `${body} (declared application/json but did not parse)`);
     }
-    return new ControlRequestError(res.status, body, typeof parsed.code === "string" ? parsed.code : undefined);
+    return new ControlRequestError(res.status, body, typeof parsed?.code === "string" ? parsed.code : undefined);
 }
 /**
  * Connect and return a remote `SessionControl`. Async because `capabilities()` is synchronous in
@@ -130,7 +130,12 @@ export async function connectSessionControl(options) {
                     catch (parseError) {
                         throw new Error(`control events: non-JSON data on the stream (${String(parseError)}) — protocol mismatch?`);
                     }
-                    if (typeof wire.seq !== "number" || typeof wire.event !== "object" || wire.event === null) {
+                    if (typeof wire !== "object" ||
+                        wire === null ||
+                        typeof wire.seq !== "number" ||
+                        typeof wire.event !== "object" ||
+                        wire.event === null ||
+                        typeof wire.event.type !== "string") {
                         throw new Error("control events: malformed envelope — the endpoint does not speak this protocol version");
                     }
                     // Envelope checks — consumed HERE. (epoch is not compared: it cannot change within
@@ -156,6 +161,7 @@ export async function connectSessionControl(options) {
             }
             finally {
                 watchdog.stop();
+                abort.abort();
             }
         })();
         return {
@@ -288,9 +294,7 @@ export function connectAgent(options) {
                     };
                     return;
                 }
-                // Exactly-one-terminal discipline across the wire: a drop AFTER the server's terminal
-                // must not append a second one (catch included), and a stream that ends WITHOUT one
-                // (server died mid-run) must be closed with a failed — never a terminal-less end.
+                // A terminal closes the stream. Cleanup errors must not append a second terminal.
                 let terminalSeen = false;
                 // Armed BEFORE the fetch — the run's driver must not hang on a black-holed connect
                 // either (the connect await is a pending read; headers arriving disarm it).
@@ -328,38 +332,30 @@ export function connectAgent(options) {
                             event = JSON.parse(data);
                         }
                         catch (parseError) {
-                            // Protocol drift (version skew, non-SSE middlebox), NOT transport trouble:
-                            // re-sending the same prompt cannot fix an unparseable stream — retryable: false.
-                            // (Guarded by terminalSeen: garbage AFTER the terminal must not add a second one.)
-                            if (!terminalSeen) {
-                                yield {
-                                    type: "failed",
-                                    details: `remote invoke: unparseable event on the stream (${String(parseError)})`,
-                                    retryable: false,
-                                };
-                            }
+                            yield {
+                                type: "failed",
+                                details: `remote invoke: unparseable event on the stream (${String(parseError)})`,
+                                retryable: false,
+                            };
                             return;
                         }
                         // Shape check, same discipline as the events plane: `data: null` / `data: 42` is
                         // valid JSON but protocol drift — it must not TypeError into the catch below and be
                         // misclassified as retryable network trouble.
                         if (typeof event !== "object" || event === null || typeof event.type !== "string") {
-                            if (!terminalSeen) {
-                                yield {
-                                    type: "failed",
-                                    details: "remote invoke: non-event data on the stream — protocol mismatch?",
-                                    retryable: false,
-                                };
-                            }
+                            yield {
+                                type: "failed",
+                                details: "remote invoke: non-event data on the stream — protocol mismatch?",
+                                retryable: false,
+                            };
                             return;
                         }
-                        if (event.type === "completed" || event.type === "failed")
-                            terminalSeen = true;
+                        terminalSeen = event.type === "completed" || event.type === "failed";
                         yield event;
+                        if (terminalSeen)
+                            return;
                     }
-                    if (!terminalSeen) {
-                        yield { type: "failed", details: "remote invoke: stream ended without a terminal", retryable: true };
-                    }
+                    yield { type: "failed", details: "remote invoke: stream ended without a terminal", retryable: true };
                 }
                 catch (error) {
                     if (abort.signal.aborted) {
@@ -377,6 +373,7 @@ export function connectAgent(options) {
                 }
                 finally {
                     watchdog.stop();
+                    abort.abort();
                 }
             })();
             // ONE stream per invoke, like a local async generator (which is its own iterator): a second

package/dist/session.d.ts

@@ -290,7 +290,7 @@ export interface SessionState {
     /** Set by `update({ name })`, so a client that opens a session directly gets the same label the list
      *  showed. */
     name?: string;
-    /** `compacting` refers to Phase 2 MANUAL compaction at a session boundary. Automatic overflow
+    /** `compacting` refers to MANUAL compaction (`compact`) at a session boundary. Automatic overflow
      *  compaction happens inside a run's activity window and reports as `running`. */
     status: "idle" | "running" | "compacting";
     activeRunId?: string;

package/dist/slack.d.ts

@@ -1,2 +1,4 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
 export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
+export { slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
+export type { SentSlackMessage, SlackTarget, UploadedSlackFile } from "./channels/slack/slack-api.ts";

package/dist/slack.js

@@ -1,2 +1,3 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
 export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
+export { slackTransport } from "./channels/slack/shared-api.js";

package/dist/tunnel.d.ts

@@ -15,15 +15,25 @@ export interface Tunnel {
 }
 /** Extract a Cloudflare quick-tunnel URL from a chunk of cloudflared output, if present. */
 export declare function parseTunnelUrl(chunk: string): string | undefined;
+/** Whether cloudflared's output so far reports an edge connection — see {@link TUNNEL_CONNECTED_RE}. */
+export declare function hasTunnelConnection(output: string): boolean;
+/**
+ * How long after that connection to hand the URL over. The one number here that is not observed: 5s
+ * covers the widest of the 7 measured gaps (3.9s), all taken over cloudflared's http2 transport
+ * because this network blocks its QUIC. Costs a beat of `dev --tunnel` start-up; buys the first
+ * registration attempt landing on a name that resolves.
+ */
+export declare const TUNNEL_DNS_LAG_MS = 5000;
 /** How cloudflared is launched; injectable so tests can drive the child without a real process. */
 type SpawnCloudflared = (port: number) => ChildProcess;
 /**
- * Start a Cloudflare quick tunnel to localhost:`port`, resolving once its public URL appears.
- * cloudflared sometimes exits before printing a URL (a transient trycloudflare API error), so retry a
- * few times. ALWAYS resolves to undefined WITH an operator log saying why — missing binary, the exit
- * reason, or "gave up after retries" — never silently; serving continues without a tunnel either way.
- * (Edge warmup AFTER the URL appears is handled downstream: the telegram registrar polls /health before
- * it calls setWebhook, so a not-yet-routable tunnel just delays registration rather than failing it.)
+ * Start a Cloudflare quick tunnel to localhost:`port`, resolving once its public URL is assigned AND
+ * the tunnel has an edge connection — the URL is printed first and is not usable yet
+ * ({@link hasTunnelConnection}). cloudflared sometimes exits before printing a URL (a transient
+ * trycloudflare API error), so retry a few times. ALWAYS resolves to undefined WITH an operator log
+ * saying why — missing binary, the exit reason, or "gave up after retries" — never silently; serving
+ * continues without a tunnel either way. What remains after this is the PLATFORM's own warm-up, which
+ * each registrar absorbs by retrying while the platform reports it cannot yet verify the URL.
  */
 export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloudflared, attemptTimeoutMs?: number): Promise<Tunnel | undefined>;
 /**

package/dist/tunnel.js

@@ -23,6 +23,28 @@ const TUNNEL_URL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com/i;
 export function parseTunnelUrl(chunk) {
     return chunk.match(TUNNEL_URL_RE)?.[0];
 }
+/**
+ * cloudflared's line for an established edge connection. THIS, not the URL, is when the hostname
+ * begins to exist: `*.trycloudflare.com` is no wildcard, and a quick tunnel's record is published
+ * once the tunnel registers a connection — so the URL is printed while the name is still NXDOMAIN.
+ * A platform told about it inside that window answers "Failed to resolve host" and goes on answering
+ * it far longer than any registrar's retry budget (#435); the record going live seconds later does
+ * not undo the answer it already gave, which is why more retries were never the fix.
+ *
+ * Measured over 7 quick tunnels: the URL at +0s, this line at +1.1-1.9s, the record 0.5-3.9s later.
+ */
+const TUNNEL_CONNECTED_RE = /Registered tunnel connection/i;
+/** Whether cloudflared's output so far reports an edge connection — see {@link TUNNEL_CONNECTED_RE}. */
+export function hasTunnelConnection(output) {
+    return TUNNEL_CONNECTED_RE.test(output);
+}
+/**
+ * How long after that connection to hand the URL over. The one number here that is not observed: 5s
+ * covers the widest of the 7 measured gaps (3.9s), all taken over cloudflared's http2 transport
+ * because this network blocks its QUIC. Costs a beat of `dev --tunnel` start-up; buys the first
+ * registration attempt landing on a name that resolves.
+ */
+export const TUNNEL_DNS_LAG_MS = 5000;
 /** Global timer (rather than timers/promises) so timeout/retry behavior is deterministic under fake timers. */
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const TUNNEL_ATTEMPTS = 3;
@@ -31,12 +53,13 @@ const TUNNEL_RETRY_MS = 2000;
 const TUNNEL_START_TIMEOUT_MS = 30_000;
 const spawnCloudflared = (port) => spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], { stdio: ["ignore", "pipe", "pipe"] });
 /**
- * Start a Cloudflare quick tunnel to localhost:`port`, resolving once its public URL appears.
- * cloudflared sometimes exits before printing a URL (a transient trycloudflare API error), so retry a
- * few times. ALWAYS resolves to undefined WITH an operator log saying why — missing binary, the exit
- * reason, or "gave up after retries" — never silently; serving continues without a tunnel either way.
- * (Edge warmup AFTER the URL appears is handled downstream: the telegram registrar polls /health before
- * it calls setWebhook, so a not-yet-routable tunnel just delays registration rather than failing it.)
+ * Start a Cloudflare quick tunnel to localhost:`port`, resolving once its public URL is assigned AND
+ * the tunnel has an edge connection — the URL is printed first and is not usable yet
+ * ({@link hasTunnelConnection}). cloudflared sometimes exits before printing a URL (a transient
+ * trycloudflare API error), so retry a few times. ALWAYS resolves to undefined WITH an operator log
+ * saying why — missing binary, the exit reason, or "gave up after retries" — never silently; serving
+ * continues without a tunnel either way. What remains after this is the PLATFORM's own warm-up, which
+ * each registrar absorbs by retrying while the platform reports it cannot yet verify the URL.
  */
 export async function startCloudflareTunnel(port, spawnFn = spawnCloudflared, attemptTimeoutMs = TUNNEL_START_TIMEOUT_MS) {
     for (let attempt = 1; attempt <= TUNNEL_ATTEMPTS; attempt++) {
@@ -55,26 +78,35 @@ export async function startCloudflareTunnel(port, spawnFn = spawnCloudflared, at
     }
     return undefined;
 }
-/** One cloudflared launch: a Tunnel on the first URL, or a failure (missing binary / exit before a URL). */
+/** One cloudflared launch: a Tunnel once its URL is assigned AND the edge connection is up, or a
+ *  failure (missing binary / exit before a URL). */
 function spawnTunnelOnce(port, spawnFn, timeoutMs) {
     return new Promise((resolve) => {
         const child = spawnFn(port);
         let settled = false;
         let timer;
+        let handOver;
         let tail = ""; // recent output, surfaced as the failure reason
+        let assigned; // printed well before the tunnel can carry anything
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             if (timer)
                 clearTimeout(timer);
+            if (handOver)
+                clearTimeout(handOver);
             resolve(result);
         };
+        const handOverNow = (url) => finish({ tunnel: { url, close: () => child.kill("SIGTERM") } });
         const onChunk = (buf) => {
             tail = (tail + String(buf)).slice(-600);
-            const url = parseTunnelUrl(String(buf));
-            if (url)
-                finish({ tunnel: { url, close: () => child.kill("SIGTERM") } });
+            assigned ??= parseTunnelUrl(String(buf));
+            if (!assigned || handOver || !hasTunnelConnection(tail))
+                return;
+            const url = assigned;
+            handOver = setTimeout(() => handOverNow(url), TUNNEL_DNS_LAG_MS);
+            handOver.unref();
         };
         child.stdout?.on("data", onChunk);
         child.stderr?.on("data", onChunk); // cloudflared prints the URL (and its errors) on stderr
@@ -91,6 +123,15 @@ function spawnTunnelOnce(port, spawnFn, timeoutMs) {
         });
         child.on("exit", () => finish({ fatal: false, detail: lastErrorLine(tail) }));
         timer = setTimeout(() => {
+            // A URL whose tunnel never connected is not worth a fresh one — the next attempt meets the same
+            // network. Serve it and name what is wrong, rather than retrying into the same wall.
+            if (assigned) {
+                log.warn(`[fastagent] --tunnel: cloudflared never reported an edge connection for ${assigned} within ` +
+                    `${Math.round(timeoutMs / 1000)}s — serving it anyway. Nothing reaches a tunnel that has not ` +
+                    "connected, so a webhook registration that cannot resolve the host is this, not the platform.");
+                handOverNow(assigned);
+                return;
+            }
             child.kill("SIGTERM");
             finish({ fatal: false, detail: `timed out after ${Math.round(timeoutMs / 1000)}s waiting for a public URL` });
         }, timeoutMs);
@@ -135,8 +176,8 @@ channels, opts = {}) {
         log.warn(`[fastagent] could not read ${dotEnvPath(dir)}: ${error.message} — continuing without it`);
     }
     // Readiness is the registrar's job: a fresh quick tunnel returns Cloudflare 530 for ~20-30s before its
-    // origin connects, and the automatic registrars poll /health before configuring the platform (the same
-    // wait the deploy runners rely on). GitHub needs no wait — the operator adds that webhook by hand.
+    // origin connects, and each registrar absorbs that by retrying the platform call whose own URL
+    // verification reports it. GitHub needs no wait — the operator adds that webhook by hand.
     //
     // The registrars differ from the deploy path's in what they carry, not in which channels they answer
     // for: this one narrates to the log and opens the console for a manual Feishu step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, Telegram, Slack, or behind any channel.",
   "keywords": [
     "agent",
@@ -94,6 +94,7 @@
     "build": "tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "test": "vitest --run",
+    "test:live": "vitest --run --config vitest.live.config.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src test && node scripts/check-doc-links.mjs && knip",
     "format": "biome check --write src test",
@@ -105,9 +106,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.84.3",
-    "@earendil-works/pi-ai": "^0.84.3",
-    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "@earendil-works/pi-agent-core": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
     "@hono/node-server": "^2.1.1",
     "@larksuiteoapi/node-sdk": "^1.71.1",
     "@octokit/webhooks-methods": "^6.0.0",

package/dist/channels/slack/bot-auth.d.ts

@@ -1,15 +0,0 @@
-export interface SlackBotTokenProviderOptions {
-    statePath: string;
-    botToken: string;
-    botRefreshToken?: string;
-    clientId?: string;
-    clientSecret?: string;
-    botTokenExpiresAt?: number;
-    apiBaseUrl?: string;
-    fetch?: typeof fetch;
-}
-/** Latest local rotating credentials for `deploy --run`. The remote runtime still prefers its own
- * durable volume; this overlay prevents a locally consumed refresh token from being redeployed. */
-export declare function readSlackBotAuthEnv(statePath: string): Record<string, string>;
-/** Resolve the current bot token, refreshing once per process when it approaches expiry. */
-export declare function createSlackBotTokenProvider(options: SlackBotTokenProviderOptions): () => Promise<string>;