@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <a href="https://github.com/fastagent-sh/fastagent"><img src="https://raw.githubusercontent.com/fastagent-sh/fastagent/main/assets/hero.png" alt="FastAgent — Vibe first. Then FastAgent. An agent directory becomes a live service in your app, on GitHub, in Telegram, or any channel." width="860"></a>
+  <a href="https://fastagent.sh"><img src="https://raw.githubusercontent.com/fastagent-sh/fastagent/main/assets/hero.png" alt="FastAgent — Vibe first. Then FastAgent. An agent directory becomes a live service in your app, on GitHub, in Telegram, or any channel." width="860"></a>
 </p>
 
 [![CI](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml/badge.svg)](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@fastagent-sh/fastagent.svg)](https://www.npmjs.com/package/@fastagent-sh/fastagent)
-[![license](https://img.shields.io/npm/l/@fastagent-sh/fastagent.svg)](LICENSE)
+[![license](https://img.shields.io/npm/l/@fastagent-sh/fastagent.svg)](https://github.com/fastagent-sh/fastagent/blob/main/LICENSE)
 [![node](https://img.shields.io/node/v/@fastagent-sh/fastagent.svg)](https://nodejs.org)
 [![built with pi](https://img.shields.io/badge/built%20with-pi-0b7285.svg)](https://pi.dev)
 
@@ -16,7 +16,7 @@
 
 A file-defined agent directory can become a live service. FastAgent takes it out of the terminal and serves it in your Next/Astro app, Telegram, GitHub/webhook events, an API endpoint, or your own channel.
 
-Leave the terminal. Become a real service.
+Leave the terminal. Become a live service.
 
 - **Add it to your app** — one route, your auth, your database, your host.
 - **Run it as a live service** — Telegram support, GitHub PR review, webhook handler, API endpoint, or custom channel.
@@ -24,53 +24,57 @@ Leave the terminal. Become a real service.
 FastAgent is not a new agent-authoring DSL. You bring the existing definition and project layout; FastAgent provides the serving runtime and adapters around it.
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="fastagent dev boots an existing agent directory (AGENTS.md, skills/, tools/, channels/) into a live service; a GitHub pull_request.opened webhook arrives and the agent reviews PR #42 and posts inline comments." width="860">
+  <img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="Three acts in one terminal: a coding agent vibes a support agent into a directory; fastagent dev serves it live, answering a GitHub pull request, a Telegram message, and an HTTP invoke; fastagent deploy fly --run ships it to a live URL." width="860">
 </p>
 
 ## Why FastAgent
 
 Coding agents made it cheap to vibe useful agent directories. The hard part is the next step: local agents live in terminals, but real services receive webhooks, join Telegram, serve product users, and expose stable APIs.
 
-FastAgent is the missing bridge from local agent directory to real service.
+FastAgent is the missing bridge from local agent directory to live service.
 
 ## Features
 
 - **Vibe first — a directory is an agent.** Point FastAgent at the `AGENTS.md` + `skills/` you already vibed in a coding agent. Markdown instructions, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite.
 - **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, an HTTP/SSE endpoint, or your own adapter — verified webhooks, streaming replies, group-aware.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
-- **App embedding — your stack, we plug in.** Like Flask/FastAPI for agents: FastAgent never owns your framework. Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler — your auth, your database, your host.
-- **Deploy anywhere.** Run the directory directly — no build step; `fastagent deploy fly|railway` generates the host config + a runbook and hands off (`--run` drives the deploy to completion). The generated container also runs on other Docker hosts.
-
-Using a coding agent? Give it [`docs/ai-start.md`](docs/ai-start.md) for an AI-guided setup path.
+- **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
+- **Deploy anywhere.** No build step — the directory is the deployable unit. `fastagent deploy fly|railway` generates the deploy config + a runbook (`--run` drives it to completion); idle agents scale to zero and resume in hundreds of milliseconds on the next webhook. The generated container runs on any Docker host.
 
 ## Design philosophy
 
 FastAgent is built around a small serving contract, app-owned runtime concerns, typed boundaries, and composable adapters.
 
-- **Small serving core** — `invoke` decouples channels, agents, engines, and hosts.
+- **Small serving core** — `invoke` decouples channels, agents, harnesses, and infra.
 - **App-owned runtime** — no takeover of your auth, database, routes, or deployment.
 - **Typed edges** — typed tools, explicit events, boundary validation.
 - **Agent-native shape** — the directory is the deployable unit, and channels drive the same contract.
 
-Read [Design principles](docs/principles.md) for the full rationale.
+Read the [Design principles](https://fastagent.sh/docs/principles/) for the full rationale.
 
 ## What we didn't build
 
-FastAgent stays a small serving layer, so it never dictates your stack. Capabilities other agent frameworks bake into a platform, we leave to your app, your host, or the agent itself — composed in, not locked in.
+FastAgent stays a small serving layer, so it never dictates your stack. Capabilities other agent frameworks bake into a platform, we leave to your app, your infra, or the agent itself — composed in, not locked in.
 
-- **No platform to move to.** No dashboard, no control plane, no runtime you deploy *into* — run it locally, embed it in your app, or ship the directory to any host.
+- **No platform to move to.** No dashboard, no control plane, no runtime you deploy *into* — run it locally, embed it in your app, or ship the directory anywhere.
 - **No new format or DSL.** `AGENTS.md`, Agent Skills, TypeScript tools, HTTP/SSE — FastAgent consumes the standards you already use instead of a parallel ecosystem.
 - **No workflow engine.** The agent decides its own steps; for deterministic multi-step orchestration, call `invoke` from your own queue or workflow.
-- **No model or cloud lock-in.** The Agent Handler contract is engine-neutral, with pi as the reference implementation; another engine can implement the same `Agent` contract without changing channels.
+- **No model or cloud lock-in.** The Agent Handler contract is harness-neutral (the [SPEC](https://fastagent.sh/docs/spec/) says *engine* — same seam), with [pi](https://pi.dev) as the built-in harness; bring your own harness and every channel keeps working unchanged.
 
 ## Install
 
+For agents — paste this into Claude Code, Codex, Cursor, or any coding agent that reads the web:
+
+> Read https://fastagent.sh/start.md and build an agent in this project.
+
+For humans:
+
 ```bash
 npm i -g @fastagent-sh/fastagent   # CLI: fastagent init/dev/start/...
 npm i @fastagent-sh/fastagent      # library API for embedding or code tools
 ```
 
-Requires **Node >= 22.19** (the floor is inherited from the pi reference engine and `undici`), and also runs under **Bun** (smoke-tested in CI on Bun 1.3; its native fetch replaces the undici path). The npm package ships compiled JavaScript and type declarations.
+Requires **Node >= 22.19** (the floor is inherited from the pi harness and `undici`), and also runs under **Bun** (smoke-tested in CI on Bun 1.3; its native fetch replaces the undici path). The npm package ships compiled JavaScript and type declarations.
 
 ## Quickstart
 
@@ -133,20 +137,20 @@ const agent = createPiAgent({
 
 | Document | Purpose |
 |---|---|
-| [docs/README.md](docs/README.md) | Documentation index |
-| [docs/quickstart.md](docs/quickstart.md) | Scaffold, run, add a tool, and start |
-| [docs/configuration.md](docs/configuration.md) | Configure model, auth, ports, sessions, tools, and channels |
-| [docs/principles.md](docs/principles.md) | Design choices, core primitives, and non-goals |
-| [docs/cli.md](docs/cli.md) | CLI reference |
-| [docs/embedding.md](docs/embedding.md) | Use FastAgent as a library inside your own app |
-| [docs/channels.md](docs/channels.md) | Add webhook/bot channels |
-| [docs/deploy.md](docs/deploy.md) | Ship the directory to Fly, Railway, or any Docker host |
-| [docs/github.md](docs/github.md) / [docs/telegram.md](docs/telegram.md) | First-party channel guides |
-| [docs/channel-development.md](docs/channel-development.md) | Build custom channel adapters |
-| [docs/api-reference.md](docs/api-reference.md) | Public TypeScript API reference |
-| [docs/troubleshooting.md](docs/troubleshooting.md) | Common setup/runtime issues |
-| [docs/SPEC.md](docs/SPEC.md) | Agent Handler protocol v0.1 |
-| [docs/design/core.md](docs/design/core.md) | Maintainer architecture notes |
+| [Documentation index](https://fastagent.sh/docs/) | Documentation map |
+| [Quickstart](https://fastagent.sh/docs/quickstart/) | Scaffold, run, add a tool, and start |
+| [Configuration](https://fastagent.sh/docs/configuration/) | Configure model, auth, ports, sessions, tools, and channels |
+| [Design principles](https://fastagent.sh/docs/principles/) | Design choices, core primitives, and non-goals |
+| [CLI reference](https://fastagent.sh/docs/cli/) | CLI commands and flags |
+| [Embedding](https://fastagent.sh/docs/embedding/) | Use FastAgent as a library inside your own app |
+| [Channels](https://fastagent.sh/docs/channels/) | Add webhook/bot channels |
+| [Deploy](https://fastagent.sh/docs/deploy/) | Ship the directory to Fly, Railway, or any Docker host |
+| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
+| [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
+| [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
+| [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
+| [Agent Handler SPEC](https://fastagent.sh/docs/spec/) | Agent Handler protocol v0.1 |
+| [Core design](https://fastagent.sh/docs/design/core/) | Maintainer architecture notes |
 
 ## Public API surface & stability
 
@@ -166,7 +170,9 @@ Subpath exports:
 - `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel/host kit, schedules;
 - `@fastagent-sh/fastagent/pi` — the pi reference implementation;
 - `@fastagent-sh/fastagent/github` — GitHub webhook channel;
-- `@fastagent-sh/fastagent/telegram` — Telegram bot channel.
+- `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
+- `@fastagent-sh/fastagent/feishu` — canonical Feishu bot channel (飞书, open.feishu.cn);
+- `@fastagent-sh/fastagent/lark` — Lark-international compatibility profile over the Feishu engine.
 
 ## Repository layout
 
@@ -191,19 +197,19 @@ The neutral contract leaves room for capabilities that are not complete product
 - **Durable execution** — Telegram accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
 - **Sandboxed execution** — `ExecutionEnv` is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
 - **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
-- **More reference bindings and channels** — pi is the reference implementation; another engine can implement the Agent contract, and community channels can use the channel kit.
+- **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
 - **More deploy targets** — Fly and Railway ship today; the generated container is the portable path for other hosts.
 
-See [Contributing](CONTRIBUTING.md) if one of these is the problem you want to work on.
+See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
 
 ## Project
 
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
+- [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md)
+- [Security policy](https://github.com/fastagent-sh/fastagent/blob/main/SECURITY.md)
 
 ## Acknowledgements
 
-FastAgent stands on open source. The reference implementation is built on **[pi](https://github.com/earendil-works/pi)** ([pi.dev](https://pi.dev)) — its agent harness, multi-provider LLM API, and the interactive TUI that `fastagent chat` drives.
+FastAgent stands on open source. The built-in harness is **[pi](https://github.com/earendil-works/pi)** ([pi.dev](https://pi.dev)) — its agent loop, multi-provider LLM API, and the interactive TUI that `fastagent chat` drives.
 
 It also depends on, and is grateful to, [zod](https://github.com/colinhacks/zod), [undici](https://github.com/nodejs/undici), [chokidar](https://github.com/paulmillr/chokidar), [giget](https://github.com/unjs/giget), [@clack/prompts](https://github.com/bombshell-dev/clack), [ignore](https://github.com/kaelzhang/node-ignore), and [octokit/webhooks](https://github.com/octokit/webhooks).
 
@@ -211,4 +217,4 @@ The scaffolded `writing-great-skills` skill is vendored from [mattpocock/skills]
 
 ## License
 
-[MIT](LICENSE). Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored `writing-great-skills` scaffold includes its own license.
+[MIT](https://github.com/fastagent-sh/fastagent/blob/main/LICENSE). Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored `writing-great-skills` scaffold includes its own license.

package/dist/channels/feishu/bootstrap-token.d.ts

@@ -0,0 +1,42 @@
+import type { FeishuCloudKind } from "./cloud.ts";
+/** What the bootstrap needs from the API pipeline (subset of FeishuApi; injectable in tests). */
+interface EventSubscriptionPatcher {
+    updateEventSubscription(appId: string, cfg: {
+        subscriptionType: "webhook";
+        requestUrl: string;
+    }): Promise<void>;
+}
+export interface FeishuBootstrapTokenOptions {
+    api: EventSubscriptionPatcher;
+    appId: string;
+    /** Canonical Feishu by default; Lark compatibility binds its own route explicitly. */
+    kind?: FeishuCloudKind;
+    /** Expose local `port` on a public URL (production: startCloudflareTunnel; tests: loopback). */
+    startTunnel: (port: number) => Promise<{
+        url: string;
+        close(): void;
+    } | undefined>;
+    /** Budget for the whole capture (the challenge normally lands within the PATCH round-trip). */
+    timeoutMs?: number;
+    /** PATCH attempts × delay — the PATCH is the one and only readiness probe (see below). */
+    patchAttempts?: number;
+    patchRetryMs?: number;
+    /** Retry classifier. Default: retry every PATCH failure (Feishu edge warm-up compatibility).
+     * Lark onboarding rejects a definitive config-route 404 immediately so it can fall back by hand. */
+    shouldRetryPatch?: (error: unknown) => boolean;
+    /** Progress hooks: production prints the assigned URL/retries; tests keep transport IO injected. */
+    onTunnelReady?: (url: string) => void;
+    onPatchRetry?: (info: {
+        error: unknown;
+        attempt: number;
+        attempts: number;
+        retryMs: number;
+    }) => void;
+}
+/**
+ * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
+ * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
+ * degrades to the manual console instruction.
+ */
+export declare function bootstrapFeishuVerificationToken(options: FeishuBootstrapTokenOptions): Promise<string>;
+export {};

package/dist/channels/feishu/bootstrap-token.js

@@ -0,0 +1,94 @@
+/**
+ * Verification-Token bootstrap — the token has NO read API (field-tested 2026-07: the v6 app detail
+ * never returns `encryption`, and the v7 config route only supports PATCH). The platform's only
+ * programmatic delivery is the `url_verification` challenge it POSTs to the request URL while an
+ * event-subscription PATCH is verified — the challenge body carries `token`, the app's Verification
+ * Token. So `add feishu`'s create flow finishes the job by: standing up a throwaway local responder,
+ * exposing it on an ephemeral quick tunnel, PATCHing the app's event subscription at it, capturing
+ * the token from the challenge, and tearing everything down. `dev --tunnel` / `deploy … --run`
+ * re-PATCH the request URL onto the real server later (the token is app-level and survives that).
+ *
+ * Security: the serving path keeps its strict non-empty-token requirement — no bootstrap mode there.
+ * The throwaway URL is random (unguessable), lives for seconds, and only the FIRST challenge is
+ * accepted, immediately after our own credential-authenticated PATCH.
+ */
+import { createServer } from "node:http";
+/**
+ * Run the bootstrap (module header). Resolves with the app's Verification Token; rejects with a
+ * plain, actionable Error (tunnel unavailable, PATCH refused, challenge never arrived) — the caller
+ * degrades to the manual console instruction.
+ */
+export async function bootstrapFeishuVerificationToken(options) {
+    let capturedToken;
+    const token = new Promise((resolve) => {
+        capturedToken = resolve;
+    });
+    // The throwaway responder: answers /health (diagnostics) and the url_verification challenge
+    // (echo `challenge` back), capturing `token` from the FIRST challenge only.
+    const server = createServer((req, res) => {
+        if (req.method === "GET") {
+            res.end("ok");
+            return;
+        }
+        let body = "";
+        req.on("data", (d) => {
+            body += String(d);
+        });
+        req.on("end", () => {
+            try {
+                const j = JSON.parse(body);
+                if (j.type === "url_verification" && typeof j.challenge === "string" && typeof j.token === "string") {
+                    capturedToken?.(j.token);
+                    capturedToken = undefined; // first challenge only
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({ challenge: j.challenge }));
+                    return;
+                }
+            }
+            catch {
+                /* not the challenge — fall through to the empty ACK */
+            }
+            res.end("{}");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : 0;
+    const tunnel = await options.startTunnel(port);
+    try {
+        if (!tunnel)
+            throw new Error("no tunnel came up (is cloudflared installed?)");
+        options.onTunnelReady?.(tunnel.url);
+        // Do NOT health-poll the edge here: "can WE reach it" says nothing about platform→edge, the path
+        // the challenge uses (field-tested: local negative-DNS caching failed while that path worked).
+        // PATCH immediately; it is the real probe because success requires the challenge round-trip.
+        const attempts = options.patchAttempts ?? 8;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await options.api.updateEventSubscription(options.appId, {
+                    subscriptionType: "webhook",
+                    requestUrl: `${tunnel.url}/${options.kind ?? "feishu"}`,
+                });
+                break;
+            }
+            catch (e) {
+                if (attempt >= attempts || options.shouldRetryPatch?.(e) === false)
+                    throw e;
+                const retryMs = options.patchRetryMs ?? 10_000;
+                options.onPatchRetry?.({ error: e, attempt, attempts, retryMs });
+                await new Promise((resolve) => setTimeout(resolve, retryMs));
+            }
+        }
+        const winner = await Promise.race([
+            token,
+            new Promise((resolve) => setTimeout(() => resolve(undefined), options.timeoutMs ?? 30_000)),
+        ]);
+        if (winner === undefined)
+            throw new Error("the registration challenge never arrived");
+        return winner;
+    }
+    finally {
+        tunnel?.close();
+        server.close();
+    }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
+ * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
+ * the card DSL is data-in → string-out and testable without the pump.
+ *
+ * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
+ * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
+ * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
+ * element, `streaming_mode` off — one write flips content and mode together.
+ *
+ * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
+ * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ */
+/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+export declare const ANSWER_ELEMENT_ID = "answer";
+/** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
+export declare const CARD_MARKDOWN_MAX_BYTES: number;
+/**
+ * The answer's first line as plain text — what the chat list and the push notification show for the
+ * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
+ * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
+ * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
+ * emphasis/heading/list markers removed.
+ */
+export declare function cardSummary(markdown: string): string;
+/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
+export declare function streamingCardJson(initial: string): string;
+/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
+ *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+export declare function finalCardJson(markdown: string): string;
+/** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
+export declare function cardEntityContent(cardId: string): string;

package/dist/channels/feishu/card.js

@@ -0,0 +1,66 @@
+/**
+ * Card JSON builders — PURE: the streaming-card entity (JSON 2.0) the live preview creates, the settled
+ * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
+ * the card DSL is data-in → string-out and testable without the pump.
+ *
+ * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
+ * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
+ * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
+ * element, `streaming_mode` off — one write flips content and mode together.
+ *
+ * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
+ * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
+ */
+import { truncateCodePointPrefix } from "./text.js";
+/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+export const ANSWER_ELEMENT_ID = "answer";
+/** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
+export const CARD_MARKDOWN_MAX_BYTES = 20 * 1024;
+/** Character budget for the settled card's summary (the chat-list / push-notification preview). */
+const SUMMARY_MAX_CHARS = 60;
+/**
+ * The answer's first line as plain text — what the chat list and the push notification show for the
+ * settled card (`config.summary.content`). Without it a card message previews as a generic "[Card]"
+ * placeholder: the user's notification would never carry the actual answer. Markdown is stripped
+ * lightly (this is a one-line teaser, not a renderer): fenced code dropped, links/images → their text,
+ * emphasis/heading/list markers removed.
+ */
+export function cardSummary(markdown) {
+    const line = markdown
+        .replace(/```[\s\S]*?(```|$)/g, " ") // fenced code is never a readable one-line preview
+        .split("\n")
+        .map((l) => l
+        .replace(/^\s{0,3}(?:#{1,6}|>|[-*+]|\d+[.)])\s+/, "") // heading / quote / list markers
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images → alt text
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links → link text
+        .replace(/[*_~`]/g, "")
+        .trim())
+        .find((l) => l !== "") ?? "";
+    return truncateCodePointPrefix(line, SUMMARY_MAX_CHARS);
+}
+function cardJson(markdown, streaming, summary) {
+    return JSON.stringify({
+        schema: "2.0",
+        config: {
+            streaming_mode: streaming,
+            update_multi: true,
+            // Only the settled card sets a summary — while streaming, the platform's default (a localized
+            // "[Generating…]") is better than any fixed text we could pin.
+            ...(summary ? { summary: { content: summary } } : {}),
+        },
+        body: { elements: [{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }] },
+    });
+}
+/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
+export function streamingCardJson(initial) {
+    return cardJson(initial, true);
+}
+/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
+ *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+export function finalCardJson(markdown) {
+    return cardJson(markdown, false, cardSummary(markdown));
+}
+/** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
+export function cardEntityContent(cardId) {
+    return JSON.stringify({ type: "card", data: { card_id: cardId } });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Feishu is the canonical implementation. Lark international speaks the same protocol but trails the
+ * primary cloud in control-plane capabilities, so it binds the Feishu engine through this explicit
+ * compatibility profile instead of becoming the engine's naming/design center.
+ */
+export type FeishuCloudKind = "feishu" | "lark";
+export interface FeishuCloudProfile {
+    kind: FeishuCloudKind;
+    envPrefix: "FEISHU" | "LARK";
+    apiBase: string;
+    capabilities: {
+        appCreation: "scan-to-create" | "guided-console";
+    };
+}
+export declare const FEISHU_CLOUD: FeishuCloudProfile;
+export declare const LARK_COMPAT_CLOUD: FeishuCloudProfile;
+export declare function cloudFor(kind: FeishuCloudKind): FeishuCloudProfile;

package/dist/channels/feishu/cloud.js

@@ -0,0 +1,19 @@
+export const FEISHU_CLOUD = {
+    kind: "feishu",
+    envPrefix: "FEISHU",
+    apiBase: "https://open.feishu.cn",
+    capabilities: {
+        appCreation: "scan-to-create",
+    },
+};
+export const LARK_COMPAT_CLOUD = {
+    kind: "lark",
+    envPrefix: "LARK",
+    apiBase: "https://open.larksuite.com",
+    capabilities: {
+        appCreation: "guided-console",
+    },
+};
+export function cloudFor(kind) {
+    return kind === "feishu" ? FEISHU_CLOUD : LARK_COMPAT_CLOUD;
+}

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

@@ -0,0 +1,13 @@
+/** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
+export declare function timingSafeEqualStr(a: string, b: string): boolean;
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
+ *  or a wrong key (bad padding) — the caller turns that into a 4xx, never a silent drop. */
+export declare function decryptEvent(encryptKey: string, encryptB64: string): string;
+/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+export declare function eventSignature(encryptKey: string, timestamp: string, nonce: string, rawBody: string): string;
+/** Whether a request's signature headers verify against the raw body (constant-time). */
+export declare function verifySignature(encryptKey: string, headers: {
+    timestamp: string;
+    nonce: string;
+    signature: string;
+}, rawBody: string): boolean;

package/dist/channels/feishu/crypto.js

@@ -0,0 +1,41 @@
+/**
+ * Canonical Feishu webhook security (reused by Lark compatibility) — PURE: AES event decryption and request
+ * signature, exactly as the open platform defines them. When an Encrypt Key is configured in the
+ * developer console, every event arrives as `{"encrypt": "<base64>"}` with signature headers; without
+ * one, events arrive in plaintext and carry only the verification token in the body. feishu.ts owns the
+ * fail-closed policy (which checks run when); this module owns the math.
+ *
+ *  - Decryption: AES-256-CBC. The key is sha256(encryptKey); the base64 payload is IV (16 bytes) ‖
+ *    ciphertext; the plaintext is the event JSON (PKCS#7 padding handled by the cipher).
+ *  - Signature: `X-Lark-Signature = sha256(timestamp + nonce + encryptKey + rawBody)` hex, where
+ *    rawBody is the VERBATIM request body (the encrypted form) — computed over bytes, so the caller
+ *    must pass the raw text, never a re-serialization.
+ *
+ * Comparisons are constant-time (timingSafeEqual) so neither the signature check nor the verification-
+ * token check leaks a timing signal.
+ */
+import { createDecipheriv, createHash, timingSafeEqual } from "node:crypto";
+/** Constant-time string equality (padded to equal length first — timingSafeEqual demands it). */
+export function timingSafeEqualStr(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+/** Decrypt an `{"encrypt": …}` event payload to its plaintext JSON string. Throws on malformed input
+ *  or a wrong key (bad padding) — the caller turns that into a 4xx, never a silent drop. */
+export function decryptEvent(encryptKey, encryptB64) {
+    const key = createHash("sha256").update(encryptKey, "utf8").digest();
+    const buf = Buffer.from(encryptB64, "base64");
+    if (buf.length <= 16)
+        throw new Error("encrypted event payload is too short to carry an IV + ciphertext");
+    const decipher = createDecipheriv("aes-256-cbc", key, buf.subarray(0, 16));
+    return Buffer.concat([decipher.update(buf.subarray(16)), decipher.final()]).toString("utf8");
+}
+/** The expected `X-Lark-Signature` for a request: sha256(timestamp + nonce + encryptKey + rawBody) hex. */
+export function eventSignature(encryptKey, timestamp, nonce, rawBody) {
+    return createHash("sha256").update(`${timestamp}${nonce}${encryptKey}${rawBody}`, "utf8").digest("hex");
+}
+/** Whether a request's signature headers verify against the raw body (constant-time). */
+export function verifySignature(encryptKey, headers, rawBody) {
+    return timingSafeEqualStr(eventSignature(encryptKey, headers.timestamp, headers.nonce, rawBody), headers.signature);
+}

package/dist/channels/feishu/feishu-api.d.ts

@@ -0,0 +1,108 @@
+import type { ImageRef } from "../../agent.ts";
+import type { FeishuCloudKind } from "./cloud.ts";
+/** Where a reply goes: a chat, optionally quote-replying a message (in-thread in topic groups). */
+export interface FeishuTarget {
+    chatId: string;
+    /** Message to reply to (the summoning message). Set in groups so the answer threads under the asker. */
+    replyTo?: string;
+    /** Reply into the message's topic thread (topic groups). */
+    replyInThread?: boolean;
+}
+/** A downloaded inbound file: an absolute local path the agent's tools (read/bash) can open. */
+export interface DownloadedFile {
+    path: string;
+    name: string;
+    size: number;
+}
+/** Whether an error is the platform's "card streaming closed/timed out" reject — preview.ts re-enables
+ *  streaming once when it sees this. A plain code check on the typed error, exported instead of the
+ *  class so no caller can construct/throw one. */
+export declare function isCardStreamingClosed(e: unknown): boolean;
+/** Whether the platform origin has no application-config route at all. Onboarding uses this narrow
+ * signal to fall back to a manual token/mode setup; auth/scope/network failures must remain visible. */
+export declare function isFeishuConfigApiMissing(e: unknown): boolean;
+/** Whether a registration-PATCH failure is transient weather worth retrying: network/DNS/timeouts, or
+ *  the platform's 210042 "request_url validation failed" while its own path to a fresh tunnel edge
+ *  warms up. Everything else (scope, auth, app under review, the config-route 404 above) is definitive
+ *  — the registrars and the token bootstrap share this one classifier. */
+export declare function isTransientFeishuRegistrationError(e: unknown): boolean;
+export interface FeishuApiOptions {
+    /** Branded diagnostics; defaults to the canonical Feishu cloud. */
+    kind?: FeishuCloudKind;
+    /** API origin: `https://open.feishu.cn` (Feishu) or `https://open.larksuite.com` (Lark intl). */
+    baseUrl: string;
+    appId: string;
+    appSecret: string;
+}
+/**
+ * The Feishu Open API client: one instance per channel, holding the token cache. Every method rides the
+ * single pipeline (module header). Throws {@link FeishuApiError} on any failure.
+ */
+export interface FeishuApi {
+    /** Validate appId/appSecret by acquiring the tenant token through this pipeline. Does not require
+     *  the bot capability (unlike botInfo), so guided onboarding can fail before persisting a typo. */
+    verifyCredentials(): Promise<void>;
+    /** GET /bot/v3/info — the bot's own identity (open_id drives @mention summon). */
+    botInfo(): Promise<{
+        openId?: string;
+        appName?: string;
+    }>;
+    /** Send a message to a chat; returns the new message_id (undefined if the body carried none). */
+    sendMessage(chatId: string, msgType: string, content: string): Promise<string | undefined>;
+    /** Reply to a message (quote; `replyInThread` stays inside a topic group's thread). */
+    replyMessage(messageId: string, msgType: string, content: string, opts?: {
+        replyInThread?: boolean;
+    }): Promise<string | undefined>;
+    /** Send `text`, split at the platform's size cap: ordinary groups quote only the first chunk; topic
+     *  groups reply_in_thread on every chunk. Returns the FIRST message_id. */
+    sendText(target: FeishuTarget, text: string): Promise<string | undefined>;
+    /** Edit a sent text message in place (PUT; the platform caps edits at 20 per message). */
+    editTextMessage(messageId: string, text: string): Promise<void>;
+    /** Recall (delete) a message the bot sent. */
+    deleteMessage(messageId: string): Promise<void>;
+    /** Fetch one message (the reply-referent path). Undefined when the API returns no item. */
+    getMessage(messageId: string): Promise<{
+        message_id?: string;
+        msg_type?: string;
+        body?: {
+            content?: string;
+        };
+        mentions?: unknown[];
+        sender?: unknown;
+    } | undefined>;
+    /** Download a message resource (image/file bytes). Caps at {@link MAX_DOWNLOAD_BYTES}. */
+    downloadResource(messageId: string, fileKey: string, type: "image" | "file"): Promise<{
+        bytes: Buffer;
+        contentType?: string;
+    }>;
+    /** Download an image resource as a vision ImageRef. */
+    fetchImage(messageId: string, fileKey: string): Promise<ImageRef>;
+    /** Download a file resource to `<filesDir>/<chat>/<name>`. */
+    fetchFile(messageId: string, fileKey: string, name: string, chatId: string, filesDir: string): Promise<DownloadedFile>;
+    /** Read the app's own event-security config (the platform-generated verification token / encrypt
+     *  key) — the scan-to-create flow copies these into .env so the operator never opens the console. */
+    getAppConfig(appId: string): Promise<{
+        verificationToken?: string;
+        encryptionKey?: string;
+    }>;
+    /** Update the app's own event subscription (application-v7 config PATCH — tenant token can only
+     *  operate on itself; the request-URL change takes effect immediately, no version publish). The
+     *  platform VERIFIES `requestUrl` with a url_verification challenge during this call, so the server
+     *  behind it must already be answering. */
+    updateEventSubscription(appId: string, cfg: {
+        subscriptionType: "webhook";
+        requestUrl: string;
+    }): Promise<void>;
+    /** Create a card entity (card JSON 2.0). Returns its card_id. */
+    createCard(cardJson: string): Promise<string>;
+    /** Stream-update a card element's text (full-content snapshot + strictly increasing sequence). */
+    updateCardElement(cardId: string, elementId: string, content: string, sequence: number): Promise<void>;
+    /** Replace a card entity's content (the settle write; also flips streaming_mode off via the JSON). */
+    updateCard(cardId: string, cardJson: string, sequence: number): Promise<void>;
+}
+/** The platform caps a text-message request body at 150 KB; stay well under it (the content is a JSON
+ *  envelope around the text, and multi-byte characters inflate the byte count). */
+export declare const FEISHU_MAX_TEXT_BYTES: number;
+/** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
+export declare function chunkFeishuText(text: string, maxBytes?: number): string[];
+export declare function createFeishuApi(opts: FeishuApiOptions): FeishuApi;