@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/dist/channels/turn-store.js

@@ -0,0 +1,139 @@
+/**
+ * Durable turn intent: the L1 half of durable execution (the L2 exactly-once / deterministic
+ * step-replay layer is the K-axis backend — docs/design/core.md §11). Persists an accepted turn BEFORE
+ * the webhook 200 (pre-ACK, like the telegram context-buffer) and removes it when the turn ENDS — the
+ * runner's `finally`: a completed turn OR any caught error both remove it. Precisely, a completed turn's
+ * removal fires at the `completed` event (the session is committed), which is BEFORE the reply reaches
+ * the chat platform: so L1 recovers the ACKed-but-un-COMPLETED window, not un-DELIVERED. A crash in
+ * that narrow tail (completed, session-committed, but the message not yet sent) leaves the answer in the
+ * session history undelivered and is deliberately NOT replayed — replaying a session-committed turn
+ * would double-append it; the asker re-asks (and sees the prior answer in history). L1's scope is the
+ * INTERRUPTED-run window (the `finally` never runs); a caught error is NOT retried here — a `failed`
+ * event already told the user, and a transport throw is dropped exactly like the pre-L1 in-memory queue
+ * did (replaying it could double-send). Only an interrupted run leaves the record on disk — and
+ * "interrupted" is not just a rare crash: `runStart` has no graceful drain (cli.ts), so a SIGTERM exits
+ * mid-turn too, i.e. EVERY rolling deploy that catches an in-flight turn. Recovery re-enqueues it next start.
+ *
+ * This recovers the ACKed-but-unfinished window the in-memory turn-queue drops (turn-queue.ts). Weigh
+ * the trade before trusting it: the alternative (dropping the turn) fails VISIBLY and self-corrects
+ * (the turn vanished, the asker re-asks); replay's sharpest cost is the opposite — invisible. It is
+ * at-least-once, not exactly-once:
+ *   - PRIMARY cost: replay re-runs the WHOLE turn, so every external side effect happens AGAIN — re-sent
+ *     messages, re-fired tool actions — and nobody may notice (unlike the visible loss it replaces).
+ *     And the trigger is not rare (above): it fires on every deploy that interrupts an in-flight turn,
+ *     not just on crashes. So "safe only if the turn's tools are idempotent" is a bar to judge against
+ *     DEPLOY frequency: it holds for a Q&A bot, and is the gate for adding side-effecting tools. (A
+ *     mid-stream interruption also leaves an orphan "💭 Thinking…" preview — cosmetic.)
+ *   - The pre-ACK window overlaps webhook redelivery: a crash AFTER the persist but BEFORE the 200
+ *     means recovery replays the turn AND the platform (never-ACKed) redelivers the same event — same
+ *     id, and unless the channel dedups accepted ids, the turn can run twice. Exactly-once (a persisted
+ *     delivery key) is L2.
+ *
+ * Channel-neutral, generic over the record shape: the channel supplies its own record type (everything
+ * its runner needs to re-execute the turn), the shape validator (state files are an IO boundary), the
+ * arrival ordering for recovery, and its log label. telegram/turn-store.ts and the Feishu channel are the
+ * two consumers.
+ *
+ * ponytail: at-least-once with a per-turn EXECUTION ceiling. A poison turn that deterministically
+ * crashes the process would replay forever under a container restart policy. The counter is bumped at
+ * `startAttempt` — when a turn is about to RUN, not per restart cycle — so it counts a turn's OWN
+ * execution attempts: `recover()` re-enqueues every surviving turn without touching its count, and a
+ * poison turn at a session's head is dropped on its own N+1th run WITHOUT penalizing the never-run turns
+ * queued behind it (they keep their full budget and get their turn once the poison one is gone). On drop,
+ * the runner notifies the asker (the chain's end must get a signal — a log line the user can't see isn't).
+ * The bump is the ONE post-ACK write that fails CLOSED (not best-effort): if it can't be persisted the
+ * turn is DEFERRED — skipped this cycle and left on disk to replay on the next start — rather than run
+ * untracked, because an unpersisted count lets recover() re-run a poison turn every restart (the ceiling
+ * would never advance on disk). It replays on the next START — a restart is required; disk recovery alone
+ * does not re-run a deferred turn — and the asker is NOT told (a transient system degrade, not a user-
+ * actionable failure — telling them "ask again" would double-answer on that replay).
+ * Single-process, single-writer: same durability model as state.ts (crash-safe via atomic rename;
+ * power-loss is best-effort — no fsync, consistent with the rest of the channel's state).
+ */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+export function createTurnStore(path, opts) {
+    const { label, isRecord, order } = opts;
+    const load = () => {
+        const raw = loadStateFile(path);
+        if (raw === undefined)
+            return new Map();
+        if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.values(raw).every(isRecord)) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`${label} unexpected shape in ${path} — starting with no pending turns`);
+        return new Map();
+    };
+    const turns = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(turns));
+    // Post-ACK writes (remove, startAttempt) must not abort a turn: log a failed write, never throw.
+    const persistBestEffort = (what) => {
+        try {
+            persist();
+        }
+        catch (e) {
+            log.error(`${label} turn-store ${what} write failed post-ACK: ${String(e)}`);
+        }
+    };
+    return {
+        add(rec) {
+            // Idempotent on re-add: a redelivery (pre-ACK crash → never-ACKed event replayed) re-submits an id
+            // already in the store. Skip it — the intent is already durable, and overwriting would RESET this
+            // turn's execution count, handing a poison turn a fresh ceiling budget.
+            if (turns.has(rec.id))
+                return;
+            turns.set(rec.id, rec);
+            try {
+                persist(); // pre-ACK: a throw becomes the webhook's 500 and the platform redelivers
+            }
+            catch (e) {
+                // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom
+                // entry makes the redelivery's `add` short-circuit on `turns.has` — running the turn with its
+                // intent never persisted, defeating this module — and gets flushed later by an unrelated persist.
+                turns.delete(rec.id);
+                throw e;
+            }
+        },
+        remove(id) {
+            if (turns.delete(id))
+                persistBestEffort("remove (a restart may replay an answered turn)");
+        },
+        recover() {
+            // The channel's arrival order, applied explicitly rather than leaning on JS object-key enumeration
+            // happening to survive the load's JSON round-trip.
+            return [...turns.values()].sort(order);
+        },
+        startAttempt(id, maxAttempts) {
+            const rec = turns.get(id);
+            if (!rec)
+                return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
+            const attempts = rec.attempts + 1;
+            if (attempts > maxAttempts) {
+                // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps
+                // this whether IT poisoned the process or a deploy/OOM took it down each time.
+                log.error(`${label} dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +
+                    `(session=${rec.session}) — it may be crashing the process, or was killed mid-run each time; notifying the asker`);
+                turns.delete(id);
+                persistBestEffort("drop");
+                return "exceeded";
+            }
+            turns.set(id, { ...rec, attempts });
+            try {
+                persist();
+            }
+            catch (e) {
+                // The bump MUST be durable, unlike remove/drop: if it isn't, a restart's recover() reads the old
+                // count and RE-RUNS this turn — a poison turn would re-execute forever (the ceiling never advances
+                // on disk). Fail closed: roll the memory bump back (match disk) and DEFER — the record stays on
+                // disk with its old count and replays on the next start (a restart is required; disk recovery
+                // alone won't re-run it). Not a drop: under disk failure the removal couldn't persist anyway.
+                // The runner skips silently (no notify).
+                turns.set(id, rec);
+                log.error(`${label} cannot persist turn ${id}'s attempt count — deferring it to the next start rather ` +
+                    `than run it untracked (session=${rec.session}): ${String(e)}`);
+                return "defer";
+            }
+            return "run";
+        },
+    };
+}

