@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/channels/feishu/register-webhook.js

@@ -0,0 +1,106 @@
+/**
+ * Feishu/Lark event-URL registration — the platform-domain step both `--tunnel` (dev, tunnel.ts) and
+ * `deploy … --run` (the host runners' post-deploy step) invoke, once per mounted kind. What
+ * "registering feishu/lark" means lives here, beside the engine it serves; it reads the same .env
+ * credentials the channel of that kind uses (`FEISHU_*` / `LARK_*`).
+ *
+ * Mechanism: the application-v7 config PATCH (`updateEventSubscription`) flips the app's event
+ * subscription to webhook mode and points it at `<baseUrl>/<kind>`. Two properties make this the full
+ * telegram-setWebhook parity: the platform applies a request-URL change IMMEDIATELY (no version
+ * publish), and it VERIFIES the URL with a url_verification challenge during the PATCH — which is why
+ * this waits for `<baseUrl>/health` to serve first (the same readiness race the telegram registrar
+ * fixes). Requires the `application:application:patch` scope (field-tested: `self_manage` does NOT
+ * cover this PATCH) — `add feishu` requests it at creation via addons; without it the PATCH fails
+ * visibly and the manual console instruction is printed.
+ *
+ * CLOUD LAG: the application-v7 config API exists on open.feishu.cn but (as of 2026-07) is NOT
+ * deployed on open.larksuite.com — the route 404s there. The registrar still attempts it (the day the
+ * platform ships it, registration starts working with no change here) and names the real cause in the
+ * fallback instead of blaming the app's scopes.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { log } from "../../log.js";
+import { waitForHealth } from "../wait-health.js";
+import { cloudFor } from "./cloud.js";
+import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError } from "./feishu-api.js";
+export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
+    const profile = cloudFor(kind);
+    const envPrefix = profile.envPrefix;
+    const appId = process.env[`${envPrefix}_APP_ID`];
+    const appSecret = process.env[`${envPrefix}_APP_SECRET`];
+    const apiBase = opts.apiBase ?? profile.apiBase;
+    const requestUrl = `${baseUrl}/${kind}`;
+    const manual = `switch Subscription mode to webhook and set the event Request URL in the developer console (Events & Callbacks) to ${requestUrl} — keep the server running while you save (the console verifies the URL with a challenge)`;
+    if (!appId || !appSecret) {
+        log.info(`[fastagent] ${kind}: set ${envPrefix}_APP_ID + ${envPrefix}_APP_SECRET in .env, then re-run to auto-register. Or ${manual}`);
+        return "manual";
+    }
+    // Align registration with the server actually serving: the PATCH triggers the platform's
+    // url_verification challenge against requestUrl — registering before /health serves would fail.
+    log.info(`[fastagent] ${kind}: waiting for ${baseUrl} to be reachable before registering the event URL…`);
+    const ready = await waitForHealth(`${baseUrl}/health`, opts.readyTimeoutMs ?? 120_000, opts.readyIntervalMs ?? 3_000);
+    if (!ready) {
+        // Terminal for this run (registration will not be retried) — error, not warn: the event URL is NOT
+        // registered and the operator must act. Same taxonomy as the permanent PATCH failure below.
+        log.error(`[fastagent] ${kind}: ${baseUrl}/health did not come up in time — the app may still be starting. ${manual}`);
+        return "failed";
+    }
+    const api = createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret });
+    const consoleUrl = `${apiBase}/app/${encodeURIComponent(appId)}/event`;
+    const versionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/version`;
+    const manualRegistration = () => {
+        log.info(`[fastagent] ${kind}: Events & Callbacks:\n  ${consoleUrl}`);
+        log.info(`[fastagent] ${kind}: switch Subscription mode to webhook and copy this Request URL:\n  ${requestUrl}\n` +
+            `  Keep fastagent running while saving — the console verifies the URL immediately.`);
+        log.info(`[fastagent] ${kind}: if this app's webhook mode has not been published yet, ` +
+            `create + publish a version before testing messages:\n  ${versionUrl}`);
+        try {
+            opts.onManualRegistration?.({ consoleUrl, requestUrl });
+        }
+        catch (callbackError) {
+            log.warn(`[fastagent] ${kind}: could not open Events & Callbacks: ${String(callbackError)}`);
+        }
+    };
+    // Reachable → register. The PATCH is the real probe (same lesson as the token bootstrap): the
+    // platform verifies request_url with a challenge DURING the call, and a fresh tunnel's edge can be
+    // reachable from here while the platform's own path still lags — its 210042 "request_url validation
+    // failed" is therefore retried with backoff, alongside transient network errors. Only a permanent
+    // config error (missing scope, app under review, the intl 404) is reported once with the manual path.
+    const attempts = 8;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (attempt > 0)
+            await sleep(opts.retryMs ?? 10_000);
+        try {
+            await api.updateEventSubscription(appId, { subscriptionType: "webhook", requestUrl });
+            log.info(`[fastagent] ${kind}: event Request URL registered → ${requestUrl}`);
+            // Field-tested: a URL change applies immediately, but the MODE flip (the template's long
+            // connection → webhook) only takes effect when a version is published — the dispatcher serves
+            // the published snapshot, and version publishing has no open API. One console click, once.
+            log.info(`[fastagent] ${kind}: if messages do not arrive, publish a version (one click, prompted) — the switch to webhook mode takes effect on publish: ${versionUrl}`);
+            return "registered";
+        }
+        catch (e) {
+            // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is
+            // live on open.feishu.cn but not yet on open.larksuite.com. Name that — "check your scopes"
+            // would send the operator hunting for a problem they cannot fix.
+            if (isFeishuConfigApiMissing(e)) {
+                log.warn(`[fastagent] ${kind}: this cloud (${apiBase}) returned HTTP 404 for the app-config API — ` +
+                    `manual registration is required`);
+                manualRegistration();
+                return "manual"; // that cloud has no config API — the manual path is the norm there
+            }
+            if (!isTransientFeishuRegistrationError(e)) {
+                log.error(`[fastagent] ${kind}: could not register the event URL (${String(e)}). ` +
+                    `The app may lack the "application:application:patch" scope (console → Permissions) or be under review; manual registration is available below.`);
+                manualRegistration();
+                return "failed";
+            }
+        }
+    }
+    // Exhausted retries end in the same state as a permanent error (event URL not registered, manual
+    // action required) — report at the same level. The cloud-lag 404 above stays warn: on that cloud the
+    // manual path is the known norm, not an exceptional failure.
+    log.error(`[fastagent] ${kind}: registration still failing after retries — manual registration is required`);
+    manualRegistration();
+    return "failed";
+}

package/dist/channels/feishu/scaffold/channel.ts

@@ -0,0 +1,41 @@
+import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
+
+// feishuChannel is fastagent's canonical Feishu adapter (verify + run + reply), configured with YOUR
+// policy. fastagent discovers this file, mounts POST /feishu, and pipes the agent + state home to it.
+// Feishu (open.feishu.cn) only; a Lark-international
+// tenant uses `fastagent add lark` instead. Setup (developer console):
+//   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
+//   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
+//      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
+//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
+//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
+//   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
+//      .env; RECOMMENDED: set an Encrypt Key there and mirror it in FEISHU_ENCRYPT_KEY
+//   4. the event Request URL (https://your.host/feishu) is registered AUTOMATICALLY by
+//      `fastagent dev --tunnel` and `fastagent deploy … --run`; to set it by hand in the console,
+//      keep the server running while you save (the platform verifies the URL with a challenge)
+//   5. create a version and publish the app (a Feishu admin approves it), then add the bot to a chat
+// `fastagent add feishu` already did steps 1-3 for you (scan-to-create); this walkthrough is for a
+// hand-made app or for auditing what the scan configured.
+export default feishuChannel({
+  appId: process.env.FEISHU_APP_ID ?? "", // missing → fails at startup (no replies could be sent)
+  appSecret: process.env.FEISHU_APP_SECRET ?? "",
+  verificationToken: process.env.FEISHU_VERIFICATION_TOKEN ?? "", // authenticates inbound events
+  encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
+  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
+  // directMessageSession: "continuous",
+  // groupMessageSession: "continuous",
+  // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+  // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+  // full details always go to the server log regardless.
+  onError: (failed) => `⚠️ ${failed.details}`,
+  // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
+  // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
+  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
+  // threads. Other human group/thread discussion buffers until that place's next answered turn;
+  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // Override to customise explicit routing, reusing the export:
+  //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
+  //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
+});

package/dist/channels/feishu/scaffold/feishu-send.ts

@@ -0,0 +1,87 @@
+import { defineTool, z } from "@fastagent-sh/fastagent";
+
+// Send a message to a Feishu chat. In a CHAT turn the channel delivers the reply itself — this
+// tool is for turns NO channel is carrying: a scheduled turn (schedules/<name>.ts) or a self-scheduled
+// wake-up, whose plain reply is not delivered anywhere. The chatId comes from the [feishu: chat …]
+// context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
+// the target chat id. tools/ is auto-discovered.
+
+// Standalone copy of the channel transport's discipline: a timeout so a wedged connection can't hang
+// the tool call (and the turn), named errors, and success gated on the body's own code===0.
+// Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
+// fail-fast beats a silently sleeping tool.
+const BASE = "https://open.feishu.cn";
+
+async function callApi(path: string, body: unknown, token?: string): Promise<Record<string, unknown>> {
+  let res: Response;
+  let raw: string;
+  try {
+    res = await fetch(`${BASE}${path}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+    raw = await res.text();
+  } catch (e) {
+    throw new Error(`feishu ${path}: ${String(e)}`, { cause: e });
+  }
+  let data: { code?: number; msg?: string; [k: string]: unknown };
+  try {
+    data = JSON.parse(raw) as typeof data;
+  } catch {
+    data = {};
+  }
+  if (!res.ok || data.code !== 0) {
+    throw new Error(`feishu ${path} failed: ${res.status} ${data.msg ?? "response was not the expected JSON"}`);
+  }
+  return data;
+}
+
+async function tenantToken(): Promise<string> {
+  const appId = process.env.FEISHU_APP_ID;
+  const appSecret = process.env.FEISHU_APP_SECRET;
+  if (!appId || !appSecret) throw new Error("FEISHU_APP_ID / FEISHU_APP_SECRET are not set");
+  const data = await callApi("/open-apis/auth/v3/tenant_access_token/internal", {
+    app_id: appId,
+    app_secret: appSecret,
+  });
+  const token = data.tenant_access_token;
+  if (typeof token !== "string") throw new Error("feishu tenant_access_token: response carried no token");
+  return token;
+}
+
+export default defineTool({
+  description:
+    "Send a message to a Feishu chat: plain `text`, or `markdown` (rendered as a card — headings, " +
+    "bold, code blocks, links). Exactly one of the two. In a chat turn take chatId from the " +
+    "[feishu: chat …] context line; in a scheduled/woken turn (no context line) the chat id must come " +
+    "from your instruction.",
+  input: z.object({
+    chatId: z.string().describe("target chat id (oc_…)"),
+    text: z.string().optional().describe("plain text message to send"),
+    markdown: z.string().optional().describe("markdown to send as a card"),
+  }),
+  async execute({ chatId, text, markdown }) {
+    if ((text === undefined) === (markdown === undefined)) {
+      throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
+    }
+    const token = await tenantToken();
+    const msg =
+      text !== undefined
+        ? { msg_type: "text", content: JSON.stringify({ text }) }
+        : {
+            msg_type: "interactive",
+            // An inline static card: one markdown element, no entity/streaming machinery needed here.
+            content: JSON.stringify({
+              schema: "2.0",
+              body: { elements: [{ tag: "markdown", content: markdown }] },
+            }),
+          };
+    await callApi(`/open-apis/im/v1/messages?receive_id_type=chat_id`, { receive_id: chatId, ...msg }, token);
+    return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
+  },
+});

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,47 @@
+/**
+ * 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/channels/feishu/text.d.ts

@@ -0,0 +1,13 @@
+/** Pure Unicode-safe text slicing helpers shared by Feishu/Lark rendering paths. JavaScript string
+ * indexes are UTF-16 code units, so direct `slice()` can tear a surrogate pair and send replacement
+ * characters after JSON/UTF-8 encoding. These helpers only cut at Unicode code-point boundaries. */
+/** Take at most `maxPoints` Unicode code points from the start, without adding a marker. */
+export declare function codePointPrefix(text: string, maxPoints: number): string;
+/** Ellipsize from the right while keeping the result within `maxPoints` Unicode code points. */
+export declare function truncateCodePointPrefix(text: string, maxPoints: number, marker?: string): string;
+/** Ellipsize from the left while keeping the result within `maxPoints` Unicode code points. */
+export declare function truncateCodePointSuffix(text: string, maxPoints: number, marker?: string): string;
+/** Largest code-point-aligned prefix whose UTF-8 encoding fits `maxBytes`. */
+export declare function utf8Prefix(text: string, maxBytes: number): string;
+/** Ellipsize a UTF-8 string without exceeding `maxBytes` or tearing a code point. */
+export declare function truncateUtf8(text: string, maxBytes: number, marker?: string): string;

