@steerable/agent-shell 0.6.15

package/dist/local-backend/context-compactor.js

@@ -0,0 +1,213 @@
+/**
+ * 单轮上下文压缩辅助（context compaction helpers）。
+ *
+ * 跨轮历史压缩已下沉框架 CoreLoop（token 压力触发 `CompactionHooks`，压缩
+ * 边界持久化到 durable record，桌面发全量原始历史种子、由框架 reconcile）。
+ * 桌面不再维护滚动摘要。本模块只剩两类纯函数：
+ *
+ * 1. **单轮工具结果截断**：`compactToolResultJson` 在把 tool 结果写回
+ *    messages 前逐字段截断 + 总量封顶（reverse-tools 用），`truncateMiddle`
+ *    是通用中间截断原语。
+ * 2. **@引用对话摘录**：`formatHistoryForSummary` 把最近消息格式化成
+ *    "用户：… / 助手：…" 的 transcript 摘录（referenced-chat 上下文用）。
+ *
+ * 全部是纯函数，不依赖 electron / 数据库，便于单测。
+ */
+// ─── token 估算 ──────────────────────────────────────────────────────────────
+/**
+ * 粗略 token 估算（无 tokenizer 依赖）。
+ * 经验值：CJK 字符 ≈ 0.6 token/字（DeepSeek 官方口径），其它字符 ≈ 0.25 token/字。
+ * 用于"要不要压缩"的阈值判断，不追求精确。
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    let cjk = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        // CJK 统一表意文字 + 常用中文标点区间
+        if ((code >= 0x4e00 && code <= 0x9fff) ||
+            (code >= 0x3000 && code <= 0x303f) ||
+            (code >= 0xff00 && code <= 0xffef)) {
+            cjk++;
+        }
+    }
+    const other = text.length - cjk;
+    return Math.ceil(cjk * 0.6 + other * 0.25);
+}
+/** 估算整个 messages 数组的 token（content + reasoningContent + toolCalls 参数）。 */
+export function estimateMessagesTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        total += estimateTokens(msg.content || '');
+        if (msg.reasoningContent)
+            total += estimateTokens(msg.reasoningContent);
+        if (msg.toolCalls) {
+            for (const call of msg.toolCalls) {
+                total += estimateTokens(call.name) + estimateTokens(JSON.stringify(call.arguments || {}));
+            }
+        }
+        total += 8; // 每条消息的角色 / 分隔符开销
+    }
+    return total;
+}
+// ─── 字符串截断原语 ──────────────────────────────────────────────────────────
+const TRUNCATION_MARKER = (omitted) => `\n…[已截断 ${omitted} 字符]…\n`;
+/**
+ * 中间截断：保留头 60% + 尾 40%（头部通常是结构化字段，尾部通常是 error / 退出码）。
+ * `maxChars` 含截断标记本身。
+ */
+export function truncateMiddle(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const marker = TRUNCATION_MARKER(text.length - maxChars);
+    const budget = Math.max(40, maxChars - marker.length);
+    const head = Math.ceil(budget * 0.6);
+    const tail = budget - head;
+    return text.slice(0, head) + marker + text.slice(text.length - tail);
+}
+const DEFAULT_TOOL_RESULT_MAX_TOTAL = 8000;
+const DEFAULT_TOOL_RESULT_MAX_FIELD = 2000;
+const DEFAULT_TOOL_RESULT_MAX_ARRAY = 50;
+/** 递归截断对象里的长字符串字段 / 超长数组，返回新对象（不改原值）。 */
+export function deepTruncateStrings(value, maxFieldChars, maxArrayItems = DEFAULT_TOOL_RESULT_MAX_ARRAY) {
+    if (typeof value === 'string') {
+        return value.length > maxFieldChars ? truncateMiddle(value, maxFieldChars) : value;
+    }
+    if (Array.isArray(value)) {
+        const capped = value.slice(0, maxArrayItems).map((item) => deepTruncateStrings(item, maxFieldChars, maxArrayItems));
+        if (value.length > maxArrayItems) {
+            capped.push(`…[已省略 ${value.length - maxArrayItems} 项]`);
+        }
+        return capped;
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = deepTruncateStrings(v, maxFieldChars, maxArrayItems);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * 压缩一条要塞回 LLM 上下文的 tool 结果 JSON。
+ * 短的原样返回；超限先逐字段截断，仍超限则整体中间截断并包成合法 JSON 信封，
+ * 保证输出永远是合法 JSON（部分 OpenAI 兼容服务器会解析 tool content）。
+ *
+ * 注意：只影响喂给 LLM 的 messages，**不影响**落库 / 前端展示用的
+ * executedActions（那份保留完整结果）。
+ */
+export function compactToolResultJson(json, options = {}) {
+    const maxTotal = options.maxTotalChars ?? DEFAULT_TOOL_RESULT_MAX_TOTAL;
+    const maxField = options.maxFieldChars ?? DEFAULT_TOOL_RESULT_MAX_FIELD;
+    const maxArray = options.maxArrayItems ?? DEFAULT_TOOL_RESULT_MAX_ARRAY;
+    if (json.length <= maxTotal)
+        return json;
+    try {
+        const parsed = JSON.parse(json);
+        let out = JSON.stringify(deepTruncateStrings(parsed, maxField, maxArray));
+        if (out.length <= maxTotal)
+            return out;
+        // 逐字段截断后仍超限（大量小字段 / 深层结构）：按比例再收紧字段上限
+        const tighterField = Math.max(200, Math.floor((maxField * maxTotal) / out.length));
+        out = JSON.stringify(deepTruncateStrings(parsed, tighterField, Math.min(maxArray, 20)));
+        if (out.length <= maxTotal)
+            return out;
+    }
+    catch {
+        // 非法 JSON：走下面的信封兜底
+    }
+    return JSON.stringify({
+        truncated: true,
+        originalChars: json.length,
+        note: '工具结果过长，已截断。完整结果已展示给用户，无需复述原文。',
+        preview: truncateMiddle(json, Math.max(500, maxTotal - 300)),
+    });
+}
+/** 从 tool 结果 JSON 里抽取关键语义字段，生成收缩版 content（合法 JSON）。 */
+function briefToolContent(json, maxChars) {
+    const PICK_KEYS = [
+        'success', 'status', 'error', 'message', 'hint',
+        'exitCode', 'code', 'taskId', 'total', 'totalFound',
+    ];
+    try {
+        const parsed = JSON.parse(json);
+        const result = parsed && typeof parsed.result === 'object' && parsed.result !== null
+            ? parsed.result
+            : parsed;
+        const picked = {};
+        for (const key of PICK_KEYS) {
+            if (key in result && result[key] !== undefined && result[key] !== null) {
+                const v = result[key];
+                picked[key] = typeof v === 'string' && v.length > 300 ? truncateMiddle(v, 300) : v;
+            }
+        }
+        return JSON.stringify({
+            compacted: true,
+            note: '完整结果已因上下文超限被压缩，仅保留关键字段。',
+            result: picked,
+        });
+    }
+    catch {
+        return JSON.stringify({
+            compacted: true,
+            note: '完整结果已因上下文超限被压缩。',
+            preview: truncateMiddle(json, maxChars),
+        });
+    }
+}
+/**
+ * 每轮 LLM 调用前对 messages 做**原地**滚动压缩：
+ * 估算 token 超出预算时，从最旧的 tool 消息开始把 content 收缩成关键字段摘要，
+ * 直到回到预算内或没有可压对象。最近 `keepRecentToolResults` 条 tool 消息
+ * 永远保持原文（当前任务大概率还依赖它们）。
+ *
+ * 只动 tool 消息的 content：
+ * - 消息条数 / 顺序 / toolCallId 不变 → 不破坏 assistant(tool_calls)/tool 配对；
+ * - 不碰 reasoningContent（DeepSeek thinking 模式要求原样回传）。
+ */
+export function compactMessagesForContext(messages, options) {
+    const keepRecent = options.keepRecentToolResults ?? 4;
+    const compactedMaxChars = options.compactedMaxChars ?? 600;
+    let total = estimateMessagesTokens(messages);
+    if (total <= options.maxContextTokens) {
+        return { compactedCount: 0, estimatedTokens: total };
+    }
+    const toolIndexes = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === 'tool')
+            toolIndexes.push(i);
+    }
+    const protectedIndexes = new Set(toolIndexes.slice(-keepRecent));
+    let compactedCount = 0;
+    for (const idx of toolIndexes) {
+        if (total <= options.maxContextTokens)
+            break;
+        if (protectedIndexes.has(idx))
+            continue;
+        const msg = messages[idx];
+        if (!msg.content || msg.content.length <= compactedMaxChars)
+            continue;
+        const before = estimateTokens(msg.content);
+        msg.content = briefToolContent(msg.content, compactedMaxChars);
+        total -= before - estimateTokens(msg.content);
+        compactedCount++;
+    }
+    return { compactedCount, estimatedTokens: total };
+}
+// ─── @引用对话摘录 ───────────────────────────────────────────────────────────
+/**
+ * 把消息列表格式化成 "用户：… / 助手：…" 的 transcript 摘录，单条消息中间
+ * 截断防止单条爆掉。referenced-chat（@引用别的对话）上下文用。
+ */
+export function formatHistoryForSummary(items, perMessageMaxChars = 1200) {
+    return items
+        .map((item) => {
+        const label = item.role === 'user' ? '用户' : '助手';
+        const content = truncateMiddle((item.content || '').trim(), perMessageMaxChars);
+        return `${label}：${content}`;
+    })
+        .filter((line) => line.length > 3)
+        .join('\n\n');
+}

