@rynx-ai/plugin-channel-lark 0.1.9

package/dist/lark.d.ts

@@ -0,0 +1,500 @@
+import { type CodexCapabilities } from "@rynx-ai/core";
+import type { PluginAgentSummary, PluginExecutionDefaults, PluginResolvedSessionExecution, PluginSessionExecutionSnapshot } from "@rynx-ai/plugin-sdk";
+import { chunkLarkReplyText, extractLarkTextPrompt, isLarkNewSessionCommand, isLarkStopCommand } from "./lark-content.js";
+import { type LarkConversationDirectory } from "./lark-conversation-directory.js";
+import { LarkClientProvider, LarkSdkMessageSender } from "./lark-sender.js";
+import { type LarkActiveSessionStore } from "./lark-session-store.js";
+import type { ConversationProvider, ConversationRuntime } from "@rynx-ai/core";
+export { chunkLarkReplyText, extractLarkTextPrompt, isLarkNewSessionCommand, isLarkStopCommand, };
+export { LarkClientProvider, LarkSdkMessageSender };
+export interface LarkUserIdentifier {
+    union_id?: string;
+    user_id?: string;
+    open_id?: string;
+}
+export interface LarkMessageMention {
+    key: string;
+    id: LarkUserIdentifier;
+    name: string;
+    tenant_key?: string;
+}
+export interface LarkMessageReceiveEvent {
+    tenant_key?: string;
+    sender: {
+        sender_id?: LarkUserIdentifier;
+        sender_type: string;
+        tenant_key?: string;
+    };
+    message: {
+        message_id: string;
+        root_id?: string;
+        parent_id?: string;
+        create_time: string;
+        update_time?: string;
+        chat_id: string;
+        thread_id?: string;
+        chat_type: string;
+        message_type: string;
+        content: string;
+        mentions?: LarkMessageMention[];
+        user_agent?: string;
+    };
+}
+export interface LarkBotStatus {
+    connected: boolean;
+    mode: "ws";
+    last_event_at: string | null;
+    last_error: string | null;
+}
+export interface LarkBotRuntime {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): LarkBotStatus;
+}
+interface LarkLogEntry {
+    event: string;
+    tenant_key?: string;
+    chat_id?: string;
+    thread_id?: string;
+    message_id?: string;
+    session_key?: string;
+    session_id?: string;
+    previous_session_id?: string;
+    provider?: ConversationProvider;
+    model?: string;
+    error?: string;
+    emoji_type?: string;
+    reason?: string;
+    kind?: unknown;
+    source?: string;
+    command?: string;
+    reasoning_effort?: string | null;
+    rotated?: boolean;
+}
+interface LarkLogger {
+    log(entry: LarkLogEntry): void;
+}
+export declare class LarkConversationKeyResolver {
+    resolve(event: LarkMessageReceiveEvent): string;
+}
+export declare class PerThreadQueue {
+    private readonly tails;
+    enqueue(key: string, task: () => Promise<void>): Promise<void>;
+}
+export declare class LarkMessageDeduper {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs?: number);
+    markIfNew(messageId: string, now?: number): boolean;
+    private prune;
+}
+export interface LarkMessageSender {
+    createText(args: {
+        chatId: string;
+        text: string;
+        uuid: string;
+    }): Promise<void>;
+    getMessage?(args: {
+        messageId: string;
+    }): Promise<LarkFetchedMessage | null>;
+    createReaction(args: {
+        messageId: string;
+        emojiType: string;
+    }): Promise<string | undefined>;
+    deleteReaction(args: {
+        messageId: string;
+        reactionId: string;
+    }): Promise<void>;
+    replyText(args: {
+        messageId: string;
+        text: string;
+        uuid: string;
+        replyInThread: boolean;
+    }): Promise<void>;
+    createCard?(args: {
+        cardJson: string;
+    }): Promise<{
+        cardId: string;
+    }>;
+    batchUpdateCard?(args: {
+        cardId: string;
+        sequence: number;
+        actions: string;
+        uuid?: string;
+    }): Promise<void>;
+    sendInteractive?(args: {
+        chatId: string;
+        cardId: string;
+        uuid: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+    replyInteractive?(args: {
+        messageId: string;
+        cardId: string;
+        uuid: string;
+        replyInThread: boolean;
+    }): Promise<{
+        messageId: string;
+    }>;
+    forwardThread?(args: {
+        threadId: string;
+        receiveId: string;
+        receiveIdType: "chat_id" | "thread_id";
+        uuid: string;
+    }): Promise<void>;
+    sendText?(args: {
+        chatId: string;
+        text: string;
+        uuid: string;
+    }): Promise<{
+        messageId: string;
+        threadId?: string;
+    }>;
+    createChat?(args: {
+        name: string;
+        userIdList: string[];
+        uuid: string;
+    }): Promise<{
+        chatId: string;
+    }>;
+    getChat?(args: {
+        chatId: string;
+    }): Promise<{
+        name: string;
+    }>;
+    listChatMembers?(args: {
+        chatId: string;
+    }): Promise<Array<{
+        memberId: string;
+        name: string;
+    }>>;
+    listMessages?(args: {
+        containerIdType: "chat" | "thread";
+        containerId: string;
+        pageSize?: number;
+    }): Promise<Array<{
+        msgType: string;
+        senderId?: string;
+        senderType?: string;
+        content: string;
+    }>>;
+}
+export interface LarkFetchedMessage {
+    messageId?: string;
+    msgType?: string;
+    content?: string;
+    body?: {
+        content?: string;
+    };
+}
+export interface LarkCardActionEvent {
+    /** Whatever we put in the button's/select's `behaviors[0].value` payload. */
+    value: Record<string, unknown> | null;
+    /** Selected option value for a `select_static` change (Feishu `action.option`). */
+    option?: string | null;
+    /** Form field values for a `form_submit` button (Feishu `action.form_value`). */
+    formValue?: Record<string, unknown> | null;
+    /** open_message_id of the card carrying the control, if Lark surfaced it. */
+    messageId?: string;
+}
+/**
+ * Shape Feishu expects in response to a card.action.trigger callback. At
+ * minimum a `toast` is enough to acknowledge the click and surface UI
+ * feedback to the user without a partial card update.
+ */
+export interface LarkCardActionResponse {
+    toast?: {
+        type: "info" | "success" | "warning" | "error";
+        content: string;
+    };
+    /**
+     * Replace the card that triggered the action, atomically, as part of the
+     * callback response. For raw schema-2.0 cards: `{ type: "raw", data: <card> }`.
+     * Preferred over an out-of-band `card.update` (which can briefly flash the new
+     * card and then revert to the original form).
+     */
+    card?: {
+        type: "raw";
+        data: Record<string, unknown>;
+    };
+}
+export interface LarkWsClientStartOptions {
+    onMessage: (event: LarkMessageReceiveEvent) => void;
+    onCardAction?: (event: LarkCardActionEvent) => LarkCardActionResponse | void | Promise<LarkCardActionResponse | void>;
+}
+export interface LarkWsClientProvider {
+    getMessageSender(): LarkMessageSender;
+    /**
+     * Resolve this bot's own `open_id` (via the bot info API). Used to tell, in a
+     * group with several bots, whether an incoming `@` actually targets us.
+     * Returns `null` when it cannot be determined.
+     */
+    getBotOpenId?(): Promise<string | null>;
+    start(options: LarkWsClientStartOptions): Promise<void>;
+    stop(): Promise<void>;
+}
+type LarkConversationRuntime = Pick<ConversationRuntime, "runLive">;
+interface LarkMessageIngestorOptions {
+    conversationRuntime: LarkConversationRuntime;
+    messageSender: LarkMessageSender;
+    cwd?: string;
+    /** Default runtime for conversations without a `/runtime` choice. */
+    defaultRuntime?: ConversationProvider;
+    /** Default declarative agent for conversations without an `/agent` choice. */
+    defaultAgent?: string;
+    /** Host-backed agent catalog and first-turn execution resolver. */
+    agentCatalog?: LarkAgentCatalog;
+    activeSessionStore: LarkActiveSessionStore;
+    conversationKeyResolver?: LarkConversationKeyResolver;
+    deduper?: LarkMessageDeduper;
+    queue?: PerThreadQueue;
+    logger?: LarkLogger;
+    cardThrottleMs?: number;
+    /** Read-only Codex capabilities powering `/models` and `/search`. */
+    capabilities?: CodexCapabilities;
+    /** Conversation directory powering `/resume`. */
+    conversationDirectory?: LarkConversationDirectory;
+    /** Allowlist of roots a `/cwd` target must live under. */
+    allowedRoots?: string[];
+    /**
+     * This bot's own `open_id`. In a group hosting several bots, only a message
+     * that `@`-mentions this `open_id` triggers a run. When unset, any mention
+     * triggers (legacy single-bot behavior).
+     */
+    botOpenId?: string | null;
+    /** When true, private (p2p) chats are rejected — the bot is group-only. */
+    disableP2p?: boolean;
+    /** When true, only groups in `groupAllowlist` may use the bot. */
+    groupAllowlistEnabled?: boolean;
+    /** Group `chat_id`s allowed when `groupAllowlistEnabled` is true. */
+    groupAllowlist?: string[];
+    /** Optional CLI-takeover mirror; receives Codex-thread bindings and turn
+     *  completions so it can mirror terminal-driven turns back into Feishu. */
+    mirror?: LarkCliMirror;
+    /** Host-RPC backed title updater for daemon-owned machine sessions. */
+    sessionTitleWriter?: (sessionId: string, title: string) => Promise<void>;
+    /** Host-RPC backed allocator used by `/fork` before binding the new chat. */
+    sessionProvisioner?: (input: {
+        sessionKey: string;
+        fromSessionId: string;
+    }) => Promise<string>;
+}
+export interface LarkAgentCatalog {
+    list(): Promise<PluginAgentSummary[]>;
+    get(id: string): Promise<PluginAgentSummary | null>;
+    resolveExecution(input: {
+        defaultAgent?: string;
+        session: PluginSessionExecutionSnapshot;
+    }): Promise<PluginResolvedSessionExecution>;
+}
+/**
+ * Collaborator that mirrors CLI-driven Codex turns back into Feishu. The
+ * ingestor only needs to (a) register a session's Codex thread as it becomes
+ * bound, and (b) let the mirror claim the lines the bridge itself wrote so they
+ * aren't mirrored twice.
+ */
+export interface LarkCliMirror {
+    noteBoundSession(codexSessionId: string): Promise<void>;
+    claimToEof(codexSessionId: string): Promise<void>;
+}
+export declare class LarkMessageIngestor {
+    private readonly conversationRuntime;
+    private readonly messageSender;
+    /** Default runtime for this bot; per-conversation choices override it. */
+    private readonly provider;
+    /** Default declarative agent for this bot; per-conversation `/agent` overrides it. */
+    private readonly defaultAgent?;
+    /** Host-backed agent catalog for `/agent` and execution freezing. */
+    private readonly agentCatalog?;
+    /** Transient per-conversation settings-card selections, keyed by sessionKey. */
+    private readonly pendingSettings;
+    private readonly cwd?;
+    private readonly activeSessionStore;
+    private readonly conversationKeyResolver;
+    private readonly deduper;
+    private readonly queue;
+    private readonly logger;
+    private readonly cardThrottleMs;
+    private readonly capabilities?;
+    private readonly conversationDirectory;
+    private readonly allowedRoots;
+    private botOpenId;
+    private readonly disableP2p;
+    private readonly groupAllowlistEnabled;
+    private readonly groupAllowlist;
+    private readonly mirror?;
+    private readonly sessionTitleWriter?;
+    private readonly sessionProvisioner?;
+    private readonly inFlight;
+    constructor({ conversationRuntime, messageSender, cwd, defaultRuntime, defaultAgent, agentCatalog, activeSessionStore, conversationKeyResolver, deduper, queue, logger, cardThrottleMs, capabilities, conversationDirectory, allowedRoots, botOpenId, disableP2p, groupAllowlistEnabled, groupAllowlist, mirror, sessionTitleWriter, sessionProvisioner, }: LarkMessageIngestorOptions);
+    /** Best-effort title update for the daemon-owned machine-session record. */
+    private registerSession;
+    /**
+     * Set this bot's own `open_id` once it has been resolved asynchronously
+     * (the runtime fetches it from the bot info API at startup).
+     */
+    setBotOpenId(openId: string | null): void;
+    /** Whether a bridge-driven turn is currently running for `sessionKey`. The
+     *  CLI mirror reads this to skip turns already shown live in Feishu. */
+    isInFlight(sessionKey: string): boolean;
+    /**
+     * Whether a group message is addressed to *this* bot. With a known
+     * `botOpenId`, that means one of the `@`-mentions carries our `open_id` —
+     * so in a group hosting several bots, only the one actually mentioned runs.
+     * When `botOpenId` is unknown, fall back to "any mention" (legacy single-bot
+     * behavior) rather than going silent.
+     */
+    private isAddressedToBot;
+    /**
+     * Handle a Feishu CardKit button click. Supported actions:
+     * - `{ kind: "stop_turn", sessionKey }` — the in-card "停止" button.
+     * - `{ kind: "resume_forward", threadId, chatId }` — forward a topic thread
+     *   into `chatId` (from the `/resume` card).
+     * Anything else is logged and ignored.
+     */
+    ingestCardAction(event: LarkCardActionEvent): Promise<LarkCardActionResponse>;
+    private handleResumeForwardAction;
+    /** Where a forward should land for the conversation `event` arrived in:
+     *  inside the current topic thread when present, else the chat. */
+    private forwardTargetOf;
+    /**
+     * Cancel the in-flight turn for `sessionKey`, if any. Returns true if a
+     * turn was actually aborted. Safe to call from outside the per-session
+     * queue (that's the whole point — the queue is serialized but interrupt
+     * must bypass it).
+     */
+    interruptSession(sessionKey: string): boolean;
+    private registerInFlight;
+    private clearInFlight;
+    ingest(event: LarkMessageReceiveEvent): Promise<void>;
+    private handleStopCommand;
+    private handleInfoCommand;
+    private handleActionCommand;
+    /**
+     * Render the working-tree diff as a CardKit card (summary + per-file stats +
+     * a collapsed full diff). Falls back to a plain-text reply when the sender
+     * has no card capability or the card send fails.
+     */
+    private handleDiffCommand;
+    private collectGitDiff;
+    private renderGoalReply;
+    private capabilityErrorText;
+    private conversationKindOf;
+    private recordConversation;
+    private handleCwdCommand;
+    private handleResumeCommand;
+    private resumeList;
+    private resumeByShortId;
+    private sendStandaloneCard;
+    private handleForkCommand;
+    /**
+     * Send the `/runtime` (or `/model`) settings card and seed the pending
+     * selection state with the conversation's current settings.
+     */
+    private handleSettingsCommand;
+    /**
+     * `/agent` — list declarative agents, or select one for this conversation.
+     * Selecting rotates to a fresh session (so sandbox/persona/tools don't change
+     * mid-thread) and drops explicit runtime/model overrides so the agent drives them.
+     */
+    private handleAgentCommand;
+    /**
+     * Label shown for the model in the turn card. An empty model means the
+     * runtime follows its own configured default (e.g. traex with no
+     * `TRAEX_MODEL`); show a placeholder so the status row isn't blank (the
+     * runtime itself is shown separately).
+     */
+    private displayModel;
+    private renderSettingsSummary;
+    /** Assemble the settings-card input from the current pending selection. */
+    private settingsCardInput;
+    private fetchModelOptions;
+    /**
+     * Handle a settings-card dropdown change. A runtime change re-scopes the
+     * model list (and resets model/effort); a model change re-scopes the effort
+     * list — both re-render the card in place via the callback response so the
+     * dependent dropdowns update. Effort changes just update pending state.
+     */
+    private handleSettingsSelect;
+    /** Card-action response that re-renders the open settings card in place. */
+    private settingsCardResponse;
+    /** Apply the pending settings-card selections to the conversation. */
+    private handleSettingsApply;
+    /** Cancel an open settings card without changing anything. */
+    private handleSettingsCancel;
+    /**
+     * Build a card-action response that swaps the settings card for a static
+     * result card. Returning the card in the callback response replaces it
+     * atomically; an out-of-band `card.update` would briefly show the result and
+     * then revert to the form.
+     */
+    private settingsResultCard;
+    private renderModelsReply;
+    private handleNewSessionCommand;
+    private logMessageReceived;
+    private tryCreateReaction;
+    private tryDeleteReaction;
+    /**
+     * If this turn replies to a Lark message card, fetch the parent card and wrap
+     * the prompt so the agent receives the card content as context. Generic: it
+     * forwards any interactive (card) parent and names no specific skill — the
+     * agent decides how to act on the card. Returns null when the parent is not a
+     * card (or cannot be fetched), so the caller falls back to the raw prompt.
+     */
+    private tryBuildCardReplyPrompt;
+    /**
+     * Map a session to the {@link TurnSettings} a turn runs with. Already-frozen
+     * sessions are resolved locally; first-turn defaults and named-agent lookup
+     * are delegated to the capability-gated host and then persisted exactly once.
+     */
+    private resolveTurnExecution;
+    private buildReply;
+    private canUseCardSender;
+    private tryBuildReplyWithCard;
+    /**
+     * On the turn's first `session.status` carrying a runtime session id, bind it
+     * to the in-flight turn and register it with the CLI mirror (so the mirror
+     * watches that rollout file, and the bridge's own lines are later claimed).
+     */
+    private noteRuntimeSession;
+    private buildReplyDrain;
+    private sendReplyText;
+}
+interface LocalLarkBotRuntimeOptions {
+    /** Host-computed defaults carried on the explicit contribution start request. */
+    executionDefaults?: PluginExecutionDefaults;
+    /** Capability-gated host view of agent metadata and execution resolution. */
+    agentCatalog?: LarkAgentCatalog;
+    conversationRuntime: LarkConversationRuntime;
+    clientProvider?: LarkWsClientProvider;
+    messageIngestor?: LarkMessageIngestor;
+    logger?: LarkLogger;
+    /** Read-only agent capabilities for `/models` and `/search`. */
+    capabilities?: CodexCapabilities;
+    /** Per-instance options (credentials + knobs) overriding global config. */
+    options?: Record<string, unknown>;
+    /** Per-instance default declarative agent. */
+    defaultAgent?: string;
+    /** Explicit plugin-scoped state files. Runtime entries always supply both. */
+    activeSessionStore?: LarkActiveSessionStore;
+    conversationDirectory?: LarkConversationDirectory;
+    /** Host RPC seams; no daemon object crosses into this process. */
+    sessionTitleWriter?: (sessionId: string, title: string) => Promise<void>;
+    sessionProvisioner?: (input: {
+        sessionKey: string;
+        fromSessionId: string;
+    }) => Promise<string>;
+}
+export declare class LocalLarkBotRuntime implements LarkBotRuntime {
+    private readonly clientProvider?;
+    private readonly messageIngestor?;
+    private readonly logger;
+    private connected;
+    private lastEventAt;
+    private lastError;
+    constructor({ executionDefaults, agentCatalog, conversationRuntime, options, defaultAgent, logger, clientProvider, messageIngestor, capabilities, activeSessionStore: injectedActiveSessionStore, conversationDirectory: injectedConversationDirectory, sessionTitleWriter, sessionProvisioner, }: LocalLarkBotRuntimeOptions);
+    getStatus(): LarkBotStatus;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}