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
"""OpenViking file system tools: read, write, list, search resources."""
import asyncio
import base64
import hashlib
import itertools
import json
import tempfile
import time
from abc import ABC
from pathlib import Path, PurePosixPath
from typing import TYPE_CHECKING, Any, Mapping, Optional
import httpx
from loguru import logger
from openviking.utils.media_limits import MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
from vikingbot.agent.tools.base import MultimodalToolResult, Tool, ToolContext
from vikingbot.openviking_mount.ov_server import VikingClient
from vikingbot.utils.image_format import sniff_image_format
if TYPE_CHECKING:
from vikingbot.config.schema import Config
def local_path_for_viking_uri(uri: str) -> str:
"""Map a viking:// URI to a workspace-relative path, dropping the namespace prefix.
``viking://resources/a/b`` -> ``a/b`` and
``viking://user/<id>/resources/a/b`` -> ``a/b``, so the materialized tree does not
collide with the viking ``resources``/``skills`` namespace names.
"""
path = str(uri).removeprefix("viking://").lstrip("/")
for prefix in ("resources/", "skills/", "memories/", "sessions/"):
if path.startswith(prefix):
return path[len(prefix) :]
parts = path.split("/")
if (
len(parts) >= 3
and parts[0] in {"user", "agent"}
and parts[2] in {"resources", "skills", "memories", "sessions"}
):
return "/".join(parts[3:])
return path
class OVFileTool(Tool, ABC):
_memory_commit_counter = itertools.count(1)
def __init__(self, config: "Config | None" = None):
super().__init__()
self._clients = {}
self._config = config
@staticmethod
def _has_request_connection(tool_context: ToolContext) -> bool:
return bool(getattr(tool_context, "openviking_connection", None))
@staticmethod
def _actor_peer_id(tool_context: ToolContext) -> str | None:
return getattr(tool_context, "actor_peer_id", None) or getattr(
tool_context, "sender_id", None
)
async def _get_client(self, tool_context: ToolContext):
actor_peer_id = self._actor_peer_id(tool_context)
if self._has_request_connection(tool_context):
return await VikingClient.create(
tool_context.workspace_id,
connection=tool_context.openviking_connection,
actor_peer_id=actor_peer_id,
config=self._config,
)
if actor_peer_id:
return await VikingClient.create(
tool_context.workspace_id,
actor_peer_id=actor_peer_id,
config=self._config,
)
cache_key = str(tool_context.workspace_id or "__default__")
client = self._clients.get(cache_key)
if client is None:
client = await VikingClient.create(tool_context.workspace_id, config=self._config)
self._clients[cache_key] = client
return client
async def _release_client(self, tool_context: ToolContext, client: VikingClient | None) -> None:
if client is not None and (
self._has_request_connection(tool_context) or self._actor_peer_id(tool_context)
):
close = getattr(client, "close", None)
if callable(close):
await close()
@staticmethod
def _normalize_uri(uri: str | None) -> str:
normalized = (uri or "").strip()
if normalized == "viking://":
return normalized
return normalized.rstrip("/")
@staticmethod
def _dedupe_strings(values: list[str | None]) -> list[str]:
deduped: list[str] = []
seen: set[str] = set()
for value in values:
if not value:
continue
value = str(value).strip()
if not value or value in seen:
continue
seen.add(value)
deduped.append(value)
return deduped
def _memory_peer_ids(self, tool_context: ToolContext) -> list[str]:
return self._dedupe_strings(
[
self._actor_peer_id(tool_context),
*(getattr(tool_context, "memory_peer_ids", None) or []),
]
)
def _is_default_memory_uri(self, uri: str | None) -> bool:
normalized = self._normalize_uri(uri)
# ``viking://user/memories`` is the legacy spelling of the current-user default
# target; it is still accepted here because it survives in stored bot configs and
# LLM output. New emissions always use the ``viking://~`` home alias.
return normalized in {"", "viking://user/memories", "viking://~/memories"}
def _is_default_root_uri(self, uri: str | None) -> bool:
return self._normalize_uri(uri) in {"", "viking://", "viking://user", "viking://~"}
def _peer_memory_uris(
self,
client: VikingClient,
tool_context: ToolContext,
peer_ids: list[str] | None = None,
) -> list[str]:
builder = getattr(client, "build_current_memory_target_uris", None)
if not callable(builder):
return []
return builder(
peer_ids=peer_ids if peer_ids is not None else self._memory_peer_ids(tool_context),
include_self=False,
)
def _fs_retrieval_uris(
self,
client: VikingClient,
tool_context: ToolContext,
uri: str | None,
) -> list[str]:
if getattr(client, "actor_peer_id", None):
if self._is_default_root_uri(uri):
return [uri or "viking://"]
if self._is_default_memory_uri(uri):
return [uri or "viking://~/memories/"]
return [uri or ""]
if not self._is_default_memory_uri(uri):
if not self._is_default_root_uri(uri):
return [uri or ""]
target_uris = [
"viking://resources/",
"viking://~/resources/",
"viking://~/memories/",
"viking://~/skills/",
*self._peer_memory_uris(client, tool_context),
]
return self._dedupe_strings(target_uris)
builder = getattr(client, "build_current_memory_target_uris", None)
if callable(builder):
uris = builder(peer_ids=self._memory_peer_ids(tool_context))
if uris:
return uris
return [uri or "viking://~/memories/"]
class VikingListTool(OVFileTool):
"""Tool to list Viking resources."""
@property
def name(self) -> str:
return "openviking_list"
@property
def description(self) -> str:
return "List resources in a OpenViking folder path."
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"uri": {
"type": "string",
"description": "Optional parent Viking URI to list. Defaults to all visible OpenViking roots plus current peer memory.",
"default": "viking://",
},
"recursive": {
"type": "boolean",
"description": "Whether to list recursively",
"default": False,
},
},
"required": [],
}
async def execute(
self,
tool_context: "ToolContext",
uri: str = "viking://",
recursive: bool = False,
node_limit: int = 1000,
**kwargs: Any,
) -> str:
client = None
try:
client = await self._get_client(tool_context)
entries = []
target_uris = self._fs_retrieval_uris(client, tool_context, uri)
for target_uri in target_uris:
try:
entries.extend(
await client.list_resources(
path=target_uri,
recursive=recursive,
node_limit=node_limit,
)
)
except Exception as exc:
if len(target_uris) == 1:
raise
logger.debug(f"Skip OpenViking list target {target_uri}: {exc}")
continue
if not entries:
return f"No resources found at {uri}"
result = []
for entry in entries:
item = {
"name": entry["name"],
"size": entry["size"],
"uri": entry["uri"],
"isDir": entry["isDir"],
}
result.append(str(item))
return "\n".join(result)
except Exception as e:
logger.exception(f"Error processing message: {e}")
return f"Error listing Viking resources: {str(e)}"
finally:
await self._release_client(tool_context, client)
class VikingDiffPathsTool(OVFileTool):
"""Expose paginated snapshot changes, including deletions, without reading file bodies."""
@property
def name(self) -> str:
return "openviking_diff_paths"
@property
def description(self) -> str:
return (
"List added, modified and deleted file URIs under directories between snapshots. "
"Omit base or pass null to list all files at head. Results include has_more and "
"next_offset; query all pages to enumerate the complete change set. "
"Read required file contents separately with openviking_multi_read."
)
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"paths": {
"type": "array",
"items": {"type": "string", "minLength": 1},
"minItems": 1,
"description": "Source directory Viking URIs to compare.",
},
"base": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Base commit ID; omitted or null means an empty tree.",
},
"head": {"type": "string", "description": "Required target snapshot commit ID."},
"offset": {"type": "integer", "minimum": 0, "default": 0},
"limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100},
},
"required": ["paths", "head"],
}
async def execute(
self,
tool_context: ToolContext,
paths: list[str],
head: str,
base: str | None = None,
offset: int = 0,
limit: int = 100,
**kwargs: Any,
) -> str:
"""Return the requested change page as JSON, or an explicit query error."""
client = None
try:
client = await self._get_client(tool_context)
result = await client.diff_paths(
paths, base=base, head=head, offset=offset, limit=limit
)
return json.dumps(result, ensure_ascii=False)
except Exception as exc:
logger.warning(f"Error querying Viking snapshot changes: {exc}")
return f"Error querying Viking snapshot changes: {exc}"
finally:
await self._release_client(tool_context, client)
class VikingSearchTool(OVFileTool):
"""Tool to search Viking resources."""
@property
def name(self) -> str:
return "openviking_search"
@property
def description(self) -> str:
return (
"Using query to search for resources (knowledge, code, files, workflow, etc.) in OpenViking. "
"Result: Only URIs and summaries are included here. To view the full content, use openviking_multi_read tool. "
"This operation performs semantic retrieval, not full character matching. "
"Avoid duplicate calls with the same intent in the same turn, but do search again for a new user question or a follow-up that asks for a different remembered fact. "
"For questions about the user's memory, profile, preferences, or personal facts, use this tool before concluding no relevant record exists."
)
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The search query"},
"target_uri": {
"type": "string",
"description": "Optional target URI to limit search scope, if is None, then search the entire range.(e.g., viking://resources/)",
},
"min_score": {
"type": "number",
"description": "Minimum relevance score threshold",
"default": 0.35,
},
"limit": {
"type": "integer",
"description": "Maximum candidates per search scope; increase if needed.",
"minimum": 1,
"default": 10,
},
},
"required": ["query"],
}
@staticmethod
def _extract_search_items(results: Any) -> list[dict[str, Any]]:
items: list[dict[str, Any]] = []
group_map = {
"memories": "memory",
"resources": "resource",
"skills": "skill",
}
if isinstance(results, dict):
for key, item_type in group_map.items():
group = results.get(key, [])
if not isinstance(group, list):
continue
for item in group:
if isinstance(item, dict):
items.append({**item, "type": item.get("type", item_type)})
return items
if (
hasattr(results, "memories")
or hasattr(results, "resources")
or hasattr(results, "skills")
):
for key, item_type in group_map.items():
for item in getattr(results, key, []) or []:
items.append(
{
"type": item_type,
"uri": getattr(item, "uri", ""),
"abstract": getattr(item, "abstract", ""),
"is_leaf": getattr(item, "is_leaf", False),
"score": getattr(item, "score", 0.0),
}
)
return items
if isinstance(results, list):
for item in results:
if isinstance(item, dict):
raw_type = str(item.get("type") or item.get("context_type") or "").lower()
item_type = "resource"
if "memory" in raw_type:
item_type = "memory"
elif "skill" in raw_type:
item_type = "skill"
items.append({**item, "type": item_type})
else:
raw_type = str(getattr(item, "context_type", "")).lower()
item_type = "resource"
if "memory" in raw_type:
item_type = "memory"
elif "skill" in raw_type:
item_type = "skill"
items.append(
{
"type": item_type,
"uri": getattr(item, "uri", ""),
"abstract": getattr(item, "abstract", ""),
"is_leaf": getattr(item, "is_leaf", False),
"score": getattr(item, "score", 0.0),
}
)
return items
@staticmethod
def _to_float(value: Any) -> float:
try:
return float(value)
except (TypeError, ValueError):
return 0.0
def _filter_search_items(
self, results: Any, min_score: float
) -> dict[str, list[dict[str, Any]]]:
grouped: dict[str, list[dict[str, Any]]] = {
"memory": [],
"resource": [],
"skill": [],
}
for item in self._extract_search_items(results):
score = self._to_float(item.get("score", 0.0))
if score < min_score:
continue
item_type = str(item.get("type", "resource")).lower()
if item_type not in grouped:
item_type = "resource"
grouped[item_type].append(
{
"uri": str(item.get("uri", "") or ""),
"abstract": str(item.get("abstract", "") or ""),
"is_leaf": bool(item.get("is_leaf", False)),
"score": score,
}
)
return grouped
@staticmethod
def _build_group_json(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
group_items: list[dict[str, Any]] = []
for index, item in enumerate(items, 1):
group_items.append(
{
"index": index,
"uri": item["uri"],
"abstract": item["abstract"],
"is_leaf": item["is_leaf"],
"score": round(item["score"], 6),
}
)
return group_items
def _format_search_items_json(
self, grouped_items: dict[str, list[dict[str, Any]]], min_score: float
) -> str:
memories = self._build_group_json(grouped_items.get("memory", []))
resources = self._build_group_json(grouped_items.get("resource", []))
skills = self._build_group_json(grouped_items.get("skill", []))
payload = {
"count": len(memories) + len(resources) + len(skills),
"memories": memories,
"resources": resources,
"skills": skills,
}
return json.dumps(payload, ensure_ascii=False, indent=2)
async def execute(
self,
tool_context: "ToolContext",
query: str,
target_uri: Optional[str] = "",
min_score: float = 0.35,
limit: int = 10,
**kwargs: Any,
) -> str:
client = None
try:
client = await self._get_client(tool_context)
memory_owner_user_ids = getattr(tool_context, "memory_owner_user_ids", None)
legacy_memory_user_ids = getattr(tool_context, "memory_user_ids", None)
grouped_items = {
"memory": [],
"resource": [],
"skill": [],
}
if (
not target_uri
and not getattr(client, "actor_peer_id", None)
and client.should_sender_fanout()
and (memory_owner_user_ids or legacy_memory_user_ids)
):
user_ids = memory_owner_user_ids or legacy_memory_user_ids
search_targets: list[tuple[str, str | None]] = [("viking://resources/", None)]
for user_id in self._dedupe_strings(list(user_ids or [])):
search_targets.extend(
[
("viking://~/resources/", user_id),
("viking://~/memories/", user_id),
("viking://~/skills/", user_id),
]
)
else:
peer_ids = self._memory_peer_ids(tool_context)
if not target_uri:
actor_peer_id = getattr(client, "actor_peer_id", None)
if actor_peer_id and not peer_ids:
peer_ids = [actor_peer_id]
if actor_peer_id or peer_ids:
target_uris = self._dedupe_strings(
[
"viking://resources/",
"viking://~/resources/",
"viking://~/memories/",
"viking://~/skills/",
*self._peer_memory_uris(
client,
tool_context,
peer_ids=peer_ids,
),
]
)
else:
target_uris = [""]
elif (
self._is_default_memory_uri(target_uri)
and not getattr(client, "actor_peer_id", None)
and peer_ids
):
target_uris = self._dedupe_strings(
[
"viking://~/memories/",
*self._peer_memory_uris(client, tool_context, peer_ids=peer_ids),
]
)
else:
target_uris = [target_uri]
search_targets = [(search_target_uri, None) for search_target_uri in target_uris]
for search_target_uri, search_user_id in search_targets:
search_kwargs = {
"target_uri": search_target_uri,
"limit": limit,
}
if search_user_id:
search_kwargs["user_id"] = search_user_id
results = await client.search(query, **search_kwargs)
filtered_items = self._filter_search_items(results, min_score=min_score)
for item_type, items in filtered_items.items():
grouped_items[item_type].extend(items)
total = sum(len(items) for items in grouped_items.values())
if total == 0:
return f"No results found for query: {query}"
return self._format_search_items_json(grouped_items, min_score=min_score)
except Exception as e:
return f"Error searching Viking: {str(e)}"
finally:
await self._release_client(tool_context, client)
class VikingRuleSearchTool(OVFileTool):
"""Tool to retrieve compiled Rules applicable to a task."""
@property
def name(self) -> str:
return "openviking_rule_search"
@property
def description(self) -> str:
return (
"Use this tool when a concrete task may be governed by OpenViking Rules. "
"It searches the rule set using the task context and returns every relevant Rule "
"the backend determines applicable, with complete applies_when, exception, and "
"application protocol details. Returned Rules must be strictly evaluated against "
"their applies_when, exception, and content."
)
@property
def preserve_complete_result(self) -> bool:
return True
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"task_context": {
"type": "string",
"description": (
"Concrete task, object, evidence, and scenario used to determine which "
"compiled Rules apply."
),
},
},
"required": ["task_context"],
"additionalProperties": False,
}
async def execute(
self,
tool_context: ToolContext,
task_context: str,
**kwargs: Any,
) -> str:
client = None
try:
client = await self._get_client(tool_context)
result = await client.rule_search(task_context)
rendered = result.get("rendered") if isinstance(result, dict) else None
if isinstance(rendered, str) and rendered.strip():
return rendered
return json.dumps(result, ensure_ascii=False)
except Exception as e:
return f"Error searching OpenViking Rules: {str(e)}"
finally:
await self._release_client(tool_context, client)
class VikingAddResourceTool(OVFileTool):
"""Tool to add a resource to Viking."""
@property
def name(self) -> str:
return "openviking_add_resource"
@property
def description(self) -> str:
return "Add a resource (url like pic, git code or local file path) to OpenViking.This is a asynchronous operation."
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"path": {"type": "string", "description": "Url or local file path"},
"description": {"type": "string", "description": "Description of the resource"},
"to": {
"type": "string",
"description": "Optional exact target URI under viking://resources/. When omitted, OpenViking chooses the resource URI.",
},
},
"required": ["path", "description"],
}
@property
def resource_inputs(self) -> dict[str, str]:
return {"path": "local_file"}
async def execute(
self,
tool_context: "ToolContext",
path: str,
description: str,
to: Optional[str] = None,
**kwargs: Any,
) -> str:
client = None
temp_dir: tempfile.TemporaryDirectory[str] | None = None
try:
upload_path = path
if path and not path.startswith("http"):
if tool_context.sandbox_manager is not None:
sandbox = await tool_context.sandbox_manager.get_sandbox(
tool_context.session_key
)
local_path = sandbox.local_file_path(path)
if local_path is not None:
upload_path = str(local_path)
else:
temp_dir = tempfile.TemporaryDirectory(prefix="vikingbot-add-resource-")
local_path = Path(temp_dir.name) / (Path(path).name or "resource")
await sandbox.export_file(path, local_path)
upload_path = str(local_path)
else:
local_path = Path(path).expanduser().resolve()
if not local_path.exists():
return f"Error: File not found: {path}"
if not local_path.is_file():
return f"Error: Not a file: {path}"
upload_path = str(local_path)
client = await self._get_client(tool_context)
result = await client.add_resource(upload_path, description, to=to)
if result:
root_uri = result.get("root_uri", "")
return f"Successfully added resource: {root_uri}"
else:
return "Failed to add resource"
except httpx.ReadTimeout:
return "Request timed out. The resource addition task may still be processing on the server side."
except Exception as e:
logger.warning(f"Error adding resource: {e}")
return f"Error adding resource to Viking: {str(e)}"
finally:
await self._release_client(tool_context, client)
if temp_dir is not None:
temp_dir.cleanup()
class VikingGrepTool(OVFileTool):
"""Tool to search Viking resources using a regex pattern."""
@property
def name(self) -> str:
return "openviking_grep"
@property
def description(self) -> str:
return (
"Search Viking resources using a regex pattern (like grep)."
"Result: Only URIs and summaries are included here. To view the full content, use openviking_multi_read tool."
"Avoid duplicate calls with the same intent in the same turn."
)
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"uri": {
"type": "string",
"description": "Optional Viking URI to search within. Defaults to all visible OpenViking roots plus current peer memory.",
"default": "viking://",
},
"pattern": {
"type": "string",
"description": "Regex pattern to search for",
},
"case_insensitive": {
"type": "boolean",
"description": "Case-insensitive search",
"default": False,
},
},
"required": ["pattern"],
}
async def execute(
self,
tool_context: "ToolContext",
pattern: str,
uri: str = "viking://",
case_insensitive: bool = False,
**kwargs: Any,
) -> str:
client = None
try:
client = await self._get_client(tool_context)
matches = []
target_uris = self._fs_retrieval_uris(client, tool_context, uri)
for target_uri in target_uris:
try:
result = await client.grep(
target_uri,
pattern,
case_insensitive=case_insensitive,
)
except Exception as exc:
if len(target_uris) == 1:
raise
logger.debug(f"Skip OpenViking grep target {target_uri}: {exc}")
continue
if isinstance(result, dict):
matches.extend(result.get("matches", []))
else:
matches.extend(getattr(result, "matches", []))
if not matches:
return f"No matches found for pattern: '{pattern}'"
merged_results: dict[str, list[tuple[int, str]]] = {}
for match in matches:
if isinstance(match, dict):
match_uri = match.get("uri", "unknown")
line = match.get("line", "?")
content = match.get("content", "")
else:
match_uri = getattr(match, "uri", "unknown")
line = getattr(match, "line", "?")
content = getattr(match, "content", "")
if match_uri not in merged_results:
merged_results[match_uri] = []
merged_results[match_uri].append((line, content))
result_lines = [
f"Found {len(matches)} match{'es' if len(matches) != 1 else ''} for pattern '{pattern}':"
]
for match_uri, uri_matches in merged_results.items():
uri_matches.sort(key=lambda x: int(x[0]) if str(x[0]).isdigit() else 0)
result_lines.append(f"\n📄 {match_uri}")
for line, content in uri_matches:
result_lines.append(f" Line {line}:")
result_lines.append(f" {content}")
return "\n".join(result_lines)
except Exception as e:
return f"Error searching Viking with grep: {str(e)}"
finally:
await self._release_client(tool_context, client)
class VikingGlobTool(OVFileTool):
"""Tool to find Viking resources using glob patterns."""
@property
def name(self) -> str:
return "openviking_glob"
@property
def description(self) -> str:
return (
"Find Viking resources using glob patterns (like **/*.md, *.py)."
"Result: Only URIs and summaries are included here. To view the full content, use openviking_multi_read tool."
)
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "Glob pattern to match (e.g., **/*.md, *.py, src/**/*.js)",
},
"uri": {
"type": "string",
"description": "The whole Viking URI to search within (e.g., viking://resources/path/)",
"default": "",
},
},
"required": ["pattern"],
}
async def execute(
self, tool_context: "ToolContext", pattern: str, uri: str = "", **kwargs: Any
) -> str:
client = None
try:
client = await self._get_client(tool_context)
matches = []
count = 0
target_uris = self._fs_retrieval_uris(client, tool_context, uri or "viking://")
for target_uri in target_uris:
try:
result = await client.glob(pattern, uri=target_uri or "viking://")
except Exception as exc:
if len(target_uris) == 1:
raise
logger.debug(f"Skip OpenViking glob target {target_uri}: {exc}")
continue
if isinstance(result, dict):
batch_matches = result.get("matches", [])
batch_count = result.get("count", len(batch_matches))
else:
batch_matches = getattr(result, "matches", [])
batch_count = getattr(result, "count", len(batch_matches))
matches.extend(batch_matches)
count += int(batch_count or 0)
if not matches:
return f"No files found for pattern: {pattern}"
result_lines = [f"Found {count} file{'s' if count != 1 else ''}:"]
for match_uri in matches:
if isinstance(match_uri, dict):
match_uri = match_uri.get("uri", str(match_uri))
result_lines.append(f"📄 {match_uri}")
return "\n".join(result_lines)
except Exception as e:
return f"Error searching Viking with glob: {str(e)}"
finally:
await self._release_client(tool_context, client)
class VikingMemoryCommitTool(OVFileTool):
"""Tool to commit messages to OpenViking session."""
async def _get_commit_task_result(
self,
client: VikingClient,
task_id: str | None,
attempts: int = 20,
interval: float = 0.5,
) -> dict[str, Any] | None:
if not task_id:
return None
get_task = getattr(client.client, "get_task", None)
if not callable(get_task):
return None
task = None
for _ in range(attempts):
task = await get_task(task_id)
if isinstance(task, dict) and task.get("status") in {"completed", "failed"}:
return task
await asyncio.sleep(interval)
return task if isinstance(task, dict) else None
@staticmethod
def _extract_memory_diff_uris(diff: Any) -> dict[str, list[str]]:
operations = diff.get("operations", {}) if isinstance(diff, dict) else {}
return {
"added_uris": [
item["uri"]
for item in operations.get("adds", [])
if isinstance(item, dict) and item.get("uri")
],
"updated_uris": [
item["uri"]
for item in operations.get("updates", [])
if isinstance(item, dict) and item.get("uri")
],
"deleted_uris": [
item["uri"]
for item in operations.get("deletes", [])
if isinstance(item, dict) and item.get("uri")
],
}
@staticmethod
def _format_commit_error(error: Exception) -> str:
message = str(error)
if "<title>403 Forbidden</title>" in message or "<h1>403 Forbidden</h1>" in message:
return "HTTP 403 Forbidden"
return message
@property
def name(self) -> str:
return "openviking_memory_commit"
@property
def description(self) -> str:
return "When user has personal information needs to be remembered, Commit messages to OpenViking."
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"messages": {
"type": "array",
"description": "List of messages to commit, each with role, content",
"items": {
"type": "object",
"properties": {
"role": {"type": "string", "enum": ["user", "assistant"]},
"content": {"type": "string"},
},
"required": ["role", "content"],
},
},
},
"required": ["messages"],
}
async def execute(
self,
tool_context: ToolContext,
messages: list[dict[str, Any]],
**kwargs: Any,
) -> str:
client = None
try:
client = await self._get_client(tool_context)
actor_peer_id = self._actor_peer_id(tool_context)
if not actor_peer_id:
return "Error: peer id is required for OpenViking memory commit."
source_session_id = tool_context.session_key.safe_name()
commit_seq = next(self._memory_commit_counter)
timestamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
session_id = f"{source_session_id}__memory_commit__{timestamp}__{commit_seq:04d}"
result = await client.commit(session_id, messages, peer_id=actor_peer_id)
session_id = (
result.get("session_id", session_id) if isinstance(result, dict) else session_id
)
commit_result = result.get("commit", {}) if isinstance(result, dict) else {}
archive_uri = commit_result.get("archive_uri")
memory_diff_uri = f"{archive_uri}/memory_diff.json" if archive_uri else None
task_id = commit_result.get("task_id")
task = await self._get_commit_task_result(client, task_id)
changed_uris = {"added_uris": [], "updated_uris": [], "deleted_uris": []}
if task and task.get("status") == "completed" and memory_diff_uri:
raw_diff = await client.read_content(memory_diff_uri, level="read")
if raw_diff:
try:
changed_uris = self._extract_memory_diff_uris(json.loads(raw_diff))
except json.JSONDecodeError:
logger.warning(f"Failed to parse memory diff from {memory_diff_uri}")
return json.dumps(
{
"status": "success",
"session_id": session_id,
"memory_commit_session_id": session_id,
"source_session_id": source_session_id,
"message_count": len(messages),
"archived": commit_result.get("archived"),
**changed_uris,
"archive_uri": archive_uri,
"memory_diff_uri": memory_diff_uri,
"task_id": task_id,
"task_status": task.get("status") if isinstance(task, dict) else None,
},
ensure_ascii=False,
indent=2,
)
except Exception as e:
logger.exception(f"Error processing message: {e}")
return f"Error: committing to Viking failed: {self._format_commit_error(e)}"
finally:
await self._release_client(tool_context, client)
class VikingMultiReadTool(OVFileTool):
"""Tool to read content from multiple Viking resources concurrently."""
_FULL_READ_WARN_BYTES = 512 * 1024
_MAX_INLINE_IMAGES = 4
_MAX_INLINE_MEDIA_BYTES = MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
_INLINE_IMAGE_EXTENSIONS = frozenset({".gif", ".jpeg", ".jpg", ".png", ".webp"})
_INLINE_IMAGE_MIME_TYPES = frozenset({"image/gif", "image/jpeg", "image/png", "image/webp"})
_AUDIO_EXTENSIONS = frozenset(
{".aac", ".ac3", ".flac", ".m4a", ".mp3", ".ogg", ".opus", ".wav"}
)
_VIDEO_EXTENSIONS = frozenset({".avi", ".flv", ".mkv", ".mov", ".mp4", ".webm", ".wmv"})
@staticmethod
def _uri_suffix(uri: str) -> str:
path = uri.split("#", 1)[0].split("?", 1)[0]
return PurePosixPath(path).suffix.lower()
@classmethod
def _media_kind(cls, uri: str) -> str | None:
suffix = cls._uri_suffix(uri)
if suffix in cls._INLINE_IMAGE_EXTENSIONS:
return "image"
if suffix in cls._AUDIO_EXTENSIONS:
return "audio"
if suffix in cls._VIDEO_EXTENSIONS:
return "video"
return None
@property
def name(self) -> str:
return "openviking_multi_read"
@property
def description(self) -> str:
return (
"Read content from multiple OpenViking resources concurrently. By default returns "
"complete content. Large files (over 512 KB) are not returned in full: first use "
"openviking_grep to locate relevant lines, then read a bounded window with offset "
"and limit (line numbers, 0-indexed)."
)
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"uris": {
"type": "array",
"items": {"type": "string"},
"description": 'List of Viking file URIs to read from (e.g., ["viking://resources/path/123.md"])',
},
"offset": {
"type": "integer",
"description": "Starting line number (0-indexed) for bounded reads; default 0.",
"default": 0,
},
"limit": {
"type": "integer",
"description": "Number of lines to read; -1 reads to the end (default). Use a small value to page through large files.",
"default": -1,
},
},
"required": ["uris"],
}
@classmethod
async def _read_image(cls, client, uri):
"""Load one native image for multi-read and Compile using the same checks."""
stat = await client.stat(uri)
size = stat.get("size") if isinstance(stat, dict) else None
if isinstance(size, bool) or not isinstance(size, int) or size < 0:
return {
"uri": uri,
"content": "Image size is unavailable; cannot attach it safely.",
"success": False,
"media_kind": "image",
}
if size > cls._MAX_INLINE_MEDIA_BYTES:
return {
"uri": uri,
"content": (
f"Image is {size} bytes; the inline limit is "
f"{cls._MAX_INLINE_MEDIA_BYTES} bytes."
),
"success": False,
"media_kind": "image",
}
data = await client.download_bytes(uri)
if len(data) > size:
return {
"uri": uri,
"content": "Image changed after its size was checked; retry the read.",
"success": False,
"media_kind": "image",
}
image_format = sniff_image_format(data)
if image_format is None or image_format.mime_type not in cls._INLINE_IMAGE_MIME_TYPES:
return {
"uri": uri,
"content": ("File bytes do not match a supported PNG, JPEG, GIF, or WebP image."),
"success": False,
"media_kind": "image",
}
encoded = base64.b64encode(data).decode("ascii")
return {
"uri": uri,
"content": (f"Image resource ({image_format.mime_type}, {len(data)} bytes)."),
"image": {
"type": "image_url",
"image_url": {"url": f"data:{image_format.mime_type};base64,{encoded}"},
},
"media_bytes": len(data),
"sha256": hashlib.sha256(data).hexdigest(),
"success": True,
"media_kind": "image",
}
async def execute(
self,
tool_context: ToolContext,
uris: list[str],
offset: int = 0,
limit: int = -1,
with_revision: bool = False,
**kwargs: Any,
) -> str | MultimodalToolResult:
"""Read content; with_revision returns raw UTF-8 ranges and full-file hashes as JSON."""
level = "read" # 默认获取完整内容
client = None
try:
if not uris:
return "Error: No URIs provided."
client = await self._get_client(tool_context)
max_concurrent = 10
semaphore = asyncio.Semaphore(max_concurrent)
image_indexes = [
index for index, uri in enumerate(uris) if self._media_kind(uri) == "image"
]
inline_image_indexes = set(image_indexes[: self._MAX_INLINE_IMAGES])
async def read_single_uri(index: int, uri: str) -> dict[str, Any]:
async with semaphore:
try:
media_kind = self._media_kind(uri)
if with_revision and (
media_kind or offset < 0 or (limit != -1 and limit < 1)
):
raise ValueError(
"Revision reads require text files and valid line ranges"
)
if media_kind == "image":
if index not in inline_image_indexes:
return {
"uri": uri,
"content": (
"Image was not attached because one tool result supports "
f"at most {self._MAX_INLINE_IMAGES} images. Read fewer "
"images at once."
),
"success": False,
"media_kind": media_kind,
}
return await self._read_image(client, uri)
if media_kind in {"audio", "video"}:
content = await client.read_content(uri, level="overview")
if not content:
return {
"uri": uri,
"content": (
"No OpenViking textual overview is available for this "
f"{media_kind} resource."
),
"success": False,
"media_kind": media_kind,
}
return {
"uri": uri,
"content": content,
"success": True,
"media_kind": media_kind,
}
if limit == -1:
try:
stat = await client.stat(uri)
size = stat.get("size")
except Exception:
size = None
if isinstance(size, int) and size > self._FULL_READ_WARN_BYTES:
return {
"uri": uri,
"content": (
f"File is {size} bytes; reading it fully would exceed "
"the tool result budget. Use openviking_grep to locate "
"relevant lines, then read a window with "
"openviking_multi_read offset/limit."
),
"success": False,
"media_kind": None,
}
if with_revision:
raw = await client.download_bytes(uri)
lines = raw.decode("utf-8").splitlines(keepends=True)
return {
"uri": uri,
"content": "".join(
lines[offset:]
if limit == -1
else lines[offset : offset + limit]
),
"base_hash": hashlib.sha256(raw).hexdigest(),
"success": True,
}
content = await client.read_content(
uri, level=level, offset=offset, limit=limit
)
skill_runtime = getattr(tool_context, "skill_runtime", None)
if skill_runtime is not None:
active_skill = await skill_runtime.activate_from_read(uri, content)
if active_skill is not None:
content = skill_runtime.render_skill_content(active_skill)
return {
"uri": uri,
"content": content,
"success": True,
"media_kind": None,
}
except Exception as e:
logger.warning(f"Error reading from {uri}: {e}")
return {
"uri": uri,
"content": f"Error reading from Viking: {str(e)}",
"success": False,
"media_kind": self._media_kind(uri),
}
# 并发读取所有URI
read_tasks = [read_single_uri(index, uri) for index, uri in enumerate(uris)]
results = await asyncio.gather(*read_tasks)
if with_revision:
return json.dumps(results, ensure_ascii=False)
inline_media_bytes = 0
for result in results:
if result.get("image") is None:
continue
media_bytes = result.get("media_bytes", 0)
if inline_media_bytes + media_bytes > self._MAX_INLINE_MEDIA_BYTES:
result.pop("image", None)
result["media_bytes"] = 0
result["content"] = (
"Image was not attached because the combined inline media size would "
f"exceed {self._MAX_INLINE_MEDIA_BYTES} bytes. Read fewer images at once."
)
result["success"] = False
continue
inline_media_bytes += media_bytes
# 构建结果
range_note = (
""
if limit == -1
else f" (lines {offset}..{offset + limit - 1 if limit > 0 else 'end'})"
)
result_lines = [f"Multi-read results for {len(uris)} resources (level: {level}):"]
has_images = any(result.get("image") is not None for result in results)
content_parts: list[dict[str, Any]] = (
[{"type": "text", "text": result_lines[0]}] if has_images else []
)
for result in results:
uri = result["uri"]
content = result["content"]
success = result["success"]
item_range_note = "" if result["media_kind"] else range_note
start_marker = f"\n--- START OF {uri}{item_range_note} ---"
end_marker = f"--- END OF {uri} ---"
result_lines.append(start_marker)
if success:
result_lines.append(content)
else:
result_lines.append(f"ERROR: {content}")
result_lines.append(end_marker)
if has_images:
content_parts.append(
{
"type": "text",
"text": f"{start_marker}\n{'ERROR: ' if not success else ''}{content}",
}
)
image = result.get("image")
if image is not None:
content_parts.append(image)
content_parts.append({"type": "text", "text": end_marker})
text_result = "\n".join(result_lines)
if has_images:
return MultimodalToolResult(
text=text_result,
content=content_parts,
)
return text_result
except Exception as e:
logger.exception(f"Error in VikingMultiReadTool: {e}")
return f"Error multi-reading Viking resources: {str(e)}"
finally:
await self._release_client(tool_context, client)
class VikingExportTool(OVFileTool):
"""Materialize viking:// files into the task sandbox so shell tools can process them.
The OpenViking ``exec``/``write_file`` tools operate on the task sandbox filesystem,
which does not contain viking:// source files by default. This tool downloads a
viking:// file or directory into the sandbox workspace (under ``compile_resources/``
by default), so the agent can then run arbitrary shell commands on them with ``exec``
(``jq``, ``wc``, ``grep``, ``head``, ``python``, ...) or inspect them with
``read_file``. It is intentionally data-format agnostic: the agent decides which
files to pull and how to process them.
"""
_MAX_FILES = 1000
_MAX_TOTAL_BYTES = 1024 * 1024 * 1024 # 1 GiB
_DEFAULT_DEST = "compile_resources"
@property
def name(self) -> str:
return "openviking_export"
@property
def description(self) -> str:
return (
"Download a viking:// file or directory into the task sandbox workspace "
"(under `compile_resources/` by default) so you can process it with "
"exec/read_file — for example `jq`, `wc`, `grep`, `head`, `python`. Use this "
"instead of openviking_multi_read for large or structured files that you want "
"to filter or aggregate with shell tools."
)
@property
def parameters(self) -> dict[str, Any]:
return {
"type": "object",
"properties": {
"uri": {
"type": "string",
"description": "Viking URI of a file or directory to materialize into the workspace.",
},
"dest": {
"type": "string",
"description": "Base directory under the workspace to write into (default 'compile_resources').",
"default": self._DEFAULT_DEST,
},
},
"required": ["uri"],
}
async def _collect_uris(self, client: VikingClient, uri: str) -> tuple[list[str], bool]:
"""Return (file URIs to export, whether the listing hit the file-count cap).
The second element lets the caller warn that files beyond the cap were
not exported, instead of dropping them silently.
"""
try:
stat = await client.stat(uri)
except Exception:
return [], False
if not stat.get("isDir"):
return [uri], False
entries = await client.list_resources(path=uri, recursive=True, node_limit=self._MAX_FILES)
uris = []
for entry in entries:
if not isinstance(entry, Mapping):
continue
entry_uri = str(entry.get("uri") or "")
if not entry_uri:
continue
uris.append(entry_uri)
if len(uris) >= self._MAX_FILES:
break
truncated = len(entries) >= self._MAX_FILES
return uris, truncated
@staticmethod
def _local_path(uri: str) -> str:
return local_path_for_viking_uri(uri)
async def execute(
self,
tool_context: ToolContext,
uri: str,
dest: str = "compile_resources",
**kwargs: Any,
) -> str:
del kwargs
client = None
try:
if tool_context.sandbox_manager is None:
return "Error: openviking_export requires a task sandbox to write into."
client = await self._get_client(tool_context)
file_uris, listing_truncated = await self._collect_uris(client, uri)
if not file_uris:
return f"No files found under {uri}"
sandbox = await tool_context.sandbox_manager.get_sandbox(tool_context.session_key)
dest = dest.strip("/") or self._DEFAULT_DEST
exported: list[str] = []
skipped_binary = 0
total_bytes = 0
byte_limit_hit = False
for file_uri in file_uris:
try:
stat = await client.stat(file_uri)
size = stat.get("size")
if isinstance(size, int) and total_bytes + size > self._MAX_TOTAL_BYTES:
byte_limit_hit = True
break
payload = await client.download_bytes(file_uri)
except Exception as exc:
logger.warning(f"openviking_export failed to download {file_uri}: {exc}")
continue
total_bytes += len(payload)
relative = f"{dest}/{self._local_path(file_uri)}"
try:
text = payload.decode("utf-8")
except UnicodeDecodeError:
skipped_binary += 1
continue
await sandbox.write_file(relative, text)
exported.append(f"{relative} ({len(payload)} bytes)")
if not exported:
if byte_limit_hit:
return (
f"No text files exported from {uri}: the first file alone would "
f"exceed the total-byte budget ({self._MAX_TOTAL_BYTES} bytes)."
)
return f"No text files exported from {uri}."
lines = [f"Exported {len(exported)} file(s) into the workspace under '{dest}/':"]
lines.extend(f"- {line}" for line in exported)
if skipped_binary:
lines.append(f"Skipped {skipped_binary} non-UTF-8 (binary) file(s).")
if byte_limit_hit:
lines.append(
"NOTE: stopped before the total-byte budget "
f"({self._MAX_TOTAL_BYTES} bytes) was exceeded; remaining files were "
"not exported. Narrow the uri or ask to raise the limit if you need them."
)
elif listing_truncated:
lines.append(
f"NOTE: the source listing was capped at {self._MAX_FILES} entries; "
"files beyond that were not exported."
)
lines.append(
"You can now process these with exec (jq/wc/grep/head/python) or read_file."
)
return "\n".join(lines)
except Exception as e:
logger.exception("Error in VikingExportTool: %s", e)
return f"Error exporting Viking resources: {str(e)}"
finally:
await self._release_client(tool_context, client)