package/dist/channels/wait-health.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Poll `healthUrl` until it responds 200, or the timeout elapses. Any error (not routable yet, DNS not
+ * settled, connection refused) is a "keep waiting", not a failure — that IS the readiness signal. Each
+ * probe has its own short timeout so one slow attempt can't eat the whole budget.
+ */
+export declare function waitForHealth(healthUrl: string, timeoutMs: number, intervalMs: number): Promise<boolean>;

package/dist/channels/wait-health.js

@@ -0,0 +1,27 @@
+/**
+ * Readiness probe shared by the webhook registrars (telegram setWebhook, lark config PATCH): both
+ * platforms VERIFY the URL at registration time, and a fresh deploy's container or a fresh tunnel's
+ * DNS is not routable for some seconds — registering before the server actually serves would fail.
+ * Tracking real readiness (not a fixed timer) is what fixes that race.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+/**
+ * Poll `healthUrl` until it responds 200, or the timeout elapses. Any error (not routable yet, DNS not
+ * settled, connection refused) is a "keep waiting", not a failure — that IS the readiness signal. Each
+ * probe has its own short timeout so one slow attempt can't eat the whole budget.
+ */
+export async function waitForHealth(healthUrl, timeoutMs, intervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            if ((await fetch(healthUrl, { signal: AbortSignal.timeout(5000) })).ok)
+                return true;
+        }
+        catch {
+            /* not routable yet — keep polling until the deadline */
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(intervalMs);
+    }
+}

