lark-remote 0.1.0

package/dist/runner/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Runner 模块类型定义
+ *
+ * 本文件包含所有 Agent 相关的类型定义，从 runner/index.ts 提取。
+ * 所有下游模块应从本文件 import 类型，而非直接依赖实现。
+ */
+export interface SystemInitEvent {
+    type: 'system';
+    subtype: 'init';
+    session_id: string;
+    cwd: string;
+    model: string;
+    timestamp?: string;
+}
+interface SystemCompactEvent {
+    type: 'system';
+    subtype: 'compact_boundary';
+    timestamp?: string;
+    compactMetadata?: {
+        postTokens: number;
+        preTokens: number;
+    };
+}
+interface ThinkingContent {
+    type: 'thinking';
+    thinking: string;
+}
+interface TextContent {
+    type: 'text';
+    text: string;
+}
+interface ToolUseContent {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+}
+interface ToolResultContent {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: unknown;
+    is_error: boolean;
+}
+export type AssistantContent = ThinkingContent | TextContent | ToolUseContent;
+export interface AssistantEvent {
+    type: 'assistant';
+    timestamp?: string;
+    message: {
+        content: AssistantContent[];
+    };
+}
+export interface UserEvent {
+    type: 'user';
+    timestamp?: string;
+    message: {
+        content: ToolResultContent[];
+    };
+}
+export interface ResultEvent {
+    type: 'result';
+    subtype: 'success' | 'error';
+    session_id: string;
+    timestamp?: string;
+    usage?: {
+        /** Non-cached input tokens. For codex this is raw `input_tokens` minus
+         *  `cached_input_tokens`; for pi/claude/opencode the raw value is already
+         *  non-cached. Aligns with ccusage's displayed-input semantics. */
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens?: number;
+        /** Cache-write (prompt-cache creation) tokens. Codex has none (0). */
+        cache_creation_tokens?: number;
+        /** Anthropic 原生命名，claude CLI 的 result 事件使用此字段名。 */
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+        /** Agent-declared total; when present the display uses max(total, sum of parts). */
+        total_tokens?: number;
+    };
+    total_cost_usd?: number;
+    errorMessage?: string;
+}
+/** TokenUsage = ResultEvent['usage'] without the optional wrapper.
+ *
+ *  Usage sites that have already checked `event.usage` is present can type the
+ *  value as `TokenUsage` to avoid repeated `!` assertions.
+ */
+export type TokenUsage = NonNullable<ResultEvent['usage']>;
+/** Plan event — for agents that report execution plans (e.g. Codex). */
+export interface PlanEvent {
+    type: 'plan';
+    plan: string;
+    timestamp?: string;
+}
+/** File change event — for agents that report file modifications (e.g. Codex). */
+export interface FileChangeEvent {
+    type: 'file_change';
+    path: string;
+    diff?: string;
+    operation: 'create' | 'edit' | 'delete' | 'read';
+    timestamp?: string;
+}
+export type AgentEvent = SystemInitEvent | SystemCompactEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent;
+export interface SpawnOptions {
+    cwd: string;
+    sessionId?: string;
+    model?: string;
+    effort?: string;
+    /** Codex reasoning effort override (per-run, takes precedence over constructor default). */
+    reasoningEffort?: string;
+    settings?: string;
+}
+/**
+ * Seam (§3): the contract any agent runner (claude/codex/opencode/pi/kimi)
+ * must satisfy for the router/bridge.
+ * Declared here so callers depend on the interface, not the concrete
+ * runner classes — test stubs satisfy this structurally.
+ */
+export interface Runner {
+    readonly isRunning: boolean;
+    run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Stop the running process. SIGTERM → grace → SIGKILL on the per-workspace
+     * proc. `immediate: true` skips the grace period and SIGKILLs directly
+     * (used by user-initiated `/stop`).
+     */
+    stop(opts?: {
+        immediate?: boolean;
+    }): Promise<void>;
+    killOrphan(): void;
+    registerExitHandlers(): void;
+    /**
+     * Remove the runner from the process-level exit dispatcher (P1-1). Called by
+     * the bridge when the (cwd, kind) cache slot is evicted so the instance is
+     * not retained by the singleton dispatcher. Optional so test stubs that only
+     * satisfy `registerExitHandlers` remain structurally valid.
+     */
+    unregisterExitHandlers?(): void;
+}
+export type AgentKind = 'claude' | 'codex' | 'opencode' | 'pi' | 'kimi';
+/** Unified session descriptor returned by every AgentSessionReader. */
+export interface AgentSession {
+    sessionId: string;
+    summary: string;
+    mtime: number;
+}
+/** A single renderable event from session history. */
+export interface AgentSessionContentEvent {
+    type: string;
+    content: string;
+    timestamp?: string;
+}
+export interface AgentSessionUsage {
+    inputTokens: number;
+    outputTokens: number;
+    contextLength: number;
+    /** Claude auto-compact 次数（数 compact_boundary 事件）；codex/opencode 无此概念，留 undefined。 */
+    compactCount?: number;
+    /** 从缓存读取的 token 数（节省的费用）。 */
+    cacheReadTokens?: number;
+    /** 新建缓存的 token 数。 */
+    cacheCreationTokens?: number;
+    /** Agent 声明的总量；展示用 max(total, 分项和)。 */
+    totalTokens?: number;
+    /** 会话累计 total token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
+    cumulativeTotalTokens?: number;
+    /** 会话累计 input token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
+    cumulativeInputTokens?: number;
+    /** 会话累计 output token（所有 run 之和，含本次）。 */
+    cumulativeOutputTokens?: number;
+    /** 会话累计 cache read token（所有 run 之和）。用于 Run 卡片展示累计缓存命中。 */
+    cumulativeCacheReadTokens?: number;
+    /** 会话累计 cache creation token（所有 run 之和）。 */
+    cumulativeCacheCreationTokens?: number;
+}
+/** Unified session content payload returned by every AgentSessionReader. */
+export interface SessionContent {
+    events: AgentSessionContentEvent[];
+    usage?: AgentSessionUsage;
+    aiTitle?: string;
+    recap?: string;
+    displayTitle?: string;
+}
+/**
+ * Reads an agent's session history. Each agent implements its own (Claude reads
+ * `~/.claude/projects/`, Codex calls `thread/list`, OpenCode calls `GET /session`).
+ *
+ * Q-C decision: `projectsDir` and other agent-specific path config live on the
+ * concrete reader's constructor, NOT on these method opts. The router/bridge
+ * depend only on this interface and never pass path config.
+ */
+export interface AgentSessionReader {
+    /**
+     * List sessions for a cwd, newest first by mtime.
+     *
+     * `sessions` is the page `[offset, offset+limit)` of the full set ordered
+     * by mtime desc, with same-mtime ties broken by a deterministic secondary
+     * key (sessionId/file path) so ordering is stable across calls. When
+     * `limit` is omitted, codex/pi/kimi return their default-sized page
+     * (default 20); claude/opencode return the full remaining set from
+     * `offset`. `total` is ALWAYS the size of the full cwd-matched set before
+     * pagination — never the truncated page length. A negative `offset` is
+     * clamped to 0 (first page).
+     */
+    listSessions(cwd: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): {
+        sessions: AgentSession[];
+        total: number;
+    };
+    getNewestSession(cwd: string): AgentSession | null;
+    readSessionContent(sessionId: string, cwd: string, opts?: {
+        maxEvents?: number;
+    }): SessionContent;
+    /**
+     * Whether a session is still active (process may still be running).
+     *
+     * Dormant API: no production caller reads this today — the router decides
+     * "is an agent running" via the in-memory `bridge.isBusyFor(cwd)` (see
+     * `cmdPs`), not by probing session files. Retained on the reader contract
+     * because all 5 readers implement it and it is the natural hook if a
+     * file-based liveness check is ever needed; not wired into the bridge.
+     */
+    isSessionActive(sessionId: string, cwd: string): boolean;
+}
+/**
+ * AgentRunner extends Runner with agent identity and a session reader.
+ * Bridge/Router depend on this interface so adding a new agent is
+ * "implement AgentRunner + register" with zero upstream changes.
+ */
+export interface AgentRunner extends Runner {
+    readonly kind: AgentKind;
+    readonly sessionReader: AgentSessionReader;
+    /** Return current status info for /status display. */
+    getStatusInfo(): AgentStatusInfo;
+}
+/** Agent self-describing status info for /status display. */
+export interface AgentStatusInfo {
+    /** Agent kind (claude/codex/opencode/pi/kimi). */
+    kind: AgentKind;
+    /** Display model name. */
+    model: string;
+    /** Optional provider name. */
+    provider?: string;
+    /** Reasoning/thinking level. */
+    reasoning?: string;
+    /** Agent-specific extra fields (e.g. codex.sandbox). */
+    extras?: Record<string, string>;
+}
+export {};