package/dist/channels/feishu/text.js

@@ -0,0 +1,63 @@
+/** Pure Unicode-safe text slicing helpers shared by Feishu/Lark rendering paths. JavaScript string
+ * indexes are UTF-16 code units, so direct `slice()` can tear a surrogate pair and send replacement
+ * characters after JSON/UTF-8 encoding. These helpers only cut at Unicode code-point boundaries. */
+/** Take at most `maxPoints` Unicode code points from the start, without adding a marker. */
+export function codePointPrefix(text, maxPoints) {
+    if (maxPoints <= 0)
+        return "";
+    const out = [];
+    for (const point of text) {
+        if (out.length >= maxPoints)
+            break;
+        out.push(point);
+    }
+    return out.join("");
+}
+/** Ellipsize from the right while keeping the result within `maxPoints` Unicode code points. */
+export function truncateCodePointPrefix(text, maxPoints, marker = "…") {
+    const points = Array.from(text);
+    if (points.length <= maxPoints)
+        return text;
+    if (maxPoints <= 0)
+        return "";
+    const markerPoints = Array.from(marker);
+    if (markerPoints.length >= maxPoints)
+        return markerPoints.slice(0, maxPoints).join("");
+    return `${points.slice(0, maxPoints - markerPoints.length).join("")}${marker}`;
+}
+/** Ellipsize from the left while keeping the result within `maxPoints` Unicode code points. */
+export function truncateCodePointSuffix(text, maxPoints, marker = "…") {
+    const points = Array.from(text);
+    if (points.length <= maxPoints)
+        return text;
+    if (maxPoints <= 0)
+        return "";
+    const markerPoints = Array.from(marker);
+    if (markerPoints.length >= maxPoints)
+        return markerPoints.slice(0, maxPoints).join("");
+    return `${marker}${points.slice(points.length - (maxPoints - markerPoints.length)).join("")}`;
+}
+/** Largest code-point-aligned prefix whose UTF-8 encoding fits `maxBytes`. */
+export function utf8Prefix(text, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    const out = [];
+    let bytes = 0;
+    for (const point of text) {
+        const pointBytes = Buffer.byteLength(point, "utf8");
+        if (bytes + pointBytes > maxBytes)
+            break;
+        out.push(point);
+        bytes += pointBytes;
+    }
+    return out.join("");
+}
+/** Ellipsize a UTF-8 string without exceeding `maxBytes` or tearing a code point. */
+export function truncateUtf8(text, maxBytes, marker = "…") {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    const markerBytes = Buffer.byteLength(marker, "utf8");
+    if (markerBytes > maxBytes)
+        return utf8Prefix(marker, maxBytes);
+    return `${utf8Prefix(text, maxBytes - markerBytes)}${marker}`;
+}

