lark-remote 0.1.0

package/dist/session/codex/rollout-reader.js

@@ -0,0 +1,473 @@
+/**
+ * Codex Rollout File Reader.
+ *
+ * Reads Codex session history from rollout JSONL files in `~/.codex/sessions/`.
+ *
+ * Rollout file format (appendix C in design doc):
+ * ```
+ * {"timestamp":"...","type":"session_meta","payload":{"session_id":"...","cwd":"...","originator":"lark-remote",...}}
+ * {"timestamp":"...","type":"event_msg","payload":{"type":"task_started","turn_id":"..."}}
+ * {"timestamp":"...","type":"response_item","payload":{"type":"message","role":"user|developer","content":[...]}}
+ * ```
+ *
+ * Note: This handles the **rollout file format** (historical logging), NOT the
+ * `codex exec --json` stdout format. Those are two different JSONL formats
+ * (see design doc appendix B vs C).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonlLines, findJsonlLine } from '../common/jsonl.js';
+import { getLogger } from '../../logger/index.js';
+import { isRecord, stringValue } from '../../common/guards.js';
+import { resolveCodexHome } from '../../config/codex-config.js';
+/** Field-wise difference (total - previous) for cumulative->incremental. */
+function subtractRawUsage(a, b) {
+    return {
+        input_tokens: a.input_tokens - b.input_tokens,
+        cached_input_tokens: a.cached_input_tokens - b.cached_input_tokens,
+        output_tokens: a.output_tokens - b.output_tokens,
+        total_tokens: a.total_tokens - b.total_tokens,
+    };
+}
+export function readCodexRollout(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const lines = readJsonlLines(filePath);
+        const events = [];
+        let sessionMeta = null;
+        // Real user input is identified by a paired `event_msg` whose
+        // payload.type === "user_message" - codex emits this ONLY for text the
+        // human actually typed. Injected scaffolding (AGENTS.md project rules,
+        // <environment_context>, permissions) is also written as `role:"user"`
+        // response_items but has NO user_message event, so it must be excluded
+        // from displayTitle/recap/summary. Regression 2026-07-13: the first
+        // `role:user` message is the injected AGENTS.md, mistakenly shown as
+        // "最近输入".
+        const realUserMessages = [];
+        // token_count tracking: codex emits cumulative `total_token_usage` and an
+        // incremental `last_token_usage`. We want the LAST turn's usage (matches
+        // pi/opencode /resume "last turn" display semantics). When
+        // last_token_usage is absent we derive it as total - previous_total.
+        let lastRawUsage;
+        // Final total_token_usage (cumulative across the whole session) for the
+        // Run card's "累计" display. Codex emits this alongside last_token_usage.
+        let lastTotalUsage;
+        let previousTotals;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (!parsed || typeof parsed.type !== 'string')
+                    continue;
+                if (parsed.type === 'session_meta' && parsed.payload) {
+                    sessionMeta = parsed.payload;
+                }
+                else if (parsed.type === 'event_msg' && parsed.payload) {
+                    // user_message events carry the authoritative human-typed text.
+                    const payload = parsed.payload;
+                    if (payload.type === 'user_message') {
+                        const text = stringValue(payload.message);
+                        if (text) {
+                            realUserMessages.push(text.slice(0, 200));
+                        }
+                    }
+                    else if (payload.type === 'token_count') {
+                        const info = payload.info;
+                        const last = info?.last_token_usage;
+                        const total = info?.total_token_usage;
+                        let raw;
+                        if (last) {
+                            raw = last;
+                        }
+                        else if (total && previousTotals) {
+                            raw = subtractRawUsage(total, previousTotals);
+                        }
+                        else {
+                            raw = total;
+                        }
+                        if (total) {
+                            previousTotals = total;
+                            lastTotalUsage = total;
+                        }
+                        if (raw && (raw.input_tokens || raw.cached_input_tokens || raw.output_tokens)) {
+                            lastRawUsage = raw;
+                        }
+                    }
+                }
+                else if (parsed.type === 'response_item' && parsed.payload) {
+                    const payload = parsed.payload;
+                    if (payload.type === 'message' && Array.isArray(payload.content)) {
+                        // Extract text content for display
+                        const messages = extractMessageContent(payload);
+                        for (const msg of messages) {
+                            events.push({
+                                type: msg.role === 'user' ? 'user' : 'assistant',
+                                content: msg.text,
+                                timestamp: parsed.timestamp,
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                // Skip malformed lines
+                continue;
+            }
+        }
+        const firstUserMessage = realUserMessages[0] ?? '';
+        const lastRealUserMessage = realUserMessages[realUserMessages.length - 1] ?? '';
+        if (!sessionMeta) {
+            return null;
+        }
+        const sessionId = stringValue(sessionMeta.session_id) ?? stringValue(sessionMeta.id) ?? '';
+        const cwd = stringValue(sessionMeta.cwd) ?? '';
+        if (!sessionId) {
+            return null;
+        }
+        // Use file mtime as updatedAtMs, or parse timestamp from session_meta
+        const stats = fs.statSync(filePath);
+        const createdAtMs = sessionMeta.timestamp
+            ? new Date(String(sessionMeta.timestamp)).getTime()
+            : stats.birthtimeMs;
+        const updatedAtMs = stats.mtimeMs;
+        // Build ccusage-aligned usage from the last turn's raw tokens.
+        // input = raw - cached (codex reports cached input separately), cache
+        // creation is never reported by codex, reasoning is a subset of output
+        // (display-only, never added to total).
+        // contextLength = input_tokens (= (input_tokens-cached) + cached + 0),
+        // i.e. input + cacheRead + cacheCreation — the unified context-window
+        // occupancy contract across all five readers (review P2-8, excludes
+        // output/reasoning).
+        let usage;
+        if (lastRawUsage) {
+            const r = lastRawUsage;
+            const cached = Math.min(r.cached_input_tokens, r.input_tokens);
+            usage = {
+                inputTokens: r.input_tokens - cached,
+                outputTokens: r.output_tokens,
+                contextLength: r.input_tokens,
+                cacheReadTokens: cached,
+                cacheCreationTokens: 0,
+                totalTokens: r.total_tokens,
+            };
+            // Cumulative from the final total_token_usage (non-cached input +
+            // output), summed across all turns in the session.
+            if (lastTotalUsage) {
+                const cumCached = Math.min(lastTotalUsage.cached_input_tokens, lastTotalUsage.input_tokens);
+                usage.cumulativeInputTokens = lastTotalUsage.input_tokens - cumCached;
+                usage.cumulativeOutputTokens = lastTotalUsage.output_tokens;
+                usage.cumulativeTotalTokens = lastTotalUsage.total_tokens;
+                usage.cumulativeCacheReadTokens = cumCached;
+                usage.cumulativeCacheCreationTokens = 0; // Codex 不报告 cache creation
+            }
+        }
+        return {
+            threadId: sessionId,
+            cwd,
+            firstUserMessage: firstUserMessage || '(no user message)',
+            lastRealUserMessage,
+            createdAtMs,
+            updatedAtMs,
+            events,
+            usage,
+        };
+    }
+    catch (err) {
+        getLogger().warn(`[codex-rollout-reader] failed to read ${filePath}: ${err}`);
+        return null;
+    }
+}
+/**
+ * List Codex sessions from rollout files.
+ *
+ * Returns `{ entries, total }`: `total` is the size of the full cwd-matched
+ * set before pagination; `entries` are the newest `limit` entries by mtime.
+ *
+ * A global order over the full set is established first (plan §1.4: no early
+ * termination before ordering) using the lightweight session index — full
+ * walk + first-line session_meta parse + stat mtime, 5s TTL cache. Only the
+ * returned page is fully parsed for summary/usage (plan §2.2).
+ */
+export function listCodexRollouts(opts = {}) {
+    const codexHome = resolveCodexHome(opts.codexHome);
+    const limit = opts.limit ?? 20;
+    const offset = Math.max(0, opts.offset ?? 0);
+    const filterCwd = opts.cwd;
+    // Full index: every rollout file's session_meta + mtime, no early break.
+    const index = getSessionIndex(codexHome);
+    const matched = [];
+    for (const entry of index.values()) {
+        // Subagent thread rollouts are part of a thread tree, not standalone
+        // sessions: exclude them explicitly (plan §2.1) so a pure-subagent
+        // session (main file missing) never pollutes the list or total.
+        if (entry.isSubagent)
+            continue;
+        if (filterCwd && entry.cwd !== filterCwd)
+            continue;
+        matched.push(entry);
+    }
+    // Establish the global order by mtime desc, then slice the page.
+    // Same-mtime ties use filePath as a deterministic secondary key so index
+    // rebuilds / walk order changes never reorder the page.
+    matched.sort((a, b) => b.mtimeMs - a.mtimeMs || a.filePath.localeCompare(b.filePath));
+    const total = matched.length;
+    const page = matched.slice(offset, offset + limit);
+    // Full-parse only the page being returned (summary/usage).
+    const entries = [];
+    for (const item of page) {
+        const entry = readCodexRollout(item.filePath);
+        if (entry)
+            entries.push(entry);
+    }
+    return { entries, total };
+}
+/**
+ * Read the full content of a specific session by its threadId.
+ *
+ * P2-4: Uses session index for O(1) file lookup instead of walking the
+ * entire directory tree and fully parsing every file. Only the matching
+ * file is fully parsed.
+ *
+ * `maxEvents` (optional): when set, only the LAST `maxEvents` events are
+ * returned (most recent activity). This matches the auto-resume use case
+ * ("show recent history") and keeps the card payload small. Unlike claude,
+ * codex events are already at message granularity (no multi-block split),
+ * so a hard `slice(-maxEvents)` is sufficient — no soft-cap complication.
+ */
+export function readCodexSessionContent(sessionId, opts = {}) {
+    const codexHome = resolveCodexHome(opts.codexHome);
+    // P2-4: Use session index for direct file lookup
+    let index = getSessionIndex(codexHome);
+    let entry = index.get(sessionId);
+    // P3-2: On miss, the index may be stale (a rollout file created after the
+    // cache was built but within the 5s TTL). Force a refresh and recheck so a
+    // brand-new session is found without waiting for TTL expiry.
+    if (!entry) {
+        index = getSessionIndex(codexHome, true);
+        entry = index.get(sessionId);
+    }
+    if (!entry) {
+        return { events: [] };
+    }
+    const rollout = readCodexRollout(entry.filePath);
+    if (!rollout || rollout.threadId !== sessionId) {
+        return { events: [] };
+    }
+    // Apply maxEvents cap: keep the LAST N events (most recent).
+    // See function docstring for rationale.
+    // P2-7: maxEvents <= 0 returns [] — guards the `slice(-0) === slice(0)`
+    // full-array trap (no caller passes 0 today, but the contract must hold).
+    const events = opts.maxEvents !== undefined && opts.maxEvents > 0 && rollout.events.length > opts.maxEvents
+        ? rollout.events.slice(-opts.maxEvents)
+        : opts.maxEvents !== undefined && opts.maxEvents <= 0
+            ? []
+            : rollout.events;
+    return {
+        events,
+        // displayTitle = LAST real user message (matches the
+        // "最近输入" label). recap is undefined: codex has no
+        // compact-summary concept, so never fake one from a user
+        // message (was: firstUserMessage = injected AGENTS.md).
+        displayTitle: rollout.lastRealUserMessage
+            ? rollout.lastRealUserMessage.slice(0, 50)
+            : undefined,
+        recap: undefined,
+        usage: rollout.usage,
+    };
+}
+/**
+ * Check if a session is still active (recently updated).
+ *
+ * P2-4: Uses session index for direct file lookup, then checks mtime
+ * via statSync — no full rollout parse required. This reduces the
+ * cost from "walk entire directory + full-parse every file" to a single
+ * statSync call for the matching file.
+ */
+export function isCodexSessionActive(sessionId, opts = {}) {
+    const codexHome = resolveCodexHome(opts.codexHome);
+    const threshold = opts.activeThresholdMs ?? 10 * 60 * 1000; // 10 minutes default
+    // P2-4: Use session index for direct file lookup + mtime check
+    let index = getSessionIndex(codexHome);
+    let entry = index.get(sessionId);
+    // P3-2: On miss, refresh the index in case the session file was created
+    // after the cache was built (within the 5s TTL). See readCodexSessionContent.
+    if (!entry) {
+        index = getSessionIndex(codexHome, true);
+        entry = index.get(sessionId);
+    }
+    if (!entry) {
+        return false;
+    }
+    // Subagent thread rollouts are never "active sessions": their mtime
+    // reflects thread-tree activity, not the parent session's liveness
+    // (plan §2.1). A pure-subagent session must report inactive.
+    if (entry.isSubagent) {
+        return false;
+    }
+    // Re-stat to get fresh mtime (index may be up to INDEX_TTL_MS stale)
+    try {
+        const stat = fs.statSync(entry.filePath);
+        return Date.now() - stat.mtimeMs < threshold;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk the YYYY/MM/DD directory tree under `sessionsDir` and return all
+ * rollout-*.jsonl file paths. Silently skips non-directory entries and
+ * malformed names; returns an empty array if `sessionsDir` doesn't exist
+ * or is unreadable.
+ */
+function walkRolloutFiles(sessionsDir) {
+    if (!fs.existsSync(sessionsDir))
+        return [];
+    const result = [];
+    try {
+        const years = fs.readdirSync(sessionsDir);
+        for (const year of years) {
+            if (!/^\d{4}$/.test(year))
+                continue;
+            const yearPath = path.join(sessionsDir, year);
+            if (!fs.statSync(yearPath).isDirectory())
+                continue;
+            const months = fs.readdirSync(yearPath);
+            for (const month of months) {
+                if (!/^\d{2}$/.test(month))
+                    continue;
+                const monthPath = path.join(yearPath, month);
+                if (!fs.statSync(monthPath).isDirectory())
+                    continue;
+                const days = fs.readdirSync(monthPath);
+                for (const day of days) {
+                    if (!/^\d{2}$/.test(day))
+                        continue;
+                    const dayPath = path.join(monthPath, day);
+                    if (!fs.statSync(dayPath).isDirectory())
+                        continue;
+                    const files = fs
+                        .readdirSync(dayPath)
+                        .filter((f) => f.startsWith('rollout-') && f.endsWith('.jsonl'));
+                    for (const file of files) {
+                        result.push(path.join(dayPath, file));
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        getLogger().warn(`[codex-rollout-reader] failed to walk sessions dir: ${err}`);
+    }
+    return result;
+}
+const INDEX_TTL_MS = 5_000; // 5 seconds — covers a single /resume flow
+const sessionIndexCache = new Map();
+/**
+ * Build or return cached session index for a given resolved codexHome.
+ * The index maps sessionId → {filePath, cwd, mtimeMs}.
+ *
+ * @param resolvedCodexHome  Already-resolved codex home path (from resolveCodexHome).
+ * @param forceRefresh       When true, bypass the TTL cache and rebuild. Used
+ *                           on an index MISS (readCodexSessionContent /
+ *                           isCodexSessionActive) so a rollout file created
+ *                           AFTER the cache was built — but still within the
+ *                           5s TTL — is found without waiting for expiry.
+ *
+ * Cache shape note: `sessionIndexCache` is module-level and keyed by the
+ * resolved codexHome string. In production `CodexSessionReader` resolves
+ * codexHome once in its constructor and reuses it for every call, so a single
+ * bridge instance produces exactly one cache entry — the Map does NOT grow
+ * unbounded. The TTL refreshes the value on each rebuild; entries are never
+ * evicted, but there is effectively just one.
+ */
+function getSessionIndex(resolvedCodexHome, forceRefresh = false) {
+    const cacheKey = resolvedCodexHome;
+    const cached = sessionIndexCache.get(cacheKey);
+    if (!forceRefresh && cached && Date.now() - cached.builtAt < INDEX_TTL_MS) {
+        return cached.index;
+    }
+    const sessionsDir = path.join(resolvedCodexHome, 'sessions');
+    const files = walkRolloutFiles(sessionsDir);
+    const index = new Map();
+    for (const filePath of files) {
+        // Use findJsonlLine to extract session_meta without full file parse.
+        // session_meta is always the first line of a rollout file.
+        const metaLine = findJsonlLine(filePath, (line) => {
+            try {
+                const obj = JSON.parse(line);
+                return obj.type === 'session_meta';
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!metaLine)
+            continue;
+        try {
+            const meta = JSON.parse(metaLine);
+            const sessionId = meta.payload?.session_id;
+            if (!sessionId)
+                continue;
+            let mtimeMs;
+            try {
+                mtimeMs = fs.statSync(filePath).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            // Codex multi-agent threads: subagent rollout files share the parent
+            // session's session_id but carry thread_source === 'subagent' (or a
+            // source.subagent marker). Keep only the main-thread file for a given
+            // session id; among files of the same kind pick the newest mtime, with
+            // filePath as a deterministic tie-breaker — resolution never depends on
+            // fs.readdirSync order (APFS hash order is not filename order).
+            const isSubagent = meta.payload?.thread_source === 'subagent' || meta.payload?.source?.subagent !== undefined;
+            const candidate = {
+                filePath,
+                cwd: meta.payload?.cwd ?? '',
+                mtimeMs,
+                isSubagent,
+            };
+            const existing = index.get(sessionId);
+            if (!existing ||
+                (existing.isSubagent && !isSubagent) ||
+                (existing.isSubagent === isSubagent && mtimeMs > existing.mtimeMs) ||
+                (existing.isSubagent === isSubagent &&
+                    mtimeMs === existing.mtimeMs &&
+                    filePath.localeCompare(existing.filePath) < 0)) {
+                index.set(sessionId, candidate);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    sessionIndexCache.set(cacheKey, { index, builtAt: Date.now() });
+    return index;
+}
+/** Clear the session index cache. Exposed for tests. */
+export function clearSessionIndexCache() {
+    sessionIndexCache.clear();
+}
+function extractMessageContent(payload) {
+    const result = [];
+    const content = payload.content;
+    if (!Array.isArray(content)) {
+        return result;
+    }
+    const role = stringValue(payload.role) ?? 'assistant';
+    for (const item of content) {
+        if (!isRecord(item))
+            continue;
+        const text = stringValue(item.text) ?? stringValue(item.input_text);
+        if (text) {
+            result.push({ role, text });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=rollout-reader.js.map

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

@@ -0,0 +1,21 @@
+import type { AgentSession, SessionContent, AgentSessionReader } from '../../runner/index.js';
+interface CodexSessionReaderOptions {
+    codexHome?: string;
+}
+export declare class CodexSessionReader implements AgentSessionReader {
+    private readonly codexHome;
+    constructor(opts?: CodexSessionReaderOptions);
+    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;
+}
+export {};

package/dist/session/codex/sessions.js

@@ -0,0 +1,40 @@
+import { resolveCodexHome } from '../../config/codex-config.js';
+import { listCodexRollouts, readCodexSessionContent, isCodexSessionActive, } from './rollout-reader.js';
+export class CodexSessionReader {
+    codexHome;
+    constructor(opts = {}) {
+        this.codexHome = resolveCodexHome(opts.codexHome);
+    }
+    listSessions(cwd, opts) {
+        const result = listCodexRollouts({
+            codexHome: this.codexHome,
+            cwd,
+            limit: opts?.limit ?? 20,
+            offset: opts?.offset,
+        });
+        return {
+            sessions: result.entries.map((entry) => ({
+                sessionId: entry.threadId,
+                // '(no user message)' 是 reader 的占位符，不是真实输入；给空串由
+                // router 的占位符集合统一过滤。`|| entry.cwd` 永不达（rollout-reader
+                // 已保证 firstUserMessage 非空字符串），去掉以免把 cwd 误当摘要。
+                summary: entry.firstUserMessage === '(no user message)' ? '' : entry.firstUserMessage,
+                mtime: entry.updatedAtMs,
+            })),
+            total: result.total,
+        };
+    }
+    getNewestSession(cwd) {
+        return this.listSessions(cwd, { limit: 1 }).sessions[0] ?? null;
+    }
+    readSessionContent(sessionId, _cwd, opts) {
+        return readCodexSessionContent(sessionId, {
+            codexHome: this.codexHome,
+            maxEvents: opts?.maxEvents,
+        });
+    }
+    isSessionActive(sessionId, _cwd) {
+        return isCodexSessionActive(sessionId, { codexHome: this.codexHome });
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/session/common/catch-up.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Find the index of the last line in a JSONL line array whose parsed object
+ * satisfies the given predicate.
+ *
+ * Invalid JSON, empty, and whitespace-only lines are silently skipped.
+ *
+ * @param lines          Array of raw JSONL line strings.
+ * @param isUserMessage  Predicate that receives the parsed object and returns
+ *                       true for lines considered "user" messages.
+ * @returns The array index of the last matching line, or -1 if none match.
+ */
+export declare function findLastUserIndex(lines: string[], isUserMessage: (obj: Record<string, unknown>) => boolean): number;

package/dist/session/common/catch-up.js

@@ -0,0 +1,31 @@
+/**
+ * Find the index of the last line in a JSONL line array whose parsed object
+ * satisfies the given predicate.
+ *
+ * Invalid JSON, empty, and whitespace-only lines are silently skipped.
+ *
+ * @param lines          Array of raw JSONL line strings.
+ * @param isUserMessage  Predicate that receives the parsed object and returns
+ *                       true for lines considered "user" messages.
+ * @returns The array index of the last matching line, or -1 if none match.
+ */
+export function findLastUserIndex(lines, isUserMessage) {
+    let lastIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (isUserMessage(obj)) {
+            lastIdx = i;
+        }
+    }
+    return lastIdx;
+}
+//# sourceMappingURL=catch-up.js.map

package/dist/session/common/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Session-related constants shared across agent session readers.
+ */
+/**
+ * Threshold (in milliseconds) after which a session is considered inactive.
+ *
+ * Set to 1 hour — well above the typical 15-minute idle watchdog, so a
+ * legitimately paused session is not prematurely marked stale. A file whose
+ * mtime is older than this threshold cannot be from a running process.
+ */
+export declare const STALE_MS: number;

package/dist/session/common/constants.js

@@ -0,0 +1,12 @@
+/**
+ * Session-related constants shared across agent session readers.
+ */
+/**
+ * Threshold (in milliseconds) after which a session is considered inactive.
+ *
+ * Set to 1 hour — well above the typical 15-minute idle watchdog, so a
+ * legitimately paused session is not prematurely marked stale. A file whose
+ * mtime is older than this threshold cannot be from a running process.
+ */
+export const STALE_MS = 60 * 60 * 1000;
+//# sourceMappingURL=constants.js.map

package/dist/session/common/content-blocks.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Parameterized content-block extraction shared across session readers.
+ *
+ * Different agents (Claude, pi, …) use different field names for tool_use /
+ * tool_result blocks. The {@link ContentBlockMapping} type captures those
+ * differences so a single implementation can serve all readers.
+ */
+/** A single extracted content block for rendering. */
+interface ContentBlock {
+    type: 'text' | 'thinking' | 'tool_use' | 'tool_result';
+    content: string;
+}
+/** Maps agent-specific field names to the generic extraction logic. */
+export interface ContentBlockMapping {
+    /** The `type` value that identifies a tool-use block (e.g. 'tool_use' or 'toolCall'). */
+    toolUseType: string;
+    /** The `type` value that identifies a tool-result block (e.g. 'tool_result' or 'toolResult'). */
+    toolResultType: string;
+    /** Field name holding the tool input/arguments (e.g. 'input' or 'arguments'). */
+    toolInputField: string;
+    /** Field name holding the error flag (e.g. 'is_error' or 'isError'). */
+    toolErrorField: string;
+}
+/**
+ * Extract content blocks from a message content array.
+ *
+ * Handles text, thinking, tool_use, and tool_result blocks. Blank text and
+ * whitespace-only tool_result content are skipped. Tool input is serialized
+ * to JSON and truncated at 200 characters.
+ *
+ * @param content  The raw `content` value from a message (array expected;
+ *                 non-array values return an empty array).
+ * @param mapping  Agent-specific field-name mapping.
+ * @returns Array of {@link ContentBlock} objects.
+ */
+export declare function extractContentBlocks(content: unknown, mapping: ContentBlockMapping): ContentBlock[];
+export {};