package/dist/runner/types.js

@@ -0,0 +1,8 @@
+/**
+ * Runner 模块类型定义
+ *
+ * 本文件包含所有 Agent 相关的类型定义，从 runner/index.ts 提取。
+ * 所有下游模块应从本文件 import 类型，而非直接依赖实现。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/session/claude/index.d.ts

@@ -0,0 +1 @@
+export { ClaudeSessionReader } from './session-reader.js';

package/dist/session/claude/index.js

@@ -0,0 +1,2 @@
+export { ClaudeSessionReader } from './session-reader.js';
+//# sourceMappingURL=index.js.map

package/dist/session/claude/session-reader.d.ts

@@ -0,0 +1,34 @@
+import type { AgentSession, AgentSessionReader, SessionContent } from '../../runner/index.js';
+/**
+ * Adapter that exposes Claude Code's session-reading functions through the
+ * unified `AgentSessionReader` interface. This lets `SessionReaderRegistry`
+ * treat Claude / Codex / OpenCode uniformly.
+ *
+ * Q-C decision: `projectsDir` lives on the reader (not the router). The router
+ * injects a reader configured with its test `projectsDir`; production code
+ * uses the default (`~/.claude/projects/`).
+ *
+ * All methods are thin wrappers around `claude-sessions.ts` exports — zero
+ * behavior change. Router and bridge reach session data exclusively through
+ * this reader (via `SessionReaderRegistry`); the underlying functions remain
+ * exported for tests and the reader itself.
+ */
+export declare class ClaudeSessionReader implements AgentSessionReader {
+    private readonly projectsDir?;
+    constructor(opts?: {
+        projectsDir?: string;
+    });
+    listSessions(cwd: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): {
+        sessions: AgentSession[];
+        total: number;
+    };
+    getNewestSession(cwd: string): AgentSession | null;
+    readSessionContent(sessionId: string, cwd: string, opts?: {
+        maxEvents?: number;
+    }): SessionContent;
+    isSessionActive(sessionId: string, cwd: string): boolean;
+    private readerOpts;
+}