package/dist/local-backend/coreloop-stream.d.ts

@@ -0,0 +1,245 @@
+/**
+ * A4: drive one chat turn through the sidecar-hosted Python CoreLoop.
+ *
+ * This is the default chat path (since 2026-08-26): the sidecar owns
+ * think→act→observe, and tool calls come back over the reverse channel
+ * (`tool.invoke`, registered in `main.ts`). This module only translates the
+ * wire notifications into the existing SSE contract — the renderer, preload
+ * and IPC layers are untouched.
+ *
+ * This is the only chat path (the TS loop was deleted 2026-08-26). If the
+ * sidecar failed to start, the router fails loud with a 503 — there is no
+ * in-process fallback loop anymore. `STEERABLE_USE_SIDECAR=0` still
+ * disables the sidecar process itself (auxiliary LLM calls then fall back
+ * to the in-proc providers), but chat requires the sidecar.
+ */
+import type { SidecarChatStreamRequest, SidecarChildEvent, SidecarRawChunk, SidecarSupervisor } from '../sidecar/index.js';
+import type { LlmMessage } from '../llm/types.js';
+export interface CoreLoopToolAction {
+    id?: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+    success: boolean;
+    result?: string;
+    error?: string;
+    durationMs?: number;
+    /**
+     * W4-2: per-exec sandbox marker from `SandboxedToolExecutor`
+     * (`data._sandbox` on the tool result). `enforcement: full | partial |
+     * none` — rendered on the tool card so the confinement actually applied
+     * is user-visible.
+     */
+    sandbox?: {
+        backend?: string;
+        enforcement: string;
+    };
+}
+export interface CoreLoopTurnOutcome {
+    status: string;
+    reason?: string;
+    /** Sidecar trace id for this turn — the router persists it into
+     *  harness_traces so the CoreLoop path leaves the same audit trail as the
+     *  TS loop (and dogfood traces can be replayed/diffed). */
+    traceId?: string;
+    /** W6-9: the run's accumulated billable usage (+ costUsd when priced). */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedPromptTokens?: number;
+        costUsd?: number;
+    };
+}
+/**
+ * A6 分层披露:本轮技能目录的过滤上下文。sidecar 据此注入 catalog 层
+ * (首轮 pre_step 写入系统消息,hook_action 落 trace)并用 `skill` 工具
+ * 按需返回技能正文;eager 层正文仍由宿主系统提示词携带。
+ */
+export interface SkillTurnContext {
+    /** 活跃条件串(tool:* / has-tools / plan-mode),与提示词拼装同源。 */
+    conditions: string[];
+    /**
+     * 目录里不出现的技能:模式级排除(plan 模式排掉执行类技能)、智能体关闭
+     * 「允许其他技能」时的未勾选项、以及已随系统提示词常驻的勾选项(避免
+     * 模型再调 `skill` 工具加载第二遍)。
+     */
+    exclude: string[];
+    /** 智能体的「加载全部技能」:catalog 无视条件全量列出。 */
+    ignoreConditions: boolean;
+}
+export interface StreamCoreLoopTurnOptions {
+    supervisor: SidecarSupervisor;
+    chatId: string;
+    /** W5-2: the chat's active durable record (a branch id after a
+     *  regenerate-fork). Undefined = the chatId itself. */
+    recordId?: string;
+    /**
+     * W7-1: continue the durable record's interrupted turn. The sidecar
+     * replays the record's projection (dangling tool_calls closed) as the
+     * loop seed; `messages` must be empty — the record is authoritative and
+     * the host neither re-sends the last user message nor fabricates a
+     * synthetic continuation prompt.
+     */
+    resume?: boolean;
+    messages: LlmMessage[];
+    tools: Array<{
+        name: string;
+        description: string;
+        inputSchema: unknown;
+    }>;
+    provider: string;
+    model: string;
+    baseUrl?: string;
+    apiKey?: string;
+    temperature?: number;
+    /** W2.8.2: assembled system prompt, sent as a typed fragment param (cap
+     * enforced sidecar-side) instead of a leading system message. */
+    systemPrompt?: string;
+    /** W1.3.2 explicit compat flag overrides, forwarded verbatim; omitted →
+     * the sidecar auto-detects from the base-URL host. */
+    compat?: SidecarChatStreamRequest['compat'];
+    /** Provider-preset choice (auto/off/pinned), forwarded verbatim; omitted →
+     * the sidecar auto-matches the llm.presets registry on base-URL+model. */
+    presets?: SidecarChatStreamRequest['presets'];
+    /** Per-turn reasoning effort from the chat model picker. Forwarded
+     * verbatim; the sidecar validates it strict against the model's catalog
+     * entry, so an unsupportable level fails the turn at stream start
+     * (invalid_params) instead of being silently dropped. */
+    reasoningEffort?: string;
+    /** Forwarded on every reverse tool.invoke (host enforces plan-mode etc.). */
+    toolContext?: Record<string, unknown>;
+    /**
+     * 4.6a: advertise the sidecar-hosted ask_user tool. Default on for chat
+     * turns; background task streams pass `false` — no user is watching the
+     * question card, and the task prompt tells the model not to ask.
+     */
+    askUser?: boolean;
+    /**
+     * 分层技能披露:skills 根目录 + 本轮过滤上下文。缺省 = 技能机制整体
+     * 旁路(显式自定义系统提示词的回合,与旧行为一致)。
+     */
+    skills?: SkillTurnContext & {
+        roots: string[];
+    };
+    /**
+     * Wave 2 world-state:慢变宿主上下文(当前时间/时区)作为数据节下发。
+     * sidecar 首轮注入 <world-state> 片段,后续轮次与记录里的快照 diff——
+     * 未变零 token,变了只追加一个 RFC 7386 小补丁。由 buildWorldState()
+     * 构建;缺省 = 不注入(与旧行为一致)。
+     */
+    worldState?: Record<string, unknown>;
+    /**
+     * W4-2: per-exec sandbox config forwarded verbatim to the sidecar
+     * (`SandboxedToolExecutor`). The router builds it from the chat's project
+     * binding (writableRoots = project root) and the provider baseUrl
+     * (allowedHosts when network is on).
+     */
+    execSandbox?: SidecarChatStreamRequest['execSandbox'];
+    /**
+     * W4-1: approval algebra config forwarded verbatim to the sidecar
+     * (`ApprovalExecutor` + `HostApprover`). The router enables host mode;
+     * the reverse-channel handler in main.ts drives the Electron UI.
+     */
+    approval?: SidecarChatStreamRequest['approval'];
+    /**
+     * P3.1 multi-agent orchestration (六件套), forwarded verbatim to the
+     * sidecar. OPT-IN advanced mode: only `enabled: true` exposes
+     * agent_spawn/send/wait/close/list/interrupt. Default off since the
+     * delegate-on-pool unification — the model's multi-agent surface is
+     * `delegate_subagent` (see `subagent`).
+     */
+    orchestration?: SidecarChatStreamRequest['orchestration'];
+    /**
+     * delegate-on-pool 委派,原样转发给 sidecar。桌面默认开(`subagent:
+     * true`):模型获得单工具 delegate_subagent,子代理作为 AgentPool 池化
+     * 子运行执行,生命周期经 `agent.child` 通知(由 `onChildEvent` 上抛)
+     * 进编排卡片;concurrent profile 的同轮委派在池预算内并行。
+     */
+    subagent?: SidecarChatStreamRequest['subagent'];
+    /** W6-9: per-turn token budget override. When set, forwarded as
+     * `budgetTokens` and the sidecar uses it instead of its rounds-scaled
+     * default. */
+    budgetTokens?: number;
+    signal?: AbortSignal;
+    /** Fired once the sidecar streamId is known — needed for steerChat. */
+    onStreamId?: (streamId: string) => void;
+    /** Assistant text chunk, display-cleaned by the sidecar already. */
+    onText: (delta: string) => void;
+    /** Thinking-model chain-of-thought delta (sidecar `reasoningDelta`). */
+    onReasoning?: (delta: string) => void;
+    /** Fired when a tool call starts (running row on the timeline). */
+    onToolStart?: (call: {
+        id: string;
+        tool: string;
+        arguments: Record<string, unknown>;
+    }) => void;
+    /** Fired when a tool finishes on the host (for tool-card rendering). */
+    onToolAction?: (action: CoreLoopToolAction) => void;
+    /** soft_timeout / budget_exhausted notices from the loop. */
+    onNotice?: (kind: string, notice?: {
+        kind: string;
+        [key: string]: unknown;
+    }) => void;
+    /**
+     * Opt-in (`streamRawChunks: true`, default off): every pre-digestion
+     * provider chunk the sidecar's `on_stream_chunk` hook observed, before
+     * UI-tag stripping produced the display `delta`. For incremental
+     * renderers; costs one notification per chunk.
+     */
+    streamRawChunks?: boolean;
+    /** Fired per raw provider chunk when `streamRawChunks` is on. */
+    onRawChunk?: (chunk: SidecarRawChunk) => void;
+    /** P3.1: child-agent lifecycle events (spawn/complete/fail/interrupt/
+     *  resume), demuxed from the sidecar's `agent.child` notifications —
+     *  fired by orchestration children and by delegate_subagent delegations. */
+    onChildEvent?: (event: SidecarChildEvent) => void;
+}
+/** Sidecar streamId of the chat's running CoreLoop turn, if any. */
+export declare function getActiveCoreLoopStreamId(chatId: string): string | undefined;
+/**
+ * W6-7b world-state 扩面的输入。除 time 外各节都可缺省——缺省的节不出现在
+ * 快照里,与"只喂了 time 一节"的旧行为一致。各节都是小型对比数据(不是
+ * 正文),sidecar 逐节 merge-patch diff:没变零 token,变了只补一个小补丁。
+ */
+export interface WorldStateInput {
+    /** 当前时间(可注入以便测试);缺省 = 现在。 */
+    now?: Date;
+    /** 协作模式(agent/plan)。模型据此明确当前模式,而不只靠系统提示词。 */
+    mode?: 'agent' | 'plan';
+    /**
+     * 权限姿态:approval 模式 + 执行沙箱。让模型事先知道哪些目录可写、网络
+     * 是否开、工具调用是否要过审批,避免去尝试必然被拦的操作。
+     */
+    permissions?: {
+        approval: 'host' | 'off';
+        sandbox: {
+            enabled: boolean;
+            writableRoots: string[];
+            network: boolean;
+        };
+    };
+    /**
+     * 技能姿态(紧凑):本轮活跃条件 + 模式级排除清单。只放过滤上下文,不放
+     * 技能正文——正文由分层披露(catalog/eager)机制携带,这里给模型一个
+     * "当前技能过滤面"的可 diff 数据视图。
+     */
+    skills?: {
+        conditions: string[];
+        exclude: string[];
+    };
+    /**
+     * 场景包附加节（1.2 pack 回合钩子）：原样并入输出。包用包前缀键
+     * （如 `<pack>_workspace`）避免与 shell 节碰撞。
+     */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 构建本轮的 world-state 节(Wave 2 起;W6-7b 从只有 time 扩到多节)。
+ *
+ * time 节分钟精度是刻意的:模型不需要秒,而快照在同一分钟内稳定,sidecar
+ * 的 merge-patch diff 对连续轮次就是零 token 空转;跨分钟只追加一个几
+ * token 的尾部补丁,系统提示词前缀保持字节稳定(cache 净收益)。其余各节
+ * (mode/permissions/skills)同理——慢变,变了才补一个小补丁。
+ */
+export declare function buildWorldState(input?: WorldStateInput): Record<string, unknown>;
+export declare function streamCoreLoopTurn(options: StreamCoreLoopTurnOptions): Promise<CoreLoopTurnOutcome>;