@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/dist/scaffold/add-channel.js

@@ -17,6 +17,7 @@ const CHANNEL_SCAFFOLDS = {
             {
                 name: "GITHUB_WEBHOOK_SECRET",
                 hint: "any random string; set the same value in the GitHub webhook",
+                required: true,
                 generate: true,
             },
         ],
@@ -29,14 +30,75 @@ const CHANNEL_SCAFFOLDS = {
     },
     telegram: {
         env: [
-            { name: "TELEGRAM_BOT_TOKEN", hint: "from @BotFather → /newbot" },
-            { name: "TELEGRAM_SECRET_TOKEN", hint: "any random string; verifies inbound updates", generate: true },
+            { name: "TELEGRAM_BOT_TOKEN", hint: "from @BotFather → /newbot", required: true },
+            {
+                name: "TELEGRAM_SECRET_TOKEN",
+                hint: "any random string; verifies inbound updates",
+                required: true,
+                generate: true,
+            },
         ],
         steps: [
             "edit {channel} — customise routing with route() (optional; the defaults already work)",
             "the agent can send messages or files back by calling the scaffolded {tools}/telegram-send.ts tool",
         ],
     },
+    // Feishu is the canonical engine/cloud; Lark international reuses its protocol through a degraded
+    // compatibility profile. Each remains its own channel KIND: route, env, state, console, onboarding.
+    // No `generate` in either: every value comes FROM the platform (a locally generated Encrypt Key
+    // would break inbound events until mirrored in the console). `add feishu` scan-creates the app;
+    // Lark lacks that control-plane capability, so `add lark` guides console credential collection.
+    feishu: {
+        env: [
+            {
+                name: "FEISHU_APP_ID",
+                hint: "created + written automatically by `add feishu` (console → Credentials & Basic Info)",
+                required: true,
+            },
+            {
+                name: "FEISHU_APP_SECRET",
+                hint: "created + written automatically by `add feishu` (console → Credentials & Basic Info)",
+                required: true,
+            },
+            {
+                name: "FEISHU_VERIFICATION_TOKEN",
+                hint: "captured automatically (console → Events & Callbacks)",
+                required: true,
+            },
+            {
+                name: "FEISHU_ENCRYPT_KEY",
+                hint: "optional but recommended — set one in the console and copy it here",
+                required: false,
+            },
+        ],
+        steps: [
+            "PUBLISH the app version on the page the CLI opened — the switch to webhook mode takes effect on publish (one click, once ever; no API for it)",
+            "edit {channel} — routing policy (the header walks through the console setup, for hand-made apps)",
+            "the event Request URL is auto-registered by `dev --tunnel` / `deploy --run`",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
+        ],
+    },
+    lark: {
+        env: [
+            { name: "LARK_APP_ID", hint: "developer console → Credentials & Basic Info", required: true },
+            { name: "LARK_APP_SECRET", hint: "developer console → Credentials & Basic Info", required: true },
+            {
+                name: "LARK_VERIFICATION_TOKEN",
+                hint: "console → Events & Callbacks; authenticates inbound events",
+                required: true,
+            },
+            {
+                name: "LARK_ENCRYPT_KEY",
+                hint: "optional but recommended — set one in the console and copy it here",
+                required: false,
+            },
+        ],
+        steps: [
+            "finish the console setup: enable Bot and add the permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
+            "run `fastagent dev --tunnel` and keep it running; if auto-registration reports a config-API 404, manually switch Subscription mode to webhook, set its printed https://…/lark Request URL, save, then create + publish a version",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
+        ],
+    },
 };
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
@@ -83,11 +145,13 @@ function mentionsEnvName(content, name) {
 }
 /**
  * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept. Manual values (e.g.
- * TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is ready to
- * edit while no fake secret is committed to the user's mental model.
+ * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * `overwrite`: those are authoritative (e.g. the credentials of an app `add feishu` JUST minted —
+ * skipping them for a stale value would silently discard a fresh, unrecoverable secret). Manual values
+ * (e.g. TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is
+ * ready to edit while no fake secret is committed to the user's mental model.
  */
