@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/tunnel.d.ts

@@ -1,7 +1,7 @@
 /**
  * `--tunnel`: expose the local dev server on a public HTTPS URL via a Cloudflare quick tunnel, then
- * auto-register the first-party webhook channels against it (Telegram setWebhook; Feishu/Lark
- * application-config PATCH; GitHub prints the URL to paste into repo settings). This closes the
+ * auto-register the first-party webhook channels against it (Telegram setWebhook; onboarded Slack
+ * App Manifest update; Feishu/Lark application-config PATCH; GitHub/manual Slack print URLs). This closes the
  * "local dev → public URL" gap webhooks need.
  *
  * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
@@ -25,10 +25,13 @@ type SpawnCloudflared = (port: number) => ChildProcess;
  */
 export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloudflared, attemptTimeoutMs?: number): Promise<Tunnel | undefined>;
 /**
- * Print the public URL and wire up the first-party webhook channels found under `dir`: Telegram and
- * Feishu/Lark auto-register using credentials from .env; GitHub prints the URL to add in repo settings.
+ * 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.
  */
 export declare function announceWebhooks(dir: string, baseUrl: string, opts?: {
     openUrl?: (url: string) => void;
+    routeChannels?: string[];
+    stateRoot?: string;
 }): Promise<void>;
 export {};

package/dist/tunnel.js

@@ -1,7 +1,7 @@
 /**
  * `--tunnel`: expose the local dev server on a public HTTPS URL via a Cloudflare quick tunnel, then
- * auto-register the first-party webhook channels against it (Telegram setWebhook; Feishu/Lark
- * application-config PATCH; GitHub prints the URL to paste into repo settings). This closes the
+ * auto-register the first-party webhook channels against it (Telegram setWebhook; onboarded Slack
+ * App Manifest update; Feishu/Lark application-config PATCH; GitHub/manual Slack print URLs). This closes the
  * "local dev → public URL" gap webhooks need.
  *
  * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
@@ -10,8 +10,10 @@ 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 { loadDotEnv } from "./env.js";
+import { dotEnvPath, loadDotEnv } from "./env.js";
+import { resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";
 // `(?!api\.)`: cloudflared's ERROR lines mention its request endpoint (`https://api.trycloudflare.com/tunnel`,
 // e.g. "failed to request quick Tunnel: Post ... timeout" under a flaky proxy) — without the exclusion a
@@ -116,8 +118,9 @@ function channelBasenames(dir) {
     }
 }
 /**
- * Print the public URL and wire up the first-party webhook channels found under `dir`: Telegram and
- * Feishu/Lark auto-register using credentials from .env; GitHub prints the URL to add in repo settings.
+ * 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.
  */
 export async function announceWebhooks(dir, baseUrl, opts = {}) {
     log.info(`[fastagent] public URL: ${baseUrl}`);
@@ -130,27 +133,35 @@ export async function announceWebhooks(dir, baseUrl, opts = {}) {
         // void-called with no unhandledRejection handler, so a throw here would terminate the process. Warn
         // (surface it, rule 8) and continue best-effort; each registrar then surfaces its own
         // missing-credential guidance. loadDotEnv keeps throwing for the synchronous command callers.
-        log.warn(`[fastagent] could not read ${join(dir, ".env")}: ${error.message} — continuing without it`);
+        log.warn(`[fastagent] could not read ${dotEnvPath(dir)}: ${error.message} — continuing without it`);
     }
-    const channels = channelBasenames(dir);
-    if (channels.length === 0)
+    // 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 (channels.includes("telegram"))
+    if (routeChannels.includes("telegram"))
         await registerTelegramWebhook(baseUrl);
-    if (channels.includes("github")) {
+    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.
     const feishuOptions = {
         onManualRegistration: ({ consoleUrl }) => opts.openUrl?.(consoleUrl),
     };
-    if (channels.includes("feishu"))
+    if (routeChannels.includes("feishu"))
         await registerFeishuWebhook(baseUrl, "feishu", feishuOptions);
-    if (channels.includes("lark"))
+    if (routeChannels.includes("lark"))
         await registerFeishuWebhook(baseUrl, "lark", feishuOptions);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.14.0",
-  "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, in Telegram, or behind any channel.",
+  "version": "0.16.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",
     "ai-agent",
@@ -10,6 +10,7 @@
     "agent-skills",
     "agent-serving",
     "telegram",
+    "slack",
     "github",
     "webhook",
     "sse",
@@ -42,6 +43,10 @@
       "types": "./dist/core.d.ts",
       "default": "./dist/core.js"
     },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "default": "./dist/session.js"
+    },
     "./pi": {
       "types": "./dist/pi.d.ts",
       "default": "./dist/pi.js"
@@ -54,6 +59,10 @@
       "types": "./dist/telegram.d.ts",
       "default": "./dist/telegram.js"
     },
