@steerable/agent-shell 0.6.15

package/dist/local-backend/ai-title.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AI 聊天标题生成。
+ *
+ * 移植自上游 Python 服务的 ai_title 模块，行为对齐：
+ *   - 用一段固定的中文 system prompt 让模型把首条用户消息总结成 5-15 字的标题
+ *   - max tokens 限制在 ~32，避免模型啰嗦
+ *   - 失败时返回 '新对话'（与 storage createChat 默认值一致），不抛错
+ *
+ * 实现差异：
+ *   - 本地用户模型不固定是 deepseek-v3，直接复用 llmService.generate 的默认 settings
+ *     （Ollama / OpenAI-compat）。模型小、prompt 短、max tokens 低，对大多数本地模型
+ *     都足够好用了。
+ *   - 调用方应该 fire-and-forget：不要 await，也别把它挂在 SSE 主流程里阻塞 [DONE]。
+ *
+ * 公开函数返回 Promise<{ title; usedFallback }>，方便调用方判断要不要 emit
+ * `chat_title_updated` SSE 事件（fallback 时跳过 emit、避免覆盖用户手动改过的标题）。
+ */
+export interface GenerateChatTitleResult {
+    title: string;
+    /** true 表示返回的是 DEFAULT_TITLE（生成失败/被清空），调用方应该不写库或不发事件。 */
+    usedFallback: boolean;
+}
+/**
+ * 生成 chat 标题。永不抛错。
+ *
+ * @param message 首条用户消息（已去空白；空字符串会直接返回 fallback）
+ * @param opts.maxRetries 最大重试次数（不含首次），默认 0。
+ *   本地 Ollama 出错主要是"超时 / 推理慢"——retry 同一个慢模型几乎不会更快，
+ *   反而把用户的等待时间 ×N。慢机器宁可一次失败走短消息兜底也别再等。
+ * @param opts.perAttemptTimeoutMs 单次 LLM 调用的硬超时，默认 12000ms。
+ *   早期版本是 6000ms，但 Ollama 在主回复刚结束后需要重做 KV cache，
+ *   30 token 的小输出也常吃到 7-10s。12s 给中速本地模型留足余量；再慢
+ *   就别折腾用户了。
+ *   注意：这是**单次**的超时，不是整个函数的超时。这样超时后还能走"短消息直接
+ *   当标题"的兜底——把超时放在外层（用 Promise.race 包整个函数）会绕过兜底。
+ * @param opts.skipLlmForShortMessages 短消息（≤ SHORT_MESSAGE_THRESHOLD 字）
+ *   直接跳过 LLM，默认 true。可设 false 强制走 LLM（基本只在测试时用）。
+ */
+export declare function generateChatTitle(message: string, opts?: {
+    maxRetries?: number;
+    perAttemptTimeoutMs?: number;
+    skipLlmForShortMessages?: boolean;
+}): Promise<GenerateChatTitleResult>;

package/dist/local-backend/ai-title.js

