@rynx-ai/plugin-channel-lark 0.1.9

package/dist/lark-card-stream.d.ts

@@ -0,0 +1,363 @@
+import type { AgentHarnessEvent } from "@rynx-ai/core";
+import type { SessionEvent, TurnPlanStep } from "@rynx-ai/core";
+export type CardStatus = "starting" | "running" | "completed" | "failed" | "cancelled";
+export interface ToolCallSnapshot {
+    itemId: string;
+    kind: "command_execution" | "file_change" | "mcp_tool_call" | "dynamic_tool_call" | "web_search" | "other";
+    label: string;
+    status: "inProgress" | "completed" | "failed" | "declined";
+    command?: string;
+    output?: string;
+    exitCode?: number | null;
+}
+export interface TurnCardState {
+    status: CardStatus;
+    statusReason: string | null;
+    plan: TurnPlanStep[] | null;
+    reasoningSummary: string;
+    toolCalls: ToolCallSnapshot[];
+    /** Aggregated turn-level unified diff (`turn/diff/updated`). */
+    turnDiff: string | null;
+    agentMessage: string;
+    finalAnswer: string | null;
+    errorMessage: string | null;
+    localThreadId: string;
+    codexThreadId: string | null;
+    /** Stable `/resume <id>` short id for this conversation (= the conversation
+     *  directory's `shortId`). Shown in the footer so what's displayed is exactly
+     *  what the user types to jump back. Null when the conversation key is
+     *  unknown at card-creation time. */
+    resumeShortId: string | null;
+    turnId: string | null;
+    /** Short runtime label shown in the status row (e.g. `codex` / `trae`). */
+    runtime: string | null;
+    model: string;
+    /** Reasoning effort shown in the status row (e.g. `xhigh`); null = follow model default. */
+    effort: string | null;
+    usage: Record<string, unknown> | null;
+    startedAt: string;
+}
+export interface CreateInitialStateOptions {
+    localThreadId: string;
+    model: string;
+    runtime?: string;
+    /** Stable `/resume <id>` short id for this conversation, shown in the footer. */
+    resumeShortId?: string;
+    /** Reasoning effort for this turn; omit to follow the model default (hidden). */
+    effort?: string;
+    startedAt?: string;
+}
+export declare function createInitialCardState({ localThreadId, model, runtime, resumeShortId, effort, startedAt, }: CreateInitialStateOptions): TurnCardState;
+export declare function applyEventToCardState(state: TurnCardState, event: AgentHarnessEvent): TurnCardState;
+declare const ELEMENT_IDS: {
+    readonly status_row: "status_row";
+    readonly status: "status";
+    readonly stop_column: "stop_column";
+    readonly plan: "plan";
+    readonly reasoning_panel: "reasoning_panel";
+    readonly reasoning: "reasoning";
+    readonly tools_panel: "tools_panel";
+    readonly tools: "tools";
+    readonly output: "output";
+    readonly diff_panel: "diff_panel";
+    readonly diff: "diff";
+    readonly message: "message";
+    readonly error: "error";
+};
+type ElementId = (typeof ELEMENT_IDS)[keyof typeof ELEMENT_IDS];
+export declare function renderStatusMarkdown(state: TurnCardState): string;
+export declare function renderPlanMarkdown(plan: TurnPlanStep[] | null): string;
+export declare function renderReasoningMarkdown(summary: string): string;
+export declare function renderToolsMarkdown(toolCalls: ToolCallSnapshot[]): string;
+export declare function renderOutputMarkdown(toolCalls: ToolCallSnapshot[]): string;
+export declare function renderDiffMarkdown(turnDiff: string | null): string;
+export declare function renderMessageMarkdown(state: TurnCardState): string;
+export declare function renderErrorMarkdown(state: TurnCardState): string;
+interface CardMarkdownElement {
+    tag: "markdown";
+    element_id: ElementId;
+    content: string;
+}
+interface CardCollapsiblePanelElement {
+    tag: "collapsible_panel";
+    element_id: ElementId;
+    expanded: boolean;
+    header: {
+        title: {
+            tag: "plain_text";
+            content: string;
+        };
+        vertical_align?: "center" | "top" | "bottom";
+        icon: {
+            tag: "standard_icon";
+            token: string;
+        };
+    };
+    elements: CardMarkdownElement[];
+}
+interface CardColumnElement {
+    tag: "column";
+    element_id?: ElementId;
+    width: "weighted" | "auto" | "fill";
+    weight?: number;
+    vertical_align?: "top" | "center" | "bottom";
+    elements: Array<CardMarkdownElement | CardStopButtonElement>;
+}
+interface CardColumnSetElement {
+    tag: "column_set";
+    element_id: ElementId;
+    flex_mode: "none";
+    horizontal_align?: "left" | "right" | "center";
+    columns: CardColumnElement[];
+}
+type CardBodyElement = CardMarkdownElement | CardCollapsiblePanelElement | CardColumnSetElement;
+interface CardStopButtonElement {
+    tag: "button";
+    type: "text";
+    size: "small";
+    icon: {
+        tag: "standard_icon";
+        token: "stop_outlined";
+    };
+    hover_tips: {
+        tag: "plain_text";
+        content: string;
+    };
+    behaviors: Array<{
+        type: "callback";
+        value: {
+            kind: "stop_turn";
+            sessionKey: string;
+        };
+    }>;
+}
+export interface StopButtonOptions {
+    sessionKey: string;
+    /** Tooltip shown on hover. Defaults to "停止". */
+    hoverTip?: string;
+}
+export interface CreateInitialCardJsonResult {
+    cardJson: string;
+    mounted: Set<ElementId>;
+}
+export declare function createInitialCardJson(state: TurnCardState, opts?: {
+    stopButton?: StopButtonOptions;
+}): CreateInitialCardJsonResult;
+export type CardAction = {
+    action: "partial_update_element";
+    params: {
+        element_id: ElementId;
+        partial_element: {
+            content: string;
+        };
+    };
+} | {
+    action: "add_elements";
+    params: {
+        type: "insert_before" | "insert_after" | "append";
+        target_element_id?: string;
+        elements: CardBodyElement[];
+    };
+} | {
+    action: "delete_elements";
+    params: {
+        element_ids: string[];
+    };
+} | {
+    action: "partial_update_setting";
+    params: {
+        settings: Record<string, unknown>;
+    };
+};
+export declare function buildTerminalSettingsAction(): CardAction;
+export declare function buildStopColumnDeleteAction(): CardAction;
+export interface DiffCardActionsResult {
+    actions: CardAction[];
+    mounted: Set<ElementId>;
+}
+export declare function diffCardActions(prev: TurnCardState, next: TurnCardState, mounted: Set<ElementId>): DiffCardActionsResult;
+export interface LarkCardSender {
+    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;
+    }>;
+}
+export interface LarkCardLogger {
+    log(entry: Record<string, unknown>): void;
+}
+export interface CardControllerSessionInfo {
+    chatId: string;
+    /** The inbound user message to quote-reply to (used by `start()`). Absent for
+     *  CLI-mirrored turns, which post a standalone card via `startStandalone()`. */
+    messageId?: string;
+    threadId?: string;
+}
+export interface LarkTurnCardControllerOptions {
+    sender: LarkCardSender;
+    session: CardControllerSessionInfo;
+    initialState: TurnCardState;
+    throttleMs?: number;
+    logger?: LarkCardLogger;
+    stopButton?: StopButtonOptions;
+}
+export declare class LarkTurnCardController {
+    private readonly sender;
+    private readonly session;
+    private readonly throttleMs;
+    private readonly logger?;
+    private readonly stopButton;
+    private state;
+    private cardId;
+    private sequence;
+    private flushTimer;
+    private flushChain;
+    private lastFlushedState;
+    private mounted;
+    private dirty;
+    private closed;
+    private terminal;
+    private stopButtonMounted;
+    constructor({ sender, session, initialState, throttleMs, logger, stopButton, }: LarkTurnCardControllerOptions);
+    start(): Promise<void>;
+    /**
+     * Post the card as a standalone chat message instead of a quote-reply. Used
+     * to mirror a CLI-driven turn, where there is no inbound Feishu message to
+     * reply to. `sendInteractive` targets the chat (no thread-targeting param),
+     * so for topic-thread conversations the card lands at chat level.
+     */
+    startStandalone(): Promise<void>;
+    ingestEvent(event: AgentHarnessEvent): Promise<void>;
+    finalize(opts: {
+        status: "completed" | "failed" | "cancelled";
+        finalAnswer?: string;
+        error?: string;
+    }): Promise<void>;
+    getState(): TurnCardState;
+    private scheduleFlush;
+    private flush;
+}
+/** Footer metadata shown in the status row (mirrors the legacy card's footer). */
+export interface SessionCardMeta {
+    runtime: string | null;
+    model: string;
+    effort: string | null;
+    resumeShortId: string | null;
+}
+export interface LarkResponseCardControllerOptions {
+    sender: LarkCardSender;
+    chatId: string;
+    meta: SessionCardMeta;
+    throttleMs?: number;
+    logger?: LarkCardLogger;
+    stopButton?: StopButtonOptions;
+}
+/**
+ * Renders ONE response as a streaming Feishu card: a status row plus an ordered
+ * list of item blocks appended as they arrive. Keeps the legacy controller's
+ * throttle / sequence / serialized-flush machinery; only the state model + diff
+ * differ (an append-mostly ordered list rather than fixed panels).
+ */
+export declare class LarkResponseCardController {
+    private readonly sender;
+    private readonly chatId;
+    private readonly meta;
+    private readonly throttleMs;
+    private readonly logger?;
+    private readonly stopButton;
+    private cardId;
+    private sequence;
+    private flushTimer;
+    private flushChain;
+    private dirty;
+    private terminal;
+    private closed;
+    private stopButtonMounted;
+    private status;
+    /** Transient status banner (e.g. API-retry); cleared once progress resumes. */
+    private statusNote;
+    private elIdSeq;
+    private readonly items;
+    private readonly byItemId;
+    private readonly byCallId;
+    private readonly mounted;
+    private readonly lastRendered;
+    constructor(opts: LarkResponseCardControllerOptions);
+    /** Create the card (status row only) and reply/send it. Returns the posted
+     *  message id so the orchestrator can chain the next response's card under it. */
+    start(replyTo: {
+        messageId?: string;
+        replyInThread: boolean;
+    }): Promise<{
+        messageId?: string;
+    }>;
+    applyEvent(event: SessionEvent): void;
+    /** Set/replace the transient status banner (amber note in the status row). */
+    setStatusNote(note: string | null): void;
+    private clearStatusNote;
+    finalize(status: "completed" | "failed" | "cancelled"): Promise<void>;
+    private applyItem;
+    /** A fresh, Feishu-legal element_id (letter-prefixed, ≤ 20 chars). */
+    private nextElId;
+    private ensureMessage;
+    private ensureReasoning;
+    private ensureTool;
+    private scheduleFlush;
+    private flush;
+}
+export interface LarkSessionCardControllerOptions {
+    sender: LarkCardSender;
+    session: CardControllerSessionInfo;
+    meta: SessionCardMeta;
+    throttleMs?: number;
+    logger?: LarkCardLogger;
+    stopButton?: StopButtonOptions;
+    /** Called once with the underlying runtime session id (for the CLI mirror). */
+    onRuntimeSession?: (runtimeSessionId: string) => void;
+}
+/**
+ * Orchestrates a turn's {@link SessionEvent} stream into a sequence of per-
+ * response cards. Each `response.created` opens a new card (replied under the
+ * previous one, forming a thread); item/lifecycle events route by `responseId`.
+ */
+export declare class LarkSessionCardController {
+    private readonly opts;
+    private readonly cards;
+    private current;
+    private anchorMessageId?;
+    private readonly replyInThread;
+    private notedRuntimeSession;
+    private started;
+    /** Accumulated assistant text, used only as a chat fallback if no card opened. */
+    private fallback;
+    constructor(opts: LarkSessionCardControllerOptions);
+    /** Whether at least one response card was successfully posted. */
+    get cardStarted(): boolean;
+    /** The assistant text (for a plain-text reply when no card could be shown). */
+    get fallbackText(): string;
+    ingest(event: SessionEvent): Promise<void>;
+    /** Finalize any still-open cards (safety net on stream end / throw). */
+    finalizeAll(status: "completed" | "failed" | "cancelled"): Promise<void>;
+}
+export {};