package/dist/cli-add-feishu.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a committable .env, a
+ * non-interactive lark run); the caller surfaces that as a startup failure.
+ */
+export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", envIgnored: boolean): Promise<Record<string, string> | undefined>;

package/dist/cli-add-feishu.js

@@ -0,0 +1,223 @@
+/**
+ * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts
+ * (which self-executes on import), mirroring cli-models.ts/cli-auth.ts. The POLICY already lives in
+ * testable modules (register-app.ts, bootstrap-token.ts, lark/onboard.ts); this layer is the terminal
+ * wiring: clack prompts, .env staging, browser opens, progress lines.
+ *
+ * Feishu (scan-to-create): the device flow creates the app; App ID/Secret are persisted at the
+ * irreversible creation boundary, then the Verification Token is captured over a throwaway tunnel and
+ * persisted as a second stage — a re-run RESUMES the app instead of minting another. Lark
+ * (guided-console): open the unbound launcher, validate entered credentials, probe the same
+ * webhook/token bootstrap, and fall back to a manual token prompt on the definitive config-route 404.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
+import { bootstrapFeishuVerificationToken } from "./channels/feishu/bootstrap-token.js";
+import { cloudFor } from "./channels/feishu/cloud.js";
+import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "./channels/feishu/feishu-api.js";
+import { registerFeishuApp } from "./channels/feishu/register-app.js";
+import { onboardLarkApp } from "./channels/lark/onboard.js";
+import { parseEnvContent } from "./env.js";
+import { openExternalUrl } from "./open-url.js";
+import { appendChannelDotEnv } from "./scaffold/add-channel.js";
+import { startCloudflareTunnel } from "./tunnel.js";
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a committable .env, a
+ * non-interactive lark run); the caller surfaces that as a startup failure.
+ */
+export async function onboardFeishuCloudApp(target, kind, envIgnored) {
+    const { envPrefix, apiBase, capabilities } = cloudFor(kind);
+    // The CLI must never materialize a real credential into a committable file — refuse, don't warn.
+    if (!envIgnored) {
+        throw new Error(kind === "feishu"
+            ? "`add feishu` creates an app and writes real credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run"
+            : "`add lark` writes real app credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run");
+    }
+    const existing = await activeDotEnvValues(target, [
+        `${envPrefix}_APP_ID`,
+        `${envPrefix}_APP_SECRET`,
+        `${envPrefix}_VERIFICATION_TOKEN`,
+    ]);
+    if (Object.keys(existing).length === 3) {
+        console.error(`[fastagent] ${envPrefix}_APP_ID/SECRET/VERIFICATION_TOKEN already set in .env — keeping them`);
+        return undefined;
+    }
+    if (capabilities.appCreation === "scan-to-create") {
+        await createFeishuAppFlow(target, existing);
+        return undefined;
+    }
+    // guided-console (lark): the intl cloud cannot complete the bound device flow — collect + validate.
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        throw new Error("`add lark` needs an interactive terminal to onboard the Lark app credentials — re-run it in a terminal");
+    }
+    return onboardLarkApp({
+        openUrl: openExternalUrl,
+        note: (message) => clackLog.info(message),
+        async prompt(message, opts) {
+            const result = opts?.hidden ? await password({ message }) : await clackText({ message });
+            return isCancel(result) ? undefined : result;
+        },
+    }, {
+        existing,
+        verifyCredentials: async (appId, appSecret) => {
+            await createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret }).verifyCredentials();
+            console.error(`[fastagent] Lark App ID / Secret verified`);
+        },
+        bootstrapWebhook: async (appId, appSecret) => {
+            const api = createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret });
+            console.error(`[fastagent] trying Lark's webhook-mode + Verification-Token bootstrap (temporary tunnel)…`);
+            try {
+                const token = await bootstrapFeishuVerificationToken({
+                    api,
+                    appId,
+                    kind: "lark",
+                    startTunnel: (port) => startCloudflareTunnel(port),
+                    onTunnelReady: (url) => console.error(`[fastagent] temporary tunnel ready → ${url}; registering webhook mode now…`),
+                    onPatchRetry: ({ error, attempt, attempts, retryMs }) => console.error(`[fastagent] Lark could not validate the fresh tunnel yet (${String(error)}); retrying PATCH ${attempt + 1}/${attempts} in ${Math.round(retryMs / 1000)}s…`),
+                    // A route-level 404 is definitive, not edge weather: fall back immediately. Retry only
+                    // actual edge/network weather; scope/auth/config failures remain immediate.
+                    shouldRetryPatch: (error) => !isFeishuConfigApiMissing(error) && isTransientFeishuRegistrationError(error),
+                });
+                console.error(`[fastagent] Lark Verification Token captured; Subscription mode changed to webhook in the app draft`);
+                return { token };
+            }
+            catch (error) {
+                if (!isFeishuConfigApiMissing(error))
+                    throw error;
+                const manualReason = "This Lark app returned HTTP 404 for the application-config API, so automatic mode/token bootstrap is unavailable.";
+                console.error(`[fastagent] ${manualReason}`);
+                return { manualReason };
+            }
+        },
+    });
+}
+/**
+ * The scan-to-create flow `add feishu` runs by default. The device-authorization grant
+ * creates a pre-configured agent app (bot capability, messaging scopes, event subscriptions) when the
+ * user confirms a link in the app, and hands back the credentials; App ID/Secret are persisted at that
+ * irreversible boundary before the platform-generated Verification Token is captured from the
+ * registration challenge (bootstrap-token.ts). The Token is persisted as a second stage, so .env is
+ * complete before the one remaining version-publish action. The event Request URL is NOT left pointing at the throwaway
+ * tunnel for long: `dev --tunnel` / `deploy --run` re-register it against the live URL.
+ *
+ * Feishu is the reference cloud and the only kind that runs this BOUND device flow. Lark is an explicit
+ * compatibility profile: its lagging control plane uses the unbound launcher + guided credentials,
+ * then probes the canonical token/mode bootstrap with a manual fallback.
+ */
+async function createFeishuAppFlow(target, existing) {
+    const { apiBase } = cloudFor("feishu");
+    let appId = existing.FEISHU_APP_ID;
+    let appSecret = existing.FEISHU_APP_SECRET;
+    if (appId && appSecret) {
+        console.error(`[fastagent] resuming Feishu app ${appId} from .env to capture its missing Verification Token`);
+    }
+    else {
+        console.error(`[fastagent] creating the Feishu app (confirm in the app)…`);
+        const app = await registerFeishuApp({
+            name: "{user}'s agent", // the platform expands {user} to the confirming user's name; editable on the page
+            desc: "Served by fastagent",
+            // The agent template alone is not enough to SERVE: the v7 config PATCH (webhook auto-registration
+            // in `dev --tunnel` / `deploy --run`) demands application:application:patch, and the app must
+            // subscribe the receive event. Addons merge both onto the confirm page — no manual app setup.
+            addons: {
+                scopes: { tenant: ["application:application:patch"] },
+                events: { items: { tenant: ["im.message.receive_v1"] } },
+            },
+            onVerificationUrl: ({ url, expiresInS }) => {
+                console.error(`\n  Opening the confirmation link in your browser (or open it in Feishu / render it as a QR code) — valid for ${Math.round(expiresInS / 60)} minutes:\n\n    ${url}\n\n  waiting for confirmation… (keep this running — the credentials are delivered here)`);
+                openExternalUrl(url); // best-effort, like `login` — the URL above is the fallback
+            },
+        });
+        console.error(`[fastagent] app created: ${app.appId}${app.tenantBrand ? ` (${app.tenantBrand} tenant)` : ""}`);
+        // A cross-brand confirmation should be impossible (each confirm page refuses the other brand's
+        // code) — but if the platform ever reports one, the credentials would land in the WRONG kind's env
+        // namespace and serve the wrong cloud. Fail visibly instead of writing them.
+        if (app.tenantBrand && app.tenantBrand !== "feishu") {
+            throw new Error(`the confirming account is a ${app.tenantBrand} tenant, but this is \`add feishu\` — run \`fastagent add ${app.tenantBrand}\` instead`);
+        }
+        appId = app.appId;
+        appSecret = app.appSecret;
+        // IRREVERSIBLE BOUNDARY: the remote app now exists and its one-time Secret is in memory. Persist
+        // both before any config read, temporary tunnel, or Token bootstrap can be interrupted. Partial old
+        // lines are overwritten because these newly-minted credentials are authoritative as one pair.
+        await appendChannelDotEnv(target, "feishu", {
+            FEISHU_APP_ID: appId,
+            FEISHU_APP_SECRET: appSecret,
+            // A Token from a partial OLD credential set belongs to another App. Clear it at the same
+            // boundary; successful bootstrap below replaces the empty line with this App's Token.
+            FEISHU_VERIFICATION_TOKEN: "",
+        }, ["FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_VERIFICATION_TOKEN"]);
+        console.error(`[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to .env before Token bootstrap`);
+    }
+    // The webhook channel authenticates plaintext events by the platform-generated Verification Token.
+    // Try the cheap read first (the v6 detail MAY someday return `encryption`), then the real path: the
+    // token's only programmatic delivery is the url_verification challenge during registration — capture
+    // it over a throwaway tunnel (bootstrap-token.ts). Failing both is a one-line manual copy; the staged
+    // ID/Secret pair makes a re-run resume this App rather than mint another one.
+    const tokenVar = "FEISHU_VERIFICATION_TOKEN";
+    const api = createFeishuApi({ baseUrl: apiBase, appId, appSecret });
+    let token;
+    let webhookModeChanged = false;
+    try {
+        const cfg = await api.getAppConfig(appId);
+        token = cfg.verificationToken;
+    }
+    catch {
+        /* the read surface is best-effort — the bootstrap below is the real path */
+    }
+    if (!token) {
+        console.error(`[fastagent] capturing the Verification Token — a throwaway webhook registration delivers it (spinning up a temporary tunnel; can take a few minutes on a slow edge)…`);
+        try {
+            token = await bootstrapFeishuVerificationToken({
+                api,
+                appId,
+                startTunnel: (port) => startCloudflareTunnel(port),
+            });
+            webhookModeChanged = true;
+            console.error(`[fastagent] Verification Token captured`);
+        }
+        catch (e) {
+            // Transient tunnel weather is the usual cause. Do NOT suggest re-running `add feishu` as a new
+            // scan: the staged pair makes the re-run resume THIS app; manual copy completes it too.
+            console.error(`[fastagent] warn: could not capture the Verification Token: ${String(e)} — usually a transient tunnel issue; finish this app with the manual copy below`);
+        }
+    }
+    if (token) {
+        // Persist the second credential stage immediately too — opening the publish page and generic
+        // scaffold finalization happen only after the complete runtime credential set is durable.
+        const staged = await appendChannelDotEnv(target, "feishu", { [tokenVar]: token }, [tokenVar]);
+        console.error(`[fastagent] wrote ${staged.written.join(", ")} to .env`);
+    }
+    else {
+        console.error(`[fastagent] copy it manually: developer console → Events & Callbacks → Encryption Strategy → Verification Token → ${tokenVar} in .env`);
+    }
+    if (webhookModeChanged) {
+        // The bootstrap's PATCH flipped event mode in the DRAFT. It takes effect only after a version
+        // publish, which has no API; later dev/deploy runs change only the Request URL immediately.
+        const versionUrl = `${apiBase}/app/${appId}/version`;
+        console.error(`[fastagent] one console click remains: CREATE + PUBLISH a version (self-approved) — the switch to webhook mode takes effect on publish. Opening ${versionUrl}`);
+        openExternalUrl(versionUrl);
+    }
+}
+/** Active run-root `.env` values for the requested names — decided by THE .env parser, so this
+ * check can never disagree with what `loadEnvFile` reads. Empty/commented values are absent. */
+async function activeDotEnvValues(dir, names) {
+    let content;
+    try {
+        content = await readFile(join(dir, ".env"), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return {};
+        throw e;
+    }
+    const parsed = parseEnvContent(content);
+    return Object.fromEntries(names.flatMap((name) => {
+        const value = parsed.get(name)?.trim();
+        return value ? [[name, value]] : [];
+    }));
+}

package/dist/cli.js

@@ -13,6 +13,7 @@ import { logAgentLoop } from "./observe.js";
 import { log, setLogLevel } from "./log.js";
 import { loadDotEnv } from "./env.js";
 import { installProxyFetch } from "./proxy.js";
+import { openExternalUrl } from "./open-url.js";
 import { createInvokeHandler } from "./channels/http.js";
 import { text } from "./channels/respond.js";
 import { parseRouteKey, router, serveNode } from "./host/node.js";
@@ -44,6 +45,8 @@ import { deployRailwayRun } from "./deploy/railway/run.js";
 import { authSeedBytes, deployFlyRun } from "./deploy/fly/run.js";
 import { spawnRunner } from "./deploy/runner.js";
 import { assembleSecrets } from "./deploy/secrets.js";
+import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
+import { onboardFeishuCloudApp } from "./cli-add-feishu.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
 import { loadSchedules } from "./schedule/discover.js";
 import { readRuns } from "./schedule/audit.js";
@@ -64,7 +67,7 @@ function usage(code) {
   fastagent dev    [dir] [--port N] [--model provider/modelId] [--auth-path file] [--no-watch] [--tunnel]
   fastagent chat   [dir] [--model provider/modelId]
   fastagent start [dir] [--port N] [--model provider/modelId] [--sessions-dir dir] [--auth-path file] [--tunnel]
-  fastagent add   github | telegram | skill <source> [dir]
+  fastagent add   github | telegram | feishu | lark | skill <source> [dir]
   fastagent deploy fly|railway [dir] [--run] [--force] [--stop] [--no-scale-to-zero] [--into-linked]
   fastagent login [provider] [--auth-path file]
   fastagent --version
@@ -75,7 +78,7 @@ function usage(code) {
          disable). Files the agent writes as work product never trigger a restart.
          model precedence: --model > FASTAGENT_MODEL > fastagent.config.ts
          --tunnel  expose it on a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared)
-                   and auto-register the webhook channels (telegram setWebhook; github prints the URL)
+                   and auto-register the webhook channels (telegram, feishu, lark; github prints the URL)
   chat   open the SAME assembled agent in pi's interactive TUI (the real harness, not a
          crude REPL) — to try it locally before serving. Same model/tool/skill resolution
          as dev; pi handles login, sessions, and /resume natively.
