@fastagent-sh/fastagent 0.13.0 → 0.15.0

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

@@ -1,6 +1,6 @@
 import type { ImageRef } from "../../agent.ts";
 import type { FeishuCloudKind } from "./cloud.ts";
-/** Where a reply goes: a chat, optionally quote-replying a message (in-thread in topic groups). */
+/** Where a reply goes: a chat, optionally quote-replying a message inside a platform thread. */
 export interface FeishuTarget {
     chatId: string;
     /** Message to reply to (the summoning message). Set in groups so the answer threads under the asker. */
@@ -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.
@@ -49,12 +54,12 @@ export interface FeishuApi {
     }>;
     /** Send a message to a chat; returns the new message_id (undefined if the body carried none). */
     sendMessage(chatId: string, msgType: string, content: string): Promise<string | undefined>;
-    /** Reply to a message (quote; `replyInThread` stays inside a topic group's thread). */
+    /** Reply to a message; `replyInThread` creates or continues its platform thread. */
     replyMessage(messageId: string, msgType: string, content: string, opts?: {
         replyInThread?: boolean;
     }): Promise<string | undefined>;
-    /** Send `text`, split at the platform's size cap: ordinary groups quote only the first chunk; topic
-     *  groups reply_in_thread on every chunk. Returns the FIRST message_id. */
+    /** Send `text`, split at the platform's size cap: ordinary groups quote only the first chunk;
+     *  threaded targets use reply_in_thread on every chunk. Returns the FIRST message_id. */
     sendText(target: FeishuTarget, text: string): Promise<string | undefined>;
     /** Edit a sent text message in place (PUT; the platform caps edits at 20 per message). */
     editTextMessage(messageId: string, text: string): Promise<void>;
@@ -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)
@@ -212,8 +212,8 @@ export function createFeishuApi(opts) {
             let first = true;
             for (const chunk of chunks) {
                 const content = JSON.stringify({ text: chunk });
-                // A normal group quote-replies only the first chunk — N reply-quotes would be noise. A topic
-                // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to the main group.
+                // A normal group quote-replies only the first chunk — N reply-quotes would be noise. A thread
+                // must reply_in_thread on EVERY chunk; a plain chat send would leak continuations to main chat.
                 const reply = target.replyTo !== undefined && (first || target.replyInThread === true);
                 const id = reply
                     ? await api.replyMessage(target.replyTo, "text", content, {
@@ -296,6 +296,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,36 +1,58 @@
-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`. */
+    /** 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;
+    /** @deprecated Alias of {@link apiBaseUrl}; kept for existing feishu/lark channel files. */
     baseUrl?: 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, 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;