package/dist/session/claude/session-reader.js

@@ -0,0 +1,46 @@
+import { listClaudeSessions, getNewestSession, readSessionContent, isClaudeSessionActive, } from '../../session/claude/sessions.js';
+/**
+ * Adapter that exposes Claude Code's session-reading functions through the
+ * unified `AgentSessionReader` interface. This lets `SessionReaderRegistry`
+ * treat Claude / Codex / OpenCode uniformly.
+ *
+ * Q-C decision: `projectsDir` lives on the reader (not the router). The router
+ * injects a reader configured with its test `projectsDir`; production code
+ * uses the default (`~/.claude/projects/`).
+ *
+ * All methods are thin wrappers around `claude-sessions.ts` exports — zero
+ * behavior change. Router and bridge reach session data exclusively through
+ * this reader (via `SessionReaderRegistry`); the underlying functions remain
+ * exported for tests and the reader itself.
+ */
+export class ClaudeSessionReader {
+    projectsDir;
+    constructor(opts = {}) {
+        this.projectsDir = opts.projectsDir;
+    }
+    listSessions(cwd, opts) {
+        // 先拿全集（不传 limit → listClaudeSessions 不切片），total 用全集长度，
+        // 再由 reader 按 [offset, offset+limit) 切片。
+        const all = listClaudeSessions(cwd, this.readerOpts());
+        const offset = Math.max(0, opts?.offset ?? 0);
+        const limit = opts?.limit;
+        return {
+            sessions: limit === undefined ? all.slice(offset) : all.slice(offset, offset + limit),
+            total: all.length,
+        };
+    }
+    getNewestSession(cwd) {
+        const session = getNewestSession(cwd, this.readerOpts());
+        return session ?? null;
+    }
+    readSessionContent(sessionId, cwd, opts) {
+        return readSessionContent(sessionId, cwd, { ...this.readerOpts(), ...opts });
+    }
+    isSessionActive(sessionId, cwd) {
+        return isClaudeSessionActive(sessionId, cwd, this.readerOpts());
+    }
+    readerOpts() {
+        return this.projectsDir ? { projectsDir: this.projectsDir } : {};
+    }
+}
+//# sourceMappingURL=session-reader.js.map