@@ -123,8 +126,16 @@ function usage(code) {
                    point it at ~/.fastagent/auth.json to share one credential across projects)
          --tunnel  same as dev: a public HTTPS URL + auto-registered webhooks, for hosting a bot from
                    your own box without deploying (the quick-tunnel URL is ephemeral, not for production)
-  add    github | telegram: scaffold channels/<kind>.ts — third-party adapter glue with the policy
-         to edit (github maps events in on(); telegram routes in the optional route()).
+  add    github | telegram | feishu | lark: scaffold channels/<kind>.ts — third-party adapter glue
+         with the policy to edit (github maps events in on(); telegram/feishu/lark route in the
+         optional route()). Feishu (open.feishu.cn) is the canonical implementation; Lark international
+         (open.larksuite.com) is its compatibility profile with degraded control-plane setup.
+         feishu also CREATES + configures the platform app (confirm a link in the app — the platform's
+         "scan to create" flow; one version-publish action remains) and writes credentials to .env;
+         a persisted ID/Secret pair resumes missing-Token setup instead of creating another app. lark
+         opens the intl developer console only for a new/partial pair, validates App ID/Secret, then
+         probes Feishu's webhook-mode + Token automation; an explicit
+         config-route 404 falls back to a hidden Token prompt + manual mode/URL setup.
          skill <source>: vendor an Agent Skills skill into skills/<name>/ (git ref owner/repo/path, a
          local path, or a bare name from ~/.agents/skills; --update re-fetches, review with git diff)
   deploy fly|railway [dir]: generate host config + Dockerfile/.dockerignore from the definition and
