@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/tunnel.js

@@ -7,11 +7,10 @@
  * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
  */
 import { spawn } from "node:child_process";
-import { readdirSync } from "node:fs";
-import { join } from "node:path";
 import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
 import { registerSlackWebhook } from "./channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
+import { pointChannelsAt } from "./deploy/channel-ingress.js";
 import { dotEnvPath, loadDotEnv } from "./env.js";
 import { resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";
@@ -24,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;
@@ -32,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++) {
@@ -56,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
@@ -92,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);
@@ -106,23 +146,23 @@ function lastErrorLine(tail) {
         .filter(Boolean);
     return ([...lines].reverse().find((l) => /err|error|failed/i.test(l)) ?? lines.at(-1) ?? "").slice(0, 200);
 }
-/** Channel basenames present in `<dir>/channels/`. */
-function channelBasenames(dir) {
-    try {
-        return readdirSync(join(dir, "channels"))
-            .filter((n) => /\.(ts|js|mjs)$/.test(n) && !n.endsWith(".d.ts"))
-            .map((n) => n.replace(/\.(ts|js|mjs)$/, ""));
-    }
-    catch {
-        return [];
-    }
-}
 /**
  * Print the public URL and wire up first-party webhook channels found under `dir` (the agent
  * ROOT): Telegram and Feishu/Lark use runtime credentials; onboarded Slack uses its owner-local config
  * token; GitHub and a manually scaffolded Slack app receive explicit console URLs.
+ *
+ * Returns what each registrar ANSWERED, because two kinds of caller need different things from a
+ * failure. `dev`/`start` are long-running: a webhook that did not register is a logged problem, not
+ * a reason to stop serving, and they void this. `deploy … --run` is a command that exits, and an
+ * exit 0 there tells its caller the deployment is reachable — so it feeds these through
+ * `registrationGate`, exactly as the fly/railway/agentcore runners feed their own registrar calls
+ * (docker used to be the one host that could not, because this returned nothing).
  */
