Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat: externalize oversized session tool results (#2058)

HaotianChen616f39b030926fb
diff --git a/examples/openclaw-plugin/client.ts b/examples/openclaw-plugin/client.ts
index 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.ts
index 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.ts
index 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.json
index 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.md
new file mode 100644
index 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.mjs
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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 file
diff --git a/examples/openclaw-plugin/tests/ut/context-engine-afterTurn.test.ts b/examples/openclaw-plugin/tests/ut/context-engine-afterTurn.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.py
index c0cba66f6..d6263a424 100644
--- a/openviking/message/message.py
+++ b/openviking/message/message.py
@@ -108,6 +108,36 @@ class Message:
d["prompt_tokens"] = part.prompt_tokens
if 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_chars
return d
return {}
@@ -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.py
index 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 # 输入 Token
completion_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] = None
Part = 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.py
index 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.py
index 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] = None
upload_signed_ttl_seconds: int = 600
temp_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.py
index 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]] = None
tool_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] = None
PartRequest = 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.py
index 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, Optional
from openviking.core.namespace import canonical_session_uri
+from openviking.server.config import ToolOutputExternalizationConfig
from openviking.server.identity import RequestContext, Role
from openviking.service.task_tracker import get_task_tracker
from openviking.session import Session
@@ -33,6 +34,7 @@ class SessionService:
self._vikingdb = vikingdb
self._viking_fs = viking_fs
self._session_compressor = session_compressor
+ self._tool_output_externalization_config = ToolOutputExternalizationConfig()
def set_dependencies(
self,
@@ -45,6 +47,12 @@ class SessionService:
self._viking_fs = viking_fs
self._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.py
index 3acf5a740..d3865964c 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -16,10 +16,13 @@ from uuid import uuid4
from openviking.core.namespace import canonical_session_uri
from openviking.message import Message, Part
from openviking.message.part import ContextPart, TextPart, ToolPart
+from openviking.server.config import ToolOutputExternalizationConfig
from openviking.server.identity import RequestContext, Role
+from openviking.session.tool_result_store import ToolResultStore, make_preview, sha256_text
from openviking.telemetry import get_current_telemetry, tracer
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking.utils.time_utils import get_current_timestamp
+from openviking_cli.exceptions import FailedPreconditionError
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils import get_logger, run_async
from 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_fs
self._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 += 1
msg_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 += 1
self._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 msg
def _record_participant(self, msg: Message) -> None:
@@ -545,11 +853,74 @@ class Session:
tool_part.tool_output = output
tool_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_memory
diff --git a/openviking/session/tool_result_store.py b/openviking/session/tool_result_store.py
new file mode 100644
index 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.py
index 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 Request
from openviking.message import Message
from 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_service
from openviking.server.identity import RequestContext, Role
from openviking.server.routers import sessions as sessions_router
from openviking_cli.session.user_id import UserIdentifier
@@ -185,6 +187,93 @@ async def test_get_session_context_rejects_negative_token_budget(client: httpx.A
assert 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.py
new file mode 100644
index 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.py
index 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 None
assert part.prompt_tokens is None
assert 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.5
assert part.prompt_tokens == 100
assert 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."""