package/dist/session/claude/sessions.d.ts

@@ -0,0 +1,53 @@
+import type { AgentSession, AgentSessionContentEvent, AgentSessionUsage } from '../../runner/index.js';
+/**
+ * Read cwd from a Claude session JSONL by scanning events for the first
+ * `cwd` field. Claude CLI writes the absolute (symlink-resolved) cwd on
+ * every event that produces one; older versions wrote it once on init.
+ * Returns the first non-empty value, or undefined if absent.
+ *
+ * This is the SOLE source of truth for cwd. The directory name under
+ * ~/.claude/projects/ is lossy (encodes `/` AND `_` as `-`), so it cannot
+ * be decoded back to a real path. See regression 2026-06-21 /resume & /cd 路径错乱.
+ */
+export declare function readCwdFromJsonl(filePath: string): string | undefined;
+/**
+ * List Claude Code sessions for a given cwd, newest first. Each entry has
+ * the sessionId (= jsonl filename stem), a one-line summary extracted from
+ * the first user message, and the file mtime. Returns an empty array when
+ * the project directory doesn't exist or no jsonl has a matching cwd field.
+ *
+ * We locate the directory via `projectDirForCwd` (lossy but OK for locating
+ * a known cwd) and then **verify** each jsonl's cwd field matches. This
+ * prevents collision: `my_disk/foo` and `my-disk/foo` both encode to the same
+ * directory name, but only the matching cwd field is kept.
+ */
+export declare function listClaudeSessions(cwd: string, opts?: {
+    limit?: number;
+    projectsDir?: string;
+}): AgentSession[];
+/** Get the newest session for a given cwd. Returns undefined if none exist. */
+export declare function getNewestSession(cwd: string, opts?: {
+    projectsDir?: string;
+}): AgentSession | undefined;
+/**
+ * Check if a Claude session (by sessionId + cwd) is still active.
+ * Public wrapper around the internal `isSessionActive(filePath, mtimeMs, now)`
+ * for use by `ClaudeSessionReader` and the multi-agent adapter layer.
+ *
+ * Resolves the jsonl path via `projectDirForCwd`, stats it for mtime, then
+ * applies the same mtime-freshness + terminal-marker heuristic
+ * used for session-active detection. Returns false if the file doesn't exist.
+ */
+export declare function isClaudeSessionActive(sessionId: string, cwd: string, opts?: {
+    projectsDir?: string;
+}): boolean;
+export declare function readSessionContent(sessionId: string, cwd: string, opts?: {
+    projectsDir?: string;
+    maxEvents?: number;
+}): {
+    events: AgentSessionContentEvent[];
+    usage?: AgentSessionUsage;
+    aiTitle?: string;
+    recap?: string;
+    displayTitle?: string;
+};