@openviking/openclaw-plugin 2026.5.10-dev.3 → 2026.5.21

package/INSTALL-AGENT.md

@@ -9,14 +9,14 @@ User-facing docs:
 
 ## Identity
 
-This package is the OpenClaw plugin `@openclaw/openviking`.
+This package is the OpenClaw plugin `@openviking/openclaw-plugin`.
 
 | User intent | Command |
 | --- | --- |
-| Fresh install, latest | `openclaw plugins install @openclaw/openviking` |
-| Upgrade plugin to latest | `openclaw plugins install @openclaw/openviking` |
+| Fresh install, latest | `openclaw plugins install clawhub:@openviking/openclaw-plugin` |
+| Upgrade plugin to latest | `openclaw plugins install clawhub:@openviking/openclaw-plugin` |
 | Install or upgrade a specific release | Use the published ClawHub package selector if available; otherwise ask before using backup `ov-install --plugin-version=<REF>` |
-| Upgrade only the plugin | `openclaw plugins install @openclaw/openviking` |
+| Upgrade only the plugin | `openclaw plugins install clawhub:@openviking/openclaw-plugin` |
 | Show installed plugins | `openclaw plugins list` |
 | Backup install when ClawHub is unavailable | `npx -y openclaw-openviking-setup-helper@latest --base-url <URL> [--api-key <KEY>]` |
 | Operate on a specific OpenClaw instance | add `--workdir <path>` |