@@ -164,6 +175,7 @@ const { positionals, values } = parseArgs({
         "agent-dir": { type: "string" },
         "no-watch": { type: "boolean" },
         tunnel: { type: "boolean" },
+        "create-app": { type: "boolean" },
         update: { type: "boolean" },
         force: { type: "boolean" },
         stop: { type: "boolean" },
@@ -575,18 +587,39 @@ async function runAdd() {
         process.exit(1);
     }
     const channelKind = kind;
+    // App creation is not a flag — it is what `add feishu` IS (the scan-to-create flow is the default
+    // and only path there). The retired --create-app spelling gets a pointer, not silence.
+    if (values["create-app"]) {
+        if (channelKind === "feishu") {
+            console.error(`[fastagent] note: --create-app is retired — \`add feishu\` creates the app by default`);
+        }
+        else if (channelKind === "lark") {
+            failStartup(new Error("--create-app is retired — `add lark` now opens the developer console and guides credential setup by default"));
+        }
+        else {
+            failStartup(new Error("--create-app is retired — app creation is the default behavior of `add feishu`"));
+        }
+    }
     // The channel (glue + companion tool) is agent surface — it lands in agentDir (config.agentDir, or
     // target when flat), the same place dev/start discover channels/. .env(.example) and the secret
     // hygiene stay at the run root, where .env is actually read.
     const { config: addConfig } = await loadConfig(target).catch(failStartup);
     const channelHome = resolveAgentDir(target, addConfig);
-    // Preconditions before the write, so a refusal is side-effect-free.
+    // Preconditions before the write, so a refusal is side-effect-free. feishu/lark are exceptions:
+    // their add is scaffold + ONBOARD THE APP, so an existing scaffold skips the write and continues (a
+    // failed or cancelled scan/paste flow must be re-runnable without hand-deleting glue); never touch it.
+    const file = join(channelHome, "channels", `${channelKind}.ts`);
     if (await channelExists(channelHome, channelKind).catch(failStartup)) {
-        failStartup(new Error(`${relative(target, join(channelHome, "channels", `${channelKind}.ts`))} already exists — edit it, or remove it to re-scaffold`));
+        if (channelKind !== "feishu" && channelKind !== "lark") {
+            failStartup(new Error(`${relative(target, file)} already exists — edit it, or remove it to re-scaffold`));
+        }
+        console.error(`[fastagent] ${relative(target, file)} already exists — keeping it`);
+    }
+    else {
+        await assertChannelReady(channelHome).catch(failStartup);
+        await scaffoldChannel(channelHome, channelKind).catch(failStartup);
+        console.error(`[fastagent] created ${relative(target, file)}`);
     }
-    await assertChannelReady(channelHome).catch(failStartup);
-    const file = await scaffoldChannel(channelHome, channelKind).catch(failStartup);
-    console.error(`[fastagent] created ${relative(target, file)}`);
     if (await appendChannelEnv(target, channelKind).catch(failStartup)) {
         console.error(`[fastagent] added ${channelKind} env vars to .env.example`);
     }
@@ -598,11 +631,21 @@ async function runAdd() {
     if (!envIgnored) {
         console.error(`[fastagent] warn: .env is not gitignored — a deploy that copies the directory would ship a secret placed there; add .env to .gitignore/.fastagentignore, or use a real env var`);
     }
+    // `add feishu`/`add lark` = scaffold + CREATE OR RESUME the app (cli-add-feishu.ts): feishu persists
+    // its irreversible App ID/Secret boundary internally; lark returns guided credentials for the
+    // generic .env write below.
+    let created;
+    if (channelKind === "feishu" || channelKind === "lark") {
+        created = await onboardFeishuCloudApp(target, channelKind, envIgnored).catch(failStartup);
+    }
     const { env, steps } = channelSetup(channelKind);
     const generated = Object.fromEntries(env.filter((e) => e.generate).map((e) => [e.name, randomBytes(24).toString("hex")]));
     // Kind-neutral: every channel's generated secrets get the same treatment (github's webhook secret is
-    // the same class of value as telegram's).
-    const dotEnv = envIgnored ? await appendChannelDotEnv(target, channelKind, generated).catch(failStartup) : undefined;
+    // the same class of value as telegram's); guided Lark credentials ride the same write as overwrites.
+    // Feishu's irreversible credentials were already staged inside cli-add-feishu.ts before bootstrap.
+    const dotEnv = envIgnored
+        ? await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {})).catch(failStartup)
+        : undefined;
     if (dotEnv && dotEnv.written.length > 0) {
         console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to .env`);
     }
@@ -617,11 +660,12 @@ async function runAdd() {
         if (dotEnv?.written.includes(e.name)) {
             // Written, but its hint may still carry an action (github: paste the same value into the webhook
             // UI) — keep the variable visible instead of silently absorbing it.
-            console.error(`    ${e.name} — generated and written to .env   # ${e.hint}`);
+            console.error(`    ${e.name} — ${e.generate ? "generated and " : ""}written to .env   # ${e.hint}`);
             continue;
         }
         const value = e.generate ? `=${generated[e.name]}` : "";
-        console.error(`    set ${e.name}${value} in .env${envIgnored ? " (gitignored)" : ""}   # ${e.hint}`);
+        const action = e.required ? "set" : "optionally set";
+        console.error(`    ${action} ${e.name}${value} in .env${envIgnored ? " (gitignored)" : ""}   # ${e.hint}`);
     }
     // Steps carry `{channel}`/`{tools}` path placeholders (their filenames are the scaffold's private
     // knowledge) — resolve them to the real workspace-relative locations (agentDir-aware) here.
