@masterxinxin/lark-coding-agent-bridge 0.0.0-stage → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+type AgentEvent = {
+    type: 'system';
+    sessionId?: string;
+    threadId?: string;
+    cwd?: string;
+    model?: string;
+} | {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'final_text';
+    content: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+    title?: string;
+} | {
+    type: 'tool_result';
+    id: string;
+    output: string;
+    isError: boolean;
+} | {
+    /**
+     * Agent paused mid-run waiting for the user to approve / reject a tool
+     * call. Only opencode emits this today; Claude and Codex have their own
+     * non-interactive permission flows. The bridge must call
+     * AgentRun.respondToPermission(id, ...) to release the agent — the SSE
+     * stream keeps flowing during the wait, but no `done` will arrive until
+     * the request is answered (or auto-rejected on timeout).
+     */
+    type: 'permission_request';
+    id: string;
+    tool: string;
+    input?: unknown;
+    description?: string;
+} | {
+    type: 'usage';
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    reasoningOutputTokens?: number;
+    costUsd?: number;
+} | {
+    type: 'done';
+    sessionId?: string;
+    threadId?: string;
+    terminationReason: 'normal' | 'interrupted' | 'timeout';
+} | {
+    type: 'error';
+    message: string;
+    terminationReason: 'failed' | 'interrupted' | 'timeout';
+    /**
+     * Optional session correlation. Only opencode populates it today
+     * (the upstream `NormalizedEvent` carries `sessionID` and the
+     * translator forwards it); claude/codex emit `error` without it.
+     * Callers MUST tolerate its absence.
+     */
+    sessionId?: string;
+};
+
+type ToolStatus = 'running' | 'done' | 'error';
+interface ToolEntry {
+    id: string;
+    name: string;
+    input: unknown;
+    status: ToolStatus;
+    output?: string;
+    /** Optional human-readable title from upstream (opencode populates this; Claude/Codex don't). */
+    title?: string;
+}
+interface RunUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    reasoningOutputTokens?: number;
+    costUsd?: number;
+}
+type Block = {
+    kind: 'text';
+    content: string;
+    streaming: boolean;
+} | {
+    kind: 'tool';
+    tool: ToolEntry;
+};
+type FooterStatus = 'thinking' | 'tool_running' | 'streaming' | null;
+type Terminal = 'running' | 'done' | 'interrupted' | 'error' | 'idle_timeout';
+interface RunState {
+    blocks: Block[];
+    finalText?: string;
+    reasoning: {
+        content: string;
+        active: boolean;
+    };
+    footer: FooterStatus;
+    terminal: Terminal;
+    errorMsg?: string;
+    /** Set when terminal === 'idle_timeout' — how long claude was idle before
+     * the watchdog gave up (so the message can say "N 分钟无响应"). */
+    idleTimeoutMinutes?: number;
+    /** Model reported by the agent's `system` event, if any. */
+    model?: string;
+    /** Aggregated token/cost usage for the run, if the agent reported it. */
+    usage?: RunUsage;
+}
+declare const initialState: RunState;
+declare function reduce(state: RunState, evt: AgentEvent): RunState;
+declare function markInterrupted(state: RunState): RunState;
+declare function finalizeIfRunning(state: RunState): RunState;
+
+interface RunCardRenderOptions {
+    signCallback?: (action: string) => string;
+    /**
+     * Optional banner shown at the top of the card. Used by the wake-up
+     * watcher to signal "this card is the bot continuing on its own after a
+     * background task finished, not a reply to a user message you just sent".
+     */
+    headerBanner?: string;
+    /** Display name for the card header title (e.g. "opencode"). */
+    agentName?: string;
+    /** Epoch ms when the run started — enables the elapsed-time footer chip. */
+    startedAt?: number;
+    /** Override "now" for deterministic renders (tests). Defaults to Date.now(). */
+    now?: number;
+}
+declare function renderCard(state: RunState, options?: RunCardRenderOptions): object;
+
+/**
+ * Render `RunState` as plain markdown text — used in `messageReply: 'text'`
+ * mode where we stream a markdown message instead of a card.
+ *
+ * Differences vs `renderCard`:
+ *   - No collapsible panels, no buttons (markdown messages have neither)
+ *   - Tool calls collapse to a single short line each (no body)
+ *   - No reasoning / thinking output (no place to fold it; would be noise)
+ *   - Footer is appended inline at the bottom while running
+ */
+declare function renderText(state: RunState): string;
+
+/**
+ * Structured logger.
+ *
+ * Two destinations on every call:
+ *  1. JSON line into the active profile logs directory — the durable
+ *     record `/doctor` greps over.
+ *  2. Compact human-readable line on stdout/stderr — for live tailing in dev.
+ *
+ * Per-message context (traceId, chatId, msgId) is propagated automatically
+ * via AsyncLocalStorage; call `withTrace()` once at the entry point and any
+ * downstream `log.*` calls pick up the same fields.
+ */
+interface LogContext {
+    traceId?: string;
+    chatId?: string;
+    msgId?: string;
+}
+type LogFields = Record<string, unknown>;
+declare function reportMetric(name: string, value: number, tags?: Record<string, string>): void;
+declare function reportError(err: unknown, ctx?: Record<string, unknown>): void;
+
+/**
+ * Optional telemetry hook.
+ *
+ * The bridge itself ships **no** telemetry: by default this module is inert
+ * (a noop adapter), pulls in zero dependencies, and makes zero network calls.
+ *
+ * An operator who wants monitoring points `LARK_CHANNEL_TELEMETRY_MODULE` at a
+ * package that default-exports (or exposes `createAdapter`) an `AdapterFactory`.
+ * That package — not this repo — owns the vendor SDK, endpoints, and keys.
+ * See README "Optional telemetry".
+ */
+/** A single structured event — mirrors what `logger.emit` produces. */
+interface TelemetryEvent {
+    level: 'info' | 'warn' | 'error';
+    phase: string;
+    event: string;
+    fields: LogFields;
+    ctx: LogContext;
+    /** ISO-8601 timestamp, same value written to the JSON log line. */
+    ts: string;
+}
+/** Sink an external package provides to receive bridge telemetry. */
+interface TelemetryAdapter {
+    /** Called for every `log.*` call (info / warn / error). */
+    emit(event: TelemetryEvent): void;
+    /** Capture an error/exception with its stack. */
+    recordError(err: unknown, ctx?: Record<string, unknown>): void;
+    /** Record a numeric metric with optional string tags. */
+    recordMetric(name: string, value: number, tags?: Record<string, string>): void;
+    /** Flush buffered events; `timeoutMs` bounds the wait. Optional. */
+    flush?(timeoutMs?: number): Promise<void> | void;
+    /** Release resources on shutdown. Optional. */
+    close?(): Promise<void> | void;
+}
+/** Runtime metadata handed to the factory when the adapter is loaded. */
+interface AdapterMeta {
+    version: string;
+    appId?: string;
+    tenant?: string;
+    /** Host machine identifier (e.g. `os.hostname()`). Useful as a stable
+     *  `deviceId` for the telemetry sink — survives process restarts. */
+    hostname?: string;
+}
+/** The shape an external module must default-export (or expose as `createAdapter`). */
+type AdapterFactory = (meta: AdapterMeta) => TelemetryAdapter;
+
+export { type AdapterFactory, type AdapterMeta, type Block, type FooterStatus, type RunState, type TelemetryAdapter, type TelemetryEvent, type Terminal, type ToolEntry, type ToolStatus, finalizeIfRunning, initialState, markInterrupted, reduce, renderCard, renderText, reportError, reportMetric };