@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/channels/control.js

@@ -0,0 +1,214 @@
+import { INVALID_COMMAND_CODE } from "../session.js";
+import { timingSafeEqual } from "node:crypto";
+import { readBodyCapped } from "./body.js";
+import { MAX_BODY_BYTES, createInvokeHandler, sseHeartbeat } from "./http.js";
+import { text } from "./respond.js";
+const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
+// ONE constant for every Prompt-bearing wire surface (imported from the invoke channel — the two
+// caps cannot drift apart): commands carry Prompts, which may ride base64 images.
+const DISPATCH_BODY_LIMIT = MAX_BODY_BYTES;
+/**
+ * Parse-don't-validate at the wire: a remote client can send any JSON, and the hub's inner layers
+ * trust command shapes (a malformed `steer` would surface as an ENGINE failure misclassified as
+ * `run_command_failed`). Returns the typed command, or undefined for anything malformed — which
+ * answers protocol-level `invalid_command`, same responsibility as the hub's unknown-type default.
+ */
+function parseWireCommand(raw) {
+    // COMPILE-TIME drift guard, variant level: this switch hand-mirrors the SessionCommand union,
+    // and a new variant added in session.ts would otherwise compile clean while the wire answers it
+    // `invalid_command` — silently breaking local/remote isomorphism. A new variant must break THIS
+    // line first, forcing the decision of how the wire carries it.
+    const _commandDriftGuard = {
+        steer: true,
+        follow_up: true,
+        abort: true,
+        compact: true,
+        set_model: true,
+        set_thinking: true,
+    };
+    void _commandDriftGuard;
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const c = raw;
+    const imageOk = (i) => typeof i === "object" &&
+        i !== null &&
+        typeof i.data === "string" &&
+        typeof i.mimeType === "string";
+    const promptOk = (p) => {
+        if (typeof p !== "object" || p === null)
+            return false;
+        if (typeof p.text !== "string")
+            return false;
+        const images = p.images;
+        // Element-level: `images: [42]` reaching the engine would resurface exactly the misclassified
+        // failure this parser exists to prevent (ImageRef shape from src/session.ts's Prompt).
+        return images === undefined || (Array.isArray(images) && images.every(imageOk));
+    };
+    // REBUILD, never pass raw through: "typed command out" must be construction, not assertion — a
+    // passed-through object would carry arbitrary extra keys into the engine.
+    const rebuildPrompt = (p) => {
+        const images = p.images;
+        return {
+            text: p.text,
+            ...(images ? { images: images.map((i) => ({ data: i.data, mimeType: i.mimeType })) } : {}),
+        };
+    };
+    // COMPILE-TIME drift guard: whitelist reconstruction silently strips any field it does not know.
+    // A new Prompt field must break THIS line (non-empty Exclude → {} unassignable), not vanish on
+    // the wire while the client believes it was sent.
+    const _promptDriftGuard = {};
+    void _promptDriftGuard;
+    // Same guard one level down: the image whitelist ({data, mimeType}) must break when ImageRef
+    // grows a field — top-level coverage alone would let element fields vanish silently.
+    const _imageDriftGuard = {};
+    void _imageDriftGuard;
+    switch (c.type) {
+        case "steer":
+        case "follow_up":
+            return promptOk(c.prompt) ? { type: c.type, prompt: rebuildPrompt(c.prompt) } : undefined;
+        case "abort":
+            return { type: "abort" };
+        case "compact":
+            return c.instructions === undefined || typeof c.instructions === "string"
+                ? { type: "compact", instructions: c.instructions }
+                : undefined;
+        case "set_model":
+            return typeof c.model === "string" ? { type: "set_model", model: c.model } : undefined;
+        case "set_thinking":
+            return typeof c.level === "string" ? { type: "set_thinking", level: c.level } : undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ */
+export function controlRoutes(control, options) {
+    const { token } = options;
+    if (!token)
+        throw new Error("controlRoutes: a bearer token is required (empty tokens are not a mode)");
+    const epoch = crypto.randomUUID();
+    // Timing-safe: the bearer token is this surface's ONLY auth (and the --tunnel warning names it
+    // as the sole protection on a public URL) — a plain === would leak byte-by-byte via timing.
+    const expected = Buffer.from(`Bearer ${token}`);
+    const authed = (req) => {
+        const header = Buffer.from(req.headers.get("authorization") ?? "");
+        return header.length === expected.length && timingSafeEqual(header, expected);
+    };
+    const invokeHandler = options.agent ? createInvokeHandler(options.agent) : undefined;
+    /** Wrap a handler with auth + the session query param most routes need. */
+    const guard = (handler) => (req) => {
+        if (!authed(req))
+            return text("unauthorized\n", 401);
+        return handler(req, new URL(req.url));
+    };
+    // Extraction only — each route still answers its own 400 (the name must not imply enforcement).
+    const sessionParam = (url) => url.searchParams.get("session") ?? undefined;
+    return {
+        ...(invokeHandler ? { "POST /control/invoke": guard((req) => invokeHandler(req)) } : {}),
+        "GET /control/capabilities": guard(() => json(control.capabilities())),
+        "GET /control/state": guard(async (_req, url) => {
+            const session = sessionParam(url);
+            if (!session)
+                return text("missing ?session\n", 400);
+            return json(await control.state(session));
+        }),
+        "GET /control/entries": guard(async (_req, url) => {
+            const session = sessionParam(url);
+            if (!session)
+                return text("missing ?session\n", 400);
+            const since = url.searchParams.get("since") ?? undefined;
+            return json(await control.entries(session, since !== undefined ? { since } : undefined));
+        }),
+        "POST /control/dispatch": guard(async (req) => {
+            const body = await readBodyCapped(req, DISPATCH_BODY_LIMIT);
+            // The 413 names the ceiling: the docs promise images on this plane, and an unexplained
+            // rejection would send a client author hunting everywhere but the cap.
+            if ("tooLarge" in body) {
+                // Derived from the constant — a hardcoded "1 MiB" would lie the day the cap changes.
+                return text(`body too large (limit ${MAX_BODY_BYTES >> 20} MiB — images count base64-inflated)\n`, 413);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(body.text);
+            }
+            catch {
+                return text("invalid JSON\n", 400);
+            }
+            if (typeof parsed.session !== "string") {
+                return text("expected { session: string, command: SessionCommand }\n", 400);
+            }
+            const command = parseWireCommand(parsed.command);
+            if (!command) {
+                // Malformed shape = a protocol-level answer, mirrored from the hub's unknown-type default.
+                return json({
+                    ok: false,
+                    error: { code: INVALID_COMMAND_CODE, message: "malformed command", retryable: false },
+                });
+            }
+            // The result rides HTTP 200 either way: `ok: false` is a protocol-level answer (rejected
+            // before acceptance), not a transport failure.
+            return json(await control.dispatch(parsed.session, command));
+        }),
+        "GET /control/events": guard((_req, url) => {
+            const session = sessionParam(url);
+            if (!session)
+                return text("missing ?session\n", 400);
+            const iterator = control.events(session)[Symbol.asyncIterator]();
+            // EAGER registration: issue the first pull NOW, before the Response (and thus the client's
+            // fetch resolution) exists — hub subscription is registered synchronously inside next(), so
+            // "the client saw response headers" implies "events from that moment on will be delivered".
+            // Shrinks the subscribe/backfill race to network reordering instead of a full pull cycle.
+            let pending = iterator.next();
+            // Observed here so a client that disconnects BEFORE the first pull cannot turn a rejecting
+            // events iterator (this is the neutral contract face — any implementation may reject) into a
+            // process-killing unhandledRejection; awaiting `pending` at pull still surfaces the error.
+            pending.catch(() => { });
+            let seq = 0;
+            let stopHeartbeat = () => { };
+            const encoder = new TextEncoder();
+            const stream = new ReadableStream({
+                start(controller) {
+                    stopHeartbeat = sseHeartbeat(controller);
+                },
+                async pull(controller) {
+                    let next;
+                    try {
+                        next = await (pending ?? iterator.next());
+                    }
+                    catch (error) {
+                        // A rejecting implementation (the neutral contract permits it) must not leak its
+                        // subscription: an errored stream never gets cancel(), so the unsubscribe and the
+                        // heartbeat teardown happen HERE.
+                        stopHeartbeat();
+                        void iterator.return?.(undefined)?.catch?.(() => { });
+                        controller.error(error);
+                        return;
+                    }
+                    pending = undefined;
+                    if (next.done) {
+                        stopHeartbeat();
+                        controller.close();
+                        return;
+                    }
+                    const wire = { sessionId: session, epoch, seq: seq++, event: next.value };
+                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(wire)}\n\n`));
+                },
+                cancel() {
+                    stopHeartbeat();
+                    // Same neutral-contract defense as the pull error path: a rejecting return() on client
+                    // disconnect must not become a process-level unhandledRejection.
+                    void iterator.return?.(undefined)?.catch?.(() => { });
+                },
+            });
+            return new Response(stream, {
+                headers: {
+                    "content-type": "text/event-stream",
+                    "cache-control": "no-cache",
+                    connection: "keep-alive",
+                },
+            });
+        }),
+    };
+}

package/dist/channels/feishu/card.js

@@ -11,7 +11,7 @@
  * 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";
+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). */

package/dist/channels/feishu/context-buffer.d.ts

@@ -1,3 +1,4 @@
+import { type ContextBuffer } from "../context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {
     messageId: string;
@@ -16,8 +17,19 @@ export interface FeishuBufferEntry {
 export interface FeishuBufferedRef extends FeishuBufferedResource {
     from: string;
 }
-/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
-export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "rootId" | "threadId">): string;
+/**
+ * The place a message belongs to: the main chat, or a thread within it. Keyed by `thread_id`, the
+ * platform's own identity for a side conversation — NOT `root_id`, which tracks the reply chain and
+ * can differ between messages of one thread (which would split a thread's context across buckets).
+ * A quoted reply outside a thread carries a root but is main-chat discussion, so it buckets there.
+ *
+ * Its own namespace, deliberately: this names a BUCKET of undelivered text, while `parse.ts`'s
+ * `placeKey` names a SESSION. Nothing here claims anything about that session — unlike thread
+ * participation, which asserts "the agent answered into this memory" and is therefore keyed by the
+ * session itself. Re-keying either one leaves the other correct, and converging them now would strand
+ * live buckets for no gain (Slack keeps its own shape for the same reason).
+ */
+export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "threadId">): string;
 /** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
 export declare function feishuBufferText(text: string): string;
 /**
@@ -32,15 +44,5 @@ export declare function collectFeishuBufferedAttachments(consumed: FeishuBufferE
     images: FeishuBufferedRef[];
     skipped: number;
 };
-export interface FeishuContextBuffer {
-    /** Persist before webhook ACK. A failed write throws and rolls memory back for safe redelivery. */
-    push(placeKey: string, entry: FeishuBufferEntry): void;
-    /** Render and snapshot without clearing. */
-    peek(placeKey: string): {
-        text: string;
-        consumed: FeishuBufferEntry[];
-    };
-    /** Remove only the consumed snapshot after `completed`; a post-ACK write failure is logged. */
-    commit(placeKey: string, consumed: FeishuBufferEntry[]): void;
-}
+export type FeishuContextBuffer = ContextBuffer<FeishuBufferEntry>;
 export declare function createFeishuContextBuffer(path: string, label: string): FeishuContextBuffer;

package/dist/channels/feishu/context-buffer.js

@@ -1,27 +1,37 @@
 /**
- * Durable context buffer for human group messages that do NOT currently summon the Feishu/Lark Agent.
- * Entries are bucketed by conversation place (main chat, or one concrete thread root) and folded into
- * the next answered turn in that place. The consume protocol mirrors Telegram: peek without clearing,
- * then commit exactly that snapshot only after the Agent emits `completed`.
+ * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
+ * ../context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
+ * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
+ * concrete thread root) and folded into the next answered turn in that place.
  */
 import { log } from "../../log.js";
+import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
 import { loadStateFile, saveStateFile } from "../state.js";
-const BUFFER_MAX_CHARS = 4000;
-const BUFFER_ATTACH_MAX = 3;
+import { truncateCodePointPrefix } from "../text.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
         .filter(Boolean)
         .join(", ");
     return `${entry.sender} (${meta}): ${entry.body}`;
 }
-/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+/**
+ * The place a message belongs to: the main chat, or a thread within it. Keyed by `thread_id`, the
+ * platform's own identity for a side conversation — NOT `root_id`, which tracks the reply chain and
+ * can differ between messages of one thread (which would split a thread's context across buckets).
+ * A quoted reply outside a thread carries a root but is main-chat discussion, so it buckets there.
+ *
+ * Its own namespace, deliberately: this names a BUCKET of undelivered text, while `parse.ts`'s
+ * `placeKey` names a SESSION. Nothing here claims anything about that session — unlike thread
+ * participation, which asserts "the agent answered into this memory" and is therefore keyed by the
+ * session itself. Re-keying either one leaves the other correct, and converging them now would strand
+ * live buckets for no gain (Slack keeps its own shape for the same reason).
+ */
 export function feishuBufferPlaceKey(conversation) {
-    const topic = conversation.rootId ?? conversation.threadId;
-    return topic ? `${conversation.chatId}:root:${topic}` : conversation.chatId;
+    return conversation.threadId ? `${conversation.chatId}:thread:${conversation.threadId}` : conversation.chatId;
 }
 /** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
 export function feishuBufferText(text) {
-    return text.replace(/\s+/g, " ").trim().slice(0, 280);
+    return truncateCodePointPrefix(text.replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
 }
 function resourceIdentity(resource) {
     return `${resource.messageId}\u0000${resource.key}`;
@@ -70,64 +80,47 @@ function isEntry(value) {
         resources(entry.files) &&
         resources(entry.images));
 }
+/**
+ * Buckets from the pre-participant-model keying (`<chat>:root:<root_id>`) can never be produced again —
+ * a place is `<chat>` or `<chat>:thread:<thread_id>` — so nothing could ever fold or clear them, and
+ * they would hold chat content on disk forever. Dropped here, before the buffer loads, so the shared
+ * kernel never learns about a key shape one channel retired.
+ *
+ * TWO one-time losses, both accepted and both logged by count. (1) The retired shape covered every
+ * thread bucket and every main-chat quoted-reply bucket, so buffered discussion in threads does not
+ * survive the upgrade — it becomes unreachable BECAUSE of the re-keying, not before it. (2)
+ * `turns.json` persists each in-flight turn's `bufferKey` verbatim and this runs before turn recovery,
+ * so a turn spanning the upgrade finds its bucket already gone. Sparing referenced keys would couple
+ * the buffer to the turn store to protect a single upgrade, and would not help (1) at all.
+ *
+ * PERMANENT, unlike the `owned-threads.json` cleanup it otherwise resembles. That one leaves an inert
+ * orphan file, so deleting it a release later is free; this one is what stops user chat content
+ * lingering, and a deployment that skips from before the model to well after it would never run an
+ * expired version of this code. The standing cost is one key scan at load, and nothing when no retired
+ * key is present.
+ */
+function dropRetiredBuckets(path, label) {
+    const raw = loadStateFile(path);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return;
+    const live = Object.entries(raw).filter(([placeKey]) => !placeKey.includes(":root:"));
+    const dropped = Object.keys(raw).length - live.length;
+    if (dropped === 0)
+        return;
+    log.info(`${label} dropped ${dropped} context bucket(s) with a retired key shape`);
+    try {
+        saveStateFile(path, Object.fromEntries(live));
+    }
+    catch (error) {
+        log.warn(`${label} could not rewrite ${path} after dropping retired buckets: ${String(error)}`);
+    }
+}
 export function createFeishuContextBuffer(path, label) {
-    const load = () => {
-        const raw = loadStateFile(path);
-        if (raw === undefined)
-            return new Map();
-        if (typeof raw === "object" &&
-            raw !== null &&
-            !Array.isArray(raw) &&
-            Object.values(raw).every((entries) => Array.isArray(entries) && entries.every(isEntry))) {
-            return new Map(Object.entries(raw));
-        }
-        log.warn(`${label} unexpected shape in ${path} — starting with an empty context buffer`);
-        return new Map();
-    };
-    const buffers = load();
-    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
-    return {
-        push(placeKey, entry) {
-            const previous = buffers.get(placeKey);
-            const entries = previous ? [...previous] : [];
-            entries.push(entry);
-            let total = entries.reduce((sum, candidate) => sum + bufferLine(candidate).length + 1, 0);
-            while (entries.length > 1 && total > BUFFER_MAX_CHARS) {
-                const dropped = entries.shift();
-                if (dropped)
-                    total -= bufferLine(dropped).length + 1;
-            }
-            buffers.set(placeKey, entries);
-            try {
-                persist();
-            }
-            catch (error) {
-                if (previous)
-                    buffers.set(placeKey, previous);
-                else
-                    buffers.delete(placeKey);
-                throw error;
-            }
-        },
-        peek(placeKey) {
-            const entries = buffers.get(placeKey) ?? [];
-            return { text: entries.map(bufferLine).join("\n"), consumed: [...entries] };
-        },
-        commit(placeKey, consumed) {
-            const entries = buffers.get(placeKey);
-            if (!entries)
-                return;
-            const remaining = entries.filter((entry) => !consumed.includes(entry));
-            if (remaining.length === 0)
-                buffers.delete(placeKey);
-            else
-                buffers.set(placeKey, remaining);
-            try {
-                persist();
-            }
-            catch (error) {
-                log.error(`${label} context-buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(error)}`);
-            }
-        },
-    };
+    dropRetiredBuckets(path, label);
+    return createGenericContextBuffer({
+        path,
+        label,
+        isEntry,
+        line: bufferLine,
+    });
 }

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

@@ -34,6 +34,11 @@ export interface FeishuApiOptions {
     appId: string;
     appSecret: string;
 }
+export interface FeishuAppScope {
+    name: string;
+    grantStatus: number;
+    type?: "user" | "tenant";
+}
 /**
  * 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.
@@ -85,6 +90,12 @@ export interface FeishuApi {
         verificationToken?: string;
         encryptionKey?: string;
     }>;
+    /** List the app's scopes and grant state. Used by onboarding/runtime to make group visibility
+     * explicit instead of silently assuming unmentioned group events are delivered. */
+    listAppScopes(): Promise<FeishuAppScope[]>;
+    /** Add tenant scopes to the app draft through application-v7 config. Approval + version publishing
+     * remain console actions; this method only removes the error-prone manual draft edit. */
+    addAppScopes(appId: string, scopeNames: string[]): Promise<void>;
     /** 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
@@ -100,9 +111,6 @@ export interface FeishuApi {
     /** 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;

package/dist/channels/feishu/feishu-api.js

@@ -21,7 +21,7 @@
  */
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { utf8Prefix } from "./text.js";
+import { utf8Prefix } from "../text.js";
 /** Per-attempt timeout for a JSON API call — small JSON round-trips, so 30s is generous. */
 const API_TIMEOUT_MS = 30_000;
 /** Timeout for downloading resource bytes — sized for a slow link, not a JSON call. */
@@ -79,7 +79,7 @@ export function isTransientFeishuRegistrationError(e) {
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** 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 const FEISHU_MAX_TEXT_BYTES = 100 * 1024;
+const FEISHU_MAX_TEXT_BYTES = 100 * 1024;
 /** Split text into chunks whose UTF-8 size fits the message cap, preferring a newline boundary. */
 export function chunkFeishuText(text, maxBytes = FEISHU_MAX_TEXT_BYTES) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
@@ -236,7 +236,10 @@ export function createFeishuApi(opts) {
             await call("deleteMessage", "DELETE", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`);
         },
         async getMessage(messageId) {
-            const data = await call("getMessage", "GET", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`);
+            const data = await call("getMessage", "GET", 
+            // Pin the id type: callers match mentions/sender against open_ids, so the response's id shape
+            // must not depend on the platform's default staying open_id.
+            `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}?user_id_type=open_id`);
             return data.data?.items?.[0];
         },
         async downloadResource(messageId, fileKey, type) {
@@ -296,6 +299,24 @@ export function createFeishuApi(opts) {
                 encryptionKey: data.data?.app?.encryption?.encryption_key,
             };
         },
+        async listAppScopes() {
+            const data = await call("listAppScopes", "GET", "/open-apis/application/v6/scopes");
+            return (data.data?.scopes ?? []).flatMap((scope) => {
+                if (typeof scope.scope_name !== "string" || typeof scope.grant_status !== "number")
+                    return [];
+                const type = scope.scope_type === "user" || scope.scope_type === "tenant" ? scope.scope_type : undefined;
+                return [{ name: scope.scope_name, grantStatus: scope.grant_status, type }];
+            });
+        },
+        async addAppScopes(appId, scopeNames) {
+            if (scopeNames.length === 0)
+                return;
+            await call("addAppScopes", "PATCH", `/open-apis/application/v7/applications/${encodeURIComponent(appId)}/config`, {
+                scope: {
+                    add_scopes: scopeNames.map((scopeName) => ({ scope_name: scopeName, token_type: "tenant" })),
+                },
+            });
+        },
         async updateEventSubscription(appId, cfg) {
             await call("updateEventSubscription", "PATCH", `/open-apis/application/v7/applications/${encodeURIComponent(appId)}/config`, {
                 event: { subscription_type: cfg.subscriptionType, request_url: cfg.requestUrl },

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

@@ -1,46 +1,46 @@
-import type { ChannelModule } from "../../host/node.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
 import { type FeishuCloudProfile } from "./cloud.ts";
 import { type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute, feishuEnvelope } from "./parse.ts";
 import { type FeishuFailure } from "./preview.ts";
+import { connectFeishuWs } from "./ws-ingress.ts";
 export { defaultFeishuRoute, feishuEnvelope };
 export type { FeishuFailure, FeishuMessage, FeishuMessageEvent, FeishuRoute };
-export interface FeishuChannelOptions {
+interface FeishuChannelBaseOptions {
     /** App ID (developer console → Credentials & Basic Info). */
     appId: string;
-    /** App Secret (same page) — drives the tenant_access_token the replies ride on. */
+    /** App Secret (same page) — drives both ingress authentication and outbound API calls. */
     appSecret: string;
-    /** Verification Token (console → Events & Callbacks) — authenticates PLAINTEXT events. */
-    verificationToken: string;
-    /** Encrypt Key (same page, optional there — recommended): when set, ordinary events arrive encrypted
-     *  and signed; this channel then REFUSES plaintext events (fail closed — accepting both would let a
-     *  forger skip the stronger check). Feishu explicitly excludes the encrypted `url_verification`
-     *  handshake from event signature verification; that narrow path is authenticated after decryption
-     *  by the Verification Token. Must match the console exactly. */
-    encryptKey?: string;
-    /** Direct-message context + delivery policy. `threaded` (default) gives every top-level p2p message
-     * its own session, creates a platform thread for the answer, and routes later thread messages back
-     * by root message id. `continuous` keeps one session per p2p chat and sends ordinary unquoted replies. */
-    directMessageSession?: "continuous" | "threaded";
-    /** Group-message context + delivery policy. `threaded` (default) gives every top-level summoned
-     * message its own session and platform thread; later bare user messages in that managed thread answer
-     * in the same root session, while @other-only discussion buffers. `continuous` preserves the legacy
-     * chat/topic sessions (`chat_id` / `chat_id:thread_id`). Buffering and bare continuations require
-     * `im:message.group_msg`. */
-    groupMessageSession?: "continuous" | "threaded";
     /** Policy: whether/where to answer an event (return null to ignore). Defaults to {@link defaultFeishuRoute}. */
     route?: (event: FeishuMessageEvent) => FeishuRoute | null;
     /** Customer-facing failure text for the chat (the dev-facing full `details` always go to the operator
      *  log). Return a string to send it, or undefined/"" to stay silent. Default: a neutral message keyed
      *  on `retryable`. A developer's own bot can surface the raw details, e.g. `(f) => `⚠️ ${f.details}``. */
     onError?: (failed: FeishuFailure) => string | undefined;
-    /** API origin override (tests / self-hosted gateways). The kind fixes the default —
-     *  `feishuChannel` → `https://open.feishu.cn`, `larkChannel` → `https://open.larksuite.com`. */
-    baseUrl?: string;
+    /** API origin override (tests / self-hosted gateways). Feishu factories default to
+     *  `https://open.feishu.cn`; Lark factories default to `https://open.larksuite.com`. Named to match
+     *  the other channels (telegram/slack). */
+    apiBaseUrl?: string;
     /** How long (ms) a turn waits before its reply-quoted "⏳ Queued" card mounts. Defaults to 0
      *  (immediate); the same card is later taken over by the live preview/final answer. */
     queueNoticeDelayMs?: number;
 }
-/** Build the canonical Feishu channel. Lark calls the internal profile-bound builder below. */
+export interface FeishuChannelOptions extends FeishuChannelBaseOptions {
+    /** Verification Token for Request-URL authentication. */
+    verificationToken: string;
+    /** Optional webhook Encrypt Key. When set, plaintext events are rejected. */
+    encryptKey?: string;
+}
+export type FeishuWebSocketChannelOptions = FeishuChannelBaseOptions & {
+    verificationToken?: never;
+    encryptKey?: never;
+};
+/** Build the canonical Feishu Request-URL webhook channel. */
 export declare function feishuChannel(opts: FeishuChannelOptions): ChannelModule;
-/** Internal compatibility seam: protocol behavior comes from Feishu; the profile binds cloud edges. */
-export declare function buildFeishuChannel(profile: FeishuCloudProfile, { appId, appSecret, verificationToken, encryptKey, directMessageSession, groupMessageSession, route, onError, baseUrl, queueNoticeDelayMs, }: FeishuChannelOptions, factoryName: string): ChannelModule;
+/** Build the canonical Feishu WebSocket long-connection channel. */
+export declare function feishuWebSocketChannel(opts: FeishuWebSocketChannelOptions): LongConnectionChannelModule;
+/** Internal compatibility seams: protocol behavior comes from Feishu; the profile binds cloud edges. */
+interface FeishuWebSocketChannelDeps {
+    connectWs?: typeof connectFeishuWs;
+}
+export declare function buildFeishuChannel(profile: FeishuCloudProfile, opts: FeishuChannelOptions, factoryName: string): ChannelModule;
+export declare function buildFeishuWebSocketChannel(profile: FeishuCloudProfile, opts: FeishuWebSocketChannelOptions, factoryName: string, deps?: FeishuWebSocketChannelDeps): LongConnectionChannelModule;