+    "./slack": {
+      "types": "./dist/slack.d.ts",
+      "default": "./dist/slack.js"
+    },
     "./feishu": {
       "types": "./dist/feishu.d.ts",
       "default": "./dist/feishu.js"
@@ -82,15 +91,20 @@
     "prepack": "npm run build",
     "test": "vitest --run",
     "typecheck": "tsc --noEmit",
-    "lint": "biome check src test && node scripts/check-doc-links.mjs",
+    "lint": "biome check src test && node scripts/check-doc-links.mjs && knip",
     "format": "biome check --write src test",
-    "postbuild": "node scripts/copy-scaffold-assets.mjs"
+    "postbuild": "node scripts/copy-scaffold-assets.mjs",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major",
+    "knip": "knip"
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.80.10",
-    "@earendil-works/pi-ai": "^0.80.10",
-    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-agent-core": "^0.81.1",
+    "@earendil-works/pi-ai": "^0.81.1",
+    "@earendil-works/pi-coding-agent": "^0.81.1",
+    "@larksuiteoapi/node-sdk": "^1.71.1",
     "@octokit/webhooks-methods": "^6.0.0",
     "@octokit/webhooks-types": "^7.6.1",
     "chokidar": "^5.0.0",
@@ -105,6 +119,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
     "@types/proper-lockfile": "^4.1.4",
+    "knip": "^6.29.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.9"
   }

package/dist/channels/feishu/owned-threads.d.ts

@@ -1,11 +0,0 @@
-export interface OwnedFeishuThread {
-    rootId: string;
-    chatId: string;
-    createdAt: number;
-}
-export interface OwnedFeishuThreads {
-    has(chatId: string, rootId: string): boolean;
-    /** Idempotent, synchronous, pre-ACK persistence. A failed write throws so the platform redelivers. */
-    add(chatId: string, rootId: string): void;
-}
-export declare function createOwnedFeishuThreads(path: string, label: string, now?: () => number): OwnedFeishuThreads;

package/dist/channels/feishu/owned-threads.js

@@ -1,47 +0,0 @@
-/**
- * Durable ownership index for group threads the channel created from a top-level summon. Feishu/Lark
- * deliver an ordinary thread continuation as `thread_id + root_id`; the root is the original user
- * message the channel reply-threaded under. Keeping that root across restarts lets the default route
- * admit unmentioned continuations only inside Agent-managed threads, never across the whole group.
- */
-import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "../state.js";
-function isRecord(value) {
-    const record = value;
-    return (typeof record?.rootId === "string" &&
-        typeof record.chatId === "string" &&
-        typeof record.createdAt === "number" &&
-        Number.isFinite(record.createdAt));
-}
-export function createOwnedFeishuThreads(path, label, now = Date.now) {
-    const raw = loadStateFile(path);
-    let records = new Map();
-    if (raw !== undefined) {
-        if (typeof raw === "object" &&
-            raw !== null &&
-            !Array.isArray(raw) &&
-            Object.entries(raw).every(([rootId, record]) => isRecord(record) && record.rootId === rootId)) {
-            records = new Map(Object.entries(raw));
-        }
-        else {
-            log.warn(`${label} unexpected shape in ${path} — starting with no managed group threads`);
-        }
-    }
-    return {
-        has(chatId, rootId) {
-            const record = records.get(rootId);
-            return record?.chatId === chatId;
-        },
-        add(chatId, rootId) {
-            const existing = records.get(rootId);
-            if (existing?.chatId === chatId)
-                return;
-            const next = new Map(records);
-            next.set(rootId, { rootId, chatId, createdAt: now() });
-            // Persist the staged copy first: an IO failure must not leave memory claiming durability the file
-            // does not have. The webhook remains un-ACKed and the platform can redeliver after recovery.
-            saveStateFile(path, Object.fromEntries(next));
-            records = next;
-        },
-    };
-}

package/dist/channels/feishu/seen.d.ts

@@ -1,5 +0,0 @@
-export interface SeenRing {
-    has(id: string): boolean;
-    add(id: string): void;
-}
-export declare function createSeenRing(path: string, label?: string, cap?: number): SeenRing;

package/dist/channels/feishu/seen.js

@@ -1,47 +0,0 @@
-/**
- * Bounded delivery dedup for message_ids whose webhook handling produced a durable side effect: either
- * an accepted turn intent or a buffered group-context entry. Feishu/Lark document duplicate pushes even
- * after a successful 200 and recommend idempotency on message_id (not event_id). The unfinished-turn
- * store cannot cover a duplicate after completion, and a duplicated background event would otherwise be
- * folded twice.
- *
- * Record only AFTER the pre-ACK side effect is durable: recording first could turn a later state-write
- * failure into silent loss when the platform redelivers. The ring write is best-effort post-persist
- * insurance. A crash between the two writes, a ring-write failure, or an id older than the bounded cap
- * retains L1's at-least-once tail; this is dedup, not exactly-once execution.
- */
-import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "../state.js";
-export function createSeenRing(path, label = "[feishu]", cap = 2000) {
-    const load = () => {
-        const raw = loadStateFile(path);
-        if (raw === undefined)
-            return [];
-        if (Array.isArray(raw) && raw.every((id) => typeof id === "string"))
-            return raw.slice(-cap);
-        log.warn(`${label} unexpected shape in ${path} — starting with no seen ids`);
-        return [];
-    };
-    const order = load();
-    const ids = new Set(order);
-    return {
-        has: (id) => ids.has(id),
-        add(id) {
-            if (ids.has(id))
-                return;
-            ids.add(id);
-            order.push(id);
-            while (order.length > cap) {
-                const evicted = order.shift();
-                if (evicted !== undefined)
-                    ids.delete(evicted);
-            }
-            try {
-                saveStateFile(path, order);
-            }
-            catch (error) {
-                log.warn(`${label} seen-ring write failed (delivery dedup is in-memory until restart): ${String(error)}`);
-            }
-        },
-    };
-}

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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,223 +0,0 @@
-/**
- * `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-models.d.ts

@@ -1,11 +0,0 @@
-/**
- * CLI presenter for `fastagent models [search]`: the stdout/stderr output DECISION, kept out of the
- * engine config layer (config.ts owns model resolution / listModels) so this process-boundary behavior
- * is unit-testable without spawning the CLI.
- */
-/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
- *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
-export declare function formatModelsCommand(specs: string[], search?: string): {
-    lines: string[];
-    error?: string;
-};