package/dist/channels/lark/lark.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Lark-international compatibility adapter. Feishu is the canonical protocol/runtime implementation;
+ * this module binds it to Lark's cloud profile and exposes natural Lark-branded public names. Lark's
+ * weaker control-plane capabilities live in onboarding/registration, not in a fork of the turn engine.
+ */
+import type { ChannelModule } from "../../host/node.ts";
+import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute } from "../feishu/feishu.ts";
+export type LarkChannelOptions = FeishuChannelOptions;
+export type LarkFailure = FeishuFailure;
+export type LarkMessage = FeishuMessage;
+export type LarkMessageEvent = FeishuMessageEvent;
+export type LarkRoute = FeishuRoute;
+export declare const defaultLarkRoute: typeof defaultFeishuRoute;
+export declare function larkEnvelope(event: LarkMessageEvent): string;
+export declare function larkChannel(opts: LarkChannelOptions): ChannelModule;

package/dist/channels/lark/lark.js

@@ -0,0 +1,10 @@
+import { LARK_COMPAT_CLOUD } from "../feishu/cloud.js";
+import { buildFeishuChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
+import { cloudEnvelope } from "../feishu/parse.js";
+export const defaultLarkRoute = defaultFeishuRoute;
+export function larkEnvelope(event) {
+    return cloudEnvelope(event, "lark");
+}
+export function larkChannel(opts) {
+    return buildFeishuChannel(LARK_COMPAT_CLOUD, opts, larkChannel.name);
+}

package/dist/channels/lark/onboard.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Guided Lark-international onboarding. The intl cloud cannot complete the BOUND scan-to-create flow,
+ * so a new/partial setup opens its unbound one-click launcher and collects one App-scoped credential
+ * set; a complete existing ID/Secret pair resumes that App directly. Then optimistically run Feishu's
+ * webhook-mode + Verification-Token bootstrap against THIS app: a successful PATCH captures the token
+ * and flips Subscription mode; only a definitive config-route 404 falls back to the token the console
+ * displays + a manual mode switch. IO is injected so the workflow is testable without a terminal or
+ * browser.
+ */
+export declare const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
+/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
+export declare function larkEventSecurityUrl(appId: string): string;
+export interface LarkOnboardIO {
+    openUrl(url: string): void;
+    note(message: string): void;
+    prompt(message: string, opts?: {
+        hidden?: boolean;
+    }): Promise<string | undefined>;
+}
+export interface LarkBootstrapResult {
+    /** Challenge-captured token: the PATCH also switched Subscription mode to webhook. */
+    token?: string;
+    /** Present only for a definitive config-route 404; tells the user why the manual path is active. */
+    manualReason?: string;
+}
+export interface LarkOnboardOptions {
+    /** Existing active .env values. A complete credential pair is reused (and still validated). */
+    existing?: Readonly<Record<string, string | undefined>>;
+    verifyCredentials(appId: string, appSecret: string): Promise<void>;
+    bootstrapWebhook(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
+}
+export interface LarkOnboardCredentials extends Record<string, string> {
+    LARK_APP_ID: string;
+    LARK_APP_SECRET: string;
+    LARK_VERIFICATION_TOKEN: string;
+}
+/** Open the stable app console and collect everything the runtime needs. Cancellation is a visible
+ * failure: the scaffold remains and `add lark` is deliberately re-runnable to resume onboarding. */
+export declare function onboardLarkApp(io: LarkOnboardIO, opts: LarkOnboardOptions): Promise<LarkOnboardCredentials>;

package/dist/channels/lark/onboard.js

@@ -0,0 +1,58 @@
+/**
+ * Guided Lark-international onboarding. The intl cloud cannot complete the BOUND scan-to-create flow,
+ * so a new/partial setup opens its unbound one-click launcher and collects one App-scoped credential
+ * set; a complete existing ID/Secret pair resumes that App directly. Then optimistically run Feishu's
+ * webhook-mode + Verification-Token bootstrap against THIS app: a successful PATCH captures the token
+ * and flips Subscription mode; only a definitive config-route 404 falls back to the token the console
+ * displays + a manual mode switch. IO is injected so the workflow is testable without a terminal or
+ * browser.
+ */
+export const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
+/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
+export function larkEventSecurityUrl(appId) {
+    return `https://open.larksuite.com/app/${encodeURIComponent(appId)}/event?tab=safe`;
+}
+function required(value, name) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        throw new Error(`${name} is required — re-run \`fastagent add lark\` to continue setup`);
+    return trimmed;
+}
+/** Open the stable app console and collect everything the runtime needs. Cancellation is a visible
+ * failure: the scaffold remains and `add lark` is deliberately re-runnable to resume onboarding. */
+export async function onboardLarkApp(io, opts) {
+    const existingId = opts.existing?.LARK_APP_ID?.trim();
+    const existingSecret = opts.existing?.LARK_APP_SECRET?.trim();
+    const reuseExistingApp = Boolean(existingId && existingSecret);
+    // Credentials are one App-scoped set. Reuse only a COMPLETE ID/Secret pair; a partial pair starts a
+    // fresh launcher/input path, and its unrelated old Token must not be attached to the newly-entered App.
+    if (reuseExistingApp) {
+        io.note(`Reusing Lark app ${existingId}; opening its Events & Callbacks configuration directly.`);
+    }
+    else {
+        io.note(`Create the app on Lark's one-click launcher. Opening ${LARK_CONSOLE_URL}`);
+        io.openUrl(LARK_CONSOLE_URL);
+    }
+    const appId = required(reuseExistingApp ? existingId : await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID");
+    const appSecret = required(reuseExistingApp ? existingSecret : await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET");
+    await opts.verifyCredentials(appId, appSecret);
+    const eventSecurityUrl = larkEventSecurityUrl(appId);
+    io.note(`App ID / Secret verified. Opening Events & Callbacks → Security: ${eventSecurityUrl}`);
+    io.openUrl(eventSecurityUrl);
+    io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
+    const bootstrap = await opts.bootstrapWebhook(appId, appSecret);
+    if (bootstrap.token) {
+        io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");
+    }
+    else {
+        io.note(`${bootstrap.manualReason ?? "Automatic bootstrap unavailable."} Open Events & Callbacks → Encryption Strategy and copy the Verification Token. You must also switch Subscription mode to webhook when setting the Request URL.`);
+    }
+    const verificationToken = required(bootstrap.token ||
+        (reuseExistingApp ? opts.existing?.LARK_VERIFICATION_TOKEN?.trim() : undefined) ||
+        (await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN");
+    return {
+        LARK_APP_ID: appId,
+        LARK_APP_SECRET: appSecret,
+        LARK_VERIFICATION_TOKEN: verificationToken,
+    };
+}

package/dist/channels/lark/scaffold/channel.ts

@@ -0,0 +1,39 @@
+import { larkChannel } from "@fastagent-sh/fastagent/lark";
+
+// larkChannel is the branded compatibility adapter over fastagent's canonical Feishu engine, configured
+// with YOUR policy. fastagent discovers this file, mounts POST /lark, and pipes the agent + state home
+// to the adapter. Lark international (open.larksuite.com) only; a
+// Feishu tenant uses `fastagent add feishu` instead. Setup (developer console):
+//   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
+//   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
+//      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
+//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
+//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
+//   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
+//      .env; RECOMMENDED: set an Encrypt Key there and mirror it in LARK_ENCRYPT_KEY
+//   4. run `fastagent dev --tunnel`: it attempts to switch Subscription mode to webhook + register
+//      the URL automatically. If this app returns a config-API 404, do both BY HAND in the console
+//      with the server running (the platform verifies https://your.host/lark with a challenge).
+//   5. create a version and publish the app (a tenant admin approves it), then add the bot to a chat
+export default larkChannel({
+  appId: process.env.LARK_APP_ID ?? "", // missing → fails at startup (no replies could be sent)
+  appSecret: process.env.LARK_APP_SECRET ?? "",
+  verificationToken: process.env.LARK_VERIFICATION_TOKEN ?? "", // authenticates inbound events
+  encryptKey: process.env.LARK_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
+  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
+  // directMessageSession: "continuous",
+  // groupMessageSession: "continuous",
+  // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+  // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+  // full details always go to the server log regardless.
+  onError: (failed) => `⚠️ ${failed.details}`,
+  // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
+  // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultLarkRoute:
+  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
+  // threads. Other human group/thread discussion buffers until that place's next answered turn;
+  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // Override to customise explicit routing, reusing the export:
+  //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
+  //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
+});

package/dist/channels/lark/scaffold/lark-send.ts

@@ -0,0 +1,87 @@
+import { defineTool, z } from "@fastagent-sh/fastagent";
+
+// Send a message to a Lark chat. In a CHAT turn the channel delivers the reply itself — this
+// tool is for turns NO channel is carrying: a scheduled turn (schedules/<name>.ts) or a self-scheduled
+// wake-up, whose plain reply is not delivered anywhere. The chatId comes from the [lark: chat …]
+// context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
+// the target chat id. tools/ is auto-discovered.
+
+// Standalone copy of the channel transport's discipline: a timeout so a wedged connection can't hang
+// the tool call (and the turn), named errors, and success gated on the body's own code===0.
+// Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
+// fail-fast beats a silently sleeping tool.
+const BASE = "https://open.larksuite.com";
+
+async function callApi(path: string, body: unknown, token?: string): Promise<Record<string, unknown>> {
+  let res: Response;
+  let raw: string;
+  try {
+    res = await fetch(`${BASE}${path}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+    raw = await res.text();
+  } catch (e) {
+    throw new Error(`lark ${path}: ${String(e)}`, { cause: e });
+  }
+  let data: { code?: number; msg?: string; [k: string]: unknown };
+  try {
+    data = JSON.parse(raw) as typeof data;
+  } catch {
+    data = {};
+  }
+  if (!res.ok || data.code !== 0) {
+    throw new Error(`lark ${path} failed: ${res.status} ${data.msg ?? "response was not the expected JSON"}`);
+  }
+  return data;
+}
+
+async function tenantToken(): Promise<string> {
+  const appId = process.env.LARK_APP_ID;
+  const appSecret = process.env.LARK_APP_SECRET;
+  if (!appId || !appSecret) throw new Error("LARK_APP_ID / LARK_APP_SECRET are not set");
+  const data = await callApi("/open-apis/auth/v3/tenant_access_token/internal", {
+    app_id: appId,
+    app_secret: appSecret,
+  });
+  const token = data.tenant_access_token;
+  if (typeof token !== "string") throw new Error("lark tenant_access_token: response carried no token");
+  return token;
+}
+
+export default defineTool({
+  description:
+    "Send a message to a Lark chat: plain `text`, or `markdown` (rendered as a card — headings, " +
+    "bold, code blocks, links). Exactly one of the two. In a chat turn take chatId from the " +
+    "[lark: chat …] context line; in a scheduled/woken turn (no context line) the chat id must come " +
+    "from your instruction.",
+  input: z.object({
+    chatId: z.string().describe("target chat id (oc_…)"),
+    text: z.string().optional().describe("plain text message to send"),
+    markdown: z.string().optional().describe("markdown to send as a card"),
+  }),
+  async execute({ chatId, text, markdown }) {
+    if ((text === undefined) === (markdown === undefined)) {
+      throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
+    }
+    const token = await tenantToken();
+    const msg =
+      text !== undefined
+        ? { msg_type: "text", content: JSON.stringify({ text }) }
+        : {
+            msg_type: "interactive",
+            // An inline static card: one markdown element, no entity/streaming machinery needed here.
+            content: JSON.stringify({
+              schema: "2.0",
+              body: { elements: [{ tag: "markdown", content: markdown }] },
+            }),
+          };
+    await callApi(`/open-apis/im/v1/messages?receive_id_type=chat_id`, { receive_id: chatId, ...msg }, token);
+    return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
+  },
+});

package/dist/channels/registration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SHARED: the webhook registrars' outcome. A registrar reports its own FACT; what to do about it (gate
+ * the deploy or not, and with what remediation) is the CALLER's policy — `deploy --run` gates on
+ * "failed", the tunnel (a long-running dev process) ignores the result entirely.
+ *
+ * - "registered": the platform accepted the webhook / event URL.
+ * - "manual": this run did not fail, but an operator-facing step remains (the registrar printed the
+ *   instructions). Two sub-states differ on re-runnability: credentials not configured (re-run after
+ *   setting .env DOES auto-register; on the deploy path this is pre-gated by missingSecrets and
+ *   unreachable) and a cloud without the config API (the Lark cloud-lag 404 — no re-run can ever
+ *   register it; the console is the only path).
+ * - "failed": this run ends with the webhook NOT registered, and acting + re-running can fix it
+ *   (health timeout, a permanent config error, exhausted retries).
+ */
+export type RegistrationOutcome = "registered" | "manual" | "failed";

package/dist/channels/registration.js

@@ -0,0 +1 @@
+export {};