-export async function announceWebhooks(dir, baseUrl, opts = {}) {
+export async function announceWebhooks(dir, baseUrl, 
+/** Every declared channel with its ingress. Not a pre-filtered list: this used to accept "the route
+ *  channels" and default to every basename in `channels/`, which pointed a webhook at a
+ *  long-connection channel whenever a caller forgot to filter. {@link pointChannelsAt} filters. */
+channels, opts = {}) {
     log.info(`[fastagent] public URL: ${baseUrl}`);
     try {
         loadDotEnv(dir); // webhook registrars read channel credentials from .env
@@ -135,33 +175,26 @@ export async function announceWebhooks(dir, baseUrl, opts = {}) {
         // missing-credential guidance. loadDotEnv keeps throwing for the synchronous command callers.
         log.warn(`[fastagent] could not read ${dotEnvPath(dir)}: ${error.message} — continuing without it`);
     }
-    // Serving passes the validated route-channel subset. The basename fallback preserves the public
-    // helper's behavior for callers that did not assemble channels first.
-    const routeChannels = opts.routeChannels ?? channelBasenames(dir);
-    if (routeChannels.length === 0)
-        return;
-    // Readiness is the registrar's job now: 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.
-    if (routeChannels.includes("telegram"))
-        await registerTelegramWebhook(baseUrl);
-    if (routeChannels.includes("github")) {
-        log.info(`[fastagent] github: add a webhook in your repo (Settings → Webhooks): Payload URL = ${baseUrl}/webhook, content type application/json, secret = GITHUB_WEBHOOK_SECRET`);
-    }
-    if (routeChannels.includes("slack")) {
-        await registerSlackWebhook(baseUrl, {
-            stateRoot: opts.stateRoot ?? resolveStateRoot(dir),
-            log: (message) => log.info(message),
-        });
-    }
-    // feishu/lark register programmatically too (application-v7 config PATCH — telegram-setWebhook
-    // parity), once per mounted kind (each kind is its own app with its own credentials); the registrar
-    // owns its own health wait and degrades to the manual console instruction.
+    // Readiness is the registrar's job: a fresh quick tunnel returns Cloudflare 530 for ~20-30s before its
+    // 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.
     const feishuOptions = {
         onManualRegistration: ({ consoleUrl }) => opts.openUrl?.(consoleUrl),
     };
-    if (routeChannels.includes("feishu"))
-        await registerFeishuWebhook(baseUrl, "feishu", feishuOptions);
-    if (routeChannels.includes("lark"))
-        await registerFeishuWebhook(baseUrl, "lark", feishuOptions);
+    return pointChannelsAt({
+        baseUrl,
+        channels,
+        log: (message) => log.info(`[fastagent] ${message}`),
+        registrars: {
+            telegram: (url) => registerTelegramWebhook(url),
+            slack: (url) => registerSlackWebhook(url, {
+                stateRoot: opts.stateRoot ?? resolveStateRoot(dir),
+                log: (message) => log.info(message),
+            }),
+            feishu: (url, kind) => registerFeishuWebhook(url, kind, feishuOptions),
+        },
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.19.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>;

package/dist/channels/slack/bot-auth.js

@@ -1,135 +0,0 @@
-/** Rotating Slack bot-token provider backed by owner-only channel state. */
-import { readFileSync } from "node:fs";
-import { writeFileAtomic } from "../../atomic-write.js";
-const REFRESH_EARLY_MS = 5 * 60_000;
-const REQUEST_TIMEOUT_MS = 30_000;
-function isState(value) {
-    const state = value;
-    return (typeof state === "object" &&
-        state !== null &&
-        state.version === 1 &&
-        typeof state.accessToken === "string" &&
-        typeof state.refreshToken === "string" &&
-        typeof state.expiresAt === "number");
-}
-function load(path) {
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
-        throw new Error(`Slack bot auth state ${path} is unreadable: ${String(error)}`, { cause: error });
-    }
-    try {
-        const value = JSON.parse(raw);
-        if (!isState(value))
-            throw new Error("unexpected shape/version");
-        return value;
-    }
-    catch (error) {
-        // A stale env refresh token may already have been consumed. Never hide corrupt rotating state by
-        // falling back to it: recovery requires restoring the durable file or reinstalling the app.
-        throw new Error(`Slack bot auth state ${path} is invalid: ${String(error)}`, { cause: error });
-    }
-}
-function save(path, state) {
-    writeFileAtomic(path, JSON.stringify(state), 0o600);
-}
-async function refreshSlackBotToken(input) {
-    const authorization = Buffer.from(`${input.clientId}:${input.clientSecret}`, "utf8").toString("base64");
-    let lastError;
-    // Slack keeps a short grace window for a just-consumed refresh token. One retry recovers the
-    // committed-but-response-lost boundary without creating an unbounded refresh loop.
-    for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-            const response = await input.fetch(`${input.apiBaseUrl}/oauth.v2.access`, {
-                method: "POST",
-                headers: {
-                    authorization: `Basic ${authorization}`,
-                    "content-type": "application/x-www-form-urlencoded",
-                },
-                body: new URLSearchParams({
-                    grant_type: "refresh_token",
-                    refresh_token: input.refreshToken,
-                }).toString(),
-                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-            });
-            const data = (await response.json().catch(() => ({})));
-            if (!response.ok ||
-                data.ok !== true ||
-                !data.access_token ||
-                !data.refresh_token ||
-                typeof data.expires_in !== "number") {
-                throw new Error(`Slack rejected bot-token refresh (HTTP ${response.status})`);
-            }
-            return {
-                version: 1,
-                accessToken: data.access_token,
-                refreshToken: data.refresh_token,
-                expiresAt: Date.now() + data.expires_in * 1_000,
-            };
-        }
-        catch (error) {
-            lastError = error;
-        }
-    }
-    throw new Error("Slack bot-token rotation failed; restore credentials or reinstall the app", { cause: lastError });
-}
-/** 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 function readSlackBotAuthEnv(statePath) {
-    const state = load(statePath);
-    return state
-        ? {
-            SLACK_BOT_TOKEN: state.accessToken,
-            SLACK_BOT_REFRESH_TOKEN: state.refreshToken,
-            SLACK_BOT_TOKEN_EXPIRES_AT: String(state.expiresAt),
-        }
-        : {};
-}
-/** Resolve the current bot token, refreshing once per process when it approaches expiry. */
-export function createSlackBotTokenProvider(options) {
-    const rotatingFields = [options.botRefreshToken, options.clientId, options.clientSecret, options.botTokenExpiresAt];
-    const rotating = rotatingFields.some((value) => value !== undefined);
-    if (rotating && rotatingFields.some((value) => value === undefined || value === "")) {
-        throw new Error("Slack token rotation requires botRefreshToken, clientId, clientSecret, and botTokenExpiresAt together");
-    }
-    if (rotating && (!Number.isFinite(options.botTokenExpiresAt) || options.botTokenExpiresAt <= 0)) {
-        throw new Error("Slack botTokenExpiresAt must be a positive epoch-millisecond value");
-    }
-    if (!rotating)
-        return async () => options.botToken;
-    const configured = {
-        version: 1,
-        accessToken: options.botToken,
-        refreshToken: options.botRefreshToken,
-        expiresAt: options.botTokenExpiresAt,
-    };
-    const persisted = load(options.statePath);
-    // Deploy may carry a newer pair from the owner machine onto an existing remote volume; ordinary
-    // restarts carry the original stale env and therefore keep the newer persisted pair.
-    let state = persisted && persisted.expiresAt >= configured.expiresAt ? persisted : configured;
-    let refreshing;
-    return async () => {
-        if (state.expiresAt > Date.now() + REFRESH_EARLY_MS)
-            return state.accessToken;
-        refreshing ??= refreshSlackBotToken({
-            refreshToken: state.refreshToken,
-            clientId: options.clientId,
-            clientSecret: options.clientSecret,
-            apiBaseUrl: (options.apiBaseUrl ?? "https://slack.com/api").replace(/\/$/, ""),
-            fetch: options.fetch ?? globalThis.fetch,
-        })
-            .then((next) => {
-            save(options.statePath, next);
-            state = next;
-        })
-            .finally(() => {
-            refreshing = undefined;
-        });
-        await refreshing;
-        return state.accessToken;
-    };
-}