@@ -31,7 +31,7 @@ clawhub install openviking
 That installs an AgentSkill, not the plugin. The plugin install command is:
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## Required Inputs
@@ -53,7 +53,7 @@ Never silently replace another context engine.
 Use this workflow for normal installs and upgrades from published packages.
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json
@@ -62,7 +62,7 @@ openclaw openviking status --json
 If the registry prefix is required:
 
 ```bash
-openclaw plugins install clawhub:@openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## Setup JSON Contract
@@ -157,7 +157,7 @@ Requirements:
 
 Version boundaries:
 
-- `2026.4.8` is the minimum supported OpenClaw version for the current `@openclaw/openviking` plugin.
+- `2026.4.8` is the minimum supported OpenClaw version for the current `@openviking/openclaw-plugin` plugin.
 - `2026.5.3` starts requiring compiled JavaScript runtime output during package install when a plugin package declares TypeScript entries.
 - `2026.5.4` and later no longer fall back to `.ts` source for installed/global plugin runtime loading when the compiled JavaScript output is missing; the plugin may be skipped.
 - Published ClawHub packages are built before release and include `dist/*.js`, so normal users do not need to build locally.
@@ -220,7 +220,7 @@ openclaw plugins list
 Fresh install:
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json
@@ -307,7 +307,7 @@ Same plugin ID (openviking, >= 0.3.x):
 
 ```bash
 rm -rf ~/.openclaw/extensions/openviking/
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --reconfigure
 openclaw gateway restart
 openclaw openviking status --json
@@ -319,7 +319,7 @@ Old plugin ID (memory-openviking, < 0.3.x):
 openclaw plugins uninstall memory-openviking 2>/dev/null || true
 openclaw config set plugins.slots.memory none
 rm -rf ~/.openclaw/extensions/memory-openviking/
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json
@@ -333,7 +333,7 @@ Existing config fields are preserved during migration. The new plugin reads old
 
 ## Backup Path: ov-install
 
-`ov-install` is the backup path, not the primary user install path. Use it when `openclaw plugins install @openclaw/openviking` cannot reach ClawHub, is rate-limited, or when the user explicitly wants a source ref / Git branch install.
+`ov-install` is the backup path, not the primary user install path. Use it when `openclaw plugins install clawhub:@openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when the user explicitly wants a source ref / Git branch install.
 
 Backup install:
 
@@ -352,4 +352,4 @@ Backup/source commands:
 | Show helper-tracked version | `ov-install --current-version` |
 | Update helper-managed install | `ov-install --update` |
 
-For user installs, always try `openclaw plugins install @openclaw/openviking` first. Choose `ov-install` only as the backup path.
+For user installs, always try `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.

package/INSTALL-ZH.md

@@ -1,12 +1,12 @@
 # 为 OpenClaw 安装 OpenViking
 
-OpenViking 通过 `@openclaw/openviking` 插件为 OpenClaw 提供长期记忆、知识库检索、语义搜索和 RAG 上下文能力。
+OpenViking 通过 `@openviking/openclaw-plugin` 插件为 OpenClaw 提供长期记忆、知识库检索、语义搜索和 RAG 上下文能力。
 
 这份文档同时面向用户和自动化 agent：用户可以按步骤执行，agent 可以按命令和 JSON 结果判断下一步。
 
 ## 不要把插件和 Skill 装混
 
-`@openclaw/openviking` 是 OpenClaw 插件。
+`@openviking/openclaw-plugin` 是 OpenClaw 插件。
 
 不要用下面这个命令安装本插件：
 
@@ -19,7 +19,7 @@ clawhub install openviking
 安装插件应使用：
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## 前置要求
@@ -36,7 +36,7 @@ OpenClaw 插件包版本边界：
 - `2026.4.8` 是当前插件支持的最低 OpenClaw 版本。
 - `2026.5.3` 开始，OpenClaw 在安装包时会校验 TypeScript 插件入口是否有编译后的 JavaScript 产物。
 - `2026.5.4` 及之后，已安装/全局插件如果缺少编译后的 JavaScript，运行时不再回退加载 `.ts` 源码，插件可能被跳过。
-- 推荐的 `openclaw plugins install @openclaw/openviking` 会安装已经发布并包含 `dist/*.js` 的插件包，普通用户不需要本地编译。
+- 推荐的 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 会安装已经发布并包含 `dist/*.js` 的插件包，普通用户不需要本地编译。
 - `ov-install` 是备用/源码安装路径。当 ClawHub 或 OpenClaw 插件管理器路径不可用、被限流，或者明确需要测试源码 ref 时才使用。目标 OpenClaw `>= 2026.5.3` 时，它会在安装过程中编译插件。
 
 快速检查：
@@ -87,13 +87,13 @@ curl http://127.0.0.1:1933/health
 ### 1. 安装插件
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 如果你的 OpenClaw 环境需要显式 registry 前缀，使用：
 
 ```bash
-openclaw plugins install clawhub:@openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ### 2. 配置插件
@@ -271,7 +271,7 @@ python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py
 
 ## 备用路径：ov-install
 
-`ov-install` 是备用路径，不是主安装方式。仅当 `openclaw plugins install @openclaw/openviking` 无法访问 ClawHub、被限流，或者你明确需要从 Git 分支/源码 ref 安装测试时使用。
+`ov-install` 是备用路径，不是主安装方式。仅当 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 无法访问 ClawHub、被限流，或者你明确需要从 Git 分支/源码 ref 安装测试时使用。
 
 先尝试 OpenClaw 插件管理器。如果该路径不可用，再执行：
 
@@ -285,14 +285,14 @@ ov-install
 | 参数 | 含义 |
 | --- | --- |
 | `--workdir PATH` | 指定 OpenClaw state 目录 |
-| `--version REF` | 指定 Git ref、tag、branch 或发布版本 |
+| `--plugin-version=REF` | 指定插件版本：npm 版本、npm dist-tag 或 Git ref |
 | `--current-version` | 查看 helper 记录的当前版本 |
 | `--base-url URL` | OpenViking 服务器地址（启用非交互模式） |
 | `--api-key KEY` | OpenViking API key |
 | `--agent-prefix PREFIX` | Agent 路由前缀 |
 | `--update` | 更新 helper 管理的安装 |
 
-面向用户的安装，请先使用 `openclaw plugins install @openclaw/openviking`。只有作为备用路径时才选择 `ov-install`。
+面向用户的安装，请先使用 `openclaw plugins install clawhub:@openviking/openclaw-plugin`。只有作为备用路径时才选择 `ov-install`。
 
 ## 从 ov-install 迁移到 openclaw plugin install
 
@@ -307,7 +307,7 @@ ov-install 的 context-engine 部署会将文件写入 `~/.openclaw/extensions/o
 rm -rf ~/.openclaw/extensions/openviking/
 
 # 通过 OpenClaw 插件管理器安装
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 
 # 重新配置（openclaw.json 中的已有配置会保留）
 openclaw openviking setup --reconfigure
@@ -330,7 +330,7 @@ openclaw config set plugins.slots.memory none
 rm -rf ~/.openclaw/extensions/memory-openviking/
 
 # 安装新插件
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json

package/INSTALL.md

@@ -1,12 +1,12 @@
 # Install OpenViking for OpenClaw
 
-OpenViking provides long-term memory, knowledge base search, semantic retrieval, and RAG-style context for OpenClaw through the `@openclaw/openviking` plugin.
+OpenViking provides long-term memory, knowledge base search, semantic retrieval, and RAG-style context for OpenClaw through the `@openviking/openclaw-plugin` plugin.
 
 This guide describes the current plugin install flow. It is written for both people and automation agents.
 
 ## Do Not Install The Skill By Mistake
 
-`@openclaw/openviking` is an OpenClaw plugin.
+`@openviking/openclaw-plugin` is an OpenClaw plugin.
 
 Do not use this command for plugin installation:
 
@@ -19,7 +19,7 @@ That command installs an AgentSkill named `openviking`, not the OpenClaw plugin.
 Use this plugin command instead:
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ## Requirements
@@ -36,7 +36,7 @@ OpenClaw plugin package boundaries:
 - `2026.4.8` is the minimum supported OpenClaw version for the current plugin.
 - `2026.5.3` starts validating package installs so TypeScript plugin entries need compiled JavaScript output.
 - `2026.5.4` and later stop falling back to `.ts` source for installed/global plugin runtime loading when compiled JavaScript is missing.
-- The recommended `openclaw plugins install @openclaw/openviking` path installs a published package that already includes `dist/*.js`.
+- The recommended `openclaw plugins install clawhub:@openviking/openclaw-plugin` path installs a published package that already includes `dist/*.js`.
 - `ov-install` is the backup/source install path. Use it when ClawHub or the OpenClaw plugin manager path is unavailable/rate-limited, or when explicitly testing a source ref. For OpenClaw `>= 2026.5.3`, it builds the plugin during installation.
 
 Quick check:
@@ -87,13 +87,13 @@ Use this path for normal users, production installs, and agent-assisted installs
 ### 1. Install The Plugin
 
 ```bash
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 If your OpenClaw installation requires an explicit registry prefix, use:
 
 ```bash
-openclaw plugins install clawhub:@openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 ```
 
 ### 2. Configure The Plugin
@@ -253,7 +253,7 @@ This checks the Gateway to OpenViking path by injecting a real conversation and
 
 ## Backup Path: ov-install
 
-`ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install @openclaw/openviking` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
+`ov-install` is the backup path, not the primary install path. Use it when `openclaw plugins install clawhub:@openviking/openclaw-plugin` cannot reach ClawHub, is rate-limited, or when you explicitly need to install/test plugin files from a Git branch or source ref.
 
 Try the OpenClaw plugin manager first. If that path is unavailable, run:
 
@@ -267,14 +267,14 @@ Useful backup/source flags:
 | Flag | Meaning |
 | --- | --- |
 | `--workdir PATH` | Target OpenClaw state directory |
-| `--version REF` | Git ref, tag, branch, or release version to install |
+| `--plugin-version=REF` | Plugin version: npm version, npm dist-tag, or Git ref to install |
 | `--current-version` | Print the version tracked by the helper |
 | `--base-url URL` | OpenViking server URL (enables non-interactive mode) |
 | `--api-key KEY` | OpenViking API key |
 | `--agent-prefix PREFIX` | Agent routing prefix |
 | `--update` | Update an existing helper-managed install |
 
-For user-facing installs, use `openclaw plugins install @openclaw/openviking` first. Choose `ov-install` only as the backup path.
+For user-facing installs, use `openclaw plugins install clawhub:@openviking/openclaw-plugin` first. Choose `ov-install` only as the backup path.
 
 ## Migrate From ov-install To openclaw plugin install
 
@@ -289,7 +289,7 @@ The ov-install context-engine deployment writes files to `~/.openclaw/extensions
 rm -rf ~/.openclaw/extensions/openviking/
 
 # Install via the OpenClaw plugin manager
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 
 # Reconfigure (your existing config in openclaw.json is preserved)
 openclaw openviking setup --reconfigure
@@ -347,7 +347,7 @@ openclaw config set plugins.slots.memory none
 rm -rf ~/.openclaw/extensions/memory-openviking/
 
 # Install new plugin
-openclaw plugins install @openclaw/openviking
+openclaw plugins install clawhub:@openviking/openclaw-plugin
 openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
 openclaw gateway restart
 openclaw openviking status --json

package/README.md

@@ -1,59 +1,78 @@
-# @openclaw/openviking — OpenViking OpenClaw Plugin
+# OpenViking for OpenClaw
 
-OpenClaw context-engine plugin for OpenViking remote memory, context database, RAG and semantic retrieval.
+Use [OpenViking](https://github.com/volcengine/OpenViking) as OpenClaw's long-term context engine: automatic recall, session archive, memory extraction, semantic search, and RAG over a remote OpenViking server.
 
-## Important: Plugin vs Skill
+## Quick Start
 
-This page is for the **OpenClaw plugin package**:
-
-```
-@openclaw/openviking
+```bash
+openclaw plugins install clawhub:@openviking/openclaw-plugin
+openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --json
+openclaw gateway restart
+openclaw openviking status --json
 ```
 
-**Do NOT** install the plugin with `clawhub install openviking` — that installs the `openviking` AgentSkill (under `skills/openviking`), which is a different thing.
+That's it. The `setup` command activates the context-engine slot and validates the connection.
 
-For **agent-assisted plugin setup**, ask the agent to follow [INSTALL-AGENT.md](./INSTALL-AGENT.md). The primary install path is still `openclaw plugins install @openclaw/openviking`.
+### Or ask your agent
 
-## Install (Natural Language)
+> Install the OpenClaw plugin @openviking/openclaw-plugin for OpenViking remote memory. My server is at `http://my-server:1933` and my API key is `sk-xxx`.
 
-Ask your agent:
+The agent runs install → setup → restart → verify automatically. See [INSTALL-AGENT.md](./INSTALL-AGENT.md).
 
-> Install the OpenClaw plugin @openclaw/openviking for OpenViking remote memory. My server is at `http://my-server:1933` and my API key is `sk-xxx`.
+## How It Works
 
-Or in Chinese:
+| Stage | What happens |
+|-------|-------------|
+| **Every turn** (`afterTurn`) | Your messages are archived into an OpenViking session |
+| **On `/compact`** (`compact`) | Archived messages are extracted into long-term memories |
+| **Before each reply** (`assemble`) | Relevant memories are auto-retrieved and injected into context |
 
-> 帮我安装 OpenViking 远程记忆插件 @openclaw/openviking。我的服务器地址是 `http://my-server:1933`，API key 是 `sk-xxx`。
+## Tools
 
-The agent will automatically run install → setup → restart → verify. No manual steps needed.
+Once installed, the plugin provides these agent tools:
 
-## Install (Command Line)
+| Tool | Purpose |
+|------|---------|
+| `memory_recall` | Explicit long-term memory search |
+| `memory_store` | Persist important information immediately |
+| `memory_forget` | Delete memories by URI or query |
+| `ov_archive_search` | Search across archives by keyword |
+| `ov_archive_expand` | Expand an archive back to raw messages |
+| `add_resource` | Import documents, URLs, or Git repos |
+| `add_skill` | Import agent skills |
+| `memory_search` | Search imported resources and skills |
 
-```bash
-openclaw plugins install @openclaw/openviking
-openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --json
-openclaw gateway restart
-openclaw openviking status --json
-```
+## Data Flow & Privacy
 
-The `setup` command automatically activates the context-engine slot and validates the server connection.
+- **What is sent**: User/assistant message text from each turn (after stripping injected memory blocks and metadata noise).
+- **Where it goes**: Your configured OpenViking server (`baseUrl`). The plugin only sends data to that server; downstream model/provider data handling (embedding, VLM) depends on the server's configuration.
+- **Storage**: All data lives on your OpenViking server under `viking://user/*`, `viking://agent/*`, and `viking://session/*`.
+- **API Key**: Sent as `X-OpenViking-Key` header over your configured connection. Never logged or forwarded.
+- **Multi-tenant isolation**: Supports `accountId`, `userId`, and `agent_prefix` for per-tenant scoping.
 
-## Search Keywords
+## Verify
 
-@openclaw/openviking, openclaw openviking plugin, openviking remote memory plugin, OpenViking Context Database plugin, install-openviking-memory.
+```bash
+openclaw openviking status --json     # one-shot health check
+openclaw config get plugins.slots.contextEngine  # should output: openviking
+```
 
 ## Documentation
 
-- Install and upgrade: [INSTALL.md](./INSTALL.md)
-- Chinese design and install guide: [INSTALL-ZH.md](./INSTALL-ZH.md)
-- Agent-oriented operator guide: [INSTALL-AGENT.md](./INSTALL-AGENT.md)
+| Doc | Description |
+|-----|-------------|
+| [INSTALL.md](./INSTALL.md) | Full install, upgrade, and uninstall guide |
+| [INSTALL-ZH.md](./INSTALL-ZH.md) | Chinese install guide |
+| [INSTALL-AGENT.md](./INSTALL-AGENT.md) | Agent-oriented operator guide |
 
----
+> **Plugin vs Skill**: This page is for `@openviking/openclaw-plugin` (the context-engine plugin). Do **not** use `clawhub install openviking` — that installs a different AgentSkill.
 
-## Technical Overview
+---
 
-Use [OpenViking](https://github.com/volcengine/OpenViking) as the long-term memory backend for [OpenClaw](https://github.com/openclaw/openclaw). In OpenClaw, this plugin is registered as the `openviking` context engine.
+<details>
+<summary><b>Technical Overview (for integrators and engineers)</b></summary>
 
-The remainder of this document is an implementation-focused design note for integrators and engineers.
+This plugin is registered as the `openviking` context engine in OpenClaw.
 
 ## Design Positioning
 
@@ -315,3 +334,5 @@ ov tui
 ---
 
 For installation, upgrade, and uninstall operations, use [INSTALL.md](./INSTALL.md).
+
+</details>

package/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";

package/context-engine.ts

@@ -25,6 +25,8 @@ type AgentMessage = {
   timestamp?: unknown;
 };
 
+type ExtractedTurnMessage = ReturnType<typeof extractNewTurnMessages>["messages"][number];
+
 type ContextEngineInfo = {
   id: string;
   name: string;
@@ -153,10 +155,6 @@ function allocateContextBudget(totalBudget: number, instructionTokens = 0): Cont
   return { archiveMemory, sessionContext, reserved };
 }
 
-function estimateTokens(messages: AgentMessage[]): number {
-  return Math.max(1, messages.length * 80);
-}
-
 function roughEstimate(messages: AgentMessage[]): number {
   return Math.ceil(JSON.stringify(messages).length / 4);
 }
@@ -407,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)
@@ -417,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,
@@ -474,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];
@@ -1279,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, {
@@ -1387,15 +1426,13 @@ export function createMemoryOpenVikingContextEngine(params: {
             `openviking: Phase2 memory extraction runs asynchronously on the server (task_id=${commitResult.task_id}). ` +
               "memories_extracted appears only after that task completes — not in this immediate response.",
           );
-          if (cfg.logFindRequests) {
-            void pollPhase2ExtractionOutcome(
-              getClient,
-              commitResult.task_id,
-              agentId,
-              logger,
-              OVSessionId,
-            );
-          }
+          void pollPhase2ExtractionOutcome(
+            getClient,
+            commitResult.task_id,
+            agentId,
+            logger,
+            OVSessionId,
+          );
         }
       } catch (err) {
         logger.warn?.(`openviking: afterTurn failed: ${String(err)}`);