-export async function appendChannelDotEnv(dir, kind, generated) {
+export async function appendChannelDotEnv(dir, kind, generated, overwrite = []) {
     const file = join(dir, ".env");
     let current = "";
     try {
@@ -97,7 +161,9 @@ export async function appendChannelDotEnv(dir, kind, generated) {
         if (e.code !== "ENOENT")
             throw e;
     }
-    const alreadySet = CHANNEL_SCAFFOLDS[kind].env.filter((e) => hasActiveEnvValue(current, e.name)).map((e) => e.name);
+    const alreadySet = CHANNEL_SCAFFOLDS[kind].env
+        .filter((e) => !overwrite.includes(e.name) && hasActiveEnvValue(current, e.name))
+        .map((e) => e.name);
     const lines = [];
     const written = [];
     const contentLines = current.split("\n");

package/dist/tunnel.d.ts

@@ -1,7 +1,8 @@
 /**
  * `--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; github prints the
- * URL to paste into repo settings). This closes the "local dev → public URL" gap webhooks need.
+ * 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
+ * "local dev → public URL" gap webhooks need.
  *
  * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
  */
@@ -22,10 +23,12 @@ type SpawnCloudflared = (port: number) => ChildProcess;
  * (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.)
  */
-export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloudflared): Promise<Tunnel | undefined>;
+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 is
- * auto-registered via setWebhook (using .env tokens); github prints the URL to add in repo settings.
+ * 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.
  */
-export declare function announceWebhooks(dir: string, baseUrl: string): Promise<void>;
+export declare function announceWebhooks(dir: string, baseUrl: string, opts?: {
+    openUrl?: (url: string) => void;
+}): Promise<void>;
 export {};

package/dist/tunnel.js

@@ -1,14 +1,15 @@
 /**
  * `--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; github prints the
- * URL to paste into repo settings). This closes the "local dev → public URL" gap webhooks need.
+ * 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
+ * "local dev → public URL" gap webhooks need.
  *
  * 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 { setTimeout as sleep } from "node:timers/promises";
+import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
 import { loadDotEnv } from "./env.js";
 import { log } from "./log.js";
@@ -21,8 +22,12 @@ const TUNNEL_URL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com/i;
 export function parseTunnelUrl(chunk) {
     return chunk.match(TUNNEL_URL_RE)?.[0];
 }
+/** 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;
 const TUNNEL_RETRY_MS = 2000;
+/** cloudflared can stay alive without ever receiving/printing an assigned quick-tunnel URL. */
+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.
@@ -32,9 +37,9 @@ const spawnCloudflared = (port) => spawn("cloudflared", ["tunnel", "--url", `htt
  * (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.)
  */
-export async function startCloudflareTunnel(port, spawnFn = spawnCloudflared) {
+export async function startCloudflareTunnel(port, spawnFn = spawnCloudflared, attemptTimeoutMs = TUNNEL_START_TIMEOUT_MS) {
     for (let attempt = 1; attempt <= TUNNEL_ATTEMPTS; attempt++) {
-        const r = await spawnTunnelOnce(port, spawnFn);
+        const r = await spawnTunnelOnce(port, spawnFn, attemptTimeoutMs);
         if (r.tunnel)
             return r.tunnel;
         if (r.fatal) {
@@ -50,43 +55,45 @@ export async function startCloudflareTunnel(port, spawnFn = spawnCloudflared) {
     return undefined;
 }
 /** One cloudflared launch: a Tunnel on the first URL, or a failure (missing binary / exit before a URL). */
-function spawnTunnelOnce(port, spawnFn) {
+function spawnTunnelOnce(port, spawnFn, timeoutMs) {
     return new Promise((resolve) => {
         const child = spawnFn(port);
         let settled = false;
+        let timer;
         let tail = ""; // recent output, surfaced as the failure reason
-        const onChunk = (buf) => {
-            tail = (tail + String(buf)).slice(-600);
+        const finish = (result) => {
             if (settled)
                 return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(result);
+        };
+        const onChunk = (buf) => {
+            tail = (tail + String(buf)).slice(-600);
             const url = parseTunnelUrl(String(buf));
-            if (url) {
-                settled = true;
-                resolve({ tunnel: { url, close: () => child.kill("SIGTERM") } });
-            }
+            if (url)
+                finish({ tunnel: { url, close: () => child.kill("SIGTERM") } });
         };
         child.stdout?.on("data", onChunk);
         child.stderr?.on("data", onChunk); // cloudflared prints the URL (and its errors) on stderr
         child.on("error", (e) => {
-            if (settled)
-                return;
-            settled = true;
             if (e.code === "ENOENT") {
-                resolve({
+                finish({
                     fatal: true,
                     message: "[fastagent] --tunnel needs cloudflared — install it (e.g. `brew install cloudflared`), then re-run. Serving without a tunnel.",
                 });
             }
             else {
-                resolve({ fatal: false, detail: e.message });
+                finish({ fatal: false, detail: e.message });
             }
         });
-        child.on("exit", () => {
-            if (settled)
-                return;
-            settled = true;
-            resolve({ fatal: false, detail: lastErrorLine(tail) });
-        });
+        child.on("exit", () => finish({ fatal: false, detail: lastErrorLine(tail) }));
+        timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            finish({ fatal: false, detail: `timed out after ${Math.round(timeoutMs / 1000)}s waiting for a public URL` });
+        }, timeoutMs);
+        timer.unref();
     });
 }
 /** The most informative line of cloudflared's output tail (prefer an error line) for a failure log. */
@@ -109,31 +116,41 @@ function channelBasenames(dir) {
     }
 }
 /**
- * Print the public URL and wire up the first-party webhook channels found under `dir`: telegram is
- * auto-registered via setWebhook (using .env tokens); github prints the URL to add in repo settings.
+ * 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.
  */
-export async function announceWebhooks(dir, baseUrl) {
+export async function announceWebhooks(dir, baseUrl, opts = {}) {
     log.info(`[fastagent] public URL: ${baseUrl}`);
     try {
-        loadDotEnv(dir); // telegram registration reads tokens from .env
+        loadDotEnv(dir); // webhook registrars read channel credentials from .env
     }
     catch (error) {
         // best-effort boundary: a MISSING .env is already tolerated by loadDotEnv; an unreadable one (EACCES,
         // or .env is a directory) must NOT crash the long-running dev/start server — announceWebhooks is
         // void-called with no unhandledRejection handler, so a throw here would terminate the process. Warn
-        // (surface it, rule 8) and continue best-effort; telegram registration then degrades to its manual
-        // instruction if the token is absent. loadDotEnv keeps throwing for the synchronous command callers.
+        // (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`);
     }
     const channels = channelBasenames(dir);
     if (channels.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 registerTelegramWebhook polls /health until it serves before setWebhook (the
-    // same wait the deploy runners rely on). github needs no wait — the operator adds that webhook by hand.
+    // 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"))
         await registerTelegramWebhook(baseUrl);
     if (channels.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`);
     }
+    // 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"))
+        await registerFeishuWebhook(baseUrl, "feishu", feishuOptions);
+    if (channels.includes("lark"))
+        await registerFeishuWebhook(baseUrl, "lark", feishuOptions);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.12.0",
-  "description": "Vibe first. Then FastAgent: turn a local agent directory into a running service in your app, on GitHub, in Telegram, or behind any channel.",
+  "version": "0.13.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.",
   "keywords": [
     "agent",
     "ai-agent",
@@ -9,13 +9,16 @@
     "agents.md",
     "agent-skills",
     "agent-serving",
+    "telegram",
+    "github",
+    "webhook",
     "sse",
     "pi",
     "fastagent"
   ],
   "license": "MIT",
   "author": "the fastagent authors (https://github.com/fastagent-sh/fastagent)",
-  "homepage": "https://github.com/fastagent-sh/fastagent#readme",
+  "homepage": "https://fastagent.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fastagent-sh/fastagent.git"
@@ -51,6 +54,14 @@
       "types": "./dist/telegram.d.ts",
       "default": "./dist/telegram.js"
     },
+    "./feishu": {
+      "types": "./dist/feishu.d.ts",
+      "default": "./dist/feishu.js"
+    },
+    "./lark": {
+      "types": "./dist/lark.d.ts",
+      "default": "./dist/lark.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -77,13 +88,13 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.80.3",
-    "@earendil-works/pi-ai": "^0.80.3",
-    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-agent-core": "^0.80.7",
+    "@earendil-works/pi-ai": "^0.80.7",
+    "@earendil-works/pi-coding-agent": "^0.80.7",
     "@octokit/webhooks-methods": "^6.0.0",
     "@octokit/webhooks-types": "^7.6.1",
     "chokidar": "^5.0.0",
-    "croner": "^9.1.0",
+    "croner": "^10.0.1",
     "giget": "^3.3.0",
     "ignore": "^7.0.5",
     "undici": "^8.6.0",
@@ -91,7 +102,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.9"
   }
 }