package/dist/cli-models.js

@@ -1,20 +0,0 @@
-/**
- * CLI presenter for `fastagent models [search]`: the stdout/stderr output DECISION, kept out of the
- * engine config layer (config.ts owns model resolution / listModels) so this process-boundary behavior
- * is unit-testable without spawning the CLI.
- */
-/** The output of `fastagent models [search]`: the spec `lines` to print to stdout (a case-insensitive
- *  substring filter; no search → all), and an stderr `error` diagnostic when a search matches nothing. */
-export function formatModelsCommand(specs, search) {
-    if (!search)
-        return { lines: specs };
-    const q = search.toLowerCase();
-    const matches = specs.filter((spec) => spec.toLowerCase().includes(q));
-    if (matches.length === 0)
-        return { lines: matches, error: `no model matches "${search}"` };
-    // Rank a PROVIDER-name match (query in the part before "/") above an incidental model-id match, so
-    // `models anthropic` leads with anthropic/* rather than burying it under amazon-bedrock/anthropic.*
-    // and google-vertex/…-anthropic-… (which only match in the model id). Order within each group is kept.
-    const providerMatch = (spec) => spec.slice(0, spec.indexOf("/")).toLowerCase().includes(q);
-    return { lines: [...matches.filter(providerMatch), ...matches.filter((s) => !providerMatch(s))] };
-}

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

@@ -1,56 +0,0 @@
-import type { Agent } from "../../agent.ts";
-import { type FastagentConfig } from "./config.ts";
-import type { ModuleLoadFailure } from "../../loader.ts";
-import { type LoadedDefinition } from "./definition.ts";
-import type { ToolCollision } from "./tool.ts";
-export interface CreatePiAgentFromWorkspaceOptions {
-    /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
-    model?: string;
-    /**
-     * Session store directory. Default `<dir>/.fastagent/sessions` (gitignored machine state). `start`
-     * overrides it (--sessions-dir / FASTAGENT_SESSIONS_DIR / a mounted volume) so production continuity
-     * survives redeploys.
-     */
-    sessionsDir?: string;
-    /**
-     * Credentials file override. Default `<dir>/.fastagent/auth.json` (project-level, gitignored under
-     * the same `*`-ignored `.fastagent`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
-     * `~/.fastagent/auth.json` to share one credential across projects.
-     */
-    authPath?: string;
-    /**
-     * This is a long-running SERVE (`dev`/`start`), where the scheduler poller runs — so a self-scheduled
-     * wake-up is actually honored. One-shot entries (`invoke`/`fire`) leave it off (they exit after the turn
-     * and never poll). The built-in `wake` tool mounts only when this is set AND `config.selfSchedule` is on.
-     */
-    serving?: boolean;
-}
-/**
- * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
- * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
- * to report what it assembled.
- */
-export declare function createPiAgentFromWorkspace(dir: string, options?: CreatePiAgentFromWorkspaceOptions): Promise<{
-    agent: Agent;
-    definition: LoadedDefinition;
-    config: FastagentConfig;
-    configPath?: string;
-    /** The resolved "provider/modelId" spec actually in use. */
-    modelSpec: string;
-    /** Absolute agent-definition dir in use (config.agentDir resolved against dir; = dir when unset). Channels/tools/persona come from here. */
-    agentDir: string;
-    /** Absolute state root in use (FASTAGENT_STATE_DIR > <dir>/.fastagent) — the ChannelContext's stateRoot. */
-    stateRoot: string;
-    /** Absolute session store directory in use (for the startup report). */
-    sessionsDir: string;
-    /** Absolute credentials file in use (for the startup report). */
-    authPath: string;
-    /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
-     *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */
-    toolNames: string[];
-    /** Tools registered but not initially active (deferred) — activated via search_tools. */
-    deferredToolNames: string[];
-    toolCollisions: ToolCollision[];
-    /** `tools/` files that failed to import — skipped, reported by the caller, never fatal. */
-    toolFailures: ModuleLoadFailure[];
-}>;