@fastagent-sh/fastagent 0.12.0 → 0.13.0

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

@@ -0,0 +1,141 @@
+/**
+ * One-click app creation ("scan to create") — the OAuth 2.0 Device Authorization Grant (RFC 8628)
+ * flow the platform provides for agent apps: `begin` returns a one-time verification URL the user
+ * opens in Feishu/Lark and confirms (the platform pre-configures the agent app template: bot
+ * capability, messaging scopes, event subscriptions); polling returns the new app's credentials.
+ *
+ * Hand-rolled on fetch, no SDK: the wire protocol is two form-encoded POSTs to the accounts endpoint
+ * plus RFC 8628's polling error dance — shared verbatim by all four official SDKs (node/python/java/go),
+ * which makes it a de-facto stable surface even though only the SDKs document it. Provenance:
+ * larksuite/node-sdk `scene/registration` (registerApp). If the platform ever moves this behind
+ * something non-trivial (signed payloads, websockets), adopt the official SDK instead of chasing it —
+ * the same tripwire as feishu-api.ts.
+ *
+ * The scanning user's tenant decides the brand: a Lark-tenant user flips polling to the Lark accounts
+ * domain mid-flow (`tenant_brand: "lark"`), and the result carries the brand so the caller can point
+ * everything else (API origin) at the right cloud.
+ */
+import { gzipSync } from "node:zlib";
+/** Feishu accounts endpoint (the flow starts here for every user; a Lark-tenant scan switches over). */
+const FEISHU_ACCOUNTS = "https://accounts.feishu.cn";
+const LARK_ACCOUNTS = "https://accounts.larksuite.com";
+const ENDPOINT = "/oauth/v1/app/registration";
+/** Per-attempt timeout for one registration POST — small form/JSON round-trips. */
+const REQUEST_TIMEOUT_MS = 30_000;
+/** JSON → gzip → base64url — the platform's fixed addons encoding. */
+function encodeAddons(addons) {
+    return gzipSync(Buffer.from(JSON.stringify(addons), "utf8"))
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** RFC 8628 device-flow states whose non-2xx JSON bodies belong to the polling state machine. */
+const DEVICE_FLOW_ERRORS = new Set(["authorization_pending", "slow_down", "access_denied", "expired_token"]);
+/** One registration POST (form-encoded). RFC 8628 delivers polling states (authorization_pending,
+ *  slow_down, …) as HTTP 400 with a JSON body — those parse as data, not as transport failures. */
+async function post(baseUrl, params) {
+    let res;
+    let raw;
+    try {
+        res = await fetch(`${baseUrl}${ENDPOINT}`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams(params).toString(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        raw = await res.text();
+    }
+    catch (e) {
+        throw new Error(`feishu app registration: ${String(e)}`, { cause: e });
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`feishu app registration failed: ${res.status} — response was not the expected JSON`);
+    }
+    if (!res.ok && !(data.error && DEVICE_FLOW_ERRORS.has(data.error))) {
+        const diagnostic = data.error
+            ? `${data.error}${data.error_description ? ` — ${data.error_description}` : ""}`
+            : raw.trim().slice(0, 500) || "empty response";
+        throw new Error(`feishu app registration failed: HTTP ${res.status} — ${diagnostic}`);
+    }
+    return data;
+}
+/** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers. */
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Run the scan-to-create flow (module header): begin → hand the verification URL to the caller →
+ * poll until the user confirms. Resolves with the new app's credentials; rejects on denial, expiry,
+ * abort, or a transport failure — every rejection is a plain Error whose message says what to do.
+ */
+export async function registerFeishuApp(options) {
+    const feishuBase = options.accountsBaseUrl ?? FEISHU_ACCOUNTS;
+    const larkBase = options.larkAccountsBaseUrl ?? LARK_ACCOUNTS;
+    const begin = await post(feishuBase, {
+        action: "begin",
+        archetype: "PersonalAgent", // the platform's agent-app template: bot + messaging scopes + events pre-configured
+        auth_method: "client_secret",
+        request_user_info: "open_id",
+    });
+    if (!begin.device_code || !begin.verification_uri_complete) {
+        throw new Error(`feishu app registration: begin returned no device code (${begin.error ?? "unexpected response"}${begin.error_description ? `: ${begin.error_description}` : ""})`);
+    }
+    const url = new URL(begin.verification_uri_complete);
+    url.searchParams.set("from", "sdk");
+    url.searchParams.set("tp", "sdk");
+    url.searchParams.set("source", "fastagent");
+    if (options.name !== undefined)
+        url.searchParams.set("name", options.name);
+    if (options.desc !== undefined)
+        url.searchParams.set("desc", options.desc);
+    if (options.addons !== undefined)
+        url.searchParams.set("addons", encodeAddons(options.addons));
+    const expiresInS = begin.expires_in ?? 600;
+    options.onVerificationUrl({ url: url.toString(), expiresInS });
+    let pollBase = feishuBase;
+    let switched = false;
+    let intervalMs = (begin.interval ?? 5) * 1000;
+    const deadline = Date.now() + expiresInS * 1000;
+    for (;;) {
+        if (options.signal?.aborted)
+            throw new Error("feishu app registration was aborted");
+        if (Date.now() >= deadline) {
+            throw new Error("feishu app registration: the verification link expired before anyone confirmed — re-run to get a fresh one");
+        }
+        const poll = await post(pollBase, { action: "poll", device_code: begin.device_code });
+        // A Lark-tenant user: the flow continues on the Lark accounts domain (once), same device code.
+        if (poll.user_info?.tenant_brand === "lark" && !switched) {
+            switched = true;
+            pollBase = larkBase;
+            continue;
+        }
+        if (poll.client_id && poll.client_secret) {
+            return {
+                appId: poll.client_id,
+                appSecret: poll.client_secret,
+                tenantBrand: poll.user_info?.tenant_brand,
+                openId: poll.user_info?.open_id,
+            };
+        }
+        switch (poll.error) {
+            case "authorization_pending":
+                break; // the user has not confirmed yet — keep polling
+            case "slow_down":
+                intervalMs += 5000; // RFC 8628: back off and keep polling
+                break;
+            case "access_denied":
+                throw new Error("feishu app registration: the user declined the authorization");
+            case "expired_token":
+                throw new Error("feishu app registration: the verification link expired — re-run to get a fresh one");
+            default:
+                if (poll.error) {
+                    throw new Error(`feishu app registration failed: ${poll.error}${poll.error_description ? ` — ${poll.error_description}` : ""}`);
+                }
+                break; // no error, no credentials — treat as pending
+        }
+        await wait(intervalMs);
+    }
+}

package/dist/channels/feishu/register-webhook.d.ts

@@ -0,0 +1,22 @@
+import type { RegistrationOutcome } from "../registration.ts";
+import { type FeishuCloudKind } from "./cloud.ts";
+/**
+ * Register `<baseUrl>/<kind>` as the app's event Request URL (webhook mode). Missing credentials print
+ * the manual instruction instead of failing. `opts` exist for tests: timeouts + `apiBase` (a fake
+ * platform — production derives it from the kind).
+ *
+ * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
+ */
+export interface FeishuManualRegistration {
+    consoleUrl: string;
+    requestUrl: string;
+}
+export interface RegisterFeishuWebhookOptions {
+    readyTimeoutMs?: number;
+    readyIntervalMs?: number;
+    retryMs?: number;
+    apiBase?: string;
+    /** Manual fallback after a definitive config error or exhausted retries. Local dev opens this App. */
+    onManualRegistration?: (info: FeishuManualRegistration) => void;
+}
+export declare function registerFeishuWebhook(baseUrl: string, kind: FeishuCloudKind, opts?: RegisterFeishuWebhookOptions): Promise<RegistrationOutcome>;

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,34 @@
+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)
+//   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
+  // 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 only on an @mention of this bot (matched by open_id, resolved at
+  // startup). Override to customise, 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 @@
+/**
+ * Accepted-turn dedup: a bounded, persisted ring of message_ids the channel has ACCEPTED. The platform
+ * redelivers events it thinks undelivered AND documents duplicate pushes in "special scenarios", keying
+ * idempotency on message_id (its own guidance: dedup on message_id, not event_id). The turn-store alone
+ * cannot cover the tail: once a completed turn's intent is removed, a late redelivery would re-run it —
+ * this ring is what refuses that. Only ACCEPTED (routed) messages enter: ignored events are side-effect-
+ * free, so recording them would just churn the ring.
+ *
+ * Best-effort durability (post-decision insurance, not the pre-ACK intent): a failed write logs and
+ * moves on — the exposure is a re-run after BOTH a completed turn and a redelivery straddle a crash,
+ * the same at-least-once tail the turn-store documents.
+ */
+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((x) => typeof x === "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 (e) {
+                log.warn(`${label} seen-ring write failed (dedup degrades to the turn-store window): ${String(e)}`);
+            }
+        },
+    };
+}

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>;