@@ -0,0 +1,173 @@
+/**
+ * AI 聊天标题生成。
+ *
+ * 移植自上游 Python 服务的 ai_title 模块，行为对齐：
+ *   - 用一段固定的中文 system prompt 让模型把首条用户消息总结成 5-15 字的标题
+ *   - max tokens 限制在 ~32，避免模型啰嗦
+ *   - 失败时返回 '新对话'（与 storage createChat 默认值一致），不抛错
+ *
+ * 实现差异：
+ *   - 本地用户模型不固定是 deepseek-v3，直接复用 llmService.generate 的默认 settings
+ *     （Ollama / OpenAI-compat）。模型小、prompt 短、max tokens 低，对大多数本地模型
+ *     都足够好用了。
+ *   - 调用方应该 fire-and-forget：不要 await，也别把它挂在 SSE 主流程里阻塞 [DONE]。
+ *
+ * 公开函数返回 Promise<{ title; usedFallback }>，方便调用方判断要不要 emit
+ * `chat_title_updated` SSE 事件（fallback 时跳过 emit、避免覆盖用户手动改过的标题）。
+ */
+import { llmService } from '../llm/index.js';
+const DEFAULT_TITLE = '新对话';
+const SYSTEM_PROMPT = `你是一个专业的标题生成助手。请将用户的消息总结为一个简短、清晰、准确的对话标题。
+标题要求：
+1. 长度控制在5-15个字之间
+2. 提取消息的核心目标或主题
+3. 使用简洁明了的语言
+4. 不要使用引号或特殊符号
+5. 直接返回标题文本，不要有任何解释或前缀`;
+/**
+ * 把 LLM 吐出来的"标题"做一遍人肉清洗：
+ *  - 去除首尾空白、各类引号
+ *  - 取第一行（防止模型给一段解释 + 标题）
+ *  - 截断到 30 字，超过的兜底（本地模型偶尔会狂吐）
+ *  - 完全为空 → 返回 DEFAULT_TITLE
+ */
+function cleanTitle(raw) {
+    if (!raw)
+        return DEFAULT_TITLE;
+    let title = raw.trim();
+    // 取第一行，模型经常会先吐一段思考再给标题
+    const firstLine = title.split(/\r?\n/)[0]?.trim();
+    if (firstLine)
+        title = firstLine;
+    // 去除常见包裹：英文/中文引号、书名号、句号、冒号前缀
+    title = title.replace(/^[\s"'“”‘’「」『』《》【】]+|[\s"'“”‘’「」『』《》【】。.！!?？，,；;:：]+$/g, '');
+    // 去掉 "标题：xxx" / "Title: xxx" 这种前缀
+    title = title.replace(/^(标题|题目|对话标题|chat\s*title|title)\s*[:：-]\s*/i, '');
+    // 折叠多余空格
+    title = title.replace(/\s+/g, ' ').trim();
+    if (!title)
+        return DEFAULT_TITLE;
+    // 兜底长度——5-15 字是理想，但小模型偶尔会塞 50 字进来。30 是个软上限。
+    if (title.length > 30)
+        title = title.slice(0, 30).trim();
+    return title || DEFAULT_TITLE;
+}
+/**
+ * 给 promise 套一个超时。超时时 reject 一个明确的 Error，让上层 catch 走重试 /
+ * 短消息兜底分支，而**不**是直接绕过这些分支返回 DEFAULT_TITLE。
+ *
+ * 注意：被 race 掉的 promise 仍在后台继续跑——本地 Ollama 调用没有 abort 接口，
+ * 这是无害的浪费（结果会被丢弃），但比让用户等着强。
+ */
+function withTimeout(promise, timeoutMs, label) {
+    if (timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/** 短消息快速路径阈值：消息 ≤ 该字数时跳过 LLM，直接拿消息本身当标题。
+ *
+ * 选 8 字的理由：
+ *  - 「你好」「在吗」「hi」「help me」这种问候 / 唤起词，LLM 跑半天也总结
+ *    不出比"你好"更好的标题。早期实验中 12s 等待 → 兜底回原消息，纯白等
+ *  - 5-8 字的短指令（"帮我查天气" "新建任务"）跟 LLM 给的"5-15字 标题"
+ *    长度上没差别，跳过 LLM 不会丢信息
+ *  - 超过 8 字才上 LLM——这时通常有足够语义让模型抽个有意义的主题
+ */
+const SHORT_MESSAGE_THRESHOLD = 8;
+/**
+ * 生成 chat 标题。永不抛错。
+ *
+ * @param message 首条用户消息（已去空白；空字符串会直接返回 fallback）
+ * @param opts.maxRetries 最大重试次数（不含首次），默认 0。
+ *   本地 Ollama 出错主要是"超时 / 推理慢"——retry 同一个慢模型几乎不会更快，
+ *   反而把用户的等待时间 ×N。慢机器宁可一次失败走短消息兜底也别再等。
+ * @param opts.perAttemptTimeoutMs 单次 LLM 调用的硬超时，默认 12000ms。
+ *   早期版本是 6000ms，但 Ollama 在主回复刚结束后需要重做 KV cache，
+ *   30 token 的小输出也常吃到 7-10s。12s 给中速本地模型留足余量；再慢
+ *   就别折腾用户了。
+ *   注意：这是**单次**的超时，不是整个函数的超时。这样超时后还能走"短消息直接
+ *   当标题"的兜底——把超时放在外层（用 Promise.race 包整个函数）会绕过兜底。
+ * @param opts.skipLlmForShortMessages 短消息（≤ SHORT_MESSAGE_THRESHOLD 字）
+ *   直接跳过 LLM，默认 true。可设 false 强制走 LLM（基本只在测试时用）。
+ */
+export async function generateChatTitle(message, opts = {}) {
+    const trimmed = (message ?? '').trim();
+    if (!trimmed) {
+        return { title: DEFAULT_TITLE, usedFallback: true };
+    }
+    const maxRetries = Math.max(0, opts.maxRetries ?? 0);
+    const perAttemptTimeoutMs = opts.perAttemptTimeoutMs ?? 12000;
+    const skipShort = opts.skipLlmForShortMessages ?? true;
+    // ── 快速路径：极短消息直接当标题 ─────────────────────────────────────
+    // LLM 对这种输入只会返回比它本身更糟的东西（"新对话" / "你好" / 重复一遍）。
+    // 算成 Unicode 码点而不是 byte——一个汉字算 1 个字符。
+    const charCount = Array.from(trimmed).length;
+    if (skipShort && charCount <= SHORT_MESSAGE_THRESHOLD) {
+        const cleanedShort = cleanTitle(trimmed);
+        if (cleanedShort && cleanedShort !== DEFAULT_TITLE) {
+            return { title: cleanedShort, usedFallback: false };
+        }
+    }
+    // 截断用户消息——超长输入对小模型反而是噪音，标题只看核心意图就够了。
+    const truncated = trimmed.length > 500 ? trimmed.slice(0, 500) : trimmed;
+    let lastErr = null;
+    let lastRawContent = '';
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        try {
+            const result = await withTimeout(llmService.generate({
+                messages: [
+                    { role: 'system', content: SYSTEM_PROMPT },
+                    { role: 'user', content: truncated },
+                ],
+                temperature: 0.7,
+            }), perAttemptTimeoutMs, `ai-title attempt ${attempt + 1}`);
+            lastRawContent = result.content ?? '';
+            const cleaned = cleanTitle(lastRawContent);
+            if (cleaned && cleaned !== DEFAULT_TITLE) {
+                return { title: cleaned, usedFallback: false };
+            }
+            // 模型返回了空白 / 只剩兜底字符串，重试一次再说
+            lastErr = new Error(`empty title (attempt ${attempt + 1}, raw=${JSON.stringify(lastRawContent.slice(0, 80))})`);
+        }
+        catch (err) {
+            lastErr = err;
+        }
+        // 简单退避：本地模型 retry 不指数也行
+        if (attempt < maxRetries) {
+            await new Promise((resolve) => setTimeout(resolve, 300));
+        }
+    }
+    console.warn('[ai-title] LLM 标题生成失败，用消息开头兜底', lastErr);
+    // 兜底：用消息本身做标题。
+    //
+    // 设计取舍：早期版本把这个分支限制在「≤ 20 字」——长消息直接退到 DEFAULT_TITLE，
+    // 结果用户输入「看一下最近的记录里有哪些跟某指标对比相关的内容...」这种
+    // 30+ 字指令时，标题就回到"新对话"，sidebar 啥信息都没。截断后的原文哪怕
+    // 只有前 20 字也比"新对话"强得多——至少能回忆起这条对话在干嘛。
+    //
+    // 截断规则：按 Unicode 码点取前 20 字符，避免把 emoji / 中文截在半字节上。
+    const codepoints = Array.from(trimmed);
+    const head = codepoints.slice(0, 20).join('');
+    const cleaned = cleanTitle(head);
+    // 加省略号提示 sidebar 上看到的是截断版本，而不是用户输入的完整 query
+    const finalTitle = cleaned && cleaned !== DEFAULT_TITLE
+        ? codepoints.length > 20
+            ? `${cleaned}…`
+            : cleaned
+        : DEFAULT_TITLE;
+    if (finalTitle !== DEFAULT_TITLE) {
+        return { title: finalTitle, usedFallback: false };
+    }
+    return { title: DEFAULT_TITLE, usedFallback: true };
+}

package/dist/local-backend/auto-continue-helper.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Auto-continue policy for the CoreLoop turn in `router.ts`.
+ *
+ * `budget_exhausted` means the loop hit a wall, not that the model decided it
+ * was done — a finished turn terminates `completed`. So the status alone is
+ * the "unfinished" judgement; no separate goal verifier is needed to decide
+ * whether continuing is warranted.
+ *
+ * Continuation goes through the W7-1 resume channel: the sidecar replays the
+ * durable record's projection with fresh round and token budgets, so each
+ * pass is a checkpoint, not a smaller retry of the one that hit the wall.
+ *
+ * The turn stops only when the task is actually over: `completed` (the
+ * model's own finish), `failed`, `cancelled` (the user's Stop), or a pass
+ * that made no progress — a pass that spent a whole budget without running
+ * one tool or writing one character is spinning, and resuming from the
+ * transcript that produced the spin spins again. There is no pass-count cap
+ * by default: the round guardrail (`maxRounds`) bounds one pass, never the
+ * task. `STEERABLE_AUTO_CONTINUE` opts back into a cap (`0` disables
+ * continuation entirely).
+ *
+ * Pure so it is unit-testable: `storage/index.ts` can't load under plain
+ * Node/vitest (`better-sqlite3` is compiled against Electron's ABI).
+ */
+/** Continuation policy when `STEERABLE_AUTO_CONTINUE` is unset: no cap. */
+export declare const DEFAULT_AUTO_CONTINUE_MAX: number;
+export interface AutoContinueInput {
+    /** The pass's CoreLoop terminal status. */
+    status: string;
+    /** Continuation passes already spent on this turn (0 on the first pass). */
+    continuationsUsed: number;
+    /** Configured cap, from `resolveAutoContinueMax`. */
+    max: number;
+    /** The request's abort signal fired — the user pressed Stop. */
+    aborted: boolean;
+    /** The pass ran a tool or produced assistant text. */
+    madeProgress: boolean;
+}
+/**
+ * True when the turn should run another resume pass.
+ *
+ * Only `budget_exhausted` continues. `completed` is the model's own
+ * finish, `failed` would just repeat the failure, and `cancelled` is the
+ * user's explicit stop. A pass with no progress is spinning — stopping
+ * there is the runaway guard now that the pass count is uncapped.
+ */
+export declare function shouldAutoContinue(input: AutoContinueInput): boolean;
+/**
+ * Parse `STEERABLE_AUTO_CONTINUE` into a continuation cap. `0` disables
+ * auto-continue (stop at the first wall). Unset, unparseable, or negative
+ * values select the default: no cap — the turn runs until the task ends.
+ */
+export declare function resolveAutoContinueMax(raw: string | undefined): number;
+export interface AutoContinuePass {
+    /** The pass's CoreLoop terminal status. */
+    status: string;
+}
+export interface AutoContinueDriveOptions<P extends AutoContinuePass> {
+    /** Continuation cap from `resolveAutoContinueMax`; `Infinity` runs until done. */
+    max: number;
+    /** The request's abort signal fired — the user pressed Stop. */
+    isAborted(): boolean;
+    /** Cumulative progress counter (tools run + assistant chars so far). */
+    progressSnapshot(): number;
+    /** Run one pass; `continuationsUsed === 0` is the initial, non-resume pass. */
+    runPass(continuationsUsed: number): Promise<P>;
+    /** After each pass (usage recording, trace collection). */
+    afterPass?(pass: P, continuationsUsed: number): void;
+    /** When another continuation pass is about to start. */
+    onContinuation?(continuationsUsed: number, max: number): void;
+}
+/**
+ * The router's continuation loop, extracted so the pass/resume/progress
+ * wiring is unit-testable without the Electron-ABI storage module. Runs
+ * passes until `shouldAutoContinue` says stop and returns the final pass.
+ */
+export declare function driveWithAutoContinue<P extends AutoContinuePass>(opts: AutoContinueDriveOptions<P>): Promise<{
+    pass: P;
+    continuations: number;
+}>;

package/dist/local-backend/auto-continue-helper.js

@@ -0,0 +1,83 @@
+/**
+ * Auto-continue policy for the CoreLoop turn in `router.ts`.
+ *
+ * `budget_exhausted` means the loop hit a wall, not that the model decided it
+ * was done — a finished turn terminates `completed`. So the status alone is
+ * the "unfinished" judgement; no separate goal verifier is needed to decide
+ * whether continuing is warranted.
+ *
+ * Continuation goes through the W7-1 resume channel: the sidecar replays the
+ * durable record's projection with fresh round and token budgets, so each
+ * pass is a checkpoint, not a smaller retry of the one that hit the wall.
+ *
+ * The turn stops only when the task is actually over: `completed` (the
+ * model's own finish), `failed`, `cancelled` (the user's Stop), or a pass
+ * that made no progress — a pass that spent a whole budget without running
+ * one tool or writing one character is spinning, and resuming from the
+ * transcript that produced the spin spins again. There is no pass-count cap
+ * by default: the round guardrail (`maxRounds`) bounds one pass, never the
+ * task. `STEERABLE_AUTO_CONTINUE` opts back into a cap (`0` disables
+ * continuation entirely).
+ *
+ * Pure so it is unit-testable: `storage/index.ts` can't load under plain
+ * Node/vitest (`better-sqlite3` is compiled against Electron's ABI).
+ */
+/** Continuation policy when `STEERABLE_AUTO_CONTINUE` is unset: no cap. */
+export const DEFAULT_AUTO_CONTINUE_MAX = Number.POSITIVE_INFINITY;
+/**
+ * True when the turn should run another resume pass.
+ *
+ * Only `budget_exhausted` continues. `completed` is the model's own
+ * finish, `failed` would just repeat the failure, and `cancelled` is the
+ * user's explicit stop. A pass with no progress is spinning — stopping
+ * there is the runaway guard now that the pass count is uncapped.
+ */
+export function shouldAutoContinue(input) {
+    if (input.status !== 'budget_exhausted')
+        return false;
+    if (input.aborted)
+        return false;
+    if (!input.madeProgress)
+        return false;
+    return input.continuationsUsed < input.max;
+}
+/**
+ * Parse `STEERABLE_AUTO_CONTINUE` into a continuation cap. `0` disables
+ * auto-continue (stop at the first wall). Unset, unparseable, or negative
+ * values select the default: no cap — the turn runs until the task ends.
+ */
+export function resolveAutoContinueMax(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_AUTO_CONTINUE_MAX;
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_AUTO_CONTINUE_MAX;
+    return parsed;
+}
+/**
+ * The router's continuation loop, extracted so the pass/resume/progress
+ * wiring is unit-testable without the Electron-ABI storage module. Runs
+ * passes until `shouldAutoContinue` says stop and returns the final pass.
+ */
+export async function driveWithAutoContinue(opts) {
+    let continuations = 0;
+    for (;;) {
+        // Progress is judged per pass: the counters accumulate across passes, so
+        // the baseline is the snapshot before this pass ran.
+        const progressBefore = opts.progressSnapshot();
+        const pass = await opts.runPass(continuations);
+        opts.afterPass?.(pass, continuations);
+        const madeProgress = opts.progressSnapshot() > progressBefore;
+        if (!shouldAutoContinue({
+            status: pass.status,
+            continuationsUsed: continuations,
+            max: opts.max,
+            aborted: opts.isAborted(),
+            madeProgress,
+        })) {
+            return { pass, continuations };
+        }
+        continuations += 1;
+        opts.onContinuation?.(continuations, opts.max);
+    }
+}

package/dist/local-backend/branch-helper.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure helper for the `/branches` routes in `router.ts` (W1.2.1).
+ *
+ * Branch activation is fail-closed: the target record must belong to the
+ * chat's current branch family — the full tree rooted at the family's
+ * first record, so cousins and deeper descendants are switchable, not
+ * just the active record's lineage and direct children (the session-tree
+ * view exposes exactly this set). Activating an unrelated record would
+ * re-project the chat onto a conversation the user never saw in this
+ * chat, so the route rejects it rather than trusting the caller. This
+ * module only computes membership; storage and sidecar I/O stay in
+ * `router.ts` (better-sqlite3 can't load under plain vitest).
+ */
+export interface BranchTreeNodeLike {
+    recordId: string;
+    children?: BranchTreeNodeLike[];
+}
+export type BranchActivation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not_in_family';
+};
+export declare function resolveBranchActivation(activeRecordId: string, tree: BranchTreeNodeLike | null, targetRecordId: string): BranchActivation;

package/dist/local-backend/branch-helper.js

@@ -0,0 +1,27 @@
+/**
+ * Pure helper for the `/branches` routes in `router.ts` (W1.2.1).
+ *
+ * Branch activation is fail-closed: the target record must belong to the
+ * chat's current branch family — the full tree rooted at the family's
+ * first record, so cousins and deeper descendants are switchable, not
+ * just the active record's lineage and direct children (the session-tree
+ * view exposes exactly this set). Activating an unrelated record would
+ * re-project the chat onto a conversation the user never saw in this
+ * chat, so the route rejects it rather than trusting the caller. This
+ * module only computes membership; storage and sidecar I/O stay in
+ * `router.ts` (better-sqlite3 can't load under plain vitest).
+ */
+export function resolveBranchActivation(activeRecordId, tree, targetRecordId) {
+    if (targetRecordId === activeRecordId)
+        return { ok: true };
+    if (tree && treeContains(tree, targetRecordId))
+        return { ok: true };
+    return { ok: false, reason: 'not_in_family' };
+}
+/** DFS membership check. Family trees are depth-capped at 32 on the
+ *  sidecar, so recursion stays shallow. */
+function treeContains(node, targetRecordId) {
+    if (node.recordId === targetRecordId)
+        return true;
+    return (node.children ?? []).some((child) => treeContains(child, targetRecordId));
+}

package/dist/local-backend/context-compactor.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 单轮上下文压缩辅助（context compaction helpers）。
+ *
+ * 跨轮历史压缩已下沉框架 CoreLoop（token 压力触发 `CompactionHooks`，压缩
+ * 边界持久化到 durable record，桌面发全量原始历史种子、由框架 reconcile）。
+ * 桌面不再维护滚动摘要。本模块只剩两类纯函数：
+ *
+ * 1. **单轮工具结果截断**：`compactToolResultJson` 在把 tool 结果写回
+ *    messages 前逐字段截断 + 总量封顶（reverse-tools 用），`truncateMiddle`
+ *    是通用中间截断原语。
+ * 2. **@引用对话摘录**：`formatHistoryForSummary` 把最近消息格式化成
+ *    "用户：… / 助手：…" 的 transcript 摘录（referenced-chat 上下文用）。
+ *
+ * 全部是纯函数，不依赖 electron / 数据库，便于单测。
+ */
+import type { LlmMessage } from '../llm/types.js';
+/**
+ * 粗略 token 估算（无 tokenizer 依赖）。
+ * 经验值：CJK 字符 ≈ 0.6 token/字（DeepSeek 官方口径），其它字符 ≈ 0.25 token/字。
+ * 用于"要不要压缩"的阈值判断，不追求精确。
+ */
+export declare function estimateTokens(text: string): number;
+/** 估算整个 messages 数组的 token（content + reasoningContent + toolCalls 参数）。 */
+export declare function estimateMessagesTokens(messages: LlmMessage[]): number;
+/**
+ * 中间截断：保留头 60% + 尾 40%（头部通常是结构化字段，尾部通常是 error / 退出码）。
+ * `maxChars` 含截断标记本身。
+ */
+export declare function truncateMiddle(text: string, maxChars: number): string;
+export interface ToolResultCompactionOptions {
+    /** 单条 tool 消息 content 的总字符上限，默认 8000（≈ 2-4K token）。 */
+    maxTotalChars?: number;
+    /** 单个字符串字段的上限，默认 2000。 */
+    maxFieldChars?: number;
+    /** 数组元素数量上限，默认 50。 */
+    maxArrayItems?: number;
+}
+/** 递归截断对象里的长字符串字段 / 超长数组，返回新对象（不改原值）。 */
+export declare function deepTruncateStrings(value: unknown, maxFieldChars: number, maxArrayItems?: number): unknown;
+/**
+ * 压缩一条要塞回 LLM 上下文的 tool 结果 JSON。
+ * 短的原样返回；超限先逐字段截断，仍超限则整体中间截断并包成合法 JSON 信封，
+ * 保证输出永远是合法 JSON（部分 OpenAI 兼容服务器会解析 tool content）。
+ *
+ * 注意：只影响喂给 LLM 的 messages，**不影响**落库 / 前端展示用的
+ * executedActions（那份保留完整结果）。
+ */
+export declare function compactToolResultJson(json: string, options?: ToolResultCompactionOptions): string;
+export interface MessagesCompactionOptions {
+    /** 上下文 token 预算（对齐 HarnessBudget.maxContextTokens）。 */
+    maxContextTokens: number;
+    /** 最近 N 条 tool 消息保持原文不压，默认 4（约等于最近 1-2 轮的结果）。 */
+    keepRecentToolResults?: number;
+    /** 被压缩后的 tool 消息 content 目标字符数，默认 600。 */
+    compactedMaxChars?: number;
+}
+export interface MessagesCompactionResult {
+    /** 本次被收缩的 tool 消息数。 */
+    compactedCount: number;
+    /** 压缩后的估算 token 总量。 */
+    estimatedTokens: number;
+}
+/**
+ * 每轮 LLM 调用前对 messages 做**原地**滚动压缩：
+ * 估算 token 超出预算时，从最旧的 tool 消息开始把 content 收缩成关键字段摘要，
+ * 直到回到预算内或没有可压对象。最近 `keepRecentToolResults` 条 tool 消息
+ * 永远保持原文（当前任务大概率还依赖它们）。
+ *
+ * 只动 tool 消息的 content：
+ * - 消息条数 / 顺序 / toolCallId 不变 → 不破坏 assistant(tool_calls)/tool 配对；
+ * - 不碰 reasoningContent（DeepSeek thinking 模式要求原样回传）。
+ */
+export declare function compactMessagesForContext(messages: LlmMessage[], options: MessagesCompactionOptions): MessagesCompactionResult;
+/**
+ * 把消息列表格式化成 "用户：… / 助手：…" 的 transcript 摘录，单条消息中间
+ * 截断防止单条爆掉。referenced-chat（@引用别的对话）上下文用。
+ */
+export declare function formatHistoryForSummary(items: Array<{
+    role: string;
+    content: string;
+}>, perMessageMaxChars?: number): string;