Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(bot): Opt doc add workspace desc, change the type of messages appended to ov (#3236)
DuTaod2670274a4e9
diff --git a/bot/README.md b/bot/README.mdindex 47f302331..4f8ffbe7c 100644--- a/bot/README.md+++ b/bot/README.md@@ -329,6 +329,67 @@ Restart `vikingbot gateway` after changing the configuration.| `bot.ov_server.exp_recall_max_chars` | `10000` | Character budget for injected Experiences || `bot.ov_server.exp_write_tools` | `write_file`,`edit_file` | Tools that trigger experience recall before writes |+## Workspace and Agent Customization++The Workspace is VikingBot's local working directory. It contains Agent bootstrap instructions, Skills, Heartbeat tasks, and files used by file and Shell tools. The OpenViking workspace is accessed through `openviking_*` tools for Resources, Memories, and Skills; it is not the same local directory.++### Find the Active Workspace++The Workspace root is derived from `storage.workspace`:++```text+<storage.workspace>/bot/workspace+```++When `storage.workspace` is omitted, the default is `~/.openviking/data/bot/workspace`. Check the resolved path with:++```bash+vikingbot status+```++The active directory used by the Agent also depends on `bot.sandbox.mode`:++| Mode | Active Workspace |+|------|------------------|+| `shared` (default) | `<workspace>/shared` |+| `per-session` | `<workspace>/<session-key>` |+| `per-channel` | `<workspace>/<channel-key>` |++For example, with the default configuration, edit `~/.openviking/data/bot/workspace/shared/SOUL.md`.++### Customize the Agent++When an active Workspace is first used, VikingBot copies initial files from the built-in `bot/workspace` template. The main customization points are:++| File or directory | Purpose | How it is loaded |+|-------------------|---------|------------------|+| `SOUL.md` | Personality, values, and communication style | Added to the system prompt on every turn |+| `AGENTS.md` | Global working rules and task constraints; create it when needed | Added to the system prompt on every turn |+| `IDENTITY.md` | Agent name, role, and identity background; create it when needed | Added to the system prompt on every turn |+| `TOOLS.md` | Tool selection, execution boundaries, and safety rules | Added to the system prompt on every turn |+| `skills/<name>/SKILL.md` | Workflows and supporting resources for a class of tasks | A summary is injected first; full instructions are loaded progressively |+| `HEARTBEAT.md` | Tasks checked periodically | Read only by Heartbeat |++For example, edit `SOUL.md` in the active Workspace:++```markdown+# Soul++You are the team's engineering assistant.++- Lead with the conclusion, then add only necessary detail+- Inspect the current state before changing code+- Run relevant verification after making a change+- State assumptions clearly and never invent results+```++Saved changes normally take effect on the next Agent turn without restarting the Gateway. `SOUL.md` changes prompt behavior only; it cannot bypass Channel permissions, tool visibility, or Sandbox restrictions.++> [!NOTE]+> Edit files in the active Workspace. `bot/workspace` in the repository or installed package is an initialization template and does not overwrite an existing Workspace. Never store API Keys or other secrets in bootstrap files.++For the complete loading order, file responsibilities, and customization boundaries, see [Agent Capabilities](docs/en/concepts/02-agent-capabilities.md#workspace-and-agent-customization).+## Agent Tools### Built-in Toolsdiff --git a/bot/README_CN.md b/bot/README_CN.mdindex 6a862823b..4236fd110 100644--- a/bot/README_CN.md+++ b/bot/README_CN.md@@ -287,7 +287,7 @@ VikingBot 使用 OpenViking 完成:- 浏览、搜索和读取 Resource;- 增量同步并提交 Session,提取长期记忆与经验。-详细调用链见 [VikingBot 与 OpenViking 集成](docs/cn/concepts/04-openviking-integration.md)。Gateway 入口与鉴权边界来自 [RFC #3042](https://github.com/volcengine/OpenViking/discussions/3042)。+详细调用链见 [VikingBot 与 OpenViking 集成](docs/zh/concepts/04-openviking-integration.md)。Gateway 入口与鉴权边界来自 [RFC #3042](https://github.com/volcengine/OpenViking/discussions/3042)。## 配置说明@@ -329,6 +329,67 @@ export OPENVIKING_CONFIG_FILE=/path/to/ov.conf| `bot.ov_server.exp_recall_max_chars` | `10000` | Experience 注入字符预算 || `bot.ov_server.exp_write_tools` | `write_file`,`edit_file` | 写操作前触发经验召回的工具 |+## Workspace 与 Agent 定制++Workspace 是 VikingBot 的本地工作目录。它保存 Agent 启动指令、Skill、Heartbeat 任务以及文件和 Shell 工具操作的内容;OpenViking Workspace 则通过 `openviking_*` 工具访问 Resource、Memory 和 Skill,两者不是同一个目录。++### 找到当前 Workspace++Workspace 根目录由 `storage.workspace` 决定:++```text+<storage.workspace>/bot/workspace+```++未配置 `storage.workspace` 时,默认为 `~/.openviking/data/bot/workspace`。可以运行以下命令确认:++```bash+vikingbot status+```++Agent 实际使用的活动目录还取决于 `bot.sandbox.mode`:++| 模式 | 活动 Workspace |+|------|----------------|+| `shared`(默认) | `<workspace>/shared` |+| `per-session` | `<workspace>/<session-key>` |+| `per-channel` | `<workspace>/<channel-key>` |++例如,默认配置下应修改 `~/.openviking/data/bot/workspace/shared/SOUL.md`。++### 定制 Agent++首次使用某个活动 Workspace 时,VikingBot 会从内置 `bot/workspace` 模板复制初始文件。常用定制入口如下:++| 文件或目录 | 作用 | 加载方式 |+|------------|------|----------|+| `SOUL.md` | 人格、价值观和表达风格 | 每轮自动加入系统提示 |+| `AGENTS.md` | 全局工作规则和任务约束;可按需创建 | 每轮自动加入系统提示 |+| `IDENTITY.md` | Agent 名称、角色和身份背景;可按需创建 | 每轮自动加入系统提示 |+| `TOOLS.md` | 工具选择、调用边界和安全规则 | 每轮自动加入系统提示 |+| `skills/<name>/SKILL.md` | 某类任务的操作流程和配套资源 | 先注入摘要,需要时渐进加载全文 |+| `HEARTBEAT.md` | 周期检查的任务清单 | 仅由 Heartbeat 读取 |++例如,可以修改活动 Workspace 中的 `SOUL.md`:++```markdown+# Soul++你是团队的研发助手。++- 默认使用中文回答+- 先给结论,再补充必要细节+- 修改代码前先确认现状,修改后运行相关验证+- 不确定时明确说明假设,不编造结果+```++保存后通常会在下一轮 Agent 对话中生效,无需重启 Gateway。`SOUL.md` 只能改变提示行为,不能绕过 Channel 权限、工具可见性或 Sandbox 限制。++> [!NOTE]+> 请修改活动 Workspace 中的文件。仓库或安装包中的 `bot/workspace` 是初始化模板,不会覆盖已经存在的 Workspace。不要在启动文件中保存 API Key 等秘密。++完整加载顺序、文件职责和定制边界见 [Agent 能力体系](docs/zh/concepts/02-agent-capabilities.md#workspace-与-agent-定制)。+## Agent 工具### 内置工具diff --git a/bot/docs/en/concepts/02-agent-capabilities.md b/bot/docs/en/concepts/02-agent-capabilities.mdindex 556308aa5..61e51d7ed 100644--- a/bot/docs/en/concepts/02-agent-capabilities.md+++ b/bot/docs/en/concepts/02-agent-capabilities.md@@ -71,7 +71,54 @@ The main Agent uses `spawn` to submit independent work to SubagentManager. A subWhen a subagent finishes, it reports the result to the main session. The main Agent remains responsible for identity-sensitive actions and final delivery.-## Sandbox and Workspace+## Workspace and Agent Customization++The Workspace has two responsibilities: it stores bootstrap files and Skills that shape the Agent system prompt, and it serves as the local working directory for file and command tools. It is separate from the OpenViking workspace accessed through `openviking_*` tools.++### Paths and Isolation Scope++The Workspace root is `<storage.workspace>/bot/workspace`. When `storage.workspace` is omitted, it defaults to `~/.openviking/data/bot/workspace`. `vikingbot status` prints the resolved root.++ContextBuilder reads from the active Workspace selected by `sandbox.mode`:++| Mode | Active directory |+|------|------------------|+| `shared` | `<workspace>/shared` |+| `per-session` | `<workspace>/<session-key>` |+| `per-channel` | `<workspace>/<channel-key>` |++With the default `shared` mode, customize files under `<workspace>/shared`, not directly in the Workspace root.++### Bootstrap Files++On every turn, ContextBuilder reads existing non-empty files in this order: `AGENTS.md`, `SOUL.md`, `TOOLS.md`, and `IDENTITY.md`.++| File | Appropriate content |+|------|---------------------|+| `AGENTS.md` | Global working methods, task workflows, output constraints, and mandatory project rules |+| `SOUL.md` | Personality, values, tone, response style, and default behavior preferences |+| `TOOLS.md` | Tool selection rules, call order, side-effect confirmation, and safety boundaries |+| `IDENTITY.md` | Agent name, role, responsibility scope, and identity background |++These files supplement VikingBot's built-in identity and runtime prompt. They do not change actual tool Schemas, Channel authorization, or Sandbox permissions. For example, telling the Agent in `SOUL.md` to always run Shell commands cannot expose a hidden `exec` tool or bypass a sandbox policy.++The initial template also contains `USER.md`, but the current ContextBuilder does not automatically add it to the system prompt. Store durable user information in the OpenViking Peer Profile and Memories. Put static behavior rules in `AGENTS.md` or `SOUL.md`.++### Skills, Heartbeat, and Local Memory++- `skills/<name>/SKILL.md` defines a workflow for a class of tasks. A Workspace Skill takes precedence over a built-in Skill with the same name and is loaded progressively: summary first, full instructions on demand.+- `HEARTBEAT.md` is not part of the normal system prompt; HeartbeatService reads it periodically.+- `memory/MEMORY.md` and `memory/HISTORY.md` are local memory files. Old conversation consolidation writes to them only when `bot.use_local_memory` is enabled. OpenViking manages long-term context by default.++### Initialization and Update Behavior++When an active Workspace is first used, VikingBot copies bootstrap files, bundled Skill templates, and supporting directories from the installed `bot/workspace` template. Template initialization does not overwrite existing bootstrap-file customization.++Edit the active Workspace directly. ContextBuilder reads bootstrap files again on every turn, so changes to `SOUL.md`, `AGENTS.md`, `TOOLS.md`, or `IDENTITY.md` normally take effect on the next conversation turn without restarting the Gateway. Changes to `bot/workspace` in the package or repository affect only Workspaces created later.++Bootstrap files are part of the system-level prompt. Restrict their write permissions and never store API Keys, Tokens, or other secrets in them.++## Sandbox and Workspace IsolationSandboxManager selects a workspace from SessionKey and `sandbox.mode`:@@ -92,8 +139,6 @@ The current implementation provides these execution backends:In Direct mode, `restrict_to_workspace=false` may allow files and commands to access content outside the workspace. For services exposed to untrusted users, choose an isolated backend and configure explicit network and file policies.-On first use, SandboxManager copies bootstrap files such as AGENTS, SOUL, USER, TOOLS, and IDENTITY, together with enabled Skills.-## Multimodal CapabilitiesVikingBot supports three kinds of multimodal interaction:@@ -130,6 +175,7 @@ Custom Hooks can be loaded through `bot.hooks`.| Area | Path ||------|------|+| Workspace template | `bot/workspace/` || Context and Skills | `vikingbot/agent/context.py`, `skills.py` || Tool system | `vikingbot/agent/tools/` || Subagents | `vikingbot/agent/subagent.py` |diff --git a/bot/docs/zh/concepts/02-agent-capabilities.md b/bot/docs/zh/concepts/02-agent-capabilities.mdindex 88cf43417..a3b044dd2 100644--- a/bot/docs/zh/concepts/02-agent-capabilities.md+++ b/bot/docs/zh/concepts/02-agent-capabilities.md@@ -71,7 +71,54 @@ MCP 参数 Schema 会先做兼容转换,再交给模型和 ToolRegistry。子 Agent 完成后把结果通知主会话,由主 Agent 负责身份相关操作和最终交付。-## 沙箱与工作区+## Workspace 与 Agent 定制++Workspace 同时承担两个职责:一是保存构成 Agent 系统提示的启动文件和 Skill,二是作为文件与命令工具的本地工作目录。它与通过 `openviking_*` 工具访问的 OpenViking Workspace 相互独立。++### 路径与隔离范围++Workspace 根目录是 `<storage.workspace>/bot/workspace`;未配置 `storage.workspace` 时,默认为 `~/.openviking/data/bot/workspace`。`vikingbot status` 会显示解析后的根目录。++ContextBuilder 实际读取按 `sandbox.mode` 选择的活动 Workspace:++| 模式 | 活动目录 |+|------|----------|+| `shared` | `<workspace>/shared` |+| `per-session` | `<workspace>/<session-key>` |+| `per-channel` | `<workspace>/<channel-key>` |++因此,默认 `shared` 模式下,应定制 `<workspace>/shared` 中的文件,而不是直接修改 Workspace 根目录。++### 启动文件++ContextBuilder 在每轮构建系统提示时,按 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md` 的顺序读取存在且非空的文件:++| 文件 | 适合定义的内容 |+|------|----------------|+| `AGENTS.md` | 全局工作方式、任务流程、输出约束和必须遵守的项目规则 |+| `SOUL.md` | 人格、价值观、语气、回答风格和默认行为偏好 |+| `TOOLS.md` | 工具选择原则、调用顺序、副作用确认和安全边界 |+| `IDENTITY.md` | Agent 名称、角色、职责范围和身份背景 |++这些文件补充 VikingBot 内置身份和运行环境提示,不会改变真实工具 Schema、Channel 鉴权或 Sandbox 权限。例如,在 `SOUL.md` 中要求“始终执行 Shell”并不能让不可见的 `exec` 工具出现,也不能绕过沙箱策略。++初始模板中还包含 `USER.md`,但当前 ContextBuilder 不会把它自动加入系统提示。长期用户资料应优先保存在 OpenViking Peer Profile 和 Memory 中;需要静态行为规则时,应写入 `AGENTS.md` 或 `SOUL.md`。++### Skill、Heartbeat 与本地记忆++- `skills/<name>/SKILL.md` 定义某类任务的流程。Workspace Skill 优先于同名内置 Skill,并采用摘要注入、按需读取全文的渐进加载方式。+- `HEARTBEAT.md` 不属于普通系统提示,只由 HeartbeatService 周期读取。+- `memory/MEMORY.md` 和 `memory/HISTORY.md` 是本地记忆文件;只有启用 `bot.use_local_memory` 时,旧会话整理结果才会写回本地文件。默认长期上下文由 OpenViking 管理。++### 初始化与生效时机++首次使用活动 Workspace 时,VikingBot 从安装包中的 `bot/workspace` 复制启动文件、内置 Skill 模板和辅助目录。模板初始化不会覆盖已有的启动文件定制。++应直接修改活动 Workspace。ContextBuilder 每轮重新读取启动文件,因此保存 `SOUL.md`、`AGENTS.md`、`TOOLS.md` 或 `IDENTITY.md` 后,通常下一轮对话即可生效,无需重启 Gateway。修改安装包或仓库中的 `bot/workspace` 只影响以后创建的新 Workspace。++启动文件等同于系统级提示的一部分,应限制写权限,并且不要存放 API Key、Token 或其他秘密。++## 沙箱与 Workspace 隔离SandboxManager 根据 SessionKey 和 `sandbox.mode` 选择工作区:@@ -92,8 +139,6 @@ SandboxManager 根据 SessionKey 和 `sandbox.mode` 选择工作区:Direct 模式的 `restrict_to_workspace=false` 时,文件和命令可能访问工作区外内容。面向不可信用户开放服务时,应选择隔离后端并显式设置网络与文件策略。-首次使用工作区时,SandboxManager 会复制 AGENTS、SOUL、USER、TOOLS、IDENTITY 等启动文件以及启用的 Skill。-## 多模态VikingBot 支持三类多模态能力:@@ -130,6 +175,7 @@ HookManager 提供运行时扩展点。当前内置 Hook 主要用于:| 内容 | 路径 ||------|------|+| Workspace 模板 | `bot/workspace/` || 上下文与 Skill | `vikingbot/agent/context.py`、`skills.py` || 工具系统 | `vikingbot/agent/tools/` || 子 Agent | `vikingbot/agent/subagent.py` |diff --git a/bot/tests/test_agent_loop_outcome.py b/bot/tests/test_agent_loop_outcome.pyindex 0910318fc..6fc373db6 100644--- a/bot/tests/test_agent_loop_outcome.py+++ b/bot/tests/test_agent_loop_outcome.py@@ -104,6 +104,10 @@ def test_agents_config_enables_subagents_by_default():assert AgentsConfig().subagent_enabled is True+def test_agents_config_keeps_ten_recent_openviking_messages_by_default():+ assert AgentsConfig().commit_keep_recent_count == 10++def test_agent_loop_omits_spawn_tool_when_subagents_disabled(temp_dir: Path, monkeypatch):monkeypatch.setattr(AgentLoop, "_register_builtin_hooks", lambda self: None)monkeypatch.setattr("vikingbot.agent.loop.SubagentManager", _FakeSubagentManager)@@ -206,14 +210,26 @@ async def test_agent_loop_makes_final_no_tool_call_when_iteration_limit_reached()if len(self.calls) == 1:return LLMResponse(- content=None,+ content="Let me check these sources.",tool_calls=[ToolCallRequest(id="call-1",name="lookup_fact",- arguments={"query": "current facts"},+ arguments={"query": "current facts 1"},tokens=3,- )+ ),+ ToolCallRequest(+ id="call-2",+ name="lookup_fact",+ arguments={"query": "current facts 2"},+ tokens=3,+ ),+ ToolCallRequest(+ id="call-3",+ name="lookup_fact",+ arguments={"query": "current facts 3"},+ tokens=3,+ ),],usage={"prompt_tokens": 10, "completion_tokens": 2, "total_tokens": 12},)@@ -259,10 +275,12 @@ async def test_agent_loop_makes_final_no_tool_call_when_iteration_limit_reached(loop.tools = toolssession_key = SessionKey(type="cli", channel_id="default", chat_id="session-limit")+ captured_turns = []final_content, _reasoning, tools_used, token_usage, iteration = await loop._run_agent_loop(messages=[{"role": "user", "content": "please answer with lookup"}],session_key=session_key,publish_events=False,+ captured_turns=captured_turns,)assert final_content == "final answer from gathered tool results"@@ -277,9 +295,25 @@ async def test_agent_loop_makes_final_no_tool_call_when_iteration_limit_reached(message.get("content") == "tool result: useful context"for message in provider.calls[1]["messages"])- assert len(tools.execute_calls) == 1- assert tools.execute_calls[0][:2] == ("lookup_fact", {"query": "current facts"})- assert [tool["tool_name"] for tool in tools_used] == ["lookup_fact"]+ assert len(tools.execute_calls) == 3+ assert tools.execute_calls[0][:2] == ("lookup_fact", {"query": "current facts 1"})+ assert [tool["tool_name"] for tool in tools_used] == [+ "lookup_fact",+ "lookup_fact",+ "lookup_fact",+ ]+ assert len(captured_turns) == 1+ assert captured_turns[0]["content"] == "Let me check these sources."+ assert [tool["tool_call_id"] for tool in captured_turns[0]["tool_calls"]] == [+ "call-1",+ "call-2",+ "call-3",+ ]+ assert [tool["result"] for tool in captured_turns[0]["tool_calls"]] == [+ "tool result: useful context",+ "tool result: useful context",+ "tool result: useful context",+ ]assert token_usage == {"prompt_tokens": 17, "completion_tokens": 7, "total_tokens": 24}@@ -554,6 +588,68 @@ async def test_agent_loop_build_prompt_history_skips_tail_when_sync_cursor_is_paassert [message["content"] for message in history] == ["OV user turn"]+async def test_agent_loop_build_prompt_history_enforces_token_budget_for_live_tool_outputs(+ temp_dir: Path, monkeypatch+):+ monkeypatch.setattr(AgentLoop, "_register_builtin_hooks", lambda self: None)+ monkeypatch.setattr(AgentLoop, "_register_default_tools", lambda self: None)+ monkeypatch.setattr("vikingbot.agent.loop.SubagentManager", _FakeSubagentManager)++ tool_output = "x" * 10_000+ fake_ov_client = _FakeOVClient(+ context_payload={+ "messages": [+ {"role": "user", "parts": [{"type": "text", "text": "original query"}]},+ *[+ {+ "role": "assistant",+ "parts": [+ {"type": "text", "text": f"turn {index}"},+ {"type": "tool", "tool_output": tool_output},+ ],+ }+ for index in range(10)+ ],+ {"role": "assistant", "parts": [{"type": "text", "text": "final answer"}]},+ ]+ }+ )++ async def fake_get_ov_client(self, session_key, openviking_connection=None, actor_peer_id=None):+ del self, session_key, openviking_connection, actor_peer_id+ return fake_ov_client++ monkeypatch.setattr(AgentLoop, "_get_ov_client", fake_get_ov_client)++ loop = AgentLoop(+ bus=MessageBus(),+ provider=_FakeProvider(),+ workspace=temp_dir / "workspace",+ config=Config(+ storage_workspace=str(temp_dir),+ ov_server={"server_url": "http://127.0.0.1:1933"},+ agents={"session_context_enabled": True, "session_context_token_budget": 3000},+ ),+ )+ session = loop.sessions.get_or_create(+ SessionKey(type="cli", channel_id="default", chat_id="session-large-tools"),+ skip_heartbeat=True,+ )+ session.metadata["openviking"] = {+ "session_id": "ov-session-large-tools",+ "last_synced_local_index": -1,+ }++ history = await loop._build_prompt_history(session)++ assert fake_ov_client.context_calls == [("ov-session-large-tools", 3000)]+ assert sum(loop._history_message_tokens(message) for message in history) <= 3000+ assert history[-1]["content"] == "final answer"+ assert sum(str(message.get("content", "")).count("x") for message in history) < 100_000+ assert any("History truncated" in str(message.get("content", "")) for message in history)++@pytest.mark.asyncioasync def test_agent_loop_submits_openviking_session_through_compact_hook(temp_dir: Path, monkeypatch@@ -996,10 +1092,32 @@ async def test_agent_loop_emits_normalized_response_completed_payload(temp_dir:)async def fake_run_agent_loop(self, **kwargs):+ turn_tools = [+ {+ "tool_call_id": "call-search",+ "tool_name": "search_docs",+ "args": '{"query": "docs"}',+ "result": "search result",+ },+ {+ "tool_call_id": "call-fetch",+ "tool_name": "fetch_page",+ "args": '{"url": "https://example.com"}',+ "result": "page result",+ },+ ]+ kwargs["captured_turns"].append(+ {+ "role": "assistant",+ "content": "I will check the docs.",+ "tool_calls": turn_tools,+ "timestamp": "2026-04-30T00:05:01",+ }+ )return ("final answer",None,- [{"tool_name": "search_docs"}, {"tool_name": "fetch_page"}],+ turn_tools,{"prompt_tokens": 12, "completion_tokens": 8},3,)@@ -1062,8 +1180,32 @@ async def test_agent_loop_emits_normalized_response_completed_payload(temp_dir:assert fake_langfuse.calls == [(response.response_id, payload)]session_path = temp_dir / "bot" / "sessions" / "cli__default__session-1.jsonl"- metadata = json.loads(session_path.read_text().splitlines()[0])+ session_lines = session_path.read_text().splitlines()+ metadata = json.loads(session_lines[0])assert metadata["metadata"]["response_facts"][response.response_id] == payload+ persisted_assistant = json.loads(session_lines[-1])+ assert persisted_assistant["content"] == "final answer"+ assert persisted_assistant["agent_turns"] == [+ {+ "role": "assistant",+ "content": "I will check the docs.",+ "tool_calls": [+ {+ "tool_call_id": "call-search",+ "tool_name": "search_docs",+ "args": '{"query": "docs"}',+ "result": "search result",+ },+ {+ "tool_call_id": "call-fetch",+ "tool_name": "fetch_page",+ "args": '{"url": "https://example.com"}',+ "result": "page result",+ },+ ],+ "timestamp": "2026-04-30T00:05:01",+ }+ ]@pytest.mark.asynciodiff --git a/bot/tests/test_openviking_api_key_type.py b/bot/tests/test_openviking_api_key_type.pyindex efca9dc02..581923212 100644--- a/bot/tests/test_openviking_api_key_type.py+++ b/bot/tests/test_openviking_api_key_type.py@@ -1824,13 +1824,16 @@ async def test_viking_client_normalizes_system_tool_and_tool_result_messages(mon"assistant","assistant","assistant",+ "assistant",]assert all("peer_id" not in message for message in normalized)- assert normalized[0]["content"] == "system context"- assert normalized[1]["content"] == "tool response"- assert normalized[2]["content"] == "assistant answer"- assert normalized[2]["parts"][1]["type"] == "tool"- assert normalized[2]["parts"][1]["tool_name"] == "read_file"+ assert normalized[0]["parts"] == [{"type": "text", "text": "system context"}]+ assert normalized[1]["parts"] == [{"type": "text", "text": "tool response"}]+ assert "content" not in normalized[2]+ assert normalized[2]["parts"][0]["type"] == "tool"+ assert normalized[2]["parts"][0]["tool_name"] == "read_file"+ assert "content" not in normalized[3]+ assert normalized[3]["parts"] == [{"type": "text", "text": "assistant answer"}]@pytest.mark.asynciodiff --git a/bot/vikingbot/agent/loop.py b/bot/vikingbot/agent/loop.pyindex 0122b976c..a94c8c107 100644--- a/bot/vikingbot/agent/loop.py+++ b/bot/vikingbot/agent/loop.py@@ -488,6 +488,102 @@ class AgentLoop:provider_name=provider_name,)+ @staticmethod+ def _history_message_tokens(message: dict[str, Any]) -> int:+ """Estimate prompt tokens for one formatted history message."""+ content = message.get("content", "")+ if not isinstance(content, str):+ content = json.dumps(content, ensure_ascii=False, default=str)+ # Reserve a small amount for the role and provider message framing.+ return cal_str_tokens(content, text_type="mixed") + 4++ @classmethod+ def _truncate_history_message(+ cls,+ message: dict[str, Any],+ token_budget: int,+ ) -> dict[str, Any] | None:+ """Return a prompt-only copy of a message clipped to ``token_budget``."""+ if token_budget <= 4:+ return None++ content = message.get("content", "")+ if not isinstance(content, str) or not content:+ return None++ content_budget = token_budget - 4+ marker = "\n[History truncated to fit session context token budget]"++ def fits(value: str) -> bool:+ return cal_str_tokens(value, text_type="mixed") <= content_budget++ low = 0+ high = len(content)+ best = ""+ while low <= high:+ mid = (low + high) // 2+ candidate = content[:mid] + (marker if mid < len(content) else "")+ if fits(candidate):+ best = candidate+ low = mid + 1+ else:+ high = mid - 1++ # Very small budgets may not fit the marker. Preserve as much raw text+ # as possible while still honoring the hard limit.+ if not best:+ low = 0+ high = len(content)+ while low <= high:+ mid = (low + high) // 2+ candidate = content[:mid]+ if candidate and fits(candidate):+ best = candidate+ low = mid + 1+ else:+ high = mid - 1++ if not best:+ return None++ clipped = dict(message)+ clipped["content"] = best+ # Reasoning is not part of OV session messages. Drop any provider-only+ # reasoning field from a clipped local fallback message so it cannot+ # silently exceed the session-history budget.+ clipped.pop("reasoning_content", None)+ return clipped++ @classmethod+ def _trim_history_to_token_budget(+ cls,+ messages: list[dict[str, Any]],+ token_budget: int,+ ) -> list[dict[str, Any]]:+ """Keep the newest contiguous history tail within a hard token budget."""+ if token_budget <= 0 or not messages:+ return []++ total_tokens = sum(cls._history_message_tokens(message) for message in messages)+ if total_tokens <= token_budget:+ return messages++ remaining = token_budget+ retained_reversed: list[dict[str, Any]] = []+ for message in reversed(messages):+ message_tokens = cls._history_message_tokens(message)+ if message_tokens <= remaining:+ retained_reversed.append(message)+ remaining -= message_tokens+ continue++ clipped = cls._truncate_history_message(message, remaining)+ if clipped is not None:+ retained_reversed.append(clipped)+ break++ return list(reversed(retained_reversed))+async def _build_prompt_history(self,session: Session,@@ -525,7 +621,25 @@ class AgentLoop:get_unsynced_messages(session),provider_name=provider_name,)- return ov_history + local_tail+ combined_history = ov_history + local_tail+ trimmed_history = self._trim_history_to_token_budget(+ combined_history,+ token_budget,+ )+ if len(trimmed_history) != len(combined_history) or any(+ before.get("content") != after.get("content")+ for before, after in zip(+ combined_history[-len(trimmed_history) :],+ trimmed_history,+ strict=False,+ )+ ):+ logger.info(+ f"Trimmed OpenViking session history for {session_id} to "+ f"token_budget={token_budget}: messages={len(combined_history)}"+ f"->{len(trimmed_history)}"+ )+ return trimmed_historyexcept Exception as e:logger.warning(f"Failed to load OpenViking session context for {session_id}: {e}. "@@ -712,6 +826,7 @@ class AgentLoop:stop_tool_names: list[str] | None = None,on_plain_text: Any | None = None,channel_metadata: dict[str, Any] | None = None,+ captured_turns: list[dict[str, Any]] | None = None,) -> tuple[str | None, str | None, list[dict], dict[str, int], int]:"""Run the core agent loop: call LLM, execute tools, repeat until done.@@ -735,6 +850,9 @@ class AgentLoop:None, plain text is treated as the final assistant reply (default chatbotsemantics).channel_metadata: Channel-specific metadata for tools that publish outbound messages+ captured_turns: Optional mutable list populated with each intermediate assistant+ turn and the tool calls/results produced by that same model response. Reasoning+ content is intentionally excluded.Returns:tuple of (final_content, final_reasoning_content, tools_used, token_usage, iteration)@@ -888,6 +1006,7 @@ class AgentLoop:results = await asyncio.gather(*tool_tasks)# Stage 3: Process results sequentially in original order+ turn_tools: list[dict[str, Any]] = []for _idx, tool_call, result, tool_execute_duration in results:args_str = json.dumps(tool_call.arguments, ensure_ascii=False)logger.info(f"[TOOL_CALL]: {tool_call.name}({args_str[:200]})")@@ -906,6 +1025,7 @@ class AgentLoop:)tool_used_dict = {+ "tool_call_id": tool_call.id,"tool_name": tool_call.name,"args": args_str,"result": result,@@ -915,6 +1035,17 @@ class AgentLoop:"output_token": cal_str_tokens(result, text_type="mixed"),}tools_used.append(tool_used_dict)+ turn_tools.append(tool_used_dict)++ if captured_turns is not None:+ captured_turns.append(+ {+ "role": "assistant",+ "content": response.content or "",+ "tool_calls": turn_tools,+ "timestamp": datetime.now().isoformat(),+ }+ )if any(tool_call.name in stop_tools for _idx, tool_call, _result, _duration in results@@ -953,6 +1084,15 @@ class AgentLoop:if isinstance(route, _PlainTextDelivered):messages = route.messagestools_used.extend(route.tools_used)+ if captured_turns is not None:+ captured_turns.append(+ {+ "role": "assistant",+ "content": text,+ "tool_calls": list(route.tools_used),+ "timestamp": datetime.now().isoformat(),+ }+ )if route.user_terminates:final_content = ""break@@ -1318,6 +1458,7 @@ class AgentLoop:# Run agent loop within a stable response identity for tracing/tool spans.response_id = uuid.uuid4().hex+ agent_turns: list[dict[str, Any]] = []with set_response_id(response_id):(final_content,@@ -1337,6 +1478,7 @@ class AgentLoop:disabled_tools=disabled_tools,openviking_connection=openviking_connection,channel_metadata=msg.metadata,+ captured_turns=agent_turns,)if auto_memory_tool:@@ -1377,6 +1519,7 @@ class AgentLoop:token_usage=token_usage,sender_id=msg.sender_id,reasoning_content=final_reasoning_content,+ agent_turns=agent_turns if agent_turns else None,)session.metadata.setdefault("response_facts", {})[response_id] = response_completedawait self.sessions.save(session)@@ -1616,6 +1759,7 @@ class AgentLoop:)# Run agent loop (no events published)+ agent_turns: list[dict[str, Any]] = [](final_content,final_reasoning_content,@@ -1632,6 +1776,7 @@ class AgentLoop:memory_peer_ids=None,openviking_connection=msg.openviking_connection,channel_metadata=msg.metadata,+ captured_turns=agent_turns,)if final_content is None or (isinstance(final_content, str) and not final_content.strip()):@@ -1644,6 +1789,7 @@ class AgentLoop:final_content,tools_used=tools_used if tools_used else None,reasoning_content=final_reasoning_content,+ agent_turns=agent_turns if agent_turns else None,)await self.sessions.save(session)diff --git a/bot/vikingbot/config/schema.py b/bot/vikingbot/config/schema.pyindex a8ea1a12f..f46a04b2c 100644--- a/bot/vikingbot/config/schema.py+++ b/bot/vikingbot/config/schema.py@@ -460,10 +460,10 @@ class AgentsConfig(BaseModel):default=True,description="Enable the spawn tool so the main agent can start background subagents.",)- session_context_enabled: bool = False+ session_context_enabled: bool = Truesession_context_token_budget: int = 3000commit_token_threshold: int = 200000- commit_keep_recent_count: int = 5+ commit_keep_recent_count: int = 10gen_image_model: str = "openai/doubao-seedream-4-5-251128"thinking: bool = Field(default=True,diff --git a/bot/vikingbot/openviking_mount/ov_server.py b/bot/vikingbot/openviking_mount/ov_server.pyindex 416bdb330..5f5beba8b 100644--- a/bot/vikingbot/openviking_mount/ov_server.py+++ b/bot/vikingbot/openviking_mount/ov_server.py@@ -886,6 +886,87 @@ class VikingClient:normalized: list[dict[str, Any]] = []assistant_peer_id = self._assistant_peer_id()+ def build_payload(+ payload_role: str,+ parts: list[dict[str, Any]],+ created_at: Any,+ peer_id: Optional[str],+ ) -> dict[str, Any]:+ payload: dict[str, Any] = {+ "role": payload_role,+ "parts": parts,+ "created_at": created_at,+ }+ if peer_id:+ payload["peer_id"] = peer_id+ return payload++ def build_tool_parts(tool_infos: Any) -> list[dict[str, Any]]:+ parts: list[dict[str, Any]] = []+ if not isinstance(tool_infos, list):+ return parts++ for tool_info in tool_infos:+ if not isinstance(tool_info, dict):+ continue+ tool_name = str(tool_info.get("tool_name") or tool_info.get("name") or "").strip()+ if not tool_name:+ continue+ if tool_info.get("auto") is True or tool_name == "auto_memory_search":+ continue++ raw_args = tool_info.get("args", tool_info.get("arguments", {}))+ if isinstance(raw_args, dict):+ tool_input = raw_args+ else:+ try:+ tool_input = json.loads(raw_args) if raw_args else {}+ except Exception:+ tool_input = {"raw_args": str(raw_args)}++ result_str = str(tool_info.get("result", tool_info.get("tool_output", "")))+ skill_uri = ""+ if tool_name == "read_file" and result_str:+ match = re.search(+ r"^---\s*\nname:\s*(.+?)\s*\n",+ result_str,+ re.MULTILINE,+ )+ if match:+ skill_name = match.group(1).strip()+ skill_uri = self._skill_memory_uri(skill_name)++ tool_id = str(+ tool_info.get("tool_call_id")+ or tool_info.get("tool_id")+ or tool_info.get("id")+ or f"{tool_name}_{uuid.uuid4().hex[:8]}"+ )+ explicit_status = str(tool_info.get("tool_status") or "").strip()+ parts.append(+ {+ "type": "tool",+ "tool_id": tool_id,+ "tool_name": tool_name,+ "tool_uri": f"viking://session/{session_id}/tools/{tool_id}"+ if session_id+ else "",+ "tool_input": tool_input,+ "tool_output": result_str,+ "tool_status": explicit_status+ or (+ "completed"+ if tool_info.get("execute_success", True)+ else "error"+ ),+ "skill_uri": skill_uri,+ "duration_ms": float(tool_info.get("duration", 0.0) or 0.0),+ "prompt_tokens": tool_info.get("input_token"),+ "completion_tokens": tool_info.get("output_token"),+ }+ )+ return parts+for message in messages:role = str(message.get("role") or "").strip().lower()if role not in {"user", "assistant", "system", "tool"}:@@ -893,72 +974,13 @@ class VikingClient:content = self._session_message_content(message)tools_used = message.get("tools_used") or []- parts: list[dict[str, Any]] = []-- if content:- parts.append({"type": "text", "text": content})-- if isinstance(tools_used, list):- for tool_info in tools_used:- if not isinstance(tool_info, dict):- continue- tool_name = str(tool_info.get("tool_name") or "").strip()- if not tool_name:- continue-- raw_args = tool_info.get("args", {})- if isinstance(raw_args, dict):- tool_input = raw_args- else:- try:- tool_input = json.loads(raw_args) if raw_args else {}- except Exception:- tool_input = {"raw_args": str(raw_args)}-- result_str = str(tool_info.get("result", ""))- skill_uri = ""- if tool_name == "read_file" and result_str:- match = re.search(- r"^---\s*\nname:\s*(.+?)\s*\n",- result_str,- re.MULTILINE,- )- if match:- skill_name = match.group(1).strip()- skill_uri = self._skill_memory_uri(skill_name)-- tool_id = f"{tool_name}_{uuid.uuid4().hex[:8]}"- parts.append(- {- "type": "tool",- "tool_id": tool_id,- "tool_name": tool_name,- "tool_uri": f"viking://session/{session_id}/tools/{tool_id}"- if session_id- else "",- "tool_input": tool_input,- "tool_output": result_str[:2000],- "tool_status": "completed"- if tool_info.get("execute_success", True)- else "error",- "skill_uri": skill_uri,- "duration_ms": float(tool_info.get("duration", 0.0) or 0.0),- "prompt_tokens": tool_info.get("input_token"),- "completion_tokens": tool_info.get("output_token"),- }- )+ tool_parts = build_tool_parts(tools_used)+ agent_turns = message.get("agent_turns")- if not parts:+ if not content and not tool_parts and not agent_turns:continueov_role = "user" if role == "user" else "assistant"- payload = {- "role": ov_role,- "content": content,- "parts": parts,- "created_at": message.get("created_at") or message.get("timestamp"),- }-peer_id = message.get("peer_id")if not peer_id and ov_role == "user":peer_id = message.get("sender_id") or default_user_peer_id@@ -966,10 +988,58 @@ class VikingClient:peer_id = assistant_peer_idsafe_message_peer_id = self._peer_id(peer_id)- if safe_message_peer_id:- payload["peer_id"] = safe_message_peer_id+ created_at = message.get("created_at") or message.get("timestamp")- normalized.append(payload)+ turn_payloads: list[dict[str, Any]] = []+ if ov_role == "assistant" and isinstance(agent_turns, list):+ for turn in agent_turns:+ if not isinstance(turn, dict):+ continue+ turn_parts: list[dict[str, Any]] = []+ turn_content = self._session_message_content(turn)+ if turn_content:+ turn_parts.append({"type": "text", "text": turn_content})+ turn_parts.extend(build_tool_parts(turn.get("tool_calls") or turn.get("tools")))+ if not turn_parts:+ continue+ turn_payloads.append(+ build_payload(+ "assistant",+ turn_parts,+ turn.get("created_at") or turn.get("timestamp") or created_at,+ safe_message_peer_id,+ )+ )++ if ov_role == "user" and content:+ normalized.append(+ build_payload(+ "user",+ [{"type": "text", "text": content}],+ created_at,+ safe_message_peer_id,+ )+ )+ if turn_payloads:+ normalized.extend(turn_payloads)+ elif tool_parts:+ normalized.append(+ build_payload(+ "assistant",+ tool_parts,+ created_at,+ safe_message_peer_id if ov_role == "assistant" else None,+ )+ )+ if ov_role == "assistant" and content:+ normalized.append(+ build_payload(+ "assistant",+ [{"type": "text", "text": content}],+ created_at,+ safe_message_peer_id,+ )+ )return normalizeddiff --git a/bot/vikingbot/tests/unit/test_openviking_peer_identity.py b/bot/vikingbot/tests/unit/test_openviking_peer_identity.pyindex 0d7ba6055..90533a9a6 100644--- a/bot/vikingbot/tests/unit/test_openviking_peer_identity.py+++ b/bot/vikingbot/tests/unit/test_openviking_peer_identity.py@@ -60,6 +60,147 @@ def test_normalize_session_messages_skips_path_like_peer_ids():assert "peer_id" not in normalized[0]+def test_normalize_session_messages_emits_tools_before_final_assistant_text():+ client = _client()++ normalized = client._normalize_session_messages(+ [+ {+ "role": "assistant",+ "content": "final answer",+ "timestamp": "2026-07-13T12:00:00Z",+ "tools_used": [+ {+ "tool_name": "read_file",+ "args": {"path": "README.md"},+ "result": "file content",+ },+ {+ "tool_name": "grep",+ "args": {"pattern": "TODO"},+ "result": "match",+ },+ ],+ }+ ]+ )++ assert len(normalized) == 2+ assert normalized[0]["role"] == "assistant"+ assert [part["type"] for part in normalized[0]["parts"]] == ["tool", "tool"]+ assert [part["tool_name"] for part in normalized[0]["parts"]] == ["read_file", "grep"]+ assert "content" not in normalized[0]+ assert normalized[1] == {+ "role": "assistant",+ "parts": [{"type": "text", "text": "final answer"}],+ "created_at": "2026-07-13T12:00:00Z",+ }+++def test_normalize_session_messages_preserves_assistant_turn_tool_relationship():+ client = _client()+ long_output = "x" * 2500++ normalized = client._normalize_session_messages(+ [+ {"role": "user", "content": "compare these", "timestamp": "2026-07-14T10:00:00Z"},+ {+ "role": "assistant",+ "content": "final answer",+ "timestamp": "2026-07-14T10:00:03Z",+ "tools_used": [{"tool_name": "legacy", "result": "must not duplicate"}],+ "agent_turns": [+ {+ "role": "assistant",+ "content": "Let me check these.",+ "timestamp": "2026-07-14T10:00:01Z",+ "tool_calls": [+ {+ "tool_call_id": "call-1",+ "tool_name": "search",+ "args": {"query": "one"},+ "result": "result one",+ },+ {+ "tool_call_id": "call-2",+ "tool_name": "read_file",+ "args": {"path": "a.txt"},+ "result": long_output,+ },+ {+ "tool_call_id": "call-3",+ "tool_name": "grep",+ "args": {"pattern": "three"},+ "result": "result three",+ "execute_success": False,+ },+ ],+ }+ ],+ },+ ],+ session_id="session-1",+ )++ assert len(normalized) == 3+ assert normalized[0]["role"] == "user"+ turn = normalized[1]+ assert turn["role"] == "assistant"+ assert [part["type"] for part in turn["parts"]] == ["text", "tool", "tool", "tool"]+ assert turn["parts"][0]["text"] == "Let me check these."+ assert [part["tool_id"] for part in turn["parts"][1:]] == ["call-1", "call-2", "call-3"]+ assert [part["tool_name"] for part in turn["parts"][1:]] == [+ "search",+ "read_file",+ "grep",+ ]+ assert turn["parts"][2]["tool_output"] == long_output+ assert turn["parts"][3]["tool_status"] == "error"+ assert turn["created_at"] == "2026-07-14T10:00:01Z"+ assert "content" not in normalized[2]+ assert normalized[2]["parts"] == [{"type": "text", "text": "final answer"}]+ assert all(+ part.get("tool_name") != "legacy"+ for message in normalized+ for part in message.get("parts", [])+ )+++def test_normalize_session_messages_excludes_auto_memory_search():+ client = _client()++ normalized = client._normalize_session_messages(+ [+ {"role": "user", "content": "question"},+ {+ "role": "assistant",+ "content": "final answer",+ "tools_used": [+ {+ "tool_name": "auto_memory_search",+ "args": {"query": "question"},+ "result": "recalled memory",+ "auto": True,+ }+ ],+ },+ ]+ )++ assert len(normalized) == 2+ assert normalized[0]["role"] == "user"+ assert normalized[1]["role"] == "assistant"+ assert "content" not in normalized[0]+ assert "content" not in normalized[1]+ assert normalized[0]["parts"] == [{"type": "text", "text": "question"}]+ assert normalized[1]["parts"] == [{"type": "text", "text": "final answer"}]+ assert all(+ part.get("tool_name") != "auto_memory_search"+ for message in normalized+ for part in message.get("parts", [])+ )++@pytest.mark.asyncioasync def test_read_peer_profile_uses_current_user_peer_alias(monkeypatch):client = _client(api_key_type="user")@@ -288,4 +429,3 @@ async def test_search_with_peer_id_uses_peer_target_uri_without_forwarding_peer_"limit": 3,}]-