Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat: externalize oversized session tool results (#2058)
HaotianChen616f39b030926fb
diff --git a/examples/openclaw-plugin/client.ts b/examples/openclaw-plugin/client.tsindex 308c8aed7..a0b5d03dd 100644--- a/examples/openclaw-plugin/client.ts+++ b/examples/openclaw-plugin/client.ts@@ -67,6 +67,24 @@ export type OVMessagePart = {tool_output?: string;tool_status?: string;skill_uri?: string;+ duration_ms?: number;+ prompt_tokens?: number;+ completion_tokens?: number;+ tool_output_ref?: string;+ tool_output_truncated?: boolean;+ tool_output_original_chars?: number;+ tool_output_preview_chars?: number;+ tool_output_sha256?: string;+ tool_output_storage_uri?: string;+ tool_output_mime_type?: string;+ tool_output_source_ref?: string;+ tool_output_source_offset?: number;+ tool_output_source_limit?: number;+ tool_output_externalization_error?: string;+ tool_output_group_id?: string;+ tool_output_externalized_reason?: string;+ tool_output_group_original_chars?: number;+ tool_output_group_budget_chars?: number;};export type OVMessage = {@@ -96,6 +114,30 @@ export type SessionContextResult = {};};+export type ToolResultReadResult = {+ tool_result_id: string;+ content: string;+ offset: number;+ limit: number;+ offset_unit: "unicode_code_point";+ total_chars: number;+ has_more: boolean;+ metadata?: Record<string, unknown>;+};++export type ToolResultSearchResult = {+ tool_result_id: string;+ matches: Array<{+ offset: number;+ offset_unit: "unicode_code_point";+ snippet: string;+ }>;+};++export type ToolResultListResult = {+ tool_results: Array<Record<string, unknown>>;+};+export type SessionArchiveResult = {archive_id: string;abstract: string;@@ -433,6 +475,61 @@ export class OpenVikingClient {);}+ async readToolResult(+ sessionId: string,+ toolResultId: string,+ options?: { offset?: number; limit?: number; includeMetadata?: boolean },+ agentId?: string,+ ): Promise<ToolResultReadResult> {+ const params = new URLSearchParams();+ if (options?.offset !== undefined) params.set("offset", String(options.offset));+ if (options?.limit !== undefined) params.set("limit", String(options.limit));+ if (options?.includeMetadata !== undefined) {+ params.set("include_metadata", String(options.includeMetadata));+ }+ const query = params.toString();+ return this.request<ToolResultReadResult>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}${query ? `?${query}` : ""}`,+ {},+ agentId,+ );+ }++ async searchToolResult(+ sessionId: string,+ toolResultId: string,+ queryText: string,+ options?: { limit?: number; contextChars?: number },+ agentId?: string,+ ): Promise<ToolResultSearchResult> {+ const params = new URLSearchParams({ q: queryText });+ if (options?.limit !== undefined) params.set("limit", String(options.limit));+ if (options?.contextChars !== undefined) {+ params.set("context_chars", String(options.contextChars));+ }+ return this.request<ToolResultSearchResult>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}/search?${params.toString()}`,+ {},+ agentId,+ );+ }++ async listToolResults(+ sessionId: string,+ options?: { toolName?: string; limit?: number },+ agentId?: string,+ ): Promise<ToolResultListResult> {+ const params = new URLSearchParams();+ if (options?.toolName) params.set("tool_name", options.toolName);+ if (options?.limit !== undefined) params.set("limit", String(options.limit));+ const query = params.toString();+ return this.request<ToolResultListResult>(+ `/api/v1/sessions/${encodeURIComponent(sessionId)}/tool-results${query ? `?${query}` : ""}`,+ {},+ agentId,+ );+ }+async uploadTempFile(filePath: string, agentId?: string): Promise<string> {const fileBytes = await readFile(filePath);const form = new FormData();@@ -614,6 +711,20 @@ export class OpenVikingClient {tool_status?: string;tool_input?: Record<string, unknown>;tool_id?: string;+ tool_output_ref?: string;+ tool_output_truncated?: boolean;+ tool_output_original_chars?: number;+ tool_output_preview_chars?: number;+ tool_output_sha256?: string;+ tool_output_storage_uri?: string;+ tool_output_mime_type?: string;+ tool_output_source_ref?: string;+ tool_output_source_offset?: number;+ tool_output_source_limit?: number;+ tool_output_group_id?: string;+ tool_output_externalized_reason?: string;+ tool_output_group_original_chars?: number;+ tool_output_group_budget_chars?: number;uri?: string;abstract?: string;context_type?: "memory" | "resource" | "skill";diff --git a/examples/openclaw-plugin/context-engine.ts b/examples/openclaw-plugin/context-engine.tsindex d69450a85..29d7321ca 100644--- a/examples/openclaw-plugin/context-engine.ts+++ b/examples/openclaw-plugin/context-engine.ts@@ -25,6 +25,8 @@ type AgentMessage = {timestamp?: unknown;};+type ExtractedTurnMessage = ReturnType<typeof extractNewTurnMessages>["messages"][number];+type ContextEngineInfo = {id: string;name: string;@@ -403,6 +405,10 @@ export function convertToAgentMessages(msg: { role: string; parts: unknown[] }):const toolName = typeof p.tool_name === "string" ? p.tool_name : undefined;const status = typeof p.tool_status === "string" ? p.tool_status : "unknown";const output = typeof p.tool_output === "string" ? p.tool_output : "";+ const ref = typeof p.tool_output_ref === "string" ? p.tool_output_ref : "";+ const originalChars = typeof p.tool_output_original_chars === "number"+ ? p.tool_output_original_chars+ : undefined;if (toolId) {// Structured path: emit canonical toolCall + toolResult pair (works for any role)@@ -413,9 +419,15 @@ export function convertToAgentMessages(msg: { role: string; parts: unknown[] }):arguments: p.tool_input ?? {},});- const resultText = (status === "completed" || status === "error")+ let resultText = (status === "completed" || status === "error")? (output || "(no output)"): "(interrupted — tool did not complete)";+ if (ref && !resultText.includes(ref)) {+ const suffix = originalChars !== undefined+ ? `\n[tool-result-ref] ${ref} original_chars=${originalChars}`+ : `\n[tool-result-ref] ${ref}`;+ resultText += suffix;+ }const resultPayload: Record<string, unknown> = {role: "toolResult",toolCallId: toolId,@@ -470,6 +482,36 @@ export function convertToAgentMessages(msg: { role: string; parts: unknown[] }):return result;}+function isToolOnlyMessage(msg: ExtractedTurnMessage): boolean {+ return msg.role === "user" && msg.parts.length > 0 && msg.parts.every((part) => part.type === "tool");+}++function coalesceConsecutiveToolMessages(messages: ExtractedTurnMessage[]): ExtractedTurnMessage[] {+ const result: ExtractedTurnMessage[] = [];+ let pendingTools: ExtractedTurnMessage | undefined;++ const flush = () => {+ if (pendingTools) {+ result.push(pendingTools);+ pendingTools = undefined;+ }+ };++ for (const msg of messages) {+ if (isToolOnlyMessage(msg)) {+ if (!pendingTools) {+ pendingTools = { role: "user", parts: [] };+ }+ pendingTools.parts.push(...msg.parts);+ continue;+ }+ flush();+ result.push(msg);+ }+ flush();+ return result;+}+function normalizeAssistantContent(messages: AgentMessage[]): void {for (let i = 0; i < messages.length; i++) {const msg = messages[i];@@ -1275,7 +1317,8 @@ export function createMemoryOpenVikingContextEngine(params: {? afterTurnParams.prePromptMessageCount: 0;- const { messages: extractedMessages, newCount } = extractNewTurnMessages(messages, start);+ const { messages: extractedMessagesRaw, newCount } = extractNewTurnMessages(messages, start);+ const extractedMessages = coalesceConsecutiveToolMessages(extractedMessagesRaw);if (extractedMessages.length === 0) {diag("afterTurn_skip", OVSessionId, {diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.tsindex 5e7c26942..3c2f4bf2d 100644--- a/examples/openclaw-plugin/index.ts+++ b/examples/openclaw-plugin/index.ts@@ -150,6 +150,44 @@ type MemorySearchInput = {limit?: number;};+type ToolResultRef = {+ sessionId: string;+ toolResultId: string;+ ref: string;+};++function parseToolResultRef(value: unknown): ToolResultRef | null {+ const raw = typeof value === "string" ? value.trim() : "";+ if (!raw) {+ return null;+ }+ const match = raw.match(/^viking:\/\/session\/([^/]+)\/tool-results\/([^/?#]+)(?:[?#].*)?$/);+ if (!match) {+ return null;+ }+ const sessionId = decodeURIComponent(match[1]!);+ const toolResultId = decodeURIComponent(match[2]!);+ if (!sessionId || !toolResultId) {+ return null;+ }+ return {+ sessionId,+ toolResultId,+ ref: `viking://session/${encodeURIComponent(sessionId)}/tool-results/${encodeURIComponent(toolResultId)}`,+ };+}++function getOptionalInteger(value: unknown, fallback: number): number {+ if (typeof value !== "number" || !Number.isFinite(value)) {+ return fallback;+ }+ return Math.floor(value);+}++function getPositiveInteger(value: unknown, fallback: number): number {+ return Math.max(1, getOptionalInteger(value, fallback));+}+type OpenClawPluginApi = {pluginConfig?: unknown;logger: PluginLogger;@@ -1560,6 +1598,285 @@ const contextEnginePlugin = {},}), { name: "ov_archive_expand" });+ api.registerTool(+ (ctx: ToolContext) => ({+ name: "openviking_tool_result_read",+ label: "Tool Result Read (OpenViking)",+ description:+ "Restore the full original content of a tool result that was externalized by OpenViking. " ++ "Use when a previous tool result was externalized and only a preview is visible — " ++ "the preview contains a [tool-result-ref] or viking://session/.../tool-results/... URI. " ++ "\"Read\" tool returns the same truncated preview; this tool returns the complete content. " ++ "To read all content: pass offset=0 and a limit large enough to cover the whole result " ++ "(e.g. limit=100000). Use offset/limit for paging only when you need a specific section.",+ parameters: Type.Object({+ tool_output_ref: Type.String({+ description:+ "Exact OV URI from the preview, e.g. viking://session/<session_id>/tool-results/<tool_result_id>",+ }),+ offset: Type.Optional(Type.Number({ description: "Unicode character offset. Default: 0" })),+ limit: Type.Optional(Type.Number({ description: "Maximum Unicode characters to read. Default: 20000" })),+ }),+ async execute(_toolCallId: string, params: Record<string, unknown>) {+ if (isBypassedSession(ctx)) {+ return makeBypassedToolResult("openviking_tool_result_read");+ }+ const session = resolvePluginSessionRouting(ctx);+ if (!session.ovSessionId) {+ return {+ content: [{ type: "text", text: "Error: no active session." }],+ details: { error: "no_session" },+ };+ }++ const parsed = parseToolResultRef(params.tool_output_ref ?? params.ref ?? params.uri);+ if (!parsed) {+ return {+ content: [{ type: "text", text: "Error: tool_output_ref must be a viking://session/.../tool-results/... URI." }],+ details: { error: "invalid_tool_output_ref" },+ };+ }+ if (parsed.sessionId !== session.ovSessionId) {+ return {+ content: [{ type: "text", text: "Error: refusing to read a tool result from another session." }],+ details: {+ error: "session_mismatch",+ requestedSessionId: parsed.sessionId,+ currentSessionId: session.ovSessionId,+ },+ };+ }++ const offset = Math.max(0, getOptionalInteger(params.offset, 0));+ const limit = getOptionalInteger(params.limit, 20_000);+ if (limit < -1) {+ return {+ content: [{ type: "text", text: "Error: limit must be -1 or greater than or equal to 0." }],+ details: { error: "invalid_limit", limit },+ };+ }++ try {+ const client = await getClient();+ const result = await client.readToolResult(+ session.ovSessionId,+ parsed.toolResultId,+ { offset, limit, includeMetadata: true },+ session.agentId,+ );+ const returnedChars = result.content.length;+ const nextOffset = result.offset + returnedChars;+ const text = result.content || "(empty tool result chunk)";+ return {+ content: [{ type: "text", text }],+ details: {+ action: "read",+ tool_output_ref: parsed.ref,+ tool_result_id: result.tool_result_id,+ offset: result.offset,+ limit: result.limit,+ returned_chars: returnedChars,+ total_chars: result.total_chars,+ has_more: result.has_more,+ next_offset: result.has_more ? nextOffset : null,+ metadata: result.metadata ?? null,+ },+ };+ } catch (err) {+ const msg = err instanceof Error ? err.message : String(err);+ api.logger.warn?.(`openviking: openviking_tool_result_read failed: ${msg}`);+ return {+ content: [{ type: "text", text: `Failed to read tool result: ${msg}` }],+ details: { error: msg, tool_output_ref: parsed.ref },+ };+ }+ },+ }),+ { name: "openviking_tool_result_read" },+ );++ api.registerTool(+ (ctx: ToolContext) => ({+ name: "openviking_tool_result_search",+ label: "Tool Result Search (OpenViking)",+ description:+ "Search inside an externalized tool result for a keyword. " ++ "Use when you need to find specific content in a large externalized result, " ++ "before reading it with openviking_tool_result_read. " ++ "Returns matching snippets with their character offsets.",+ parameters: Type.Object({+ tool_output_ref: Type.String({+ description:+ "Exact OV URI from the preview, e.g. viking://session/<session_id>/tool-results/<tool_result_id>",+ }),+ query: Type.String({ description: "Keyword or exact text to search for" }),+ limit: Type.Optional(Type.Number({ description: "Maximum matches. Default: 20" })),+ context_chars: Type.Optional(Type.Number({ description: "Characters around each match. Default: 300" })),+ }),+ async execute(_toolCallId: string, params: Record<string, unknown>) {+ if (isBypassedSession(ctx)) {+ return makeBypassedToolResult("openviking_tool_result_search");+ }+ const session = resolvePluginSessionRouting(ctx);+ if (!session.ovSessionId) {+ return {+ content: [{ type: "text", text: "Error: no active session." }],+ details: { error: "no_session" },+ };+ }++ const parsed = parseToolResultRef(params.tool_output_ref ?? params.ref ?? params.uri);+ if (!parsed) {+ return {+ content: [{ type: "text", text: "Error: tool_output_ref must be a viking://session/.../tool-results/... URI." }],+ details: { error: "invalid_tool_output_ref" },+ };+ }+ if (parsed.sessionId !== session.ovSessionId) {+ return {+ content: [{ type: "text", text: "Error: refusing to search a tool result from another session." }],+ details: {+ error: "session_mismatch",+ requestedSessionId: parsed.sessionId,+ currentSessionId: session.ovSessionId,+ },+ };+ }++ const query = String(params.query ?? "").trim();+ if (!query) {+ return {+ content: [{ type: "text", text: "Error: query is required." }],+ details: { error: "missing_param", param: "query" },+ };+ }+ const limit = getPositiveInteger(params.limit, 20);+ const contextChars = Math.max(+ 0,+ getOptionalInteger(params.context_chars ?? params.contextChars, 300),+ );++ try {+ const client = await getClient();+ const result = await client.searchToolResult(+ session.ovSessionId,+ parsed.toolResultId,+ query,+ { limit, contextChars },+ session.agentId,+ );+ const matches = result.matches ?? [];+ const text = matches.length+ ? [+ `Found ${matches.length} match(es) for "${query}" in ${parsed.ref}:`,+ "",+ ...matches.map((match, index) =>+ `## Match ${index + 1} (offset ${match.offset})\n${match.snippet}`,+ ),+ ].join("\n")+ : `No matches found for "${query}" in ${parsed.ref}.`;+ return {+ content: [{ type: "text", text }],+ details: {+ action: "searched",+ tool_output_ref: parsed.ref,+ tool_result_id: result.tool_result_id,+ query,+ match_count: matches.length,+ matches,+ },+ };+ } catch (err) {+ const msg = err instanceof Error ? err.message : String(err);+ api.logger.warn?.(`openviking: openviking_tool_result_search failed: ${msg}`);+ return {+ content: [{ type: "text", text: `Failed to search tool result: ${msg}` }],+ details: { error: msg, tool_output_ref: parsed.ref, query },+ };+ }+ },+ }),+ { name: "openviking_tool_result_search" },+ );++ api.registerTool(+ (ctx: ToolContext) => ({+ name: "openviking_tool_result_list",+ label: "Tool Result List (OpenViking)",+ description:+ "List externalized tool results for the current session. " ++ "Use to discover available refs before calling openviking_tool_result_read. " ++ "Optionally filter by tool_name to narrow down results.",+ parameters: Type.Object({+ tool_name: Type.Optional(Type.String({ description: "Optional exact tool name filter" })),+ limit: Type.Optional(Type.Number({ description: "Maximum results. Default: 50" })),+ }),+ async execute(_toolCallId: string, params: Record<string, unknown>) {+ if (isBypassedSession(ctx)) {+ return makeBypassedToolResult("openviking_tool_result_list");+ }+ const session = resolvePluginSessionRouting(ctx);+ if (!session.ovSessionId) {+ return {+ content: [{ type: "text", text: "Error: no active session." }],+ details: { error: "no_session" },+ };+ }++ const toolName =+ typeof params.tool_name === "string" && params.tool_name.trim()+ ? params.tool_name.trim()+ : typeof params.toolName === "string" && params.toolName.trim()+ ? params.toolName.trim()+ : undefined;+ const limit = getPositiveInteger(params.limit, 50);++ try {+ const client = await getClient();+ const result = await client.listToolResults(+ session.ovSessionId,+ { toolName, limit },+ session.agentId,+ );+ const items = result.tool_results ?? [];+ const text = items.length+ ? [+ `Found ${items.length} externalized tool result(s) in current session:`,+ "",+ ...items.map((item, index) => {+ const ref = typeof item.storage_uri === "string" ? item.storage_uri : "(missing ref)";+ const name = typeof item.tool_name === "string" ? item.tool_name : "tool";+ const chars = typeof item.original_chars === "number" ? item.original_chars : "unknown";+ const created = typeof item.created_at === "string" ? ` created_at=${item.created_at}` : "";+ return `${index + 1}. ${name} original_chars=${chars}${created}\nref: ${ref}`;+ }),+ ].join("\n")+ : toolName+ ? `No externalized tool results found for tool "${toolName}" in current session.`+ : "No externalized tool results found in current session.";+ return {+ content: [{ type: "text", text }],+ details: {+ action: "listed",+ session_id: session.ovSessionId,+ tool_name: toolName ?? null,+ count: items.length,+ tool_results: items,+ },+ };+ } catch (err) {+ const msg = err instanceof Error ? err.message : String(err);+ api.logger.warn?.(`openviking: openviking_tool_result_list failed: ${msg}`);+ return {+ content: [{ type: "text", text: `Failed to list tool results: ${msg}` }],+ details: { error: msg, session_id: session.ovSessionId, tool_name: toolName ?? null },+ };+ }+ },+ }),+ { name: "openviking_tool_result_list" },+ );+let contextEngineRef: ContextEngineWithCommit | null = null;const sessionAgentResolver = createSessionAgentResolver(cfg.agent_prefix);const rememberSessionAgentId = (ctx: SessionAgentLookup) => {diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.jsonindex 5a732aeab..874cfaac5 100644--- a/examples/openclaw-plugin/openclaw.plugin.json+++ b/examples/openclaw-plugin/openclaw.plugin.json@@ -19,7 +19,10 @@"memory_store","memory_forget","ov_archive_search",- "ov_archive_expand"+ "ov_archive_expand",+ "openviking_tool_result_read",+ "openviking_tool_result_search",+ "openviking_tool_result_list"]},"commandAliases": [diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/README.md b/examples/openclaw-plugin/tests/toolresult_compression_tests/README.mdnew file mode 100644index 000000000..7fba0ddb3--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/README.md@@ -0,0 +1,77 @@+# Tool Result Compression Bench Tests++这个目录放的是用于手工回归 OpenClaw + OpenViking 工具结果压缩链路的轻量 benchmark 脚本和测试用例。++## 前置依赖++运行前需要先把下面 3 个仓库下载到 OpenClaw workspace 中,并保证路径和测试用例里的 prompt 一致:++| 仓库 | 用例 | 期望路径 |+| --- | --- | --- |+| Kubernetes | `test1.json`, `test2.json` | `/root/.openclaw/workspace/kubernetes` |+| OpenViking | `test3.json`, `test4.json` | `/root/.openclaw/workspace/OpenViking` |+| openclaw | `test5.json` | `/root/.openclaw/workspace/openclaw` |++如果本机 workspace 根目录不同,可以创建软链接到上述路径,或只在本地修改对应 `test*.json` 中的路径后再运行。++同时需要确保:++- `openclaw` 命令可用,且已安装/启用当前 OpenViking openclaw plugin。+- OpenViking 服务和 OpenClaw 配置已指向同一个可用的 OV 实例。+- 运行账号能读取 workspace 中的 3 个仓库。++## 运行单个用例++在本目录执行:++```bash+node run-sccs-bench.mjs run \+ --prompts test1.json \+ --label test1 \+ --session-id "bench-quick-$(date +%s)-ov-01-test1" \+ --timeout-sec 600 \+ --out-dir "bench-results-quick/test1-ov-01"+```++可将 `test1.json` 替换为 `test2.json` 到 `test5.json`。++## 批量运行示例++下面是一个可复制的最小 wrapper。将占位路径替换为当前机器上的 OV session 存储目录;如果只有一个存储目录,保留一个即可。++```bash+#!/bin/bash+set -euo pipefail++cd "<OpenViking>/examples/openclaw-plugin/tests/toolresult_compression_tests"++OUT_ROOT="bench-results-quick"+OV_SESSION_DIR_A="<ov-session-store-dir-a>"+OV_SESSION_DIR_B="<ov-session-store-dir-b>"+OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"++run_test() {+ local test_name="$1"+ local mode="$2"+ local i="$3"++ rm -rf "${OV_SESSION_DIR_A:?}/"*+ rm -rf "${OV_SESSION_DIR_B:?}/"*++ node run-sccs-bench.mjs run \+ --prompts "${test_name}.json" \+ --label "$test_name" \+ --session-id "bench-quick-$(date +%s)-${mode}-${i}-${test_name}" \+ --timeout-sec 600 \+ --out-dir "${OUT_ROOT}/${test_name}-${mode}-$(printf '%02d' "$i")"++ rm -rf "${OPENCLAW_STATE_DIR}/memory"+}++run_test "test1" ov 1+```++## 输出++每次运行会在 `--out-dir` 下生成本轮的 JSON/CSV 报告和 OpenClaw session 产物。`bench-results-*` 目录是本地运行产物,不需要提交。+diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/run-sccs-bench.mjs b/examples/openclaw-plugin/tests/toolresult_compression_tests/run-sccs-bench.mjsnew file mode 100644index 000000000..eafdfef3a--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/run-sccs-bench.mjs@@ -0,0 +1,685 @@+#!/usr/bin/env node+import fs from "node:fs";+import os from "node:os";+import path from "node:path";+import process from "node:process";+import { spawnSync } from "node:child_process";++function fail(message) {+ console.error(`[sccs-bench] ${message}`);+ process.exit(1);+}++function nowIso() {+ return new Date().toISOString();+}++function asNumber(value) {+ return typeof value === "number" && Number.isFinite(value) ? value : undefined;+}++function numOrZero(value) {+ return asNumber(value) ?? 0;+}++function percentile(sortedValues, p) {+ if (!sortedValues.length) {+ return 0;+ }+ const rank = (p / 100) * (sortedValues.length - 1);+ const lo = Math.floor(rank);+ const hi = Math.ceil(rank);+ if (lo === hi) {+ return sortedValues[lo];+ }+ const weight = rank - lo;+ return sortedValues[lo] * (1 - weight) + sortedValues[hi] * weight;+}++function toCsv(rows, headers) {+ const escape = (value) => {+ const raw =+ value === undefined || value === null+ ? ""+ : typeof value === "string"+ ? value+ : JSON.stringify(value);+ if (/[",\n]/.test(raw)) {+ return `"${raw.replace(/"/g, "\"\"")}"`;+ }+ return raw;+ };+ const lines = [headers.join(",")];+ for (const row of rows) {+ lines.push(headers.map((h) => escape(row[h])).join(","));+ }+ return `${lines.join("\n")}\n`;+}++function parseArgs(argv) {+ const args = {+ cmd: "run",+ openclawBin: "openclaw",+ prompts: "",+ outDir: path.resolve(process.cwd(), "bench-results"),+ label: "run",+ agent: "main",+ to: "+15555550123",+ sessionId: `sccs-bench-${Date.now()}`,+ timeoutSec: 600,+ stateDir: process.env.OPENCLAW_STATE_DIR+ ? path.resolve(process.env.OPENCLAW_STATE_DIR)+ : path.join(os.homedir(), ".openclaw"),+ continueOnError: false,+ baseline: "",+ candidate: "",+ out: "",+ };++ const positional = [];+ for (let i = 0; i < argv.length; i += 1) {+ const token = argv[i];+ if (!token.startsWith("--")) {+ positional.push(token);+ continue;+ }+ const [key, maybeValue] = token.split("=", 2);+ const nextValue = maybeValue ?? argv[i + 1];+ const takeNext = maybeValue === undefined;+ const set = (field, valueRequired = true) => {+ if (valueRequired && (nextValue === undefined || nextValue.startsWith("--"))) {+ fail(`missing value for ${key}`);+ }+ if (takeNext && valueRequired) {+ i += 1;+ }+ args[field] = valueRequired ? nextValue : true;+ };++ switch (key) {+ case "--help":+ args.cmd = "help";+ break;+ case "--openclaw":+ set("openclawBin");+ break;+ case "--prompts":+ set("prompts");+ break;+ case "--out-dir":+ set("outDir");+ break;+ case "--label":+ set("label");+ break;+ case "--agent":+ set("agent");+ break;+ case "--to":+ set("to");+ break;+ case "--session-id":+ set("sessionId");+ break;+ case "--timeout-sec":+ set("timeoutSec");+ break;+ case "--state-dir":+ set("stateDir");+ break;+ case "--continue-on-error":+ set("continueOnError", false);+ break;+ case "--baseline":+ set("baseline");+ break;+ case "--candidate":+ set("candidate");+ break;+ case "--out":+ set("out");+ break;+ default:+ fail(`unknown flag: ${key}`);+ }+ }++ if (positional.length > 0) {+ args.cmd = positional[0];+ }+ args.outDir = path.resolve(args.outDir);+ args.stateDir = path.resolve(args.stateDir);+ args.timeoutSec = Number.parseInt(String(args.timeoutSec), 10);+ if (!Number.isFinite(args.timeoutSec) || args.timeoutSec <= 0) {+ fail("--timeout-sec must be a positive integer");+ }+ return args;+}++function loadPrompts(promptsPath) {+ if (!promptsPath) {+ fail("run mode requires --prompts");+ }+ const resolved = path.resolve(promptsPath);+ if (!fs.existsSync(resolved)) {+ fail(`prompts file not found: ${resolved}`);+ }+ const raw = fs.readFileSync(resolved, "utf8");+ let prompts = [];+ if (resolved.endsWith(".json")) {+ const parsed = JSON.parse(raw);+ if (!Array.isArray(parsed)) {+ fail("prompts JSON must be an array");+ }+ prompts = parsed.map((item, index) => {+ if (typeof item === "string") {+ return { id: `turn-${index + 1}`, prompt: item };+ }+ if (+ item &&+ typeof item === "object" &&+ typeof item.prompt === "string" &&+ item.prompt.trim()+ ) {+ return {+ id: typeof item.id === "string" && item.id.trim() ? item.id.trim() : `turn-${index + 1}`,+ prompt: item.prompt,+ };+ }+ fail(`invalid prompt entry at index ${index}`);+ });+ } else {+ prompts = raw+ .split(/\r?\n/)+ .map((line) => line.trim())+ .filter(Boolean)+ .map((line, index) => ({ id: `turn-${index + 1}`, prompt: line }));+ }++ if (prompts.length === 0) {+ fail("no prompts found");+ }+ return { prompts, path: resolved };+}++function loadSessionStore(stateDir, agentId) {+ const storePath = path.join(stateDir, "agents", agentId, "sessions", "sessions.json");+ if (!fs.existsSync(storePath)) {+ return { storePath, store: {} };+ }+ try {+ const parsed = JSON.parse(fs.readFileSync(storePath, "utf8"));+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {+ return { storePath, store: {} };+ }+ return { storePath, store: parsed };+ } catch {+ return { storePath, store: {} };+ }+}++function pickSessionEntryById(store, sessionId) {+ const matches = Object.entries(store)+ .filter(([, entry]) => entry)+ .map(([key, entry]) => ({ key, entry }));+ if (matches.length === 0) {+ return undefined;+ }+ matches.sort((a, b) => (asNumber(b.entry.updatedAt) ?? 0) - (asNumber(a.entry.updatedAt) ?? 0));+ return matches[0];+}++function extractUsageInfo(parsed) {+ const root = parsed && typeof parsed === "object" ? parsed : {};+ const result = root.result && typeof root.result === "object" ? root.result : null;+ const metaCandidate =+ (result?.meta && typeof result.meta === "object" ? result.meta : null) ||+ (root.meta && typeof root.meta === "object" ? root.meta : null);+ const agentMeta =+ metaCandidate?.agentMeta && typeof metaCandidate.agentMeta === "object"+ ? metaCandidate.agentMeta+ : null;+ const usage = agentMeta?.usage && typeof agentMeta.usage === "object" ? agentMeta.usage : null;+ const readNumber = (obj, keys) => {+ if (!obj || typeof obj !== "object") {+ return undefined;+ }+ for (const key of keys) {+ const value = asNumber(obj[key]);+ if (value !== undefined) {+ return value;+ }+ }+ return undefined;+ };++ const inputTokens = readNumber(usage, [+ "input",+ "inputTokens",+ "input_tokens",+ "promptTokens",+ "prompt_tokens",+ ]);+ const outputTokens = readNumber(usage, ["output", "outputTokens", "output_tokens", "completion_tokens"]);+ const cacheRead = readNumber(usage, ["cacheRead", "cache_read", "cache_read_input_tokens"]);+ const cacheWrite = readNumber(usage, ["cacheWrite", "cache_write", "cache_creation_input_tokens"]);+ const promptTokens =+ asNumber(agentMeta?.promptTokens) ??+ (inputTokens !== undefined || cacheRead !== undefined || cacheWrite !== undefined+ ? (inputTokens ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0)+ : undefined);+ const totalUsageTokens =+ readNumber(usage, ["total", "totalTokens", "total_tokens"]) ??+ (inputTokens !== undefined ||+ outputTokens !== undefined ||+ cacheRead !== undefined ||+ cacheWrite !== undefined+ ? (inputTokens ?? 0) + (outputTokens ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0)+ : undefined);+ const compactionCount = asNumber(agentMeta?.compactionCount);+ const sessionId =+ typeof agentMeta?.sessionId === "string" && agentMeta.sessionId.trim()+ ? agentMeta.sessionId.trim()+ : undefined;++ return {+ inputTokens,+ outputTokens,+ cacheRead,+ cacheWrite,+ promptTokens,+ totalUsageTokens,+ compactionCount,+ sessionId,+ };+}++function extractReplyInfo(resultPayload) {+ const payloads = Array.isArray(resultPayload?.payloads) ? resultPayload.payloads : [];+ const textParts = [];+ let mediaCount = 0;+ for (const payload of payloads) {+ if (payload && typeof payload.text === "string" && payload.text.trim()) {+ textParts.push(payload.text);+ }+ if (payload && Array.isArray(payload.mediaUrls)) {+ mediaCount += payload.mediaUrls.length;+ }+ if (payload && typeof payload.mediaUrl === "string" && payload.mediaUrl.trim()) {+ mediaCount += 1;+ }+ }+ const text = textParts.join("\n").trim();+ return {+ textChars: text.length,+ mediaCount,+ payloadCount: payloads.length,+ };+}++function computeSummary(rows) {+ const durations = rows.map((r) => r.durationMs).filter((v) => typeof v === "number").sort((a, b) => a - b);+ const sum = (field) => rows.reduce((acc, row) => acc + (numOrZero(row[field]) || 0), 0);+ const count = rows.length;+ const totals = {+ inputTokens: sum("inputTokens"),+ outputTokens: sum("outputTokens"),+ cacheRead: sum("cacheRead"),+ cacheWrite: sum("cacheWrite"),+ promptTokens: sum("promptTokens"),+ totalUsageTokens: sum("totalUsageTokens"),+ replyChars: sum("replyChars"),+ };+ const avg = (value) => (count > 0 ? value / count : 0);+ const promptBase = totals.inputTokens + totals.cacheRead + totals.cacheWrite;+ const cacheReadShare = promptBase > 0 ? totals.cacheRead / promptBase : 0;+ return {+ turns: count,+ totals,+ averages: {+ inputTokens: avg(totals.inputTokens),+ outputTokens: avg(totals.outputTokens),+ cacheRead: avg(totals.cacheRead),+ cacheWrite: avg(totals.cacheWrite),+ promptTokens: avg(totals.promptTokens),+ totalUsageTokens: avg(totals.totalUsageTokens),+ durationMs: avg(sum("durationMs")),+ replyChars: avg(totals.replyChars),+ },+ latencyMs: {+ p50: percentile(durations, 50),+ p90: percentile(durations, 90),+ max: durations.length ? durations[durations.length - 1] : 0,+ },+ cacheReadShare,+ compactionTriggeredTurns: rows.filter((r) => numOrZero(r.compactionCountDelta) > 0).length,+ };+}++function moveSessionJsonlFiles(stateDir, agentId, outDir, sessionStorePath) {+ const sessionsDir = path.join(stateDir, "agents", agentId, "sessions");+ if (!fs.existsSync(sessionsDir)) {+ return 0;+ }+ const names = fs.readdirSync(sessionsDir).filter((name) => name.endsWith(".jsonl"));+ if (names.length === 0) {+ return 0;+ }+ fs.mkdirSync(outDir, { recursive: true });+ let moved = 0;+ for (const name of names) {+ const source = path.join(sessionsDir, name);+ // const target = path.join(outDir, name);+ const target = sessionStorePath;+ try {+ fs.renameSync(source, target);+ moved += 1;+ } catch (err) {+ if (err && typeof err === "object" && "code" in err && err.code === "EXDEV") {+ fs.copyFileSync(source, target);+ fs.unlinkSync(source);+ moved += 1;+ } else {+ throw err;+ }+ }+ }+ return moved;+}++function runBench(args) {+ const loaded = loadPrompts(args.prompts);+ const startedAt = nowIso();+ const rows = [];+ let prevCompactionCount;+ let failures = 0;+ fs.mkdirSync(args.outDir, { recursive: true });++ console.log(`[sccs-bench] started at ${startedAt}`);+ console.log(`[sccs-bench] prompts: ${loaded.path} (${loaded.prompts.length} turns)`);+ console.log(`[sccs-bench] target: agent=${args.agent} to=${args.to} sessionId=${args.sessionId}`);++ for (let i = 0; i < loaded.prompts.length; i += 1) {+ const turn = loaded.prompts[i];+ const cmdArgs = [+ "agent",+ "--agent",+ String(args.agent),+ // "--to",+ // String(args.to),+ // "--session-id",+ // String(args.sessionId),+ "--timeout",+ String(args.timeoutSec),+ "--message",+ turn.prompt,+ "--json",+ ];++ const begin = Date.now();+ const result = spawnSync(String(args.openclawBin), cmdArgs, {+ encoding: "utf8",+ maxBuffer: 10 * 1024 * 1024,+ });+ const durationMs = Date.now() - begin;++ let parsed;+ let errorMessage = "";+ if (result.status !== 0) {+ errorMessage = `exit=${result.status} stderr=${(result.stderr || "").trim()}`;+ } else {+ try {+ parsed = JSON.parse((result.stdout || "").trim() || "{}");+ } catch (err) {+ errorMessage = `json parse failed: ${String(err)}`;+ }+ }++ const usageInfo = extractUsageInfo(parsed);+ console.log(`[sccs-bench] usageInfo: ${JSON.stringify(usageInfo)}`);+ const { storePath, store } = loadSessionStore(args.stateDir, args.agent);+ const match =+ pickSessionEntryById(store, usageInfo.sessionId ?? args.sessionId) ??+ pickSessionEntryById(store, args.sessionId);+ const entry = match?.entry ?? {};++ const inputTokens = usageInfo.inputTokens ?? numOrZero(entry.inputTokens);+ const outputTokens = usageInfo.outputTokens ?? numOrZero(entry.outputTokens);+ const cacheRead = usageInfo.cacheRead ?? numOrZero(entry.cacheRead);+ const cacheWrite = usageInfo.cacheWrite ?? numOrZero(entry.cacheWrite);+ const promptTokens = usageInfo.promptTokens ?? inputTokens + cacheRead + cacheWrite;+ const totalUsageTokens =+ usageInfo.totalUsageTokens ?? inputTokens + outputTokens + cacheRead + cacheWrite;+ const compactionCount = usageInfo.compactionCount ?? numOrZero(entry.compactionCount);+ const compactionCountDelta =+ prevCompactionCount === undefined ? 0 : Math.max(0, compactionCount - prevCompactionCount);+ prevCompactionCount = compactionCount;+ const replyInfo = extractReplyInfo(parsed?.result ?? parsed);++ const row = {+ turn: i + 1,+ turnId: turn.id,+ prompt: turn.prompt,+ status: parsed?.status ?? (errorMessage ? "error" : "unknown"),+ runId: parsed?.runId ?? "",+ durationMs,+ sessionStorePath: storePath,+ sessionKey: match?.key ?? "",+ sessionId: usageInfo.sessionId ?? args.sessionId,+ inputTokens,+ outputTokens,+ cacheRead,+ cacheWrite,+ promptTokens,+ totalUsageTokens,+ contextSnapshotTokens: asNumber(entry.totalTokens) ?? null,+ contextTokensLimit: asNumber(entry.contextTokens) ?? null,+ totalTokensFresh: entry.totalTokensFresh !== false,+ compactionCount,+ compactionCountDelta,+ replyChars: replyInfo.textChars,+ replyPayloadCount: replyInfo.payloadCount,+ replyMediaCount: replyInfo.mediaCount,+ error: errorMessage,+ };+ rows.push(row);++ const basic = `turn ${i + 1}/${loaded.prompts.length} status=${row.status} dur=${durationMs}ms in=${inputTokens} out=${outputTokens} cacheR=${cacheRead}`;+ if (errorMessage) {+ failures += 1;+ console.error(`[sccs-bench] ${basic} error=${errorMessage}`);+ if (!args.continueOnError) {+ break;+ }+ } else {+ console.log(`[sccs-bench] ${basic}`);+ }+ }++ const endedAt = nowIso();+ const summary = computeSummary(rows);+ const report = {+ metadata: {+ label: args.label,+ startedAt,+ endedAt,+ promptsPath: loaded.path,+ openclawBin: args.openclawBin,+ agent: args.agent,+ to: args.to,+ sessionId: args.sessionId,+ stateDir: args.stateDir,+ failures,+ turnsExecuted: rows.length,+ },+ summary,+ rows,+ };++ const stamp = new Date().toISOString().replace(/[:.]/g, "-");+ const baseName = `${args.label}-${stamp}`;+ const jsonPath = path.join(args.outDir, `${baseName}.json`);+ const csvPath = path.join(args.outDir, `${baseName}.csv`);+ const sessionStorePath = path.join(args.outDir, `${baseName}-sessions.json`);++ fs.writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");+ const headers = [+ "turn",+ "turnId",+ "status",+ "runId",+ "durationMs",+ "inputTokens",+ "outputTokens",+ "cacheRead",+ "cacheWrite",+ "promptTokens",+ "totalUsageTokens",+ "contextSnapshotTokens",+ "contextTokensLimit",+ "totalTokensFresh",+ "compactionCount",+ "compactionCountDelta",+ "replyChars",+ "replyPayloadCount",+ "replyMediaCount",+ "sessionKey",+ "sessionId",+ "error",+ ];+ fs.writeFileSync(csvPath, toCsv(rows, headers), "utf8");+ const movedSessions = moveSessionJsonlFiles(args.stateDir, args.agent, args.outDir, sessionStorePath);+ if (movedSessions > 0) {+ console.log(`[sccs-bench] archived ${movedSessions} session jsonl file(s) to ${args.outDir}`);+ }++ console.log(`[sccs-bench] finished at ${endedAt}`);+ console.log(`[sccs-bench] report json: ${jsonPath}`);+ console.log(`[sccs-bench] report csv : ${csvPath}`);+ console.log(+ `[sccs-bench] totals: input=${summary.totals.inputTokens} output=${summary.totals.outputTokens} cacheRead=${summary.totals.cacheRead} cacheWrite=${summary.totals.cacheWrite} usageTotal=${summary.totals.totalUsageTokens}`,+ );+}++function ratioDiff(base, cand) {+ if (base === 0) {+ return null;+ }+ return (cand - base) / base;+}++function compareReports(args) {+ if (!args.baseline || !args.candidate) {+ fail("compare mode requires --baseline and --candidate");+ }+ const basePath = path.resolve(args.baseline);+ const candPath = path.resolve(args.candidate);+ if (!fs.existsSync(basePath) || !fs.existsSync(candPath)) {+ fail("baseline/candidate report file not found");+ }+ const base = JSON.parse(fs.readFileSync(basePath, "utf8"));+ const cand = JSON.parse(fs.readFileSync(candPath, "utf8"));++ const pick = (obj, pathExpr) =>+ pathExpr.split(".").reduce((acc, key) => (acc && key in acc ? acc[key] : undefined), obj);+ const metrics = [+ "summary.totals.inputTokens",+ "summary.totals.outputTokens",+ "summary.totals.cacheRead",+ "summary.totals.cacheWrite",+ "summary.totals.totalUsageTokens",+ "summary.averages.durationMs",+ "summary.latencyMs.p50",+ "summary.latencyMs.p90",+ "summary.compactionTriggeredTurns",+ ];+ const rows = metrics.map((name) => {+ const baseline = numOrZero(pick(base, name));+ const candidate = numOrZero(pick(cand, name));+ const diff = candidate - baseline;+ const pct = ratioDiff(baseline, candidate);+ return {+ metric: name,+ baseline,+ candidate,+ diff,+ diffPercent: pct,+ };+ });++ const report = {+ comparedAt: nowIso(),+ baseline: {+ path: basePath,+ label: base?.metadata?.label ?? "baseline",+ turns: base?.summary?.turns ?? 0,+ },+ candidate: {+ path: candPath,+ label: cand?.metadata?.label ?? "candidate",+ turns: cand?.summary?.turns ?? 0,+ },+ metrics: rows,+ };++ const outPath = args.out+ ? path.resolve(args.out)+ : path.join(+ path.dirname(candPath),+ `compare-${Date.now()}.json`,+ );+ fs.writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");++ console.log(`[sccs-bench] compare report: ${outPath}`);+ for (const row of rows) {+ const pctText =+ row.diffPercent === null ? "n/a" : `${(row.diffPercent * 100).toFixed(2)}%`;+ console.log(+ `[sccs-bench] ${row.metric}: baseline=${row.baseline} candidate=${row.candidate} diff=${row.diff} (${pctText})`,+ );+ }+}++function printHelp() {+ console.log(`Usage:+ node bench/run-sccs-bench.mjs run \\+ --prompts bench/prompts-realistic-24.json \\+ --label baseline --agent main --to +15555550123 --session-id bench-baseline++ node bench/run-sccs-bench.mjs compare \\+ --baseline bench-results/baseline.json \\+ --candidate bench-results/sccs.json++Run options:+ --openclaw <bin> openclaw binary path (default: openclaw)+ --prompts <file> prompts file (.json array or .txt line-by-line)+ --out-dir <dir> output directory (default: ./bench-results)+ --label <name> run label for output files+ --agent <id> agent id (default: main)+ --to <E.164> fixed sender/recipient for stable session key+ --session-id <id> fixed session id for this benchmark+ --timeout-sec <sec> agent timeout seconds (default: 600)+ --state-dir <dir> OpenClaw state dir (default: ~/.openclaw)+ --continue-on-error continue remaining turns on failures++Compare options:+ --baseline <json> baseline report path+ --candidate <json> candidate report path+ --out <json> output path for compare report+`);+}++const args = parseArgs(process.argv.slice(2));+if (args.cmd === "help" || args.cmd === "--help" || args.cmd === "-h") {+ printHelp();+ process.exit(0);+}+if (args.cmd === "run") {+ runBench(args);+ process.exit(0);+}+if (args.cmd === "compare") {+ compareReports(args);+ process.exit(0);+}+fail(`unknown command: ${args.cmd}`);diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/test1.json b/examples/openclaw-plugin/tests/toolresult_compression_tests/test1.jsonnew file mode 100644index 000000000..bbd81af92--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/test1.json@@ -0,0 +1,14 @@+[+ {+ "id": "t1-heavy-ingest",+ "prompt": "严格执行:你必须且只允许调用4次 read 工具,按以下顺序读取,不允许读取其他文件,不允许 exec/rg。\n1) /root/.openclaw/workspace/kubernetes/pkg/kubelet/kubelet.go\n2) /root/.openclaw/workspace/kubernetes/pkg/scheduler/schedule_one.go\n3) /root/.openclaw/workspace/kubernetes/staging/src/k8s.io/apiserver/pkg/endpoints/handlers/create.go\n4) /root/.openclaw/workspace/kubernetes/staging/src/k8s.io/apimachinery/pkg/util/version/version.go\n读取后输出固定格式:\nMODULE_MAP:\n- module: <name>\n file: <path>\n responsibilities: [3条]\n key_functions: [3个]\nCROSS_MODULE_RISKS:\n- [5条,每条1行]\n禁止输出其他章节。"+ },+ {+ "id": "t2-no-tool-design",+ "prompt": "禁止调用任何工具(如果调用则任务失败)。仅基于上一轮已有内容,输出固定格式:\nDESIGN_V1:\n- target_module: <1个>\n- problem_statement: <3行内>\n- minimal_change_scope: <最多2文件,允许只写方案不改代码>\n- behavior_invariants: [3条]\n- rollback_plan: [2条]\n不要新增章节。"+ },+ {+ "id": "t3-no-tool-delivery",+ "prompt": "禁止调用任何工具。输出固定模板(每项1-2行):\nFILES_TOUCHED_PLAN\nBEFORE_BEHAVIOR\nAFTER_BEHAVIOR\nRISK\nNEXT_ACTION\n不要输出其他内容。"+ }+]diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/test2.json b/examples/openclaw-plugin/tests/toolresult_compression_tests/test2.jsonnew file mode 100644index 000000000..e03643cb8--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/test2.json@@ -0,0 +1,19 @@+[+ {+ "id": "t1-module-ingest",+ "prompt": "你在做一次真实的模块接手分析。目标:理解 kubelet 中“Pod 处理与状态更新”主链路。仅允许读取以下文件,不允许读取其他文件,不允许测试:\n1) /root/.openclaw/workspace/kubernetes/pkg/kubelet/kubelet.go\n2) /root/.openclaw/workspace/kubernetes/pkg/kubelet/pod_workers.go\n3) /root/.openclaw/workspace/kubernetes/pkg/kubelet/status/status_manager.go\n4) /root/.openclaw/workspace/kubernetes/pkg/kubelet/pleg/generic.go\n输出固定格式:\nCHAIN_MAP(5-8条)\nHOTSPOTS(3条)\nOBSERVABILITY_GAPS(3条)\n禁止额外章节。"+ },+ {+ "id": "t2-design-no-tools",+ "prompt": "禁止调用任何工具。基于上一轮内容,选择1个最有价值的 hotspot,给出最小改造方案(偏设计,不改代码)。输出固定格式:\nTARGET\nPROBLEM\nMINIMAL_SCOPE(最多2个文件)\nINVARIANTS(3条)\nROLLBACK(2条)"+ },+ {+ "id": "t3-patch-plan-no-tools",+ "prompt": "禁止调用任何工具。把方案细化成可执行改动计划,输出固定格式:\nEDIT_PLAN(按文件列出函数级改动)\nPSEUDO_DIFF(10-20行伪代码)\nRISK_CHECKLIST(5条)"+ },+ {+ "id": "t4-delivery-no-tools",+ "prompt": "禁止调用任何工具。输出可直接贴到 PR 描述的交付摘要,固定格式:\nCONTEXT\nROOT_CAUSE_HYPOTHESIS\nPROPOSED_CHANGE\nEXPECTED_IMPACT\nKNOWN_RISKS\nNEXT_STEP"+ }+]+diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/test3.json b/examples/openclaw-plugin/tests/toolresult_compression_tests/test3.jsonnew file mode 100644index 000000000..2a59aad55--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/test3.json@@ -0,0 +1,19 @@+[+ {+ "id": "t1-retrieval-ingest",+ "prompt": "你在做一次真实的检索链路评审。目标:梳理 OpenViking 从 API/Client 到 index engine 的检索契约。请只读取以下文件,每个只读一次:\n1) /root/.openclaw/workspace/OpenViking/docs/en/api/06-retrieval.md\n2) /root/.openclaw/workspace/OpenViking/openviking_cli/client/sync_http.py\n3) /root/.openclaw/workspace/OpenViking/openviking_cli/retrieve/types.py\n4) /root/.openclaw/workspace/OpenViking/src/index/index_engine.cpp\n输出 JSON:\n{api_contract:{inputs:[...],outputs:[...],error_shapes:[...]},pipeline:[{stage,file,function,contract}],mismatch_candidates:[{name,where_detected,why}],evidence:[{file,function,line,why}]}"+ },+ {+ "id": "t2-contract-design",+ "prompt": "基于上轮结果,优先使用已整理的上下文;只有在关键信息缺失时,才补充一次原文回查并说明原因。选 1 个最重要 mismatch,设计最小契约收敛方案(不改代码)。输出 JSON:\n{target_mismatch,proposed_contract_delta:{before,after},affected_components:[{file,owner_role}],compatibility_strategy:[{consumer,impact,mitigation}],rollout_plan:[{phase,goal,exit_criteria}]}"+ },+ {+ "id": "t3-implementation-outline",+ "prompt": "基于前两轮内容,给出实施大纲(函数级,不改代码)。输出 JSON:\n{change_outline:[{file,functions:[{name,action,expected_result}]}],data_validation_rules:[{rule,reason}],observability_additions:[{signal,location,why}],verification_matrix:[{scenario,expected_result}]}"+ },+ {+ "id": "t4-rfc-summary",+ "prompt": "基于前 3 轮内容,输出 RFC 风格摘要。输出 JSON:\n{problem,decision,alternatives_considered:[{option,reject_reason}],impact_assessment:{correctness,latency,operability},risk_register:[{risk,level,owner,mitigation}],go_no_go_criteria:[{criterion,measure}]}"+ }+]+diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/test4.json b/examples/openclaw-plugin/tests/toolresult_compression_tests/test4.jsonnew file mode 100644index 000000000..7de994c1a--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/test4.json@@ -0,0 +1,19 @@+[+ {+ "id": "t1-pipeline-ingest",+ "prompt": "你在做一次真实的集成链路评审。目标:梳理 openclaw-plugin 到 OpenViking 的记忆写入与回忆链路。请只读取以下文件,每个只读一次:\n1) /root/.openclaw/workspace/OpenViking/examples/openclaw-plugin/index.ts\n2) /root/.openclaw/workspace/OpenViking/examples/openclaw-plugin/context-engine.ts\n3) /root/.openclaw/workspace/OpenViking/examples/openclaw-plugin/client.js\n4) /root/.openclaw/workspace/OpenViking/docs/en/concepts/06-extraction.md\n输出 JSON:\n{pipeline_map:[{stage,component,file,function,input,output}],failure_points:[{name,where,symptom,severity}],consistency_requirements:[{requirement,why}],evidence:[{file,function,line,why}]}"+ },+ {+ "id": "t2-reliability-design",+ "prompt": "基于上轮结果,优先使用已整理的上下文;只有在关键信息缺失时,才补充一次原文回查并说明原因。针对 1 个最高优先 failure point,提出最小可靠性增强设计(不改代码)。输出 JSON:\n{target_failure_point,design_delta:{before,after},minimal_scope:[{file,change_intent}],failure_handling_policy:[{case,policy}],rollback:[{step,when_to_use}]}"+ },+ {+ "id": "t3-implementation-guide",+ "prompt": "基于前两轮内容,输出实施指引(函数级,不改代码)。输出 JSON:\n{implementation_guide:[{file,functions:[{name,planned_change,expected_effect}]}],observability_plan:[{signal,location,alert_condition}],verification_checklist:[{item,pass_condition}],known_tradeoffs:[{tradeoff,accepted_reason}]}"+ },+ {+ "id": "t4-handoff-summary",+ "prompt": "基于前 3 轮内容,输出交接摘要。输出 JSON:\n{problem_statement,proposed_solution,expected_reliability_gain,risk_register:[{risk,level,mitigation}],handoff_todo:[{owner,task,done_definition}],traceability:[{claim,evidence_file,evidence_function,evidence_line}]}"+ }+]+diff --git a/examples/openclaw-plugin/tests/toolresult_compression_tests/test5.json b/examples/openclaw-plugin/tests/toolresult_compression_tests/test5.jsonnew file mode 100644index 000000000..e7434e6bb--- /dev/null+++ b/examples/openclaw-plugin/tests/toolresult_compression_tests/test5.json@@ -0,0 +1,18 @@+[+ {+ "id": "t1-structured-ingest",+ "prompt": "你在做一次会话链路接手。请只读取以下文件,并只关注指定函数:\n1) /root/.openclaw/workspace/openclaw/src/agents/command/session.ts -> resolveSession\n2) /root/.openclaw/workspace/openclaw/src/agents/command/session-store.ts -> updateSessionStoreAfterAgentRun\n3) /root/.openclaw/workspace/openclaw/src/agents/command/delivery.ts -> deliverAgentCommandResult\n4) /root/.openclaw/workspace/openclaw/src/agents/agent-command.ts -> prepareAgentCommandExecution, agentCommandInternal\n输出严格 JSON(仅此结构,不要额外字段):\n{\n \"chain_map\": [\n {\"id\":\"S1\",\"stage\":\"session_resolve\",\"file\":\"\",\"function\":\"resolveSession\",\"input\":\"\",\"output\":\"\"},\n {\"id\":\"S2\",\"stage\":\"session_store_update\",\"file\":\"\",\"function\":\"updateSessionStoreAfterAgentRun\",\"input\":\"\",\"output\":\"\"},\n {\"id\":\"S3\",\"stage\":\"delivery\",\"file\":\"\",\"function\":\"deliverAgentCommandResult\",\"input\":\"\",\"output\":\"\"}\n ],\n \"evidence_index\": [\n {\"evidence_id\":\"E1\",\"claim\":\"session key/session id resolution occurs before run\",\"file\":\"\",\"function\":\"\",\"line_hint\":\"\"},\n {\"evidence_id\":\"E2\",\"claim\":\"usage and token fields are persisted in session store\",\"file\":\"\",\"function\":\"\",\"line_hint\":\"\"},\n {\"evidence_id\":\"E3\",\"claim\":\"json response envelope is formed at delivery stage\",\"file\":\"\",\"function\":\"\",\"line_hint\":\"\"}\n ]\n}"+ },+ {+ "id": "t2-fixed-design",+ "prompt": "基于上轮内容,做最小改造设计(不改代码),并固定目标为 E2 对应问题。输出严格 JSON(仅此结构):\n{\n \"target_evidence_id\": \"E2\",\n \"problem_statement\": \"\",\n \"minimal_scope\": [\n {\"file\":\"/root/.openclaw/workspace/openclaw/src/agents/command/session-store.ts\",\"planned_change\":\"\"},\n {\"file\":\"/root/.openclaw/workspace/openclaw/src/agents/agent-command.ts\",\"planned_change\":\"\"}\n ],\n \"invariants\": [\"\", \"\", \"\"],\n \"rollback\": [\"\", \"\"]\n}"+ },+ {+ "id": "t3-review-evidence-pack",+ "prompt": "现在要提交设计评审材料。请为 E2 和 E3 各提供一段精确代码证据(每段 8-12 行,保留缩进)。优先基于前文;如果需要精确原文,请从第一轮已采集引用中回取。输出严格 JSON:\n{\n \"evidence_pack\": [\n {\"evidence_id\":\"E2\",\"file\":\"\",\"function\":\"\",\"line_range_hint\":\"\",\"code_snippet\":\"\"},\n {\"evidence_id\":\"E3\",\"file\":\"\",\"function\":\"\",\"line_range_hint\":\"\",\"code_snippet\":\"\"}\n ]\n}"+ },+ {+ "id": "t4-final-summary",+ "prompt": "输出交付摘要,严格 JSON(仅此结构):\n{\n \"context\": \"\",\n \"root_cause_hypothesis\": \"\",\n \"proposed_change\": \"\",\n \"expected_impact\": \"\",\n \"known_risks\": \"\",\n \"next_step\": \"\",\n \"traceability\": [\n {\"claim\":\"session resolution\",\"evidence_id\":\"E1\"},\n {\"claim\":\"usage persistence\",\"evidence_id\":\"E2\"},\n {\"claim\":\"delivery envelope\",\"evidence_id\":\"E3\"}\n ]\n}"+ }+]\ No newline at end of filediff --git a/examples/openclaw-plugin/tests/ut/context-engine-afterTurn.test.ts b/examples/openclaw-plugin/tests/ut/context-engine-afterTurn.test.tsindex 7515dac1b..3e07edd90 100644--- a/examples/openclaw-plugin/tests/ut/context-engine-afterTurn.test.ts+++ b/examples/openclaw-plugin/tests/ut/context-engine-afterTurn.test.ts@@ -496,7 +496,7 @@ describe("context-engine afterTurn()", () => {expect(client.addSessionMessage.mock.calls[2][1]).toBe("assistant");});- it("stores adjacent toolResults as separate user groups with current extractor behavior", async () => {+ it("coalesces adjacent toolResults into one user group for turn-level budgets", async () => {const { engine, client } = makeEngine();const messages = [@@ -516,13 +516,14 @@ describe("context-engine afterTurn()", () => {prePromptMessageCount: 0,});- expect(client.addSessionMessage).toHaveBeenCalledTimes(4);+ expect(client.addSessionMessage).toHaveBeenCalledTimes(3);expect(client.addSessionMessage.mock.calls[0][1]).toBe("assistant");expect(client.addSessionMessage.mock.calls[1][1]).toBe("user");- expect((client.addSessionMessage.mock.calls[1][2] as Array<{ tool_output?: string }>)[0]?.tool_output).toContain("content of a");- expect(client.addSessionMessage.mock.calls[2][1]).toBe("user");- expect((client.addSessionMessage.mock.calls[2][2] as Array<{ tool_output?: string }>)[0]?.tool_output).toContain("ok");- expect(client.addSessionMessage.mock.calls[3][1]).toBe("assistant");+ const toolParts = client.addSessionMessage.mock.calls[1][2] as Array<{ tool_output?: string }>;+ expect(toolParts).toHaveLength(2);+ expect(toolParts[0]?.tool_output).toContain("content of a");+ expect(toolParts[1]?.tool_output).toContain("ok");+ expect(client.addSessionMessage.mock.calls[2][1]).toBe("assistant");});it("sanitizes <relevant-memories> from assistant content", async () => {diff --git a/examples/openclaw-plugin/tests/ut/text-utils.test.ts b/examples/openclaw-plugin/tests/ut/text-utils.test.tsindex ddf1ed333..29c9b0ff5 100644--- a/examples/openclaw-plugin/tests/ut/text-utils.test.ts+++ b/examples/openclaw-plugin/tests/ut/text-utils.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";import {sanitizeUserTextForCapture,getCaptureDecision,+ extractNewTurnMessages,extractNewTurnTexts,extractLatestUserText,pickRecentUniqueTexts,@@ -221,6 +222,87 @@ describe("extractNewTurnTexts", () => {});});+describe("extractNewTurnMessages", () => {+ it("keeps assistant toolCall messages that have no text block", () => {+ const messages = [+ {+ role: "assistant",+ content: [+ { type: "thinking", text: "Need to inspect the file first." },+ { type: "toolCall", id: "call_1", name: "read_file", arguments: { path: "a.txt" } },+ ],+ },+ ];++ const { messages: extracted, newCount } = extractNewTurnMessages(messages, 0);++ expect(newCount).toBe(1);+ expect(extracted).toEqual([+ {+ role: "assistant",+ parts: [{ type: "text", text: "[tool: read_file]" }],+ },+ ]);+ });++ it("keeps assistant toolUse messages that have no text block", () => {+ const messages = [+ {+ role: "assistant",+ content: [+ { type: "thinking", text: "Search first." },+ { type: "toolUse", id: "call_2", name: "grep", input: { pattern: "TODO" } },+ ],+ },+ ];++ const { messages: extracted, newCount } = extractNewTurnMessages(messages, 0);++ expect(newCount).toBe(1);+ expect(extracted).toEqual([+ {+ role: "assistant",+ parts: [{ type: "text", text: "[tool: grep]" }],+ },+ ]);+ });++ it("keeps multiple textless assistant tool calls in one placeholder", () => {+ const messages = [+ {+ role: "assistant",+ content: [+ { type: "tool_call", id: "call_1", toolName: "read_file" },+ { type: "tool_use", id: "call_2", name: "grep" },+ ],+ },+ ];++ const { messages: extracted } = extractNewTurnMessages(messages, 0);++ expect(extracted).toEqual([+ {+ role: "assistant",+ parts: [{ type: "text", text: "[tool: read_file, grep]" }],+ },+ ]);+ });++ it("does not create a placeholder for textless assistant messages without tool calls", () => {+ const messages = [+ {+ role: "assistant",+ content: [{ type: "thinking", text: "Internal reasoning only." }],+ },+ ];++ const { messages: extracted, newCount } = extractNewTurnMessages(messages, 0);++ expect(newCount).toBe(1);+ expect(extracted).toEqual([]);+ });+});+describe("extractLatestUserText", () => {it("returns last user text from messages", () => {const messages = [diff --git a/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts b/examples/openclaw-plugin/tests/ut/tool-round-trip.test.tsindex 2866fb905..e65b61fd9 100644--- a/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts+++ b/examples/openclaw-plugin/tests/ut/tool-round-trip.test.ts@@ -134,6 +134,31 @@ describe("convertToAgentMessages: structured tool round-trip", () => {expect(result[1]!.role).toBe("toolResult");});+ it("preserves externalized tool result ref in toolResult text", () => {+ const msg = {+ role: "user",+ parts: [+ {+ type: "tool",+ tool_id: "call_big",+ tool_name: "read",+ tool_status: "completed",+ tool_input: { path: "/tmp/big.txt" },+ tool_output: "preview only",+ tool_output_ref: "viking://session/s1/tool-results/tr_call_big_abc",+ tool_output_original_chars: 120000,+ },+ ],+ };++ const result = convertToAgentMessages(msg);+ const toolResult = result[1] as Record<string, unknown>;+ const content = toolResult.content as Array<Record<string, string>>;+ expect(content[0]!.text).toContain("preview only");+ expect(content[0]!.text).toContain("viking://session/s1/tool-results/tr_call_big_abc");+ expect(content[0]!.text).toContain("original_chars=120000");+ });+it("no tool_id → degrade to text (user role)", () => {const msg = {role: "user",diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.tsindex a6ff28a19..18dfaf978 100644--- a/examples/openclaw-plugin/tests/ut/tools.test.ts+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts@@ -470,6 +470,157 @@ describe("Tool: ov_archive_expand (behavioral)", () => {});});+describe("Tool: OpenViking tool result access", () => {+ it("registers read, search, and list tools", () => {+ const { tools, api } = setupPlugin();+ contextEnginePlugin.register(api as any);++ expect(tools.get("openviking_tool_result_read")).toBeDefined();+ expect(tools.get("openviking_tool_result_search")).toBeDefined();+ expect(tools.get("openviking_tool_result_list")).toBeDefined();+ });++ it("reads an externalized tool result chunk for the current session", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ expect(url).toContain("/api/v1/sessions/test-session/tool-results/tr_call_abc");+ expect(url).toContain("offset=5");+ expect(url).toContain("limit=10");+ expect(url).toContain("include_metadata=true");+ return okResponse({+ tool_result_id: "tr_call_abc",+ content: "raw",+ offset: 5,+ limit: 10,+ offset_unit: "unicode_code_point",+ total_chars: 42,+ has_more: true,+ metadata: {+ storage_uri: "viking://session/test-session/tool-results/tr_call_abc",+ tool_name: "read_file",+ },+ });+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, api } = setupPlugin();+ contextEnginePlugin.register(api as any);+ const tool = tools.get("openviking_tool_result_read")!;++ const result = await tool.execute("tc-read", {+ tool_output_ref: "viking://session/test-session/tool-results/tr_call_abc",+ offset: 5,+ limit: 10,+ }) as ToolResult;++ expect(result.content[0]!.text).toBe("raw");+ expect(result.details).toMatchObject({+ action: "read",+ tool_output_ref: "viking://session/test-session/tool-results/tr_call_abc",+ tool_result_id: "tr_call_abc",+ offset: 5,+ limit: 10,+ returned_chars: 3,+ total_chars: 42,+ has_more: true,+ next_offset: 8,+ });+ });++ it("searches within an externalized tool result", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ expect(url).toContain("/api/v1/sessions/test-session/tool-results/tr_call_abc/search?");+ expect(url).toContain("q=needle");+ expect(url).toContain("limit=2");+ expect(url).toContain("context_chars=15");+ return okResponse({+ tool_result_id: "tr_call_abc",+ matches: [+ {+ offset: 12,+ offset_unit: "unicode_code_point",+ snippet: "hay needle stack",+ },+ ],+ });+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, api } = setupPlugin();+ contextEnginePlugin.register(api as any);+ const tool = tools.get("openviking_tool_result_search")!;++ const result = await tool.execute("tc-search", {+ tool_output_ref: "viking://session/test-session/tool-results/tr_call_abc",+ query: "needle",+ limit: 2,+ context_chars: 15,+ }) as ToolResult;++ expect(result.content[0]!.text).toContain("Found 1 match");+ expect(result.content[0]!.text).toContain("offset 12");+ expect(result.content[0]!.text).toContain("hay needle stack");+ expect(result.details).toMatchObject({+ action: "searched",+ tool_output_ref: "viking://session/test-session/tool-results/tr_call_abc",+ tool_result_id: "tr_call_abc",+ query: "needle",+ match_count: 1,+ });+ });++ it("lists externalized tool results for the current session", async () => {+ const fetchMock = vi.fn(async (url: string) => {+ expect(url).toContain("/api/v1/sessions/test-session/tool-results?");+ expect(url).toContain("tool_name=read_file");+ expect(url).toContain("limit=5");+ return okResponse({+ tool_results: [+ {+ tool_result_id: "tr_call_abc",+ storage_uri: "viking://session/test-session/tool-results/tr_call_abc",+ tool_name: "read_file",+ original_chars: 42000,+ created_at: "2026-05-15T00:00:00Z",+ },+ ],+ });+ });+ vi.stubGlobal("fetch", fetchMock);++ const { tools, api } = setupPlugin();+ contextEnginePlugin.register(api as any);+ const tool = tools.get("openviking_tool_result_list")!;++ const result = await tool.execute("tc-list", {+ tool_name: "read_file",+ limit: 5,+ }) as ToolResult;++ expect(result.content[0]!.text).toContain("read_file");+ expect(result.content[0]!.text).toContain("original_chars=42000");+ expect(result.content[0]!.text).toContain("viking://session/test-session/tool-results/tr_call_abc");+ expect(result.details).toMatchObject({+ action: "listed",+ session_id: "test-session",+ tool_name: "read_file",+ count: 1,+ });+ });++ it("rejects refs from another session", async () => {+ const { tools, api } = setupPlugin();+ contextEnginePlugin.register(api as any);+ const tool = tools.get("openviking_tool_result_read")!;++ const result = await tool.execute("tc-read", {+ tool_output_ref: "viking://session/other-session/tool-results/tr_call_abc",+ }) as ToolResult;++ expect(result.content[0]!.text).toContain("another session");+ expect(result.details.error).toBe("session_mismatch");+ });+});+describe("Tool: add_resource, add_skill, and memory_search (registration)", () => {it("registers add_resource tool with expected parameters", () => {const { tools, api } = setupPlugin();@@ -763,10 +914,10 @@ describe("OpenViking memory_search command parsing", () => {});describe("Plugin registration", () => {- it("registers all 8 tools", () => {+ it("registers all 11 tools", () => {const { api } = setupPlugin();contextEnginePlugin.register(api as any);- expect(api.registerTool).toHaveBeenCalledTimes(8);+ expect(api.registerTool).toHaveBeenCalledTimes(11);});it("registers add and search commands", () => {diff --git a/examples/openclaw-plugin/text-utils.ts b/examples/openclaw-plugin/text-utils.tsindex 7b7d39784..4f715f8fc 100644--- a/examples/openclaw-plugin/text-utils.ts+++ b/examples/openclaw-plugin/text-utils.ts@@ -426,6 +426,40 @@ export function extractNewTurnMessages(}],});}+ } else {+ /// 如果原始消息有 toolCall,提取所有工具名并生成占位符+ if (role === "assistant" && Array.isArray(content)) {+ const toolNames: string[] = [];++ // 收集所有 toolCall 的 tool_name+ for (const block of content) {+ const b = block as Record<string, unknown>;+ const blockType = b?.type as string;+ if (+ blockType === "toolCall" ||+ blockType === "toolUse" ||+ blockType === "tool_use" ||+ blockType === "tool_call"+ ) {+ const name = b?.name as string || b?.toolName as string;+ if (name && typeof name === "string" && name.trim()) {+ toolNames.push(name.trim());+ }+ }+ }++ // 只有找到 toolCall 时才添加占位符+ if (toolNames.length > 0) {+ const toolNamesStr = toolNames.join(", ");+ result.push({+ role: "assistant",+ parts: [{+ type: "text",+ text: `[tool: ${toolNamesStr}]`,+ }],+ });+ }+ }}}diff --git a/openviking/message/message.py b/openviking/message/message.pyindex c0cba66f6..d6263a424 100644--- a/openviking/message/message.py+++ b/openviking/message/message.py@@ -108,6 +108,36 @@ class Message:d["prompt_tokens"] = part.prompt_tokensif part.completion_tokens is not None:d["completion_tokens"] = part.completion_tokens+ if part.tool_output_ref:+ d["tool_output_ref"] = part.tool_output_ref+ if part.tool_output_truncated:+ d["tool_output_truncated"] = part.tool_output_truncated+ if part.tool_output_original_chars is not None:+ d["tool_output_original_chars"] = part.tool_output_original_chars+ if part.tool_output_preview_chars is not None:+ d["tool_output_preview_chars"] = part.tool_output_preview_chars+ if part.tool_output_sha256:+ d["tool_output_sha256"] = part.tool_output_sha256+ if part.tool_output_storage_uri:+ d["tool_output_storage_uri"] = part.tool_output_storage_uri+ if part.tool_output_mime_type and part.tool_output_mime_type != "text/plain":+ d["tool_output_mime_type"] = part.tool_output_mime_type+ if part.tool_output_source_ref:+ d["tool_output_source_ref"] = part.tool_output_source_ref+ if part.tool_output_source_offset is not None:+ d["tool_output_source_offset"] = part.tool_output_source_offset+ if part.tool_output_source_limit is not None:+ d["tool_output_source_limit"] = part.tool_output_source_limit+ if part.tool_output_externalization_error:+ d["tool_output_externalization_error"] = part.tool_output_externalization_error+ if part.tool_output_group_id:+ d["tool_output_group_id"] = part.tool_output_group_id+ if part.tool_output_externalized_reason:+ d["tool_output_externalized_reason"] = part.tool_output_externalized_reason+ if part.tool_output_group_original_chars is not None:+ d["tool_output_group_original_chars"] = part.tool_output_group_original_chars+ if part.tool_output_group_budget_chars is not None:+ d["tool_output_group_budget_chars"] = part.tool_output_group_budget_charsreturn dreturn {}@@ -147,6 +177,25 @@ class Message:duration_ms=p.get("duration_ms"),prompt_tokens=p.get("prompt_tokens"),completion_tokens=p.get("completion_tokens"),+ tool_output_ref=p.get("tool_output_ref", ""),+ tool_output_truncated=bool(p.get("tool_output_truncated", False)),+ tool_output_original_chars=p.get("tool_output_original_chars"),+ tool_output_preview_chars=p.get("tool_output_preview_chars"),+ tool_output_sha256=p.get("tool_output_sha256", ""),+ tool_output_storage_uri=p.get("tool_output_storage_uri", ""),+ tool_output_mime_type=p.get("tool_output_mime_type", "text/plain"),+ tool_output_source_ref=p.get("tool_output_source_ref", ""),+ tool_output_source_offset=p.get("tool_output_source_offset"),+ tool_output_source_limit=p.get("tool_output_source_limit"),+ tool_output_externalization_error=p.get(+ "tool_output_externalization_error", ""+ ),+ tool_output_group_id=p.get("tool_output_group_id", ""),+ tool_output_externalized_reason=p.get(+ "tool_output_externalized_reason", ""+ ),+ tool_output_group_original_chars=p.get("tool_output_group_original_chars"),+ tool_output_group_budget_chars=p.get("tool_output_group_budget_chars"),))return cls(diff --git a/openviking/message/part.py b/openviking/message/part.pyindex 8eeebaea3..f947436be 100644--- a/openviking/message/part.py+++ b/openviking/message/part.py@@ -48,6 +48,21 @@ class ToolPart:duration_ms: Optional[float] = None # 执行耗时(毫秒)prompt_tokens: Optional[int] = None # 输入 Tokencompletion_tokens: Optional[int] = None # 输出 Token+ tool_output_ref: str = ""+ tool_output_truncated: bool = False+ tool_output_original_chars: Optional[int] = None+ tool_output_preview_chars: Optional[int] = None+ tool_output_sha256: str = ""+ tool_output_storage_uri: str = ""+ tool_output_mime_type: str = "text/plain"+ tool_output_source_ref: str = ""+ tool_output_source_offset: Optional[int] = None+ tool_output_source_limit: Optional[int] = None+ tool_output_externalization_error: str = ""+ tool_output_group_id: str = ""+ tool_output_externalized_reason: str = ""+ tool_output_group_original_chars: Optional[int] = None+ tool_output_group_budget_chars: Optional[int] = NonePart = Union[TextPart, ContextPart, ToolPart]@@ -83,6 +98,21 @@ def part_from_dict(data: dict) -> Part:duration_ms=data.get("duration_ms"),prompt_tokens=data.get("prompt_tokens"),completion_tokens=data.get("completion_tokens"),+ tool_output_ref=data.get("tool_output_ref", ""),+ tool_output_truncated=bool(data.get("tool_output_truncated", False)),+ tool_output_original_chars=data.get("tool_output_original_chars"),+ tool_output_preview_chars=data.get("tool_output_preview_chars"),+ tool_output_sha256=data.get("tool_output_sha256", ""),+ tool_output_storage_uri=data.get("tool_output_storage_uri", ""),+ tool_output_mime_type=data.get("tool_output_mime_type", "text/plain"),+ tool_output_source_ref=data.get("tool_output_source_ref", ""),+ tool_output_source_offset=data.get("tool_output_source_offset"),+ tool_output_source_limit=data.get("tool_output_source_limit"),+ tool_output_externalization_error=data.get("tool_output_externalization_error", ""),+ tool_output_group_id=data.get("tool_output_group_id", ""),+ tool_output_externalized_reason=data.get("tool_output_externalized_reason", ""),+ tool_output_group_original_chars=data.get("tool_output_group_original_chars"),+ tool_output_group_budget_chars=data.get("tool_output_group_budget_chars"),)else:return TextPart(text=str(data))diff --git a/openviking/server/app.py b/openviking/server/app.pyindex 115722aa8..35777c9b9 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -162,6 +162,15 @@ def create_app(validate_server_config(config)+ def _configure_session_tool_outputs(service_obj) -> None: # noqa: ANN001+ sessions = getattr(service_obj, "sessions", None)+ setter = getattr(sessions, "set_tool_output_externalization_config", None)+ if callable(setter):+ setter(config.tool_output_externalization)++ if service is not None:+ _configure_session_tool_outputs(service)+async def _deferred_init(service, app, config):"""Run heavy initialization in background after server starts accepting requests."""await service.initialize()@@ -211,6 +220,7 @@ def create_app(service = OpenVikingService()assert service is not None+ _configure_session_tool_outputs(service)set_service(service)from openviking.metrics.global_api import (diff --git a/openviking/server/config.py b/openviking/server/config.pyindex 3de9e7048..48edcdf58 100644--- a/openviking/server/config.py+++ b/openviking/server/config.py@@ -141,6 +141,21 @@ class TempUploadConfig(BaseModel):model_config = {"extra": "forbid"}+class ToolOutputExternalizationConfig(BaseModel):+ """External storage controls for oversized tool outputs."""++ enabled: bool = True+ threshold_chars: int = 20_000+ preview_chars: int = 2_000+ assistant_turn_inline_budget_chars: int = 100_000+ assistant_turn_preview_budget_chars: int = 10_000+ min_preview_chars: int = 1_000+ aggregate_selection_strategy: Literal["largest_first"] = "largest_first"+ failure_mode: Literal["reject", "preserve_raw", "preview_only"] = "preserve_raw"++ model_config = {"extra": "forbid"}++class ServerConfig(BaseModel):host: str = "127.0.0.1"port: int = 1933@@ -161,6 +176,9 @@ class ServerConfig(BaseModel):public_base_url: Optional[str] = Noneupload_signed_ttl_seconds: int = 600temp_upload: TempUploadConfig = Field(default_factory=TempUploadConfig)+ tool_output_externalization: ToolOutputExternalizationConfig = Field(+ default_factory=ToolOutputExternalizationConfig+ )model_config = {"extra": "forbid"}diff --git a/openviking/server/routers/sessions.py b/openviking/server/routers/sessions.pyindex 4f2628427..8daec3f53 100644--- a/openviking/server/routers/sessions.py+++ b/openviking/server/routers/sessions.py@@ -49,6 +49,24 @@ class ToolPartRequest(BaseModel):tool_input: Optional[Dict[str, Any]] = Nonetool_output: str = ""tool_status: str = "pending"+ duration_ms: Optional[float] = None+ prompt_tokens: Optional[int] = None+ completion_tokens: Optional[int] = None+ tool_output_ref: str = ""+ tool_output_truncated: bool = False+ tool_output_original_chars: Optional[int] = None+ tool_output_preview_chars: Optional[int] = None+ tool_output_sha256: str = ""+ tool_output_storage_uri: str = ""+ tool_output_mime_type: str = "text/plain"+ tool_output_source_ref: str = ""+ tool_output_source_offset: Optional[int] = None+ tool_output_source_limit: Optional[int] = None+ tool_output_externalization_error: str = ""+ tool_output_group_id: str = ""+ tool_output_externalized_reason: str = ""+ tool_output_group_original_chars: Optional[int] = None+ tool_output_group_budget_chars: Optional[int] = NonePartRequest = TextPartRequest | ContextPartRequest | ToolPartRequest@@ -173,6 +191,68 @@ async def get_session(return Response(status="ok", result=result)[email protected]("/{session_id}/tool-results")+async def list_tool_results(+ session_id: str = Path(..., description="Session ID"),+ tool_name: Optional[str] = Query(None, description="Filter by tool name"),+ limit: int = Query(50, ge=1, description="Maximum number of tool results"),+ _ctx: RequestContext = Depends(get_request_context),+):+ """List externalized tool results for a session."""+ service = get_service()+ session = await service.sessions.get(session_id, _ctx, auto_create=False)+ result = await session.list_tool_results(tool_name=tool_name, limit=limit)+ return Response(status="ok", result=_to_jsonable(result))++[email protected]("/{session_id}/tool-results/{tool_result_id}")+async def read_tool_result(+ session_id: str = Path(..., description="Session ID"),+ tool_result_id: str = Path(..., description="Tool result ID"),+ offset: int = Query(0, ge=0, description="Unicode character offset"),+ limit: int = Query(20_000, description="Maximum Unicode characters to return"),+ include_metadata: bool = Query(True, description="Include metadata in response"),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Read an externalized tool result by Unicode character range."""+ if limit < -1:+ return error_response(+ "INVALID_ARGUMENT",+ "limit must be -1 or greater than or equal to 0",+ details={"field": "limit", "value": limit},+ )+ service = get_service()+ session = await service.sessions.get(session_id, _ctx, auto_create=False)+ result = await session.read_tool_result(+ tool_result_id,+ offset=offset,+ limit=limit,+ include_metadata=include_metadata,+ )+ return Response(status="ok", result=_to_jsonable(result))++[email protected]("/{session_id}/tool-results/{tool_result_id}/search")+async def search_tool_result(+ session_id: str = Path(..., description="Session ID"),+ tool_result_id: str = Path(..., description="Tool result ID"),+ q: str = Query(..., min_length=1, description="Search query"),+ limit: int = Query(20, ge=1, description="Maximum matches"),+ context_chars: int = Query(300, ge=0, description="Context characters around each hit"),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Search within an externalized tool result."""+ service = get_service()+ session = await service.sessions.get(session_id, _ctx, auto_create=False)+ result = await session.search_tool_result(+ tool_result_id,+ query=q,+ limit=limit,+ context_chars=context_chars,+ )+ return Response(status="ok", result=_to_jsonable(result))++@router.get("/{session_id}/context")async def get_session_context(session_id: str = Path(..., description="Session ID"),diff --git a/openviking/service/session_service.py b/openviking/service/session_service.pyindex e0b9ece58..c7d004a00 100644--- a/openviking/service/session_service.py+++ b/openviking/service/session_service.py@@ -9,6 +9,7 @@ Provides session management operations: session, sessions, add_message, commit,from typing import Any, Dict, List, Optionalfrom openviking.core.namespace import canonical_session_uri+from openviking.server.config import ToolOutputExternalizationConfigfrom openviking.server.identity import RequestContext, Rolefrom openviking.service.task_tracker import get_task_trackerfrom openviking.session import Session@@ -33,6 +34,7 @@ class SessionService:self._vikingdb = vikingdbself._viking_fs = viking_fsself._session_compressor = session_compressor+ self._tool_output_externalization_config = ToolOutputExternalizationConfig()def set_dependencies(self,@@ -45,6 +47,12 @@ class SessionService:self._viking_fs = viking_fsself._session_compressor = session_compressor+ def set_tool_output_externalization_config(+ self, config: ToolOutputExternalizationConfig+ ) -> None:+ """Set tool output externalization controls for newly created sessions."""+ self._tool_output_externalization_config = config.model_copy(deep=True)+def _ensure_initialized(self) -> None:"""Ensure all dependencies are initialized."""if not self._viking_fs:@@ -96,6 +104,7 @@ class SessionService:user=ctx.user,ctx=ctx,session_id=session_id,+ tool_output_externalization_config=self._tool_output_externalization_config,)async def create(self, ctx: RequestContext, session_id: Optional[str] = None) -> Session:diff --git a/openviking/session/session.py b/openviking/session/session.pyindex 3acf5a740..d3865964c 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -16,10 +16,13 @@ from uuid import uuid4from openviking.core.namespace import canonical_session_urifrom openviking.message import Message, Partfrom openviking.message.part import ContextPart, TextPart, ToolPart+from openviking.server.config import ToolOutputExternalizationConfigfrom openviking.server.identity import RequestContext, Role+from openviking.session.tool_result_store import ToolResultStore, make_preview, sha256_textfrom openviking.telemetry import get_current_telemetry, tracerfrom openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking.utils.time_utils import get_current_timestamp+from openviking_cli.exceptions import FailedPreconditionErrorfrom openviking_cli.session.user_id import UserIdentifierfrom openviking_cli.utils import get_logger, run_asyncfrom openviking_cli.utils.config import get_openviking_config@@ -289,6 +292,7 @@ class Session:ctx: Optional[RequestContext] = None,session_id: Optional[str] = None,auto_commit_threshold: int = 8000,+ tool_output_externalization_config: Optional[ToolOutputExternalizationConfig] = None,):self._viking_fs = viking_fsself._vikingdb_manager = vikingdb_manager@@ -311,6 +315,11 @@ class Session:participant_user_ids=[self.ctx.user.user_id],)self._loaded = False+ self._tool_output_externalization_config = (+ tool_output_externalization_config.model_copy(deep=True)+ if tool_output_externalization_config is not None+ else ToolOutputExternalizationConfig()+ )logger.info(f"Session created: {self.session_id} for user {self.user}")@@ -475,26 +484,286 @@ class Session:except Exception:pass- def add_message(+ def _tool_result_store(self) -> Optional[ToolResultStore]:+ if not self._viking_fs:+ return None+ return ToolResultStore(self._viking_fs, self._session_uri, self.session_id, self.ctx)++ async def _hydrate_tool_outputs_for_extraction(self,- role: str,- parts: List[Part],- role_id: Optional[str] = None,- created_at: str = None,- ) -> Message:- """Add a message."""- msg = Message(- id=f"msg_{uuid4().hex}",- role=role,- parts=parts,- role_id=role_id,- created_at=created_at or datetime.now(timezone.utc).isoformat(),+ messages: List[Message],+ ) -> List[Message]:+ """Return a memory-only copy with externalized tool outputs restored."""+ hydrated = [Message.from_dict(m.to_dict()) for m in messages]+ store = self._tool_result_store()+ if not store:+ return hydrated++ for msg in hydrated:+ for part in msg.parts:+ if not isinstance(part, ToolPart):+ continue+ if not part.tool_output_ref:+ continue+ if not (part.tool_output_truncated or part.tool_output_source_ref):+ continue++ ref = part.tool_output_source_ref or part.tool_output_ref+ tool_result_id = ref.rstrip("/").split("/")[-1]+ offset = part.tool_output_source_offset if part.tool_output_source_ref else 0+ limit = part.tool_output_source_limit if part.tool_output_source_ref else -1+ if (+ part.tool_output_source_ref+ and limit is None+ and part.tool_output_original_chars is not None+ ):+ limit = part.tool_output_original_chars+ try:+ result = await store.read(+ tool_result_id,+ offset=max(0, int(offset or 0)),+ limit=int(limit) if limit is not None else -1,+ include_metadata=False,+ )+ except Exception as exc:+ logger.warning(+ "Failed to hydrate externalized tool output for extraction: "+ "session=%s message_id=%s tool_id=%s ref=%s error=%s",+ self.session_id,+ msg.id,+ part.tool_id,+ ref,+ exc,+ )+ continue+ part.tool_output = result.get("content", "")++ return hydrated++ def _effective_tool_preview_chars(+ self,+ cfg: ToolOutputExternalizationConfig,+ externalized_count: int,+ ) -> int:+ if externalized_count <= 0:+ return cfg.preview_chars+ group_share = cfg.assistant_turn_preview_budget_chars // externalized_count+ return max(0, min(cfg.preview_chars, max(cfg.min_preview_chars, group_share)))++ def _rewrite_source_read_tool_output(+ self,+ part: ToolPart,+ cfg: ToolOutputExternalizationConfig,+ *,+ group_id: str,+ group_original_chars: int,+ ) -> bool:+ """Rewrite read-back tool output as a source reference, not a new result."""+ if part.tool_name != "openviking_tool_result_read":+ return False+ tool_input = part.tool_input if isinstance(part.tool_input, dict) else {}+ source_ref = str(+ tool_input.get("tool_output_ref")+ or tool_input.get("ref")+ or tool_input.get("uri")+ or ""+ )+ if not source_ref.startswith(f"{self._session_uri}/tool-results/"):+ return False++ output = part.tool_output or ""+ preview_chars = max(cfg.min_preview_chars, cfg.preview_chars)+ preview = make_preview(+ output,+ preview_chars=preview_chars,+ ref=source_ref,+ tool_name=part.tool_name,+ sha256=sha256_text(output) if output else "",+ reason="source_read",+ original_chars=len(output),+ )+ part.tool_output = preview+ part.tool_output_ref = source_ref+ part.tool_output_truncated = len(output) > len(preview)+ part.tool_output_original_chars = len(output)+ part.tool_output_preview_chars = len(preview)+ part.tool_output_sha256 = sha256_text(output) if output else ""+ part.tool_output_storage_uri = source_ref+ part.tool_output_source_ref = source_ref+ part.tool_output_source_offset = tool_input.get("offset")+ part.tool_output_source_limit = tool_input.get("limit")+ part.tool_output_group_id = group_id+ part.tool_output_externalized_reason = "source_read"+ part.tool_output_group_original_chars = group_original_chars+ part.tool_output_group_budget_chars = cfg.assistant_turn_inline_budget_chars+ return True++ def _externalize_tool_part(+ self,+ msg: Message,+ part: ToolPart,+ cfg: ToolOutputExternalizationConfig,+ *,+ preview_chars: int,+ reason: str,+ group_id: str,+ group_original_chars: int,+ ) -> None:+ store = self._tool_result_store()+ original_output = part.tool_output or ""+ if not store or not original_output:+ return++ digest = sha256_text(original_output)+ try:+ stored = run_async(+ store.write(+ content=original_output,+ tool_id=part.tool_id,+ tool_name=part.tool_name,+ message_id=msg.id,+ agent_id=msg.role_id,+ created_at=msg.created_at,+ preview_chars=preview_chars,+ mime_type=part.tool_output_mime_type or "text/plain",+ )+ )+ except Exception as exc:+ error = f"{type(exc).__name__}: {exc}"+ part.tool_output_externalization_error = error+ if cfg.failure_mode == "reject":+ raise FailedPreconditionError(+ "Failed to externalize tool output",+ details={"tool_id": part.tool_id, "error": error},+ ) from exc+ if cfg.failure_mode == "preview_only":+ part.tool_output = make_preview(+ original_output,+ preview_chars=preview_chars,+ tool_name=part.tool_name,+ sha256=digest,+ reason=f"{reason}:externalization_failed",+ original_chars=len(original_output),+ )+ part.tool_output_ref = ""+ part.tool_output_truncated = True+ part.tool_output_original_chars = len(original_output)+ part.tool_output_preview_chars = len(part.tool_output)+ part.tool_output_sha256 = digest+ part.tool_output_externalized_reason = reason+ return++ ref = stored.storage_uri+ part.tool_output = make_preview(+ original_output,+ preview_chars=preview_chars,+ ref=ref,+ tool_name=part.tool_name,+ sha256=digest,+ reason=reason,+ original_chars=len(original_output),+ )+ part.tool_output_ref = ref+ part.tool_output_truncated = True+ part.tool_output_original_chars = len(original_output)+ part.tool_output_preview_chars = len(part.tool_output)+ part.tool_output_sha256 = digest+ part.tool_output_storage_uri = ref+ part.tool_output_mime_type = stored.metadata.get("mime_type", "text/plain")+ part.tool_output_group_id = group_id+ part.tool_output_externalized_reason = reason+ part.tool_output_group_original_chars = group_original_chars+ part.tool_output_group_budget_chars = cfg.assistant_turn_inline_budget_chars++ def _externalize_large_tool_output_group(self, messages: List[Message]) -> None:+ cfg = self._tool_output_externalization_config+ if not cfg.enabled:+ return++ tool_parts = [+ (msg, p)+ for msg in messages+ for p in msg.parts+ if isinstance(p, ToolPart) and (p.tool_output or "")+ ]+ if not tool_parts:+ return++ group_id = messages[0].id+ group_original_chars = sum(len(p.tool_output or "") for _, p in tool_parts)+ normal_indices: List[int] = []+ selected: set[int] = set()++ for idx, (_msg, part) in enumerate(tool_parts):+ part.tool_output_group_id = group_id+ part.tool_output_group_original_chars = group_original_chars+ part.tool_output_group_budget_chars = cfg.assistant_turn_inline_budget_chars+ if self._rewrite_source_read_tool_output(+ part,+ cfg,+ group_id=group_id,+ group_original_chars=group_original_chars,+ ):+ continue+ if part.tool_output_ref and part.tool_output_truncated:+ continue+ normal_indices.append(idx)+ if len(part.tool_output or "") > cfg.threshold_chars:+ selected.add(idx)++ def projected_inline_chars(selected_indices: set[int]) -> int:+ preview_chars = self._effective_tool_preview_chars(cfg, len(selected_indices))+ total = 0+ for idx, (_, part) in enumerate(tool_parts):+ output_len = len(part.tool_output or "")+ if idx in selected_indices:+ total += min(output_len, preview_chars)+ else:+ total += output_len+ return total++ remaining = sorted(+ [idx for idx in normal_indices if idx not in selected],+ key=lambda idx: len(tool_parts[idx][1].tool_output or ""),+ reverse=True,)+ while (+ projected_inline_chars(selected) > cfg.assistant_turn_inline_budget_chars and remaining+ ):+ selected.add(remaining.pop(0))++ preview_chars = self._effective_tool_preview_chars(cfg, len(selected))+ for idx in sorted(selected):+ msg, part = tool_parts[idx]+ reason = (+ "single_threshold"+ if len(part.tool_output or "") > cfg.threshold_chars+ else "turn_budget"+ )+ self._externalize_tool_part(+ msg,+ part,+ cfg,+ preview_chars=preview_chars,+ reason=reason,+ group_id=group_id,+ group_original_chars=group_original_chars,+ )++ def _externalize_large_tool_outputs(self, msg: Message) -> None:+ self._externalize_large_tool_output_group([msg])++ def _is_tool_result_aggregate(self, role: str, parts: List[Part]) -> bool:+ return (+ role == "user" and len(parts) > 1 and all(isinstance(part, ToolPart) for part in parts)+ )++ def _append_message(self, msg: Message) -> None:self._messages.append(msg)self._record_participant(msg)# Update statistics- if role == "user":+ if msg.role == "user":self._stats.total_turns += 1msg_tokens = int(msg.estimated_tokens or 0)self._stats.total_tokens += msg_tokens@@ -517,6 +786,45 @@ class Session:if self._meta.total_message_count is not None:self._meta.total_message_count += 1self._save_meta_sync()++ def add_message(+ self,+ role: str,+ parts: List[Part],+ role_id: Optional[str] = None,+ created_at: str = None,+ ) -> Message:+ """Add a message.++ A user message containing only multiple tool results is treated as a+ transport aggregate and stored as one message per tool result.+ """+ created = created_at or datetime.now(timezone.utc).isoformat()+ if self._is_tool_result_aggregate(role, parts):+ messages = [+ Message(+ id=f"msg_{uuid4().hex}",+ role=role,+ parts=[part],+ role_id=role_id,+ created_at=created,+ )+ for part in parts+ ]+ self._externalize_large_tool_output_group(messages)+ for msg in messages:+ self._append_message(msg)+ return messages[0]++ msg = Message(+ id=f"msg_{uuid4().hex}",+ role=role,+ parts=parts,+ role_id=role_id,+ created_at=created,+ )+ self._externalize_large_tool_outputs(msg)+ self._append_message(msg)return msgdef _record_participant(self, msg: Message) -> None:@@ -545,11 +853,74 @@ class Session:tool_part.tool_output = outputtool_part.tool_status = status-- self._save_tool_result(tool_id, msg, output, status)+ tool_part.tool_output_ref = ""+ tool_part.tool_output_truncated = False+ tool_part.tool_output_original_chars = None+ tool_part.tool_output_preview_chars = None+ tool_part.tool_output_sha256 = ""+ tool_part.tool_output_storage_uri = ""+ tool_part.tool_output_source_ref = ""+ tool_part.tool_output_source_offset = None+ tool_part.tool_output_source_limit = None+ tool_part.tool_output_externalization_error = ""+ tool_part.tool_output_externalized_reason = ""+ self._externalize_large_tool_outputs(msg)++ self._save_tool_result(tool_id, msg, tool_part.tool_output, status)self._update_message_in_jsonl()self._rebuild_pending_tokens()+ async def read_tool_result(+ self,+ tool_result_id: str,+ *,+ offset: int = 0,+ limit: int = 20_000,+ include_metadata: bool = True,+ ) -> Dict[str, Any]:+ store = self._tool_result_store()+ if not store:+ from openviking_cli.exceptions import NotFoundError++ raise NotFoundError(tool_result_id, "tool result")+ return await store.read(+ tool_result_id,+ offset=offset,+ limit=limit,+ include_metadata=include_metadata,+ )++ async def search_tool_result(+ self,+ tool_result_id: str,+ *,+ query: str,+ limit: int = 20,+ context_chars: int = 300,+ ) -> Dict[str, Any]:+ store = self._tool_result_store()+ if not store:+ from openviking_cli.exceptions import NotFoundError++ raise NotFoundError(tool_result_id, "tool result")+ return await store.search(+ tool_result_id,+ query=query,+ limit=limit,+ context_chars=context_chars,+ )++ async def list_tool_results(+ self,+ *,+ tool_name: Optional[str] = None,+ limit: int = 50,+ ) -> Dict[str, Any]:+ store = self._tool_result_store()+ if not store:+ return {"tool_results": []}+ return await store.list(tool_name=tool_name, limit=limit)+def commit(self, keep_recent_count: int = 0) -> Dict[str, Any]:"""Sync wrapper for commit_async()."""return run_async(self.commit_async(keep_recent_count=keep_recent_count))@@ -802,10 +1173,11 @@ class Session:latest_archive_overview = await self._get_latest_completed_archive_overview(exclude_archive_uri=archive_uri)+ extraction_messages = await self._hydrate_tool_outputs_for_extraction(messages)async def _run_archive_summary() -> None:summary = await self._generate_archive_summary_async(- messages,+ extraction_messages,latest_archive_overview=latest_archive_overview,)if self._viking_fs and summary:@@ -848,7 +1220,7 @@ class Session:_results = await asyncio.gather(_run_archive_summary(),self._session_compressor.extract_long_term_memories(- messages=messages,+ messages=extraction_messages,user=self.user,session_id=self.session_id,ctx=self.ctx,@@ -856,7 +1228,7 @@ class Session:archive_uri=archive_uri,),self._session_compressor.extract_agent_memories(- messages=messages,+ messages=extraction_messages,ctx=self.ctx,)if has_agent_memorydiff --git a/openviking/session/tool_result_store.py b/openviking/session/tool_result_store.pynew file mode 100644index 000000000..ec304f0f9--- /dev/null+++ b/openviking/session/tool_result_store.py@@ -0,0 +1,282 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Storage helpers for externalized session tool results."""++from __future__ import annotations++import hashlib+import json+import re+from dataclasses import dataclass+from typing import Any, Dict, List, Optional++from openviking.storage.viking_fs import VikingFS+from openviking_cli.exceptions import InvalidArgumentError, NotFoundError++_SAFE_ID_RE = re.compile(r"[^A-Za-z0-9_.-]+")+++def _safe_id(value: str, *, fallback: str = "tool") -> str:+ safe = _SAFE_ID_RE.sub("_", value or "").strip("._-")+ return (safe or fallback)[:96]+++def sha256_text(content: str) -> str:+ return hashlib.sha256(content.encode("utf-8")).hexdigest()+++def build_tool_result_id(tool_id: str, sha256: str) -> str:+ if tool_id:+ return f"tr_{_safe_id(tool_id)}_{sha256[:16]}"+ return f"tr_{sha256[:24]}"+++def make_preview(+ content: str,+ *,+ preview_chars: int,+ ref: str = "",+ tool_name: str = "",+ sha256: str = "",+ reason: str = "",+ original_chars: Optional[int] = None,+) -> str:+ """Build a deterministic head+tail preview."""+ original = len(content) if original_chars is None else original_chars+ if preview_chars <= 0 or len(content) <= preview_chars:+ body = content+ else:+ half = max(1, preview_chars // 2)+ body = (+ "--- BEGIN PREVIEW HEAD ---\n"+ f"{content[:half]}\n"+ "--- END PREVIEW HEAD ---\n\n"+ "--- BEGIN PREVIEW TAIL ---\n"+ f"{content[-half:]}\n"+ "--- END PREVIEW TAIL ---"+ )++ header = [+ "[OpenViking tool result externalized]",+ f"tool_name: {tool_name or 'tool'}",+ f"original_chars: {original}",+ f"preview_chars: {min(len(content), max(preview_chars, 0))}",+ ]+ if ref:+ header.append(f"ref: {ref}")+ if sha256:+ header.append(f"sha256: {sha256[:16]}")+ if reason:+ header.append(f"reason: {reason}")+ return "\n".join(header) + "\n\n" + body+++@dataclass+class StoredToolResult:+ tool_result_id: str+ storage_uri: str+ output_uri: str+ metadata_uri: str+ metadata: Dict[str, Any]+++class ToolResultStore:+ """Persist raw tool outputs outside session messages."""++ def __init__(self, viking_fs: VikingFS, session_uri: str, session_id: str, ctx: Any):+ self._viking_fs = viking_fs+ self._session_uri = session_uri+ self._session_id = session_id+ self._ctx = ctx++ def _base_uri(self) -> str:+ return f"{self._session_uri}/tool-results"++ def _result_uri(self, tool_result_id: str) -> str:+ self._validate_tool_result_id(tool_result_id)+ return f"{self._base_uri()}/{tool_result_id}"++ @staticmethod+ def _validate_tool_result_id(tool_result_id: str) -> None:+ if not tool_result_id or _SAFE_ID_RE.search(tool_result_id) or "/" in tool_result_id:+ raise InvalidArgumentError(+ "Invalid tool_result_id",+ details={"tool_result_id": tool_result_id},+ )++ async def write(+ self,+ *,+ content: str,+ tool_id: str,+ tool_name: str,+ message_id: str,+ agent_id: Optional[str],+ created_at: Optional[str],+ preview_chars: int,+ mime_type: str = "text/plain",+ ) -> StoredToolResult:+ digest = sha256_text(content)+ tool_result_id = build_tool_result_id(tool_id, digest)+ storage_uri = self._result_uri(tool_result_id)+ output_uri = f"{storage_uri}/output.txt"+ metadata_uri = f"{storage_uri}/metadata.json"++ try:+ existing_metadata = await self.read_metadata(tool_result_id)+ if existing_metadata.get("sha256") == digest:+ return StoredToolResult(+ tool_result_id=tool_result_id,+ storage_uri=storage_uri,+ output_uri=output_uri,+ metadata_uri=metadata_uri,+ metadata=existing_metadata,+ )+ except NotFoundError:+ pass++ metadata = {+ "tool_result_id": tool_result_id,+ "session_id": self._session_id,+ "message_id": message_id,+ "tool_id": tool_id,+ "tool_name": tool_name,+ "agent_id": agent_id,+ "created_at": created_at,+ "original_chars": len(content),+ "preview_chars": min(len(content), max(preview_chars, 0)),+ "sha256": digest,+ "mime_type": mime_type,+ "storage_uri": storage_uri,+ "output_uri": output_uri,+ "offset_unit": "unicode_code_point",+ }+ await self._viking_fs.write_file(output_uri, content, ctx=self._ctx)+ await self._viking_fs.write_file(+ metadata_uri,+ json.dumps(metadata, ensure_ascii=False, indent=2),+ ctx=self._ctx,+ )+ return StoredToolResult(+ tool_result_id=tool_result_id,+ storage_uri=storage_uri,+ output_uri=output_uri,+ metadata_uri=metadata_uri,+ metadata=metadata,+ )++ async def read_metadata(self, tool_result_id: str) -> Dict[str, Any]:+ metadata_uri = f"{self._result_uri(tool_result_id)}/metadata.json"+ try:+ raw = await self._viking_fs.read_file(metadata_uri, ctx=self._ctx)+ except NotFoundError:+ raise+ except Exception as exc:+ raise NotFoundError(tool_result_id, "tool result") from exc+ try:+ return json.loads(raw)+ except json.JSONDecodeError as exc:+ raise InvalidArgumentError(+ "Invalid tool result metadata",+ details={"tool_result_id": tool_result_id},+ ) from exc++ async def read(+ self,+ tool_result_id: str,+ *,+ offset: int = 0,+ limit: int = 20_000,+ include_metadata: bool = True,+ ) -> Dict[str, Any]:+ if offset < 0:+ raise InvalidArgumentError("offset must be greater than or equal to 0")+ if limit < -1:+ raise InvalidArgumentError("limit must be -1 or greater than or equal to 0")++ metadata = await self.read_metadata(tool_result_id)+ content = await self._viking_fs.read_file(+ f"{self._result_uri(tool_result_id)}/output.txt",+ ctx=self._ctx,+ )+ end = None if limit == -1 else offset + limit+ chunk = content[offset:end]+ total_chars = len(content)+ has_more = end is not None and end < total_chars+ result = {+ "tool_result_id": tool_result_id,+ "content": chunk,+ "offset": offset,+ "limit": limit,+ "offset_unit": "unicode_code_point",+ "total_chars": total_chars,+ "has_more": has_more,+ }+ if include_metadata:+ result["metadata"] = metadata+ return result++ async def search(+ self,+ tool_result_id: str,+ *,+ query: str,+ limit: int = 20,+ context_chars: int = 300,+ ) -> Dict[str, Any]:+ if not query:+ raise InvalidArgumentError("query must not be empty")+ if limit <= 0:+ raise InvalidArgumentError("limit must be greater than 0")++ content = await self._viking_fs.read_file(+ f"{self._result_uri(tool_result_id)}/output.txt",+ ctx=self._ctx,+ )+ matches = []+ start = 0+ while len(matches) < limit:+ idx = content.find(query, start)+ if idx < 0:+ break+ left = max(0, idx - context_chars)+ right = min(len(content), idx + len(query) + context_chars)+ matches.append(+ {+ "offset": idx,+ "offset_unit": "unicode_code_point",+ "snippet": content[left:right],+ }+ )+ start = idx + max(1, len(query))+ return {"tool_result_id": tool_result_id, "matches": matches}++ async def list(self, *, tool_name: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:+ if limit <= 0:+ raise InvalidArgumentError("limit must be greater than 0")+ node_limit = max(limit, 100_000) if tool_name else limit+ try:+ entries = await self._viking_fs.ls(+ self._base_uri(),+ output="original",+ node_limit=node_limit,+ ctx=self._ctx,+ )+ except NotFoundError:+ entries = []++ results: List[Dict[str, Any]] = []+ for entry in entries:+ if not entry.get("isDir"):+ continue+ tool_result_id = entry.get("name", "")+ try:+ metadata = await self.read_metadata(tool_result_id)+ except Exception:+ continue+ if tool_name and metadata.get("tool_name") != tool_name:+ continue+ results.append(metadata)+ if len(results) >= limit:+ break+ return {"tool_results": results}diff --git a/tests/server/test_api_sessions.py b/tests/server/test_api_sessions.pyindex 8b842118b..6cb35f4fb 100644--- a/tests/server/test_api_sessions.py+++ b/tests/server/test_api_sessions.py@@ -14,7 +14,9 @@ from starlette.requests import Requestfrom openviking.message import Messagefrom openviking.server.api_keys import APIKeyManager-from openviking.server.config import ServerConfig+from openviking.server.app import create_app+from openviking.server.config import ServerConfig, ToolOutputExternalizationConfig+from openviking.server.dependencies import set_servicefrom openviking.server.identity import RequestContext, Rolefrom openviking.server.routers import sessions as sessions_routerfrom openviking_cli.session.user_id import UserIdentifier@@ -185,6 +187,93 @@ async def test_get_session_context_rejects_negative_token_budget(client: httpx.Aassert body["error"]["details"] == {"field": "token_budget", "value": -1}+async def test_tool_result_externalization_read_and_search(client: httpx.AsyncClient):+ session_id = "tool-result-api-session"+ raw = "alpha\n" + ("needle-" * 4000) + "\nomega"++ resp = await client.post(+ f"/api/v1/sessions/{session_id}/messages",+ json=_message_request(+ "user",+ parts=[+ {+ "type": "tool",+ "tool_id": "call_api",+ "tool_name": "read_file",+ "tool_output": raw,+ "tool_status": "completed",+ }+ ],+ ),+ )+ assert resp.status_code == 200++ context_resp = await client.get(f"/api/v1/sessions/{session_id}/context")+ assert context_resp.status_code == 200+ part = context_resp.json()["result"]["messages"][0]["parts"][0]+ assert part["tool_output_truncated"] is True+ assert part["tool_output_ref"].startswith(f"viking://session/{session_id}/tool-results/")+ assert raw not in part["tool_output"]++ tool_result_id = part["tool_output_ref"].rsplit("/", 1)[-1]+ read_resp = await client.get(+ f"/api/v1/sessions/{session_id}/tool-results/{tool_result_id}?offset=0&limit=-1"+ )+ assert read_resp.status_code == 200+ read_body = read_resp.json()["result"]+ assert read_body["content"] == raw+ assert read_body["offset_unit"] == "unicode_code_point"++ search_resp = await client.get(+ f"/api/v1/sessions/{session_id}/tool-results/{tool_result_id}/search",+ params={"q": "needle", "limit": 1, "context_chars": 5},+ )+ assert search_resp.status_code == 200+ matches = search_resp.json()["result"]["matches"]+ assert len(matches) == 1+ assert matches[0]["offset_unit"] == "unicode_code_point"+ assert "needle" in matches[0]["snippet"]+++async def test_tool_result_externalization_respects_server_config_disabled(service):+ app = create_app(+ config=ServerConfig(+ tool_output_externalization=ToolOutputExternalizationConfig(enabled=False)+ ),+ service=service,+ )+ set_service(service)++ transport = httpx.ASGITransport(app=app)+ async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:+ session_id = "tool-result-disabled-session"+ raw = "disabled-" * 4000++ resp = await client.post(+ f"/api/v1/sessions/{session_id}/messages",+ json=_message_request(+ "user",+ parts=[+ {+ "type": "tool",+ "tool_id": "call_disabled",+ "tool_name": "read_file",+ "tool_output": raw,+ "tool_status": "completed",+ }+ ],+ ),+ )+ assert resp.status_code == 200++ context_resp = await client.get(f"/api/v1/sessions/{session_id}/context")+ assert context_resp.status_code == 200+ part = context_resp.json()["result"]["messages"][0]["parts"][0]+ assert part["tool_output"] == raw+ assert "tool_output_ref" not in part+ assert "tool_output_truncated" not in part++async def test_get_session_context_includes_incomplete_archive_messages(client: httpx.AsyncClient, service):@@ -243,6 +332,39 @@ async def test_add_message(client: httpx.AsyncClient):assert body["result"]["message_count"] == 1+async def test_add_message_splits_tool_result_aggregate(client: httpx.AsyncClient):+ create_resp = await client.post("/api/v1/sessions", json={})+ session_id = create_resp.json()["result"]["session_id"]++ resp = await client.post(+ f"/api/v1/sessions/{session_id}/messages",+ json=_message_request(+ "user",+ parts=[+ {+ "type": "tool",+ "tool_id": "call_a",+ "tool_name": "tool_a",+ "tool_output": "a",+ "tool_status": "completed",+ },+ {+ "type": "tool",+ "tool_id": "call_b",+ "tool_name": "tool_b",+ "tool_output": "b",+ "tool_status": "completed",+ },+ ],+ ),+ )++ assert resp.status_code == 200+ body = resp.json()+ assert body["status"] == "ok"+ assert body["result"]["message_count"] == 2++async def test_add_message_root_request_autofills_role_id(service, monkeypatch):session_id = "root-auto-fill"ctx = RequestContext(user=DEFAULT_USER, role=Role.ROOT)diff --git a/tests/session/test_tool_result_externalization.py b/tests/session/test_tool_result_externalization.pynew file mode 100644index 000000000..b99208643--- /dev/null+++ b/tests/session/test_tool_result_externalization.py@@ -0,0 +1,270 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++import json++from openviking.message import ToolPart+from openviking.server.config import ToolOutputExternalizationConfig+from openviking.session import Session+from openviking.session.tool_result_store import ToolResultStore+++def _small_config(**overrides):+ values = {+ "threshold_chars": 20,+ "preview_chars": 12,+ "assistant_turn_inline_budget_chars": 30,+ "assistant_turn_preview_budget_chars": 20,+ "min_preview_chars": 4,+ }+ values.update(overrides)+ return ToolOutputExternalizationConfig(**values)+++async def test_add_message_externalizes_large_tool_output(session: Session):+ session._tool_output_externalization_config = _small_config()+ raw = "alpha-" * 20++ msg = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_1",+ tool_name="read_file",+ tool_input={"path": "a.txt"},+ tool_output=raw,+ tool_status="completed",+ )+ ],+ )++ part = msg.get_tool_parts()[0]+ assert part.tool_output_truncated is True+ assert part.tool_output_ref.startswith(f"viking://session/{session.session_id}/tool-results/")+ assert part.tool_output_original_chars == len(raw)+ assert part.tool_output_externalized_reason == "single_threshold"+ assert raw not in part.tool_output++ stored = await session.read_tool_result(part.tool_output_ref.rsplit("/", 1)[-1], limit=-1)+ assert stored["content"] == raw+ assert stored["offset_unit"] == "unicode_code_point"+++async def test_hydrate_tool_outputs_for_extraction_uses_memory_copy(session: Session):+ session._tool_output_externalization_config = _small_config()+ raw = "alpha-" * 20++ msg = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_hydrate",+ tool_name="read_file",+ tool_output=raw,+ tool_status="completed",+ )+ ],+ )+ compressed_part = msg.get_tool_parts()[0]+ compressed_output = compressed_part.tool_output++ hydrated = await session._hydrate_tool_outputs_for_extraction([msg])++ assert hydrated[0] is not msg+ assert hydrated[0].get_tool_parts()[0].tool_output == raw+ assert hydrated[0].get_tool_parts()[0].tool_output_ref == compressed_part.tool_output_ref+ assert compressed_part.tool_output == compressed_output+ assert raw not in compressed_part.tool_output+++async def test_assistant_turn_budget_splits_aggregate_and_externalizes_largest_output(+ session: Session,+):+ session._tool_output_externalization_config = _small_config(+ threshold_chars=100,+ assistant_turn_inline_budget_chars=25,+ )++ start_count = len(session.messages)+ returned = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_a",+ tool_name="tool_a",+ tool_output="a" * 18,+ tool_status="completed",+ ),+ ToolPart(+ tool_id="call_b",+ tool_name="tool_b",+ tool_output="b" * 12,+ tool_status="completed",+ ),+ ],+ )++ new_messages = session.messages[start_count:]+ assert len(new_messages) == 2+ assert returned == new_messages[0]+ assert [len(msg.parts) for msg in new_messages] == [1, 1]++ parts = [msg.get_tool_parts()[0] for msg in new_messages]+ externalized = [p for p in parts if p.tool_output_truncated]+ assert len(externalized) == 1+ assert externalized[0].tool_id == "call_a"+ assert externalized[0].tool_output_externalized_reason == "turn_budget"+ assert all(p.tool_output_group_original_chars == 30 for p in parts)+ assert parts[0].tool_output_group_id == parts[1].tool_output_group_id+++async def test_tool_result_aggregate_splits_when_externalization_disabled(session: Session):+ session._tool_output_externalization_config = _small_config(enabled=False)+ start_count = len(session.messages)++ session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_a",+ tool_name="tool_a",+ tool_output="a",+ tool_status="completed",+ ),+ ToolPart(+ tool_id="call_b",+ tool_name="tool_b",+ tool_output="b",+ tool_status="completed",+ ),+ ],+ )++ new_messages = session.messages[start_count:]+ assert len(new_messages) == 2+ assert [msg.get_tool_parts()[0].tool_id for msg in new_messages] == ["call_a", "call_b"]+ assert all(msg.get_tool_parts()[0].tool_output_truncated is False for msg in new_messages)+++async def test_read_back_tool_result_reuses_source_ref(session: Session):+ session._tool_output_externalization_config = _small_config()+ raw = "source-" * 20+ original = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_src",+ tool_name="read_file",+ tool_output=raw,+ tool_status="completed",+ )+ ],+ ).get_tool_parts()[0]++ read_msg = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_read",+ tool_name="openviking_tool_result_read",+ tool_input={"tool_output_ref": original.tool_output_ref, "offset": 0, "limit": 50},+ tool_output=raw[:50],+ tool_status="completed",+ )+ ],+ )++ read_part = read_msg.get_tool_parts()[0]+ assert read_part.tool_output_ref == original.tool_output_ref+ assert read_part.tool_output_source_ref == original.tool_output_ref+ assert read_part.tool_output_source_offset == 0+ assert read_part.tool_output_source_limit == 50+ assert read_part.tool_output_externalized_reason == "source_read"+ assert read_part.tool_output_truncated is False++ hydrated = await session._hydrate_tool_outputs_for_extraction([read_msg])+ assert hydrated[0].get_tool_parts()[0].tool_output == raw[:50]+++async def test_read_back_tool_result_preview_honors_min_preview_chars(session: Session):+ session._tool_output_externalization_config = _small_config(+ preview_chars=4,+ min_preview_chars=12,+ )+ raw = "source-" * 20+ original = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_src_min_preview",+ tool_name="read_file",+ tool_output=raw,+ tool_status="completed",+ )+ ],+ ).get_tool_parts()[0]++ read_msg = session.add_message(+ "user",+ [+ ToolPart(+ tool_id="call_read_min_preview",+ tool_name="openviking_tool_result_read",+ tool_input={"tool_output_ref": original.tool_output_ref},+ tool_output="abcdefghij" * 4,+ tool_status="completed",+ )+ ],+ )++ read_part = read_msg.get_tool_parts()[0]+ assert "preview_chars: 12" in read_part.tool_output+ assert "abcdef" in read_part.tool_output+ assert "efghij" in read_part.tool_output+++async def test_update_tool_part_externalizes_large_output(session_with_tool_call):+ session, message_id, tool_id = session_with_tool_call+ session._tool_output_externalization_config = _small_config()+ raw = "updated-" * 20++ session.update_tool_part(message_id, tool_id, raw, status="completed")++ msg = next(m for m in session.messages if m.id == message_id)+ part = msg.find_tool_part(tool_id)+ assert part is not None+ assert part.tool_output_truncated is True+ assert part.tool_output_ref+ stored = await session.read_tool_result(part.tool_output_ref.rsplit("/", 1)[-1], limit=-1)+ assert stored["content"] == raw+++async def test_list_tool_results_filters_tool_name_before_limit():+ class FakeVikingFS:+ def __init__(self):+ self.entries = [+ {"name": "tr_other", "isDir": True},+ {"name": "tr_target", "isDir": True},+ ]+ self.metadata = {+ "tr_other": {"tool_result_id": "tr_other", "tool_name": "other"},+ "tr_target": {"tool_result_id": "tr_target", "tool_name": "target"},+ }++ async def ls(self, uri, *, output, node_limit, ctx): # noqa: ANN001+ return self.entries[:node_limit]++ async def read_file(self, uri, *, ctx): # noqa: ANN001+ tool_result_id = uri.rstrip("/").split("/")[-2]+ return json.dumps(self.metadata[tool_result_id])++ store = ToolResultStore(+ FakeVikingFS(),+ "viking://session/filter-before-limit",+ "filter-before-limit",+ ctx=None,+ )++ result = await store.list(tool_name="target", limit=1)++ assert result["tool_results"] == [{"tool_result_id": "tr_target", "tool_name": "target"}]diff --git a/tests/unit/test_message.py b/tests/unit/test_message.pyindex 5418e6edb..895dcb9b7 100644--- a/tests/unit/test_message.py+++ b/tests/unit/test_message.py@@ -125,6 +125,9 @@ class TestToolPart:assert part.duration_ms is Noneassert part.prompt_tokens is Noneassert part.completion_tokens is None+ assert part.tool_output_ref == ""+ assert part.tool_output_truncated is False+ assert part.tool_output_mime_type == "text/plain"assert part.type == "tool"def test_custom_values(self):@@ -140,6 +143,13 @@ class TestToolPart:duration_ms=150.5,prompt_tokens=100,completion_tokens=50,+ tool_output_ref="viking://session/s1/tool-results/tr_call",+ tool_output_truncated=True,+ tool_output_original_chars=1000,+ tool_output_preview_chars=100,+ tool_output_sha256="abc123",+ tool_output_group_id="msg-1",+ tool_output_externalized_reason="single_threshold",)assert part.tool_id == "call-123"@@ -152,6 +162,13 @@ class TestToolPart:assert part.duration_ms == 150.5assert part.prompt_tokens == 100assert part.completion_tokens == 50+ assert part.tool_output_ref == "viking://session/s1/tool-results/tr_call"+ assert part.tool_output_truncated is True+ assert part.tool_output_original_chars == 1000+ assert part.tool_output_preview_chars == 100+ assert part.tool_output_sha256 == "abc123"+ assert part.tool_output_group_id == "msg-1"+ assert part.tool_output_externalized_reason == "single_threshold"def test_tool_statuses(self):"""Test various tool statuses."""@@ -222,6 +239,11 @@ class TestPartFromDict:"duration_ms": 150.0,"prompt_tokens": 100,"completion_tokens": 50,+ "tool_output_ref": "viking://session/s1/tool-results/tr_call",+ "tool_output_truncated": True,+ "tool_output_original_chars": 1000,+ "tool_output_preview_chars": 100,+ "tool_output_sha256": "abc123",}part = part_from_dict(data)@@ -230,6 +252,11 @@ class TestPartFromDict:assert part.tool_id == "call-123"assert part.tool_name == "search"assert part.tool_status == "completed"+ assert part.tool_output_ref == "viking://session/s1/tool-results/tr_call"+ assert part.tool_output_truncated is True+ assert part.tool_output_original_chars == 1000+ assert part.tool_output_preview_chars == 100+ assert part.tool_output_sha256 == "abc123"def test_unknown_type_defaults_to_text(self):"""Test unknown type defaults to TextPart."""@@ -426,6 +453,11 @@ class TestMessageToDict:duration_ms=100,prompt_tokens=50,completion_tokens=25,+ tool_output_ref="viking://session/s1/tool-results/tr_call",+ tool_output_truncated=True,+ tool_output_original_chars=1000,+ tool_output_preview_chars=100,+ tool_output_externalized_reason="single_threshold",)],)@@ -435,6 +467,11 @@ class TestMessageToDict:assert d["parts"][0]["type"] == "tool"assert d["parts"][0]["tool_id"] == "call-1"assert d["parts"][0]["duration_ms"] == 100+ assert d["parts"][0]["tool_output_ref"] == "viking://session/s1/tool-results/tr_call"+ assert d["parts"][0]["tool_output_truncated"] is True+ assert d["parts"][0]["tool_output_original_chars"] == 1000+ assert d["parts"][0]["tool_output_preview_chars"] == 100+ assert d["parts"][0]["tool_output_externalized_reason"] == "single_threshold"def test_to_dict_timestamp_format(self):"""Test timestamp format in to_dict."""@@ -504,6 +541,11 @@ class TestMessageFromDict:"tool_name": "search","tool_uri": "viking://tools/1","tool_status": "completed",+ "tool_output_ref": "viking://session/s1/tool-results/tr_call",+ "tool_output_truncated": True,+ "tool_output_original_chars": 1000,+ "tool_output_preview_chars": 100,+ "tool_output_externalized_reason": "single_threshold",}],"created_at": "2026-03-26T10:30:00Z",@@ -513,6 +555,11 @@ class TestMessageFromDict:assert isinstance(msg.parts[0], ToolPart)assert msg.parts[0].tool_id == "call-1"+ assert msg.parts[0].tool_output_ref == "viking://session/s1/tool-results/tr_call"+ assert msg.parts[0].tool_output_truncated is True+ assert msg.parts[0].tool_output_original_chars == 1000+ assert msg.parts[0].tool_output_preview_chars == 100+ assert msg.parts[0].tool_output_externalized_reason == "single_threshold"def test_from_dict_supports_legacy_content_only_messages(self):"""Legacy messages with only content should load as a TextPart."""