@@ -629,7 +673,12 @@ async function runAdd() {
     for (const s of steps) {
         console.error(`    ${s.replace("{channel}", relative(target, file)).replace("{tools}", `${kitPrefix}tools`)}`);
     }
-    console.error(`    fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
+    if (channelKind !== "lark") {
+        console.error(`    fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
+    }
+    // The app-creation flow leaves keep-alive sockets behind (platform API fetches, the throwaway tunnel's
+    // health probes) that would hold the event loop open for a while — the work is done, exit crisply.
+    process.exit(0);
 }
 /** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
 async function runAddSkill() {
@@ -681,6 +730,7 @@ async function runDeploy() {
         process.exit(1);
     }
     loadDotEnv(target); // a custom provider/tool may read a key at config load
+    installProxyFetch(); // post-deploy channel API calls must honor HTTP(S)_PROXY under Node
     const { config } = await loadConfig(target).catch(failStartup);
     const modelSpec = resolveModelSpec(values.model, config);
     // The host-neutral pre-flight (model-travel gate, channel discovery, model-auth probe, container facts +
@@ -853,7 +903,7 @@ async function runDeployFly(params) {
         console.error(`[fastagent] deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`);
         process.exit(1);
     }
-    const outcome = await deployFlyRun({ appName, region, secrets, missingSecrets, channels, flyConfig: "fly.toml" }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl));
+    const outcome = await deployFlyRun({ appName, region, secrets, missingSecrets, channels, flyConfig: "fly.toml" }, fly, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind));
     if (!outcome.ok) {
         console.error(`[fastagent] deploy stopped: ${outcome.gate}`);
         process.exit(1);
@@ -887,7 +937,7 @@ async function runDeployRailway(params) {
         console.error(`[fastagent] deploy stopped: no model credential — run \`fastagent login\`, or set a provider API key in .env, then re-run`);
         process.exit(1);
     }
-    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, intoLinked: !!values["into-linked"] }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl));
+    const outcome = await deployRailwayRun({ name, mountPath: "/data", secrets, missingSecrets, channels, intoLinked: !!values["into-linked"] }, railway, (m) => console.error(`[fastagent] ${m}`), (baseUrl) => registerTelegramWebhook(baseUrl), (baseUrl, kind) => registerFeishuWebhook(baseUrl, kind));
     if (!outcome.ok) {
         console.error(`[fastagent] deploy stopped: ${outcome.gate}`);
         process.exit(1);
@@ -931,11 +981,6 @@ async function runLogin() {
     console.error(`[fastagent] logged in to ${result.provider} (${result.method}) — saved to ${authPath}`);
     process.exit(0); // the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
 }
-/** Best-effort open a URL in the default browser; failure is fine (the URL is always printed too). */
-function openBrowser(url) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).on("error", () => { });
-}
 /** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
 function terminalLoginIO() {
     return {
@@ -950,7 +995,7 @@ function terminalLoginIO() {
             return isCancel(r) ? undefined : r;
         },
         note: (message) => clackLog.info(message),
-        openUrl: openBrowser,
+        openUrl: openExternalUrl,
     };
 }
 /**
@@ -1118,7 +1163,7 @@ function maybeTunnel(workspaceDir, boundPort) {
     void startCloudflareTunnel(boundPort).then((t) => {
         if (!t)
             return;
-        void announceWebhooks(workspaceDir, t.url);
+        void announceWebhooks(workspaceDir, t.url, { openUrl: openExternalUrl });
         // Single-process (start / --no-watch): close the tunnel on exit (watch mode's supervisor owns its own).
         const cleanup = () => {
             t.close();

package/dist/deploy/container.js

@@ -120,12 +120,16 @@ COPY . .
 CMD ["./node_modules/.bin/fastagent", "start", "/app"]
 `;
 }
-const DOCKERIGNORE = `node_modules
-.fastagent
-.env
-.env.*
-!.env.example
-*.log
+/** Patterns are RECURSIVE (`**​/`) on purpose — dockerignore patterns are root-anchored (unlike
+ *  .gitignore), and a repo-as-agent can hold nested projects: a bare `node_modules` would upload their
+ *  build-machine deps (macOS binaries!) and a bare `.env` would bake their secrets into the image.
+ *  `.git` stays root-anchored: nested projects' own `.git` ships (the agent's write-back needs it). */
+const DOCKERIGNORE = `**/node_modules
+**/.fastagent
+**/.env
+**/.env.*
+!**/.env.example
+**/*.log
 # .git is excluded to keep the image small. If your agent runs git on its OWN history
 # (git log/blame over the repo it ships in), delete the next line so that history is in the image.
 .git