Skip to content

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

feat(vikingbot): support OpenViking remote skills (#4095)

DuTaoe3c8e56fea81
diff --git a/bot/tests/test_compile.py b/bot/tests/test_compile.py
index 89274bc9a..8accad9c3 100644
--- a/bot/tests/test_compile.py
+++ b/bot/tests/test_compile.py
@@ -1480,9 +1480,10 @@ async def test_request_normalization_uses_default_reason_and_canonical_skill(mon
async def mkdir(self, uri):
self.created.add(uri)
- async def get_skill(self, name, *, target_uri):
+ async def get_skill(self, name, *, target_uri, include_integrity=False):
assert name == "wiki"
assert target_uri == "viking://agent/skills"
+ assert include_integrity is False
return {
"root_uri": "viking://agent/skills/wiki",
"content": self.skill_content,
diff --git a/bot/tests/test_sandbox_file_access.py b/bot/tests/test_sandbox_file_access.py
index 87bdacdab..95157fdc6 100644
--- a/bot/tests/test_sandbox_file_access.py
+++ b/bot/tests/test_sandbox_file_access.py
@@ -3,8 +3,9 @@
"""Regression tests for bounded local and remote sandbox file access."""
import json
+import sys
from pathlib import Path
-from types import SimpleNamespace
+from types import ModuleType, SimpleNamespace
import pytest
from vikingbot.sandbox.backends.aiosandbox import AioSandboxBackend
@@ -35,6 +36,15 @@ async def test_local_workspace_listing_and_reads_are_bounded(tmp_path: Path):
with pytest.raises(ValueError, match="inventory exceeds 2 entries"):
await backend.list_files(max_entries=2)
+ assert backend.local_file_path("nested/artifact.bin") == tmp_path / "nested/artifact.bin"
+ exported = tmp_path / "exported.bin"
+ assert await backend.export_file("nested/artifact.bin", exported) == 8
+ assert exported.read_bytes() == b"artifact"
+ oversized = tmp_path / "oversized.bin"
+ with pytest.raises(ValueError, match="7-byte export limit"):
+ await backend.export_file("nested/artifact.bin", oversized, max_bytes=7)
+ assert not oversized.exists()
+
class _AioFileClient:
def __init__(self, *, truncated=False):
@@ -125,7 +135,16 @@ async def test_aiosandbox_lists_and_streams_from_remote_workspace(tmp_path: Path
assert await backend.read_file_bytes("artifact.bin", max_bytes=6) == b"abcdef"
with pytest.raises(ValueError, match="5-byte read limit"):
await backend.read_file_bytes("artifact.bin", max_bytes=5)
- assert files.download_calls == ["/home/gem/artifact.bin", "/home/gem/artifact.bin"]
+
+ destination = tmp_path / "download" / "artifact.bin"
+ assert backend.local_file_path("artifact.bin") is None
+ assert await backend.export_file("artifact.bin", destination) == 6
+ assert destination.read_bytes() == b"abcdef"
+ assert files.download_calls == [
+ "/home/gem/artifact.bin",
+ "/home/gem/artifact.bin",
+ "/home/gem/artifact.bin",
+ ]
@pytest.mark.asyncio
@@ -170,11 +189,27 @@ class _OpenSandboxCommands:
)
+class _RunCommandOpts(SimpleNamespace):
+ pass
+
+
def _opensandbox_vke_backend(
tmp_path: Path,
file_client: _OpenSandboxFiles,
commands: _OpenSandboxCommands,
) -> OpenSandboxBackend:
+ if "opensandbox.models.execd" not in sys.modules:
+ opensandbox_module = sys.modules.setdefault("opensandbox", ModuleType("opensandbox"))
+ models_module = sys.modules.setdefault(
+ "opensandbox.models",
+ ModuleType("opensandbox.models"),
+ )
+ execd_module = ModuleType("opensandbox.models.execd")
+ execd_module.RunCommandOpts = _RunCommandOpts
+ opensandbox_module.models = models_module
+ models_module.execd = execd_module
+ sys.modules["opensandbox.models.execd"] = execd_module
+
backend = object.__new__(OpenSandboxBackend)
backend._workspace = tmp_path
backend._is_vke = True
@@ -202,6 +237,16 @@ async def test_opensandbox_vke_uses_bounded_remote_inventory_and_range_reads(tmp
("/workspace/artifact.bin", "bytes=0-5"),
]
+ destination = tmp_path / "download" / "artifact.bin"
+ assert backend.local_file_path("artifact.bin") is None
+ assert await backend.export_file("artifact.bin", destination) == 6
+ assert destination.read_bytes() == b"abcdef"
+ assert files.read_calls == [
+ ("/workspace/artifact.bin", "bytes=0-6"),
+ ("/workspace/artifact.bin", "bytes=0-5"),
+ ("/workspace/artifact.bin", None),
+ ]
+
@pytest.mark.asyncio
async def test_opensandbox_vke_inventory_stops_at_the_remote_limit(tmp_path: Path):
diff --git a/bot/vikingbot/agent/context.py b/bot/vikingbot/agent/context.py
index ac047d2a8..dc188df0f 100644
--- a/bot/vikingbot/agent/context.py
+++ b/bot/vikingbot/agent/context.py
@@ -41,6 +41,7 @@ class ContextBuilder:
is_group_chat: bool = False,
eval: bool = False,
openviking_connection: dict[str, Any] | None = None,
+ remote_skills_summary: str = "",
enable_subagents: bool = True,
config: "Config | None" = None,
):
@@ -55,6 +56,7 @@ class ContextBuilder:
self._is_group_chat = is_group_chat
self._eval = eval
self._openviking_connection = openviking_connection
+ self._remote_skills_summary = remote_skills_summary
self._enable_subagents = enable_subagents
self._config = config
self.latest_relevant_memories: str | None = None
@@ -148,7 +150,7 @@ class ContextBuilder:
# 2. Available skills: only show summary (agent uses read_file to load)
skills_summary = self.skills.build_skills_summary()
- if skills_summary:
+ if skills_summary or self._remote_skills_summary:
required_skill_note = ""
required_skill_candidates = [
"skills/experience_loader/SKILL.md",
@@ -161,12 +163,30 @@ class ContextBuilder:
f"`{skill_path}` and apply its instructions.\n"
)
break
+ local_section = ""
+ if skills_summary:
+ local_section = f"""## Local Skills
+
+Read local SKILL.md files with the read_file tool.
+{skills_summary}"""
+ remote_section = ""
+ if self._remote_skills_summary:
+ remote_section = f"""## OpenViking Skills
+
+These are remote Skill summaries. Read a selected SKILL.md with openviking_multi_read.
+Do not use read_file for their viking:// locations. Text references stay remote; the
+runtime automatically materializes files only when a tool requires a local path.
+After activation, use the canonical resource URIs appended to SKILL.md. When multiple
+remote Skills are active, their tool policies are intersected. Use `workspace:<relative-path>`
+or an absolute path for an ordinary workspace file.
+{self._remote_skills_summary}"""
parts.append(f"""# Skills
-The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
-Skills with available="false" need dependencies installed first - you can try installing them with apt/brew.
+The following local and remote Skills extend your capabilities.
{required_skill_note}
-{skills_summary}""")
+{local_section}
+
+{remote_section}""")
# Viking peer profile (only if ov tools are enabled). In the current
# OpenViking identity model, the bot API key owns the User, and the
diff --git a/bot/vikingbot/agent/loop.py b/bot/vikingbot/agent/loop.py
index a5b04303e..4cf5b016f 100644
--- a/bot/vikingbot/agent/loop.py
+++ b/bot/vikingbot/agent/loop.py
@@ -17,9 +17,11 @@ from loguru import logger
from vikingbot.agent.context import ContextBuilder
from vikingbot.agent.memory import MemoryStore
+from vikingbot.agent.remote_skills import SkillRuntimeContext
+from vikingbot.agent.skills import SkillsLoader
from vikingbot.agent.subagent import SubagentManager
from vikingbot.agent.tools import register_default_tools
-from vikingbot.agent.tools.registry import ToolRegistry
+from vikingbot.agent.tools.registry import ToolExecutionResult, ToolRegistry
from vikingbot.bus.events import InboundMessage, OutboundEventType, OutboundMessage
from vikingbot.bus.queue import MessageBus
from vikingbot.config.schema import BotMode, Config, SessionKey
@@ -938,6 +940,7 @@ class AgentLoop:
openviking_tool_names: list[str] | set[str] | None = None,
allow_final_fallback: bool = True,
inject_write_experience: bool = True,
+ skill_runtime: 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.
@@ -1017,7 +1020,13 @@ class AgentLoop:
tool_definitions = active_tools.get_definitions(
ov_tools_enable=ov_tools_enable,
disabled_tools=disabled_tools,
+ skill_runtime=skill_runtime,
)
+ visible_tool_names = {
+ str(definition.get("function", {}).get("name") or "")
+ for definition in tool_definitions
+ if isinstance(definition, dict)
+ }
response, _streamed_content, streamed_reasoning = await self._chat_with_stream_events(
messages=messages,
tools=tool_definitions,
@@ -1094,39 +1103,63 @@ class AgentLoop:
reasoning_content=response.reasoning_content,
)
- # Stage 2: Execute all tools in parallel
- async def execute_single_tool(idx: int, tool_call):
+ # Stage 2: activate Skills first, then execute remaining tools.
+ async def execute_single_tool(
+ idx: int, tool_call, allowed_names=visible_tool_names
+ ):
"""Execute a single tool and track execution time."""
tool_execute_start_time = time.time()
+ if tool_call.name not in allowed_names:
+ result = f"Error: Tool '{tool_call.name}' is not available in this turn"
+ return (
+ idx,
+ tool_call,
+ ToolExecutionResult(
+ result=result,
+ effective_params=dict(tool_call.arguments),
+ ),
+ 0.0,
+ )
tool_connection = (
openviking_connection
if scoped_openviking_tools is None
or tool_call.name in scoped_openviking_tools
else None
)
- result = await active_tools.execute(
- tool_call.name,
- tool_call.arguments,
- session_key=session_key,
- sandbox_manager=self.sandbox_manager,
- sender_id=sender_id,
- actor_peer_id=actor_peer_id or sender_id,
- memory_peer_ids=memory_peer_ids,
- memory_owner_user_ids=memory_owner_user_ids,
- openviking_connection=tool_connection,
- channel_metadata=channel_metadata,
- )
+ execute_kwargs = {
+ "session_key": session_key,
+ "sandbox_manager": self.sandbox_manager,
+ "sender_id": sender_id,
+ "actor_peer_id": actor_peer_id or sender_id,
+ "memory_peer_ids": memory_peer_ids,
+ "memory_owner_user_ids": memory_owner_user_ids,
+ "openviking_connection": tool_connection,
+ "channel_metadata": channel_metadata,
+ }
+ if hasattr(active_tools, "execute_detailed"):
+ outcome = await active_tools.execute_detailed(
+ tool_call.name,
+ tool_call.arguments,
+ **execute_kwargs,
+ skill_runtime=skill_runtime,
+ )
+ else:
+ # Keep compatibility with embedders/tests that provide a
+ # minimal registry implementing only the legacy API.
+ result = await active_tools.execute(
+ tool_call.name, tool_call.arguments, **execute_kwargs
+ )
+ outcome = ToolExecutionResult(
+ result=result,
+ effective_params=dict(tool_call.arguments),
+ )
tool_execute_duration = (time.time() - tool_execute_start_time) * 1000
- return idx, tool_call, result, tool_execute_duration
+ return idx, tool_call, outcome, tool_execute_duration
- # Run all tool executions in parallel
- tool_tasks = [
- execute_single_tool(idx, tool_call)
- for idx, tool_call in enumerate(response.tool_calls)
- ]
- if publish_events:
- for tool_call in response.tool_calls:
- args_str = json.dumps(tool_call.arguments, ensure_ascii=False)
+ for tool_call in response.tool_calls:
+ args_str = json.dumps(tool_call.arguments, ensure_ascii=False)
+ logger.info(f"[TOOL_CALL]: {tool_call.name}({args_str[:200]})")
+ if publish_events:
await self.bus.publish_outbound(
OutboundMessage(
session_key=session_key,
@@ -1134,13 +1167,75 @@ class AgentLoop:
event_type=OutboundEventType.TOOL_CALL,
)
)
- results = await asyncio.gather(*tool_tasks)
+
+ indexed_calls = list(enumerate(response.tool_calls))
+ activation_calls = []
+ regular_calls = []
+ for indexed_call in indexed_calls:
+ _index, candidate_call = indexed_call
+ if skill_runtime is not None and skill_runtime.is_activation_call(
+ candidate_call.name, candidate_call.arguments
+ ):
+ activation_calls.append(indexed_call)
+ else:
+ regular_calls.append(indexed_call)
+
+ # Complete Skill activation first. Calls emitted from the pre-activation
+ # schema are never executed under the newly activated policy; the model
+ # retries them on the next iteration with refreshed tool definitions.
+ activation_results = await asyncio.gather(
+ *(execute_single_tool(index, call) for index, call in activation_calls)
+ )
+ activation_failed = any(
+ not _is_tool_result_success(item[2].result)
+ or not skill_runtime.activation_succeeded(item[1].arguments)
+ for item in activation_results
+ )
+ if activation_failed:
+ regular_results = [
+ (
+ index,
+ call,
+ ToolExecutionResult(
+ result=(
+ "Error: SKILL_ACTIVATION_FAILED: execution was blocked "
+ "because a Skill definition in this tool batch could not "
+ "be activated"
+ ),
+ effective_params=dict(call.arguments),
+ ),
+ 0.0,
+ )
+ for index, call in regular_calls
+ ]
+ elif activation_calls:
+ regular_results = [
+ (
+ index,
+ call,
+ ToolExecutionResult(
+ result=(
+ "Error: SKILL_CONTEXT_UPDATED: one or more remote Skills "
+ "were activated; retry this tool call using the refreshed "
+ "tool definitions"
+ ),
+ effective_params=dict(call.arguments),
+ ),
+ 0.0,
+ )
+ for index, call in regular_calls
+ ]
+ else:
+ regular_results = await asyncio.gather(
+ *(execute_single_tool(index, call) for index, call in regular_calls)
+ )
+ results = sorted([*activation_results, *regular_results], key=lambda item: item[0])
# Stage 3: Process results sequentially in original order
turn_tools: list[dict[str, Any]] = []
- for _idx, tool_call, result, tool_execute_duration in results:
+ for _idx, tool_call, outcome, tool_execute_duration in results:
+ result = outcome.result
args_str = json.dumps(tool_call.arguments, ensure_ascii=False)
- logger.info(f"[TOOL_CALL]: {tool_call.name}({args_str[:200]})")
logger.info(f"[RESULT]: {str(result)[:600]}")
if publish_events:
@@ -1159,12 +1254,16 @@ class AgentLoop:
"tool_call_id": tool_call.id,
"tool_name": tool_call.name,
"args": args_str,
+ "resolved_args": outcome.effective_params,
"result": result,
"duration": tool_execute_duration,
"execute_success": _is_tool_result_success(result),
"input_token": tool_call.tokens,
"output_token": cal_str_tokens(result, text_type="mixed"),
}
+ if outcome.skill_uris:
+ tool_used_dict["skill_uri"] = outcome.skill_uris[0]
+ tool_used_dict["skill_uris"] = list(outcome.skill_uris)
tools_used.append(tool_used_dict)
turn_tools.append(tool_used_dict)
@@ -1179,8 +1278,8 @@ class AgentLoop:
)
if any(
- tool_call.name in stop_tools and _is_tool_result_success(_result)
- for _idx, tool_call, _result, _duration in results
+ tool_call.name in stop_tools and _is_tool_result_success(_outcome.result)
+ for _idx, tool_call, _outcome, _duration in results
):
final_content = ""
break
@@ -1403,6 +1502,7 @@ class AgentLoop:
logger.debug(f"Failed to send processing tick: {e}")
monitor_task = asyncio.create_task(check_long_running())
+ skill_runtime: SkillRuntimeContext | None = None
try:
if msg.session_key.type == "system":
@@ -1578,6 +1678,19 @@ class AgentLoop:
else:
message_workspace = self.workspace
+ skill_runtime = self._create_skill_runtime(
+ session_key=session_key,
+ workspace=message_workspace,
+ ov_tools_enable=ov_tools_enable,
+ disabled_tools=disabled_tools,
+ openviking_connection=openviking_connection,
+ actor_peer_id=actor_peer_id,
+ )
+ remote_skills_summary = ""
+ if skill_runtime is not None:
+ await skill_runtime.discover(msg.content)
+ remote_skills_summary = skill_runtime.build_discovery_summary()
+
from vikingbot.agent.context import ContextBuilder
message_context = ContextBuilder(
@@ -1589,6 +1702,7 @@ class AgentLoop:
is_group_chat=is_group_chat,
eval=self._eval,
openviking_connection=openviking_connection,
+ remote_skills_summary=remote_skills_summary,
enable_subagents=self._subagents_enabled(),
config=self.config,
)
@@ -1662,6 +1776,7 @@ class AgentLoop:
openviking_connection=openviking_connection,
channel_metadata=msg.metadata,
captured_turns=agent_turns,
+ skill_runtime=skill_runtime,
)
if auto_memory_tool:
@@ -1738,6 +1853,11 @@ class AgentLoop:
tools_used_names=response_completed["tools_used_names"],
)
finally:
+ if skill_runtime is not None:
+ try:
+ await skill_runtime.close()
+ except Exception as exc:
+ logger.warning("Failed to close remote Skill runtime: {}", exc)
long_running_notified = True
monitor_task.cancel()
try:
@@ -1890,6 +2010,40 @@ class AgentLoop:
channel_config = self._get_channel_config(session_key)
return getattr(channel_config, "ov_tools_enable", True) if channel_config else True
+ def _create_skill_runtime(
+ self,
+ *,
+ session_key: SessionKey,
+ workspace: Path,
+ ov_tools_enable: bool,
+ disabled_tools: list[str] | None,
+ openviking_connection: dict[str, Any] | None,
+ actor_peer_id: str | None,
+ ) -> SkillRuntimeContext | None:
+ if (
+ self.config is None
+ or not ov_tools_enable
+ or not self.config.ov_server.is_available()
+ or not self.tools.has("openviking_multi_read")
+ or "openviking_multi_read" in set(disabled_tools or ())
+ ):
+ return None
+ local_skills = SkillsLoader(workspace).list_skills(filter_unavailable=False)
+ workspace_id = (
+ self.sandbox_manager.to_workspace_id(session_key)
+ if self.sandbox_manager
+ else session_key.safe_name()
+ )
+ return SkillRuntimeContext(
+ config=self.config,
+ session_key=session_key,
+ sandbox_manager=self.sandbox_manager,
+ workspace_id=workspace_id,
+ openviking_connection=openviking_connection,
+ actor_peer_id=actor_peer_id,
+ local_skill_names=(skill["name"] for skill in local_skills),
+ )
+
async def _process_system_message(self, msg: InboundMessage) -> OutboundMessage | None:
"""
Process a system message (e.g., subagent announce).
diff --git a/bot/vikingbot/agent/remote_skill_cache.py b/bot/vikingbot/agent/remote_skill_cache.py
new file mode 100644
index 000000000..bff978f0f
--- /dev/null
+++ b/bot/vikingbot/agent/remote_skill_cache.py
@@ -0,0 +1,349 @@
+"""Versioned, principal-scoped host cache for remote Skill snapshots."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import time
+import uuid
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+if TYPE_CHECKING:
+ from vikingbot.config.schema import Config
+
+
+_CACHE_FORMAT_VERSION = 1
+_CACHE_METADATA = "metadata.json"
+_CACHE_SNAPSHOT = "snapshot"
+
+
+@dataclass(frozen=True)
+class RemoteSkillCacheKey:
+ """Opaque filesystem-safe identity for one authorized Skill revision."""
+
+ scope_digest: str
+ root_digest: str
+ revision_digest: str
+
+
+@dataclass(frozen=True)
+class SnapshotBuildResult:
+ """Validated size information returned by a cache snapshot builder."""
+
+ total_bytes: int
+ file_count: int
+
+
+@dataclass(frozen=True)
+class CachedSkillSnapshot:
+ """One leased immutable host-side Skill snapshot."""
+
+ key: RemoteSkillCacheKey
+ path: Path
+ hit: bool
+ total_bytes: int
+ file_count: int
+
+
+@dataclass
+class _KeyLockState:
+ """One keyed lock plus the holders and waiters that still reference it."""
+
+ lock: asyncio.Lock
+ users: int = 0
+
+
+SnapshotBuilder = Callable[[Path], Awaitable[SnapshotBuildResult]]
+
+
+class RemoteSkillCacheError(RuntimeError):
+ """The host cache is unavailable; callers may fall back to uncached materialization."""
+
+
+class RemoteSkillSnapshotCache:
+ """Retain validated Skill bytes across Agent Turns without exposing them to tools."""
+
+ def __init__(self, config: Config):
+ settings = config.remote_skills
+ self.root = config.bot_data_path / "remote_skill_cache"
+ self.idle_ttl_seconds = float(settings.cache_idle_ttl_seconds)
+ self.max_entries = int(settings.cache_max_entries)
+ self.max_bytes = int(settings.cache_max_bytes)
+ self._key_locks: dict[RemoteSkillCacheKey, _KeyLockState] = {}
+ self._state_lock = asyncio.Lock()
+ self._prune_lock = asyncio.Lock()
+ self._active_entries: dict[Path, int] = {}
+
+ def entry_path(self, key: RemoteSkillCacheKey) -> Path:
+ return self.root / key.scope_digest / key.root_digest / key.revision_digest
+
+ @asynccontextmanager
+ async def acquire(
+ self,
+ *,
+ key: RemoteSkillCacheKey,
+ root_uri: str,
+ revision: str,
+ manifest_signature: str,
+ builder: SnapshotBuilder,
+ ) -> AsyncIterator[CachedSkillSnapshot]:
+ """Lease a validated cached snapshot, building it once on a cache miss."""
+ async with self._key_lock(key):
+ entry = self.entry_path(key)
+ await self._lease(entry)
+ used_successfully = False
+ try:
+ metadata = await asyncio.to_thread(
+ self._load_entry,
+ entry,
+ root_uri=root_uri,
+ revision=revision,
+ manifest_signature=manifest_signature,
+ )
+ hit = metadata is not None
+ if metadata is None:
+ if entry.exists():
+ await asyncio.to_thread(shutil.rmtree, entry, True)
+ metadata = await self._build_entry(
+ entry=entry,
+ root_uri=root_uri,
+ revision=revision,
+ manifest_signature=manifest_signature,
+ builder=builder,
+ )
+
+ yield CachedSkillSnapshot(
+ key=key,
+ path=entry / _CACHE_SNAPSHOT,
+ hit=hit,
+ total_bytes=int(metadata["total_bytes"]),
+ file_count=int(metadata["file_count"]),
+ )
+ used_successfully = True
+ finally:
+ await self._release(entry, touch=used_successfully)
+ try:
+ await self.prune()
+ except Exception as exc:
+ logger.warning("Failed to prune remote Skill cache {}: {}", self.root, exc)
+
+ async def invalidate(self, key: RemoteSkillCacheKey) -> None:
+ """Remove a corrupt or otherwise unusable cache entry."""
+ async with self._key_lock(key):
+ entry = self.entry_path(key)
+ async with self._state_lock:
+ active = self._active_entries.get(entry, 0)
+ if active:
+ return
+ await asyncio.to_thread(shutil.rmtree, entry, True)
+
+ @asynccontextmanager
+ async def _key_lock(self, key: RemoteSkillCacheKey) -> AsyncIterator[None]:
+ """Serialize one cache key and discard the lock after its last user exits."""
+ async with self._state_lock:
+ state = self._key_locks.get(key)
+ if state is None:
+ state = _KeyLockState(lock=asyncio.Lock())
+ self._key_locks[key] = state
+ state.users += 1
+ try:
+ async with state.lock:
+ yield
+ finally:
+ async with self._state_lock:
+ state.users -= 1
+ if state.users == 0 and self._key_locks.get(key) is state:
+ self._key_locks.pop(key, None)
+
+ async def prune(self) -> None:
+ """Apply idle-TTL, entry-count, and byte-size eviction to inactive entries."""
+ async with self._prune_lock:
+ if not self.root.exists():
+ return
+ async with self._state_lock:
+ active = {path for path, count in self._active_entries.items() if count > 0}
+ now = time.time()
+ entries = await asyncio.to_thread(self._scan_entries)
+
+ retained: list[tuple[Path, int, float]] = []
+ for entry, total_bytes, last_access in entries:
+ if entry not in active and now - last_access >= self.idle_ttl_seconds:
+ await asyncio.to_thread(shutil.rmtree, entry, True)
+ continue
+ retained.append((entry, total_bytes, last_access))
+
+ total = sum(item[1] for item in retained)
+ count = len(retained)
+ for entry, total_bytes, _last_access in sorted(retained, key=lambda item: item[2]):
+ if count <= self.max_entries and total <= self.max_bytes:
+ break
+ if entry in active:
+ continue
+ await asyncio.to_thread(shutil.rmtree, entry, True)
+ count -= 1
+ total -= total_bytes
+
+ await asyncio.to_thread(self._remove_empty_parents)
+
+ async def _build_entry(
+ self,
+ *,
+ entry: Path,
+ root_uri: str,
+ revision: str,
+ manifest_signature: str,
+ builder: SnapshotBuilder,
+ ) -> dict[str, Any]:
+ staging = self.root / f".partial-{uuid.uuid4().hex}"
+ snapshot = staging / _CACHE_SNAPSHOT
+ try:
+ await asyncio.to_thread(self._prepare_root)
+ await asyncio.to_thread(snapshot.mkdir, parents=True, exist_ok=False, mode=0o700)
+ result = await builder(snapshot)
+ metadata = {
+ "format_version": _CACHE_FORMAT_VERSION,
+ "root_uri": root_uri,
+ "revision": revision,
+ "manifest_signature": manifest_signature,
+ "total_bytes": int(result.total_bytes),
+ "file_count": int(result.file_count),
+ "created_at": time.time(),
+ }
+ await asyncio.to_thread(self._write_metadata, staging, metadata)
+ await asyncio.to_thread(self._make_private, staging)
+ await asyncio.to_thread(entry.parent.mkdir, parents=True, exist_ok=True, mode=0o700)
+ if entry.exists():
+ await asyncio.to_thread(shutil.rmtree, entry, True)
+ await asyncio.to_thread(os.replace, staging, entry)
+ return metadata
+ except OSError as exc:
+ await asyncio.to_thread(shutil.rmtree, staging, True)
+ raise RemoteSkillCacheError(f"Remote Skill cache is unavailable: {exc}") from exc
+ except Exception:
+ await asyncio.to_thread(shutil.rmtree, staging, True)
+ raise
+
+ async def _lease(self, entry: Path) -> None:
+ async with self._state_lock:
+ self._active_entries[entry] = self._active_entries.get(entry, 0) + 1
+
+ async def _release(self, entry: Path, *, touch: bool) -> None:
+ metadata = entry / _CACHE_METADATA
+ if touch and metadata.exists():
+ try:
+ await asyncio.to_thread(os.utime, metadata, None)
+ except OSError:
+ pass
+ async with self._state_lock:
+ remaining = self._active_entries.get(entry, 0) - 1
+ if remaining > 0:
+ self._active_entries[entry] = remaining
+ else:
+ self._active_entries.pop(entry, None)
+
+ def _prepare_root(self) -> None:
+ self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+ try:
+ self.root.chmod(0o700)
+ except OSError:
+ pass
+
+ @staticmethod
+ def _write_metadata(staging: Path, metadata: dict[str, Any]) -> None:
+ path = staging / _CACHE_METADATA
+ path.write_text(
+ json.dumps(metadata, sort_keys=True, separators=(",", ":")),
+ encoding="utf-8",
+ )
+ path.chmod(0o600)
+
+ @staticmethod
+ def _make_private(root: Path) -> None:
+ for current, directories, files in os.walk(root):
+ Path(current).chmod(0o700)
+ for directory in directories:
+ (Path(current) / directory).chmod(0o700)
+ for filename in files:
+ (Path(current) / filename).chmod(0o600)
+
+ def _load_entry(
+ self,
+ entry: Path,
+ root_uri: str,
+ revision: str,
+ manifest_signature: str,
+ ) -> dict[str, Any] | None:
+ metadata_path = entry / _CACHE_METADATA
+ snapshot_path = entry / _CACHE_SNAPSHOT
+ try:
+ metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+ except (OSError, ValueError, TypeError):
+ return None
+ if not isinstance(metadata, dict) or not snapshot_path.is_dir():
+ return None
+ expected = {
+ "format_version": _CACHE_FORMAT_VERSION,
+ "root_uri": root_uri,
+ "revision": revision,
+ "manifest_signature": manifest_signature,
+ }
+ if any(metadata.get(key) != value for key, value in expected.items()):
+ return None
+ try:
+ if int(metadata.get("total_bytes", -1)) < 0 or int(metadata.get("file_count", -1)) < 1:
+ return None
+ if time.time() - metadata_path.stat().st_mtime >= self.idle_ttl_seconds:
+ return None
+ except (OSError, TypeError, ValueError):
+ return None
+ return metadata
+
+ def _scan_entries(self) -> list[tuple[Path, int, float]]:
+ entries: list[tuple[Path, int, float]] = []
+ for metadata_path in self.root.glob(f"*/*/*/{_CACHE_METADATA}"):
+ entry = metadata_path.parent
+ try:
+ metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+ total_bytes = int(metadata.get("total_bytes", 0))
+ last_access = metadata_path.stat().st_mtime
+ except (OSError, ValueError, TypeError):
+ shutil.rmtree(entry, ignore_errors=True)
+ continue
+ entries.append((entry, max(total_bytes, 0), last_access))
+ for partial in self.root.glob(".partial-*"):
+ try:
+ if time.time() - partial.stat().st_mtime >= self.idle_ttl_seconds:
+ shutil.rmtree(partial, ignore_errors=True)
+ except OSError:
+ pass
+ return entries
+
+ def _remove_empty_parents(self) -> None:
+ if not self.root.exists():
+ return
+ for depth in (3, 2, 1):
+ pattern = "/".join("*" for _ in range(depth))
+ for path in self.root.glob(pattern):
+ if not path.is_dir() or path.name.startswith(".partial-"):
+ continue
+ try:
+ path.rmdir()
+ except OSError:
+ pass
+ try:
+ next(self.root.iterdir())
+ except StopIteration:
+ try:
+ self.root.rmdir()
+ except OSError:
+ pass
+ except OSError:
+ logger.debug("Unable to inspect remote Skill cache root {}", self.root)
diff --git a/bot/vikingbot/agent/remote_skills.py b/bot/vikingbot/agent/remote_skills.py
new file mode 100644
index 000000000..36f1a4a7a
--- /dev/null
+++ b/bot/vikingbot/agent/remote_skills.py
@@ -0,0 +1,1418 @@
+"""Request-scoped OpenViking Skill discovery, activation, and materialization."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import fnmatch
+import hashlib
+import html
+import json
+import re
+import shlex
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterable, Mapping
+
+from loguru import logger
+
+from openviking.core.namespace import classify_uri, uri_parts
+from openviking.core.skill_loader import SkillLoader
+from openviking.utils.path_safety import sanitize_relative_viking_path
+from vikingbot.agent.remote_skill_cache import (
+ RemoteSkillCacheError,
+ RemoteSkillCacheKey,
+ RemoteSkillSnapshotCache,
+ SnapshotBuildResult,
+)
+from vikingbot.openviking_mount.ov_server import VikingClient
+
+if TYPE_CHECKING:
+ from vikingbot.agent.tools.base import Tool
+ from vikingbot.config.schema import Config, RemoteSkillsConfig, SessionKey
+ from vikingbot.sandbox.manager import SandboxManager
+
+
+_SKILL_EXCLUDED_FILES = frozenset(
+ {".abstract.md", ".overview.md", ".relations.json", ".source.json"}
+)
+_EXEC_PATH_PREFIX = r"(?<![A-Za-z0-9_./-])"
+_EXEC_PATH_SUFFIX = r"(?=$|[\s\"'`;|&()<>])"
+_MATERIALIZED_SKILL_ROOT = ".remote-skill"
+_TRANSPORT_TOOLS = frozenset({"openviking_multi_read"})
+_SHELL_CONTROL_TOKENS = frozenset({";", "&", "&&", "|", "||", "<", ">", "<<", ">>"})
+_EXEC_FILE_CONSUMERS = frozenset(
+ {
+ ".",
+ "bash",
+ "cat",
+ "chmod",
+ "cp",
+ "head",
+ "node",
+ "perl",
+ "python",
+ "python3",
+ "ruby",
+ "sed",
+ "sh",
+ "source",
+ "tail",
+ }
+)
+_RESOURCE_LIKE_SUFFIXES = frozenset(
+ {
+ ".bash",
+ ".bin",
+ ".cfg",
+ ".csv",
+ ".docx",
+ ".ini",
+ ".jpeg",
+ ".jpg",
+ ".json",
+ ".md",
+ ".model",
+ ".png",
+ ".py",
+ ".sh",
+ ".sql",
+ ".svg",
+ ".toml",
+ ".tsv",
+ ".txt",
+ ".yaml",
+ ".yml",
+ }
+)
+_TOOL_ALIASES = {
+ "bash": "exec",
+ "exec": "exec",
+ "read": "read_file",
+ "read_file": "read_file",
+ "write": "write_file",
+ "write_file": "write_file",
+ "edit": "edit_file",
+ "edit_file": "edit_file",
+ "glob": "openviking_glob",
+ "grep": "openviking_grep",
+ "webfetch": "web_fetch",
+ "web_fetch": "web_fetch",
+ "websearch": "web_search",
+ "web_search": "web_search",
+ "spawn": "spawn",
+}
+
+
+class SkillRuntimeError(RuntimeError):
+ """A stable, user-facing remote Skill runtime failure."""
+
+ def __init__(self, code: str, message: str):
+ self.code = code
+ super().__init__(message)
+
+ def __str__(self) -> str:
+ return f"{self.code}: {super().__str__()}"
+
+
+class _CachedSnapshotCorrupt(RuntimeError):
+ """A host-side cache entry no longer matches its validated manifest."""
+
+
+@dataclass(frozen=True)
+class RemoteSkillCandidate:
+ name: str
+ description: str
+ root_uri: str
+ skill_md_uri: str
+ source: str
+ score: float = 0.0
+ allowed_tools: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RemoteSkillFile:
+ path: str
+ uri: str
+ is_dir: bool = False
+ kind: str = "auxiliary"
+ size: int | None = None
+ sha256: str | None = None
+ revision: str | None = None
+
+
+@dataclass
+class ActiveRemoteSkill:
+ name: str
+ description: str
+ root_uri: str
+ skill_md_uri: str
+ content: str
+ source: str
+ files: dict[str, RemoteSkillFile]
+ allowed_tools: tuple[str, ...] = ()
+ allowed_tools_declared: bool = False
+ requires: dict[str, list[str]] = field(default_factory=dict)
+ revision: str = ""
+ manifest_signature: str = ""
+
+
+@dataclass(frozen=True)
+class PreparedToolCall:
+ params: dict[str, Any]
+ skill_uris: tuple[str, ...] = ()
+
+
+def _resource_path_segments(expression: str) -> tuple[str, ...]:
+ """Parse a top-level parameter name or a JSON-Pointer-like resource path."""
+ if not expression.startswith("/"):
+ return (expression,)
+ return tuple(
+ segment.replace("~1", "/").replace("~0", "~")
+ for segment in expression.split("/")[1:]
+ if segment
+ )
+
+
+def _iter_resource_slots(
+ value: Any,
+ segments: tuple[str, ...],
+) -> Iterable[tuple[Any, str | int, Any]]:
+ """Yield mutable parent/key/value slots selected by a resource path."""
+ if not segments:
+ return
+ head, *tail = segments
+ if head == "*":
+ items: Iterable[tuple[str | int, Any]]
+ if isinstance(value, list):
+ items = enumerate(value)
+ elif isinstance(value, dict):
+ items = value.items()
+ else:
+ return
+ for key, child in items:
+ if tail:
+ yield from _iter_resource_slots(child, tuple(tail))
+ else:
+ yield value, key, child
+ return
+ if isinstance(value, dict) and head in value:
+ child = value[head]
+ if tail:
+ yield from _iter_resource_slots(child, tuple(tail))
+ else:
+ yield value, head, child
+
+
+def _normalize_uri(uri: str) -> str:
+ return str(uri or "").strip().rstrip("/")
+
+
+def _skill_identity_from_uri(uri: str) -> tuple[str, str, str, str]:
+ """Return (name, target_uri, root_uri, skill_md_uri) for one Skill definition."""
+ normalized = _normalize_uri(uri)
+ parts = uri_parts(normalized)
+ classification = classify_uri(normalized)
+ index = classification.content_index
+ if not classification.is_skill or index is None:
+ raise SkillRuntimeError(
+ "SKILL_INVALID", "Skill URI is outside an OpenViking skills namespace"
+ )
+
+ has_definition = len(parts) == index + 3 and parts[-1] == "SKILL.md"
+ has_root = len(parts) == index + 2
+ if not has_definition and not has_root:
+ raise SkillRuntimeError(
+ "SKILL_INVALID", "Skill URI must identify one Skill root or its SKILL.md"
+ )
+
+ name = parts[index + 1]
+ root_parts = parts[:-1] if has_definition else parts
+ root_uri = "viking://" + "/".join(root_parts)
+ target_uri = "viking://" + "/".join(parts[: index + 1])
+ return name, target_uri, root_uri, f"{root_uri}/SKILL.md"
+
+
+def _skill_root_for_resource_uri(uri: str) -> str | None:
+ """Return a containing Skill root for any URI inside a skills namespace."""
+ normalized = _normalize_uri(uri)
+ classification = classify_uri(normalized)
+ index = classification.content_index
+ parts = list(classification.parts)
+ if not classification.is_skill or index is None or len(parts) < index + 2:
+ return None
+ return "viking://" + "/".join(parts[: index + 2])
+
+
+def _parse_vikingbot_metadata(raw: object) -> dict[str, Any]:
+ if isinstance(raw, Mapping):
+ scoped = raw.get("vikingbot", raw)
+ return dict(scoped) if isinstance(scoped, Mapping) else {}
+ if isinstance(raw, str):
+ try:
+ return _parse_vikingbot_metadata(json.loads(raw))
+ except (json.JSONDecodeError, TypeError):
+ return {}
+ return {}
+
+
+def _normalize_requires(raw: object) -> dict[str, list[str]]:
+ if not isinstance(raw, Mapping):
+ return {"bins": [], "env": []}
+ normalized: dict[str, list[str]] = {}
+ for key in ("bins", "env"):
+ value = raw.get(key) or []
+ if isinstance(value, str):
+ value = [value]
+ normalized[key] = [str(item).strip() for item in value if str(item).strip()]
+ return normalized
+
+
+def _safe_skill_name(name: str) -> str:
+ safe = re.sub(r"[^A-Za-z0-9_.-]+", "-", name).strip(".-")
+ return safe or "remote-skill"
+
+
+def _source_for_uri(root_uri: str) -> str:
+ return (
+ "openviking_agent" if root_uri.startswith("viking://agent/skills/") else "openviking_user"
+ )
+
+
+def _manifest_signature(result: Mapping[str, Any]) -> str:
+ files = []
+ for item in result.get("files") or []:
+ if not isinstance(item, Mapping):
+ continue
+ files.append(
+ {
+ "path": item.get("path"),
+ "uri": item.get("uri"),
+ "is_dir": bool(item.get("is_dir", item.get("isDir", False))),
+ "size": item.get("size"),
+ "sha256": item.get("sha256"),
+ "revision": item.get("revision"),
+ }
+ )
+ payload = {
+ "root_uri": result.get("root_uri") or result.get("uri"),
+ "revision": result.get("revision"),
+ "content_sha256": result.get("content_sha256"),
+ "files": sorted(files, key=lambda item: str(item.get("path") or "")),
+ }
+ return hashlib.sha256(
+ json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")
+ ).hexdigest()
+
+
+class SkillRuntimeContext:
+ """State shared by all model/tool iterations in one VikingBot turn."""
+
+ def __init__(
+ self,
+ *,
+ config: "Config",
+ session_key: "SessionKey",
+ sandbox_manager: "SandboxManager | None",
+ workspace_id: str,
+ openviking_connection: dict[str, Any] | None,
+ actor_peer_id: str | None,
+ local_skill_names: Iterable[str] = (),
+ request_id: str | None = None,
+ ):
+ self.config = config
+ self.settings: RemoteSkillsConfig = config.remote_skills
+ self.session_key = session_key
+ self.sandbox_manager = sandbox_manager
+ self.workspace_id = workspace_id
+ self.openviking_connection = openviking_connection
+ self.actor_peer_id = actor_peer_id
+ self.local_skill_names = {str(name) for name in local_skill_names}
+ self.request_id = request_id or uuid.uuid4().hex
+ self.candidates: list[RemoteSkillCandidate] = []
+ self.active_skills: dict[str, ActiveRemoteSkill] = {}
+ self.materializations: dict[str, str] = {}
+ self.usage: list[dict[str, Any]] = []
+ self._client: VikingClient | None = None
+ self._activation_locks: dict[str, asyncio.Lock] = {}
+ self._materialization_locks: dict[str, asyncio.Lock] = {}
+ self._requirement_locks: dict[str, asyncio.Lock] = {}
+ self._requirements_checked: set[str] = set()
+ self._materialization_started = False
+ self._closed = False
+ cache = getattr(sandbox_manager, "remote_skill_cache", None)
+ self._snapshot_cache: RemoteSkillSnapshotCache | None = (
+ cache if isinstance(cache, RemoteSkillSnapshotCache) else None
+ )
+
+ async def _get_client(self) -> VikingClient:
+ if self._client is None:
+ self._client = await VikingClient.create(
+ self.workspace_id,
+ connection=self.openviking_connection,
+ actor_peer_id=self.actor_peer_id,
+ config=self.config,
+ )
+ return self._client
+
+ async def discover(self, query: str) -> list[RemoteSkillCandidate]:
+ """Discover only L0 Skill summaries for the current user query."""
+ if not str(query or "").strip():
+ return []
+ try:
+ client = await self._get_client()
+ result = await asyncio.wait_for(
+ client.find_skills(
+ str(query),
+ limit=self.settings.discovery_limit,
+ score_threshold=self.settings.score_threshold,
+ ),
+ timeout=self.settings.discovery_timeout_seconds,
+ )
+ except Exception as exc:
+ logger.warning("OpenViking Skill discovery skipped: {}", exc)
+ self.candidates = []
+ return []
+
+ by_name: dict[str, RemoteSkillCandidate] = {}
+ for item in result.get("skills") or []:
+ if not isinstance(item, Mapping):
+ continue
+ root_uri = _normalize_uri(str(item.get("root_uri") or item.get("uri") or ""))
+ if not root_uri:
+ continue
+ try:
+ uri_name, _target, canonical_root, skill_md_uri = _skill_identity_from_uri(root_uri)
+ except SkillRuntimeError:
+ continue
+ name = str(item.get("name") or uri_name).strip()
+ if not name or name in self.local_skill_names:
+ continue
+ candidate = RemoteSkillCandidate(
+ name=name,
+ description=str(item.get("description") or "").strip(),
+ root_uri=canonical_root,
+ skill_md_uri=skill_md_uri,
+ source=_source_for_uri(canonical_root),
+ score=float(item.get("score") or 0.0),
+ allowed_tools=tuple(str(value) for value in item.get("allowed_tools") or []),
+ )
+ current = by_name.get(name)
+ if current is None or self._candidate_precedes(candidate, current):
+ by_name[name] = candidate
+
+ self.candidates = sorted(
+ by_name.values(),
+ key=lambda candidate: (
+ 0 if candidate.source == "openviking_user" else 1,
+ -candidate.score,
+ candidate.name,
+ ),
+ )[: self.settings.discovery_limit]
+ return list(self.candidates)
+
+ @staticmethod
+ def _candidate_precedes(candidate: RemoteSkillCandidate, current: RemoteSkillCandidate) -> bool:
+ candidate_rank = 0 if candidate.source == "openviking_user" else 1
+ current_rank = 0 if current.source == "openviking_user" else 1
+ return (candidate_rank, -candidate.score) < (current_rank, -current.score)
+
+ def build_discovery_summary(self) -> str:
+ if not self.candidates:
+ return ""
+ lines = ['<skills source="openviking">']
+ for skill in self.candidates:
+ lines.extend(
+ [
+ f' <skill source="{skill.source}" available="true">',
+ f" <name>{html.escape(skill.name)}</name>",
+ f" <description>{html.escape(skill.description)}</description>",
+ f" <location>{html.escape(skill.skill_md_uri)}</location>",
+ " <read_tool>openviking_multi_read</read_tool>",
+ " </skill>",
+ ]
+ )
+ lines.append("</skills>")
+ return "\n".join(lines)
+
+ @staticmethod
+ def is_skill_definition_uri(uri: str) -> bool:
+ try:
+ _skill_identity_from_uri(uri)
+ except SkillRuntimeError:
+ return False
+ return _normalize_uri(uri).endswith("/SKILL.md")
+
+ def is_activation_call(self, tool_name: str, params: Mapping[str, Any]) -> bool:
+ if tool_name != "openviking_multi_read":
+ return False
+ return any(self.is_skill_definition_uri(str(uri)) for uri in params.get("uris") or [])
+
+ def activation_succeeded(self, params: Mapping[str, Any]) -> bool:
+ """Confirm every Skill definition requested by a multi-read became active."""
+ for uri in params.get("uris") or []:
+ if not self.is_skill_definition_uri(str(uri)):
+ continue
+ try:
+ root_uri = _skill_identity_from_uri(str(uri))[2]
+ except SkillRuntimeError:
+ return False
+ if root_uri not in self.active_skills:
+ return False
+ return True
+
+ async def activate_from_read(self, uri: str, content: str) -> ActiveRemoteSkill | None:
+ """Activate a Skill after the existing multi-read tool reads SKILL.md."""
+ if not self.is_skill_definition_uri(uri):
+ self.note_remote_read(uri)
+ return None
+
+ name, target_uri, root_uri, skill_md_uri = _skill_identity_from_uri(uri)
+ lock = self._activation_locks.setdefault(root_uri, asyncio.Lock())
+ async with lock:
+ existing = self.active_skills.get(root_uri)
+ if existing is not None:
+ return existing
+ if len(content.encode("utf-8")) > self.settings.max_file_bytes:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", "Remote SKILL.md exceeds the file limit"
+ )
+ try:
+ parsed = SkillLoader.parse(content, source_path=skill_md_uri)
+ except Exception as exc:
+ raise SkillRuntimeError("SKILL_INVALID", str(exc)) from exc
+ parsed_name = str(parsed.get("name") or "").strip()
+ if parsed_name != name:
+ raise SkillRuntimeError(
+ "SKILL_INVALID",
+ f"Skill name {parsed_name!r} does not match URI name {name!r}",
+ )
+
+ client = await self._get_client()
+ try:
+ result = await client.get_skill(
+ name,
+ target_uri=target_uri,
+ include_content=True,
+ include_files=True,
+ include_integrity=True,
+ )
+ except Exception as exc:
+ raise SkillRuntimeError("SKILL_NOT_FOUND", str(exc)) from exc
+
+ returned_root = _normalize_uri(str(result.get("root_uri") or result.get("uri") or ""))
+ if returned_root != root_uri:
+ raise SkillRuntimeError(
+ "SKILL_INVALID", "OpenViking returned a different canonical Skill root"
+ )
+
+ canonical_content = str(result.get("content") or "")
+ if not canonical_content:
+ raise SkillRuntimeError(
+ "SKILL_INTEGRITY_UNAVAILABLE",
+ "OpenViking did not return the canonical SKILL.md content",
+ )
+ if canonical_content != content:
+ raise SkillRuntimeError(
+ "SKILL_REVISION_CHANGED",
+ "Remote SKILL.md changed between read and activation",
+ )
+ content_checksum = str(result.get("content_sha256") or "").strip()
+ if not content_checksum:
+ raise SkillRuntimeError(
+ "SKILL_INTEGRITY_UNAVAILABLE",
+ "OpenViking did not return a SKILL.md content checksum",
+ )
+ if hashlib.sha256(canonical_content.encode("utf-8")).hexdigest() != content_checksum:
+ raise SkillRuntimeError(
+ "SKILL_REVISION_CHANGED",
+ "OpenViking returned inconsistent SKILL.md integrity metadata",
+ )
+ revision = str(result.get("revision") or "").strip()
+ if not revision:
+ raise SkillRuntimeError(
+ "SKILL_INTEGRITY_UNAVAILABLE",
+ "OpenViking did not return a Skill revision",
+ )
+
+ files: dict[str, RemoteSkillFile] = {}
+ for item in result.get("files") or []:
+ if not isinstance(item, Mapping):
+ continue
+ raw_path = str(item.get("path") or "")
+ if not raw_path:
+ continue
+ try:
+ path = sanitize_relative_viking_path(raw_path)
+ except ValueError as exc:
+ raise SkillRuntimeError("SKILL_INVALID", str(exc)) from exc
+ item_uri = _normalize_uri(str(item.get("uri") or ""))
+ expected_uri = f"{root_uri}/{path}"
+ if item_uri != expected_uri:
+ raise SkillRuntimeError(
+ "SKILL_INVALID",
+ f"Skill file URI does not match its canonical path: {raw_path}",
+ )
+ if path in files:
+ raise SkillRuntimeError(
+ "SKILL_INVALID", f"Skill manifest contains duplicate path: {path}"
+ )
+ is_dir = bool(item.get("is_dir", item.get("isDir", False)))
+ size = int(item["size"]) if item.get("size") is not None else None
+ checksum = str(item.get("sha256") or "") or None
+ if not is_dir and (size is None or checksum is None):
+ raise SkillRuntimeError(
+ "SKILL_INTEGRITY_UNAVAILABLE",
+ f"OpenViking did not return integrity metadata for {path}",
+ )
+ if not is_dir and (
+ size < 0 or re.fullmatch(r"[0-9a-f]{64}", checksum or "") is None
+ ):
+ raise SkillRuntimeError(
+ "SKILL_INVALID", f"Skill file has invalid integrity metadata: {path}"
+ )
+ files[path] = RemoteSkillFile(
+ path=path,
+ uri=item_uri,
+ is_dir=is_dir,
+ kind=str(item.get("kind") or "auxiliary"),
+ size=size,
+ sha256=checksum,
+ revision=str(item.get("revision") or "") or None,
+ )
+
+ definition = files.get("SKILL.md")
+ if definition is None or definition.is_dir:
+ raise SkillRuntimeError(
+ "SKILL_INVALID", "OpenViking Skill manifest is missing SKILL.md"
+ )
+ definition_bytes = canonical_content.encode("utf-8")
+ if definition.size != len(definition_bytes) or definition.sha256 != content_checksum:
+ raise SkillRuntimeError(
+ "SKILL_REVISION_CHANGED",
+ "SKILL.md content does not match its manifest integrity metadata",
+ )
+
+ metadata = _parse_vikingbot_metadata(parsed.get("metadata"))
+ active = ActiveRemoteSkill(
+ name=name,
+ description=str(parsed.get("description") or ""),
+ root_uri=root_uri,
+ skill_md_uri=skill_md_uri,
+ content=canonical_content,
+ source=_source_for_uri(root_uri),
+ files=files,
+ allowed_tools=tuple(str(value) for value in parsed.get("allowed_tools") or []),
+ allowed_tools_declared=bool(parsed.get("allowed_tools_declared")),
+ requires=_normalize_requires(metadata.get("requires")),
+ revision=revision,
+ manifest_signature=_manifest_signature(result),
+ )
+ self.active_skills[root_uri] = active
+ self.usage.append({"event": "skill.activated", "skill_uri": root_uri})
+ return active
+
+ def note_remote_read(self, uri: str) -> None:
+ normalized = _normalize_uri(uri)
+ skill = self._active_skill_for_uri(normalized)
+ if skill is not None:
+ self.usage.append(
+ {
+ "event": "skill.resource.remote_read",
+ "skill_uri": skill.root_uri,
+ "resource_uri": normalized,
+ }
+ )
+
+ def render_skill_content(self, skill: ActiveRemoteSkill) -> str:
+ """Append canonical resource bindings to the content shown to the model."""
+ resources = [
+ item
+ for item in sorted(skill.files.values(), key=lambda value: value.path)
+ if not item.is_dir
+ and item.path != "SKILL.md"
+ and Path(item.path).name not in _SKILL_EXCLUDED_FILES
+ ]
+ if not resources:
+ return skill.content
+ lines = [
+ skill.content.rstrip(),
+ "",
+ "## OpenViking resource bindings",
+ "",
+ "Packaged resources are managed by VikingBot. Do not recreate, copy, or write "
+ "them into the workspace, and do not set `working_dir` to an OpenViking storage "
+ "or materialization path. Pass the exact relative path below (or its canonical "
+ "URI) directly to the consuming tool; VikingBot materializes and rewrites it "
+ "automatically. Use `workspace:<relative-path>` or an absolute path only for an "
+ "ordinary workspace file.",
+ ]
+ lines.extend(f"- `{item.path}` → `{item.uri}`" for item in resources)
+ return "\n".join(lines) + "\n"
+
+ @staticmethod
+ def _tool_specs(skill: ActiveRemoteSkill, tool_name: str) -> list[str]:
+ if not skill.allowed_tools_declared:
+ return [tool_name]
+ matched: list[str] = []
+ for spec in skill.allowed_tools:
+ head = str(spec).split("(", 1)[0].strip()
+ normalized = _TOOL_ALIASES.get(head.lower(), head)
+ if normalized == tool_name:
+ matched.append(str(spec).strip())
+ return matched
+
+ def allows_tool(self, tool_name: str) -> bool:
+ """Return whether every active Skill allows this task tool."""
+ if tool_name in _TRANSPORT_TOOLS or not self.active_skills:
+ return True
+ return all(self._tool_specs(skill, tool_name) for skill in self.active_skills.values())
+
+ def prepare_tool_definition(self, tool: "Tool") -> dict[str, Any] | None:
+ """Apply the conservative intersection of all active Skill policies."""
+ schema = copy.deepcopy(tool.to_schema())
+ if tool.name in _TRANSPORT_TOOLS or not self.active_skills:
+ return schema
+ if not self.allows_tool(tool.name):
+ return None
+ return schema
+
+ @staticmethod
+ def tool_params_for_validation(params: Mapping[str, Any]) -> dict[str, Any]:
+ """Return a detached copy for native tool validation."""
+ return copy.deepcopy(dict(params))
+
+ async def prepare_tool_call(
+ self,
+ tool: "Tool",
+ params: Mapping[str, Any],
+ ) -> PreparedToolCall:
+ effective = copy.deepcopy(dict(params))
+ used: list[str] = []
+
+ # Text resources stay remote. Resolve relative references such as
+ # ``references/checklist.md`` to their canonical OpenViking URI before
+ # handing the call to the existing multi-read transport.
+ if tool.name == "openviking_multi_read" and isinstance(effective.get("uris"), list):
+ resolved_uris: list[Any] = []
+ for value in effective["uris"]:
+ if not isinstance(value, str):
+ resolved_uris.append(value)
+ continue
+ if value.startswith("viking://"):
+ if self.is_skill_definition_uri(value):
+ resolved_uris.append(value)
+ continue
+ skill_root = _skill_root_for_resource_uri(value)
+ if skill_root is None:
+ resolved_uris.append(value)
+ continue
+ skill = self.active_skills.get(skill_root)
+ if skill is None:
+ raise SkillRuntimeError(
+ "SKILL_NOT_ACTIVE",
+ f"Read {skill_root}/SKILL.md before accessing its resources",
+ )
+ match = self._resolve_active_resource(value, skill=skill)
+ else:
+ match = self._resolve_active_resource(value, require_match=True)
+ if match is None: # pragma: no cover - require_match is fail-closed
+ resolved_uris.append(value)
+ continue
+ skill, resource = match
+ resolved_uris.append(resource.uri)
+ used.append(skill.root_uri)
+ effective["uris"] = resolved_uris
+
+ policy_skills = [] if tool.name in _TRANSPORT_TOOLS else list(self.active_skills.values())
+ for policy_skill in policy_skills:
+ if not self._tool_specs(policy_skill, tool.name):
+ raise SkillRuntimeError(
+ "SKILL_TOOL_NOT_ALLOWED",
+ f"Tool {tool.name!r} is not allowed by {policy_skill.root_uri}",
+ )
+ self._authorize_tool_arguments(policy_skill, tool.name, effective)
+ await self._ensure_requirements(policy_skill)
+ used.append(policy_skill.root_uri)
+
+ resource_inputs = getattr(tool, "resource_inputs", {}) or {}
+ for expression, resource_kind in resource_inputs.items():
+ if resource_kind not in {"local_file", "local_directory"}:
+ continue
+ for parent, key, value in _iter_resource_slots(
+ effective, _resource_path_segments(expression)
+ ):
+ if not isinstance(value, str):
+ continue
+ resolved = await self._resolve_local_resource(
+ value,
+ resource_kind=resource_kind,
+ )
+ if resolved is not None:
+ local_path, skill_uri = resolved
+ parent[key] = local_path
+ if skill_uri:
+ used.append(skill_uri)
+
+ if tool.name == "exec" and isinstance(effective.get("command"), str):
+ command, exec_skill_uris = await self._rewrite_exec_command(effective["command"])
+ effective["command"] = command
+ used.extend(exec_skill_uris)
+
+ return PreparedToolCall(
+ params=effective,
+ skill_uris=tuple(dict.fromkeys(used)),
+ )
+
+ def _authorize_tool_arguments(
+ self,
+ skill: ActiveRemoteSkill,
+ tool_name: str,
+ params: Mapping[str, Any],
+ ) -> None:
+ specs = self._tool_specs(skill, tool_name)
+ if not skill.allowed_tools_declared or any("(" not in spec for spec in specs):
+ return
+ constrained = [spec for spec in specs if "(" in spec and spec.endswith(")")]
+ if tool_name != "exec":
+ raise SkillRuntimeError(
+ "SKILL_TOOL_NOT_ALLOWED",
+ f"Argument constraints for {tool_name!r} are not supported",
+ )
+ command = str(params.get("command") or "").strip()
+ self._reject_compound_shell_command(command, skill.root_uri)
+ patterns: list[str] = []
+ for spec in constrained:
+ body = spec.split("(", 1)[1][:-1]
+ patterns.extend(part.strip() for part in body.split("|") if part.strip())
+ for pattern in patterns:
+ variants = [pattern]
+ if ":" in pattern:
+ variants.append(pattern.replace(":", " ", 1))
+ if any(fnmatch.fnmatchcase(command, variant) for variant in variants):
+ return
+ raise SkillRuntimeError(
+ "SKILL_TOOL_NOT_ALLOWED",
+ f"Command is outside the Bash constraints declared by {skill.root_uri}",
+ )
+
+ @staticmethod
+ def _reject_compound_shell_command(command: str, skill_uri: str) -> None:
+ """Keep constrained Bash rules scoped to one simple shell command."""
+ if "\n" in command or "\r" in command or "`" in command or "$(" in command:
+ raise SkillRuntimeError(
+ "SKILL_TOOL_NOT_ALLOWED",
+ f"Compound shell syntax is outside the Bash constraints declared by {skill_uri}",
+ )
+ try:
+ lexer = shlex.shlex(command, posix=True, punctuation_chars=";&|<>")
+ lexer.whitespace_split = True
+ tokens = list(lexer)
+ except ValueError as exc:
+ raise SkillRuntimeError("SKILL_TOOL_NOT_ALLOWED", str(exc)) from exc
+ if any(token in _SHELL_CONTROL_TOKENS or set(token) <= set(";&|<>") for token in tokens):
+ raise SkillRuntimeError(
+ "SKILL_TOOL_NOT_ALLOWED",
+ f"Compound shell syntax is outside the Bash constraints declared by {skill_uri}",
+ )
+
+ async def _ensure_requirements(self, skill: ActiveRemoteSkill) -> None:
+ if skill.root_uri in self._requirements_checked:
+ return
+ lock = self._requirement_locks.setdefault(skill.root_uri, asyncio.Lock())
+ async with lock:
+ if skill.root_uri in self._requirements_checked:
+ return
+ if skill.requires.get("bins") or skill.requires.get("env"):
+ if self.sandbox_manager is None:
+ raise SkillRuntimeError(
+ "SKILL_CAPABILITY_UNAVAILABLE",
+ "Remote Skill requirements need an execution sandbox",
+ )
+ sandbox = await self.sandbox_manager.get_sandbox(self.session_key)
+ await self._check_requirements(skill, sandbox)
+ self._requirements_checked.add(skill.root_uri)
+
+ def skill_uris_for_tool(
+ self,
+ tool_name: str,
+ params: Mapping[str, Any],
+ prepared: Iterable[str] = (),
+ ) -> tuple[str, ...]:
+ used = list(prepared)
+ if tool_name == "openviking_multi_read":
+ for uri in params.get("uris") or []:
+ skill = self._active_skill_for_uri(str(uri))
+ if skill is not None:
+ used.append(skill.root_uri)
+ resolved = tuple(dict.fromkeys(used))
+ for skill_uri in resolved:
+ self.usage.append(
+ {
+ "event": "skill.tool.used",
+ "skill_uri": skill_uri,
+ "tool_name": tool_name,
+ }
+ )
+ logger.info(
+ "Remote Skill tool usage: request_id={} skill_uri={} tool_name={}",
+ self.request_id,
+ skill_uri,
+ tool_name,
+ )
+ return resolved
+
+ async def _resolve_local_resource(
+ self,
+ value: str,
+ *,
+ resource_kind: str,
+ ) -> tuple[str, str | None] | None:
+ normalized = str(value or "").strip()
+ if not normalized:
+ return None
+ if normalized.startswith(("http://", "https://", "data:")):
+ return None
+ if normalized.startswith("workspace:"):
+ try:
+ workspace_path = sanitize_relative_viking_path(normalized[len("workspace:") :])
+ except ValueError as exc:
+ raise SkillRuntimeError("SKILL_RESOURCE_NOT_FOUND", str(exc)) from exc
+ return workspace_path, None
+ if not normalized.startswith("viking://") and Path(normalized).is_absolute():
+ return None
+ if not self.active_skills and not normalized.startswith("viking://"):
+ return None
+ match = self._resolve_active_resource(
+ normalized,
+ allow_directory=resource_kind == "local_directory",
+ require_match=bool(self.active_skills) or normalized.startswith("viking://"),
+ )
+ if match is None:
+ return None
+ matched_skill, resource = match
+ root = await self.materialize(matched_skill)
+ return f"{root}/{resource.path}", matched_skill.root_uri
+
+ def _resolve_active_resource(
+ self,
+ value: str,
+ *,
+ skill: ActiveRemoteSkill | None = None,
+ allow_directory: bool = False,
+ require_match: bool = False,
+ ) -> tuple[ActiveRemoteSkill, RemoteSkillFile] | None:
+ normalized_value = str(value or "").strip()
+ if not normalized_value:
+ return None
+ skills = [skill] if skill is not None else list(self.active_skills.values())
+ if normalized_value.startswith("viking://"):
+ uri = _normalize_uri(normalized_value)
+ containing_root = _skill_root_for_resource_uri(uri)
+ if containing_root is None:
+ return None
+ containing_skill = self.active_skills.get(containing_root)
+ if containing_skill is None:
+ raise SkillRuntimeError(
+ "SKILL_NOT_ACTIVE",
+ f"Read {containing_root}/SKILL.md before accessing its resources",
+ )
+ if skill is not None and containing_skill.root_uri != skill.root_uri:
+ raise SkillRuntimeError(
+ "SKILL_RESOURCE_NOT_FOUND",
+ f"Resource {value!r} does not belong to {skill.root_uri}",
+ )
+ skills = [containing_skill]
+ matches = [
+ (candidate, item)
+ for candidate in skills
+ for item in candidate.files.values()
+ if item.uri == uri
+ ]
+ else:
+ try:
+ relative = sanitize_relative_viking_path(normalized_value.removeprefix("./"))
+ except ValueError as exc:
+ raise SkillRuntimeError("SKILL_RESOURCE_NOT_FOUND", str(exc)) from exc
+ matches = [
+ (candidate, candidate.files[relative])
+ for candidate in skills
+ if relative in candidate.files
+ ]
+ if not allow_directory:
+ matches = [(candidate, item) for candidate, item in matches if not item.is_dir]
+ if len(matches) > 1:
+ raise SkillRuntimeError(
+ "SKILL_RESOURCE_AMBIGUOUS",
+ f"Resource {value!r} exists in multiple active Skills; use its canonical URI",
+ )
+ if not matches and require_match:
+ raise SkillRuntimeError(
+ "SKILL_RESOURCE_NOT_FOUND",
+ f"Resource {value!r} is not present in the active Skill manifest",
+ )
+ return matches[0] if matches else None
+
+ async def _rewrite_exec_command(
+ self,
+ command: str,
+ ) -> tuple[str, tuple[str, ...]]:
+ if not self.active_skills:
+ return command, ()
+ rewritten = command
+ used: list[str] = []
+ candidates: dict[str, list[tuple[ActiveRemoteSkill, RemoteSkillFile]]] = {}
+ for active_skill in self.active_skills.values():
+ for item in active_skill.files.values():
+ if (
+ item.is_dir
+ or item.path == "SKILL.md"
+ or Path(item.path).name in _SKILL_EXCLUDED_FILES
+ ):
+ continue
+ candidates.setdefault(item.path, []).append((active_skill, item))
+
+ for uri in re.findall(r"viking://[^\s\"'`;|&()<>]+", command):
+ if _skill_root_for_resource_uri(uri) is not None:
+ self._resolve_active_resource(uri, require_match=True)
+
+ workspace_paths: set[str] = set()
+ workspace_pattern = re.compile(r"workspace:([^\s\"'`;|&()<>]+)")
+ for workspace_match in list(workspace_pattern.finditer(rewritten)):
+ try:
+ workspace_path = sanitize_relative_viking_path(workspace_match.group(1))
+ except ValueError as exc:
+ raise SkillRuntimeError("SKILL_RESOURCE_NOT_FOUND", str(exc)) from exc
+ workspace_paths.add(workspace_path)
+ rewritten = workspace_pattern.sub(lambda match: match.group(1), rewritten)
+
+ try:
+ tokens = shlex.split(rewritten)
+ except ValueError:
+ tokens = []
+ known_paths = set(candidates)
+ command_name = Path(tokens[0]).name if tokens else ""
+ for index, token in enumerate(tokens):
+ explicit_relative = token.startswith("./")
+ relative = token.removeprefix("./").rstrip(";,|&")
+ if not relative or relative in workspace_paths:
+ continue
+ if relative.startswith(("/", "http://", "https://", "viking://", "-")):
+ continue
+ if relative in known_paths:
+ continue
+ suffix = Path(relative).suffix.lower()
+ file_consumer_arg = command_name in _EXEC_FILE_CONSUMERS and index == 1
+ if (
+ explicit_relative
+ or "/" in relative
+ or suffix in _RESOURCE_LIKE_SUFFIXES
+ or file_consumer_arg
+ ):
+ raise SkillRuntimeError(
+ "SKILL_RESOURCE_NOT_FOUND",
+ f"Command resource {relative!r} is not present in the active Skill manifests; "
+ "use workspace:<path> for an ordinary workspace file",
+ )
+
+ for path in sorted(candidates, key=len, reverse=True):
+ for matched_skill, item in candidates[path]:
+ uri_pattern = re.compile(
+ _EXEC_PATH_PREFIX + re.escape(item.uri) + _EXEC_PATH_SUFFIX
+ )
+ if not uri_pattern.search(rewritten):
+ continue
+ local_root = await self.materialize(matched_skill)
+ rewritten = uri_pattern.sub(f"{local_root}/{item.path}", rewritten)
+ used.append(matched_skill.root_uri)
+
+ for path in sorted(candidates, key=len, reverse=True):
+ pattern = re.compile(
+ _EXEC_PATH_PREFIX + r"(?:\./)?" + re.escape(path) + _EXEC_PATH_SUFFIX
+ )
+ path_match = pattern.search(rewritten)
+ if not path_match:
+ continue
+ if len(candidates[path]) > 1:
+ raise SkillRuntimeError(
+ "SKILL_RESOURCE_AMBIGUOUS",
+ f"Command resource {path!r} exists in multiple active Skills; use its canonical URI",
+ )
+ matched_skill, item = candidates[path][0]
+ local_root = await self.materialize(matched_skill)
+ replacement = f"{local_root}/{item.path}"
+ rewritten = pattern.sub(replacement, rewritten)
+ used.append(matched_skill.root_uri)
+ return rewritten, tuple(dict.fromkeys(used))
+
+ async def materialize(self, skill: ActiveRemoteSkill) -> str:
+ existing = self.materializations.get(skill.root_uri)
+ if existing is not None:
+ return existing
+ if self.sandbox_manager is None:
+ raise SkillRuntimeError(
+ "SKILL_CAPABILITY_UNAVAILABLE", "Remote Skill files require a sandbox manager"
+ )
+
+ lock = self._materialization_locks.setdefault(skill.root_uri, asyncio.Lock())
+ async with lock:
+ existing = self.materializations.get(skill.root_uri)
+ if existing is not None:
+ return existing
+ sandbox = await self.sandbox_manager.get_sandbox(self.session_key)
+ self._materialization_started = True
+ await self._ensure_requirements(skill)
+ root = self._materialized_root(skill)
+ files = [
+ item
+ for item in skill.files.values()
+ if not item.is_dir
+ and item.path != "SKILL.md"
+ and Path(item.path).name not in _SKILL_EXCLUDED_FILES
+ ]
+ if len(files) + 1 > self.settings.max_files:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", "Remote Skill file count exceeds the limit"
+ )
+
+ definition = skill.content.encode("utf-8")
+ if len(definition) > self.settings.max_file_bytes:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", "Remote SKILL.md exceeds the file limit"
+ )
+ oversized = [
+ item.path
+ for item in files
+ if item.size is not None and item.size > self.settings.max_file_bytes
+ ]
+ if oversized:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE",
+ f"Remote Skill file exceeds the limit: {oversized[0]}",
+ )
+ declared_total = len(definition) + sum(item.size or 0 for item in files)
+ if declared_total > self.settings.max_total_bytes:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", "Remote Skill bundle exceeds the limit"
+ )
+
+ if self._snapshot_cache is None:
+ total = await self._materialize_uncached(
+ sandbox=sandbox,
+ root=root,
+ skill=skill,
+ files=files,
+ definition=definition,
+ )
+ cache_status = "disabled"
+ else:
+ try:
+ total, cache_status = await self._materialize_from_cache(
+ sandbox=sandbox,
+ root=root,
+ skill=skill,
+ files=files,
+ definition=definition,
+ )
+ except RemoteSkillCacheError as exc:
+ logger.warning("Remote Skill cache bypassed for {}: {}", skill.root_uri, exc)
+ total = await self._materialize_uncached(
+ sandbox=sandbox,
+ root=root,
+ skill=skill,
+ files=files,
+ definition=definition,
+ )
+ cache_status = "bypassed"
+
+ self.materializations[skill.root_uri] = root
+ self.usage.append(
+ {
+ "event": "skill.materialize.completed",
+ "skill_uri": skill.root_uri,
+ "path": root,
+ "bytes": total,
+ "cache": cache_status,
+ }
+ )
+ logger.info(
+ "Remote Skill materialized: request_id={} skill_uri={} bytes={} cache={}",
+ self.request_id,
+ skill.root_uri,
+ total,
+ cache_status,
+ )
+ return root
+
+ async def _materialize_uncached(
+ self,
+ *,
+ sandbox: Any,
+ root: str,
+ skill: ActiveRemoteSkill,
+ files: list[RemoteSkillFile],
+ definition: bytes,
+ ) -> int:
+ total = len(definition)
+ try:
+ await sandbox.write_file_bytes(f"{root}/SKILL.md", definition)
+ client = await self._get_client()
+ for item in files:
+ data = await client.download_bytes(item.uri)
+ self._validate_downloaded_file(item, data)
+ total += len(data)
+ if total > self.settings.max_total_bytes:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", "Remote Skill bundle exceeds the limit"
+ )
+ await sandbox.write_file_bytes(f"{root}/{item.path}", data)
+ await self._ensure_manifest_current(skill, client)
+ return total
+ except Exception:
+ try:
+ await sandbox.remove_tree(root)
+ except Exception as cleanup_exc:
+ logger.warning(
+ "Failed to clean incomplete remote Skill snapshot {}: {}",
+ root,
+ cleanup_exc,
+ )
+ raise
+
+ async def _materialize_from_cache(
+ self,
+ *,
+ sandbox: Any,
+ root: str,
+ skill: ActiveRemoteSkill,
+ files: list[RemoteSkillFile],
+ definition: bytes,
+ ) -> tuple[int, str]:
+ cache = self._snapshot_cache
+ if cache is None: # pragma: no cover - guarded by caller
+ raise RuntimeError("Remote Skill snapshot cache is unavailable")
+ key = self._cache_key(skill)
+
+ async def build(snapshot_path: Path) -> SnapshotBuildResult:
+ total = len(definition)
+ await asyncio.to_thread(
+ self._write_private_cache_file, snapshot_path / "SKILL.md", definition
+ )
+ client = await self._get_client()
+ for item in files:
+ data = await client.download_bytes(item.uri)
+ self._validate_downloaded_file(item, data)
+ total += len(data)
+ if total > self.settings.max_total_bytes:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", "Remote Skill bundle exceeds the limit"
+ )
+ await asyncio.to_thread(
+ self._write_private_cache_file,
+ snapshot_path / item.path,
+ data,
+ )
+ await self._ensure_manifest_current(skill, client)
+ return SnapshotBuildResult(total_bytes=total, file_count=len(files) + 1)
+
+ for attempt in range(2):
+ corrupt = False
+ try:
+ async with cache.acquire(
+ key=key,
+ root_uri=skill.root_uri,
+ revision=skill.revision,
+ manifest_signature=skill.manifest_signature,
+ builder=build,
+ ) as snapshot:
+ if snapshot.hit:
+ await self._ensure_manifest_current(skill)
+ total = await self._copy_cached_snapshot_to_sandbox(
+ snapshot_path=snapshot.path,
+ sandbox=sandbox,
+ root=root,
+ files=files,
+ definition=definition,
+ )
+ return total, "hit" if snapshot.hit else "miss"
+ except _CachedSnapshotCorrupt:
+ corrupt = True
+ except Exception:
+ try:
+ await sandbox.remove_tree(root)
+ except Exception as cleanup_exc:
+ logger.warning(
+ "Failed to clean incomplete remote Skill snapshot {}: {}",
+ root,
+ cleanup_exc,
+ )
+ raise
+ finally:
+ if corrupt:
+ try:
+ await sandbox.remove_tree(root)
+ except Exception as cleanup_exc:
+ logger.warning(
+ "Failed to clean corrupt remote Skill request snapshot {}: {}",
+ root,
+ cleanup_exc,
+ )
+
+ await cache.invalidate(key)
+ if attempt == 0:
+ logger.warning("Discarded corrupt remote Skill cache entry for {}", skill.root_uri)
+ continue
+ raise SkillRuntimeError(
+ "SKILL_CACHE_CORRUPT", "Remote Skill cache remained corrupt after rebuilding"
+ )
+ raise AssertionError("unreachable")
+
+ async def _copy_cached_snapshot_to_sandbox(
+ self,
+ *,
+ snapshot_path: Path,
+ sandbox: Any,
+ root: str,
+ files: list[RemoteSkillFile],
+ definition: bytes,
+ ) -> int:
+ expected: list[tuple[str, int, str]] = [
+ ("SKILL.md", len(definition), hashlib.sha256(definition).hexdigest())
+ ]
+ expected.extend((item.path, int(item.size or 0), str(item.sha256 or "")) for item in files)
+ total = 0
+ for relative_path, expected_size, expected_sha256 in expected:
+ try:
+ data = await asyncio.to_thread((snapshot_path / relative_path).read_bytes)
+ except OSError as exc:
+ raise _CachedSnapshotCorrupt(relative_path) from exc
+ if len(data) != expected_size or hashlib.sha256(data).hexdigest() != expected_sha256:
+ raise _CachedSnapshotCorrupt(relative_path)
+ total += len(data)
+ if total > self.settings.max_total_bytes:
+ raise _CachedSnapshotCorrupt(relative_path)
+ await sandbox.write_file_bytes(f"{root}/{relative_path}", data)
+ return total
+
+ async def _ensure_manifest_current(
+ self,
+ skill: ActiveRemoteSkill,
+ client: VikingClient | None = None,
+ ) -> None:
+ client = client or await self._get_client()
+ latest = await client.get_skill(
+ skill.name,
+ target_uri=_skill_identity_from_uri(skill.root_uri)[1],
+ include_content=True,
+ include_files=True,
+ include_integrity=True,
+ )
+ if _manifest_signature(latest) != skill.manifest_signature:
+ raise SkillRuntimeError(
+ "SKILL_REVISION_CHANGED", "Remote Skill changed while it was materialized"
+ )
+
+ def _validate_downloaded_file(self, item: RemoteSkillFile, data: bytes) -> None:
+ if len(data) > self.settings.max_file_bytes:
+ raise SkillRuntimeError(
+ "SKILL_PACKAGE_TOO_LARGE", f"Remote Skill file too large: {item.path}"
+ )
+ if item.size is not None and len(data) != item.size:
+ raise SkillRuntimeError(
+ "SKILL_REVISION_CHANGED", f"Remote Skill file size changed: {item.path}"
+ )
+ if item.sha256 and hashlib.sha256(data).hexdigest() != item.sha256:
+ raise SkillRuntimeError(
+ "SKILL_REVISION_CHANGED", f"Remote Skill checksum changed: {item.path}"
+ )
+
+ def _cache_key(self, skill: ActiveRemoteSkill) -> RemoteSkillCacheKey:
+ connection = dict(self.openviking_connection or {})
+ api_key = str(connection.pop("api_key", "") or "")
+ stable_identity = bool(connection.get("user_id"))
+ if api_key and not stable_identity:
+ connection["api_key_sha256"] = hashlib.sha256(api_key.encode("utf-8")).hexdigest()
+ scope_payload = {
+ "workspace_id": self.workspace_id,
+ "actor_peer_id": self.actor_peer_id,
+ "server_url": connection.get("server_url")
+ or str(getattr(self.config.ov_server, "server_url", "") or ""),
+ "connection": connection,
+ }
+ encoded_scope = json.dumps(
+ scope_payload,
+ sort_keys=True,
+ separators=(",", ":"),
+ ensure_ascii=False,
+ default=str,
+ ).encode("utf-8")
+ return RemoteSkillCacheKey(
+ scope_digest=hashlib.sha256(encoded_scope).hexdigest(),
+ root_digest=hashlib.sha256(skill.root_uri.encode("utf-8")).hexdigest(),
+ revision_digest=hashlib.sha256(skill.revision.encode("utf-8")).hexdigest(),
+ )
+
+ @staticmethod
+ def _write_private_cache_file(path: Path, data: bytes) -> None:
+ try:
+ path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+ path.write_bytes(data)
+ path.chmod(0o600)
+ except OSError as exc:
+ raise RemoteSkillCacheError(f"Remote Skill cache write failed: {exc}") from exc
+
+ async def _check_requirements(self, skill: ActiveRemoteSkill, sandbox: Any) -> None:
+ """Check declared capabilities in the sandbox that will execute the Skill."""
+ checks: list[tuple[str, str]] = []
+ for binary in skill.requires.get("bins", []):
+ checks.append((f"bin:{binary}", f"command -v -- {shlex.quote(binary)} >/dev/null 2>&1"))
+ for variable in skill.requires.get("env", []):
+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", variable):
+ raise SkillRuntimeError(
+ "SKILL_INVALID", f"Invalid environment requirement name: {variable!r}"
+ )
+ checks.append((f"env:{variable}", f'test "${{{variable}+x}}" = x'))
+ if not checks:
+ return
+ marker = "__VIKINGBOT_SKILL_REQUIREMENTS_OK__"
+ missing: list[str] = []
+ for label, check in checks:
+ output = await sandbox.execute(f"{check} && printf {marker}", timeout=10)
+ if marker not in str(output):
+ missing.append(label)
+ if missing:
+ raise SkillRuntimeError(
+ "SKILL_CAPABILITY_UNAVAILABLE",
+ f"Execution sandbox is missing declared requirements: {missing}",
+ )
+
+ def _materialized_root(self, skill: ActiveRemoteSkill) -> str:
+ digest = hashlib.sha256(skill.root_uri.encode("utf-8")).hexdigest()
+ return (
+ f"{_MATERIALIZED_SKILL_ROOT}/{self.request_id}/{digest}/{_safe_skill_name(skill.name)}"
+ )
+
+ async def close(self) -> None:
+ if self._closed:
+ return
+ self._closed = True
+ if self.sandbox_manager is not None and self._materialization_started:
+ try:
+ sandbox = await self.sandbox_manager.get_sandbox(self.session_key)
+ await sandbox.remove_tree(f"{_MATERIALIZED_SKILL_ROOT}/{self.request_id}")
+ except Exception as exc:
+ logger.warning("Failed to clean remote Skill snapshot: {}", exc)
+ if self._client is not None:
+ try:
+ await self._client.close()
+ except Exception as exc:
+ logger.warning("Failed to close remote Skill OpenViking client: {}", exc)
+ self._client = None
+
+ def _active_skill_for_uri(self, uri: str) -> ActiveRemoteSkill | None:
+ normalized = _normalize_uri(uri)
+ for skill in self.active_skills.values():
+ if normalized == skill.root_uri or normalized.startswith(skill.root_uri + "/"):
+ return skill
+ return None
diff --git a/bot/vikingbot/agent/tools/base.py b/bot/vikingbot/agent/tools/base.py
index 7358ee344..36a47a8a0 100644
--- a/bot/vikingbot/agent/tools/base.py
+++ b/bot/vikingbot/agent/tools/base.py
@@ -45,7 +45,7 @@ class ToolContext:
session_key: SessionKey = None
sandbox_manager: SandboxManager | None = None
- workspace_id: str = sandbox_manager.to_workspace_id(session_key) if sandbox_manager else None
+ workspace_id: str | None = None
sender_id: str | None = None
actor_peer_id: str | None = None
memory_peer_ids: list[str] | None = None
@@ -53,6 +53,7 @@ class ToolContext:
memory_user_ids: list[str] | None = None # Deprecated alias for memory_owner_user_ids.
openviking_connection: dict[str, Any] | None = None
channel_metadata: dict[str, Any] | None = None
+ skill_runtime: Any | None = None
def __post_init__(self) -> None:
if self.memory_owner_user_ids is None and self.memory_user_ids is not None:
@@ -61,6 +62,13 @@ class ToolContext:
self.memory_user_ids = self.memory_owner_user_ids
if self.channel_metadata is None:
self.channel_metadata = {}
+ if (
+ self.workspace_id is None
+ and self.sandbox_manager is not None
+ and self.session_key
+ and hasattr(self.sandbox_manager, "to_workspace_id")
+ ):
+ self.workspace_id = self.sandbox_manager.to_workspace_id(self.session_key)
class Tool(ABC):
@@ -133,6 +141,16 @@ class Tool(ABC):
"""JSON Schema for tool parameters."""
pass
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ """Parameters that consume a local file or directory.
+
+ The remote Skill runtime only rewrites explicitly declared parameters;
+ it never guesses from parameter names. Keys may be top-level parameter
+ names or JSON-Pointer-like paths with ``*`` list/dict wildcards.
+ """
+ return {}
+
@abstractmethod
async def execute(self, tool_context: ToolContext, **kwargs: Any) -> str:
"""
diff --git a/bot/vikingbot/agent/tools/compile.py b/bot/vikingbot/agent/tools/compile.py
index f9930b1fc..de8123cef 100644
--- a/bot/vikingbot/agent/tools/compile.py
+++ b/bot/vikingbot/agent/tools/compile.py
@@ -286,6 +286,13 @@ class SubmitWikiBundleTool(Tool):
schema.pop("title", None)
return schema
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ return {
+ "/files/*/workspace_path": "local_file",
+ "/pages/*/body_workspace_path": "local_file",
+ }
+
async def execute(
self,
tool_context: ToolContext,
diff --git a/bot/vikingbot/agent/tools/filesystem.py b/bot/vikingbot/agent/tools/filesystem.py
index 492b5fabb..02ae7c87e 100644
--- a/bot/vikingbot/agent/tools/filesystem.py
+++ b/bot/vikingbot/agent/tools/filesystem.py
@@ -27,6 +27,10 @@ class ReadFileTool(Tool):
"required": ["path"],
}
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ return {"path": "local_file"}
+
async def execute(self, tool_context: "ToolContext", path: str, **kwargs: Any) -> str:
try:
sandbox = await tool_context.sandbox_manager.get_sandbox(tool_context.session_key)
@@ -98,6 +102,10 @@ class EditFileTool(Tool):
"required": ["path", "old_text", "new_text"],
}
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ return {"path": "local_file"}
+
async def execute(
self, tool_context: "ToolContext", path: str, old_text: str, new_text: str, **kwargs: Any
) -> str:
@@ -143,6 +151,10 @@ class ListDirTool(Tool):
"required": ["path"],
}
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ return {"path": "local_directory"}
+
async def execute(self, tool_context: "ToolContext", path: str, **kwargs: Any) -> str:
try:
sandbox = await tool_context.sandbox_manager.get_sandbox(tool_context.session_key)
diff --git a/bot/vikingbot/agent/tools/image.py b/bot/vikingbot/agent/tools/image.py
index 031eb3fc2..51b49b1a9 100644
--- a/bot/vikingbot/agent/tools/image.py
+++ b/bot/vikingbot/agent/tools/image.py
@@ -83,6 +83,10 @@ class ImageGenerationTool(Tool):
"required": [],
}
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ return {"base_image": "local_file", "mask": "local_file"}
+
def __init__(
self,
gen_image_model: str | None = None,
diff --git a/bot/vikingbot/agent/tools/ov_file.py b/bot/vikingbot/agent/tools/ov_file.py
index 8acda7762..8f5078bfe 100644
--- a/bot/vikingbot/agent/tools/ov_file.py
+++ b/bot/vikingbot/agent/tools/ov_file.py
@@ -3,6 +3,7 @@
import asyncio
import itertools
import json
+import tempfile
import time
from abc import ABC
from pathlib import Path
@@ -522,6 +523,10 @@ class VikingAddResourceTool(OVFileTool):
"required": ["path", "description"],
}
+ @property
+ def resource_inputs(self) -> dict[str, str]:
+ return {"path": "local_file"}
+
async def execute(
self,
tool_context: "ToolContext",
@@ -531,16 +536,32 @@ class VikingAddResourceTool(OVFileTool):
**kwargs: Any,
) -> str:
client = None
+ temp_dir: tempfile.TemporaryDirectory[str] | None = None
try:
+ upload_path = path
if path and not path.startswith("http"):
- 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}"
+ 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(path, description, to=to)
+ result = await client.add_resource(upload_path, description, to=to)
if result:
root_uri = result.get("root_uri", "")
@@ -554,6 +575,8 @@ class VikingAddResourceTool(OVFileTool):
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):
@@ -921,6 +944,11 @@ class VikingMultiReadTool(OVFileTool):
async with semaphore:
try:
content = await client.read_content(uri, level=level)
+ 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,
diff --git a/bot/vikingbot/agent/tools/registry.py b/bot/vikingbot/agent/tools/registry.py
index 1180573ce..395495bdf 100644
--- a/bot/vikingbot/agent/tools/registry.py
+++ b/bot/vikingbot/agent/tools/registry.py
@@ -1,10 +1,13 @@
"""Tool registry for dynamic tool management."""
+import json
import time
+from dataclasses import dataclass
from typing import Any
from loguru import logger
+from vikingbot.agent.remote_skills import SkillRuntimeError
from vikingbot.agent.tools.base import Tool, ToolContext
from vikingbot.config.schema import SessionKey
from vikingbot.hooks import HookContext
@@ -14,6 +17,15 @@ from vikingbot.sandbox.manager import SandboxManager
from vikingbot.utils.tracing import get_current_response_id
+@dataclass(frozen=True)
+class ToolExecutionResult:
+ """Tool result plus request-scoped Skill resolution metadata."""
+
+ result: Any
+ effective_params: dict[str, Any]
+ skill_uris: tuple[str, ...] = ()
+
+
class ToolRegistry:
"""
Registry for agent tools.
@@ -105,6 +117,7 @@ class ToolRegistry:
self,
ov_tools_enable: bool = True,
disabled_tools: list[str] | None = None,
+ skill_runtime: Any | None = None,
) -> list[dict[str, Any]]:
"""
Get all tool definitions in OpenAI format.
@@ -132,9 +145,18 @@ class ToolRegistry:
if disabled_tools:
disabled = set(disabled_tools)
tools = [tool for tool in tools if tool.name not in disabled]
- return [tool.to_schema() for tool in tools]
-
- async def execute(
+ definitions: list[dict[str, Any]] = []
+ for tool in tools:
+ definition = (
+ skill_runtime.prepare_tool_definition(tool)
+ if skill_runtime is not None
+ else tool.to_schema()
+ )
+ if definition is not None:
+ definitions.append(definition)
+ return definitions
+
+ async def execute_detailed(
self,
name: str,
params: dict[str, Any],
@@ -147,7 +169,8 @@ class ToolRegistry:
memory_user_ids: list[str] | None = None,
openviking_connection: dict[str, Any] | None = None,
channel_metadata: dict[str, Any] | None = None,
- ) -> str:
+ skill_runtime: Any | None = None,
+ ) -> ToolExecutionResult:
"""
Execute a tool by name with given parameters.
@@ -173,7 +196,9 @@ class ToolRegistry:
"""
tool = self._tools.get(name)
if not tool:
- return f"Error: Tool '{name}' not found"
+ return ToolExecutionResult(
+ result=f"Error: Tool '{name}' not found", effective_params=dict(params)
+ )
tool_context = ToolContext(
session_key=session_key,
@@ -185,12 +210,15 @@ class ToolRegistry:
memory_user_ids=memory_user_ids,
openviking_connection=openviking_connection,
channel_metadata=dict(channel_metadata or {}),
+ skill_runtime=skill_runtime,
)
# Langfuse tool call tracing - automatic for all tools
tool_span = None
start_time = time.time()
result = None
+ effective_params = dict(params)
+ skill_uris: tuple[str, ...] = ()
response_id = get_current_response_id()
try:
if self.langfuse.enabled:
@@ -202,14 +230,39 @@ class ToolRegistry:
)
tool_span = tool_ctx.__enter__()
- errors = tool.validate_params(params)
+ validation_params = (
+ skill_runtime.tool_params_for_validation(params)
+ if skill_runtime is not None
+ else params
+ )
+ errors = tool.validate_params(validation_params)
if errors:
result = f"Error: Invalid parameters for tool '{name}': " + "; ".join(errors)
else:
- result = await tool.execute(tool_context, **params)
+ if skill_runtime is not None:
+ prepared = await skill_runtime.prepare_tool_call(tool, params)
+ effective_params = prepared.params
+ skill_uris = prepared.skill_uris
+ if effective_params != params:
+ prepared_args = json.dumps(
+ effective_params,
+ ensure_ascii=False,
+ default=str,
+ )
+ logger.info("[TOOL_PREPARED]: {}({})", name, prepared_args[:600])
+ result = await tool.execute(tool_context, **effective_params)
+ if skill_runtime is not None:
+ skill_uris = skill_runtime.skill_uris_for_tool(
+ name,
+ effective_params,
+ skill_uris,
+ )
+ except SkillRuntimeError as e:
+ result = e
+ logger.warning("Remote Skill tool call rejected: tool={} error={}", name, e)
except Exception as e:
result = e
- logger.exception("Tool call fail: ", e)
+ logger.exception("Tool call failed: {}", e)
finally:
# End Langfuse tool call tracing
duration_ms = (time.time() - start_time) * 1000
@@ -245,14 +298,49 @@ class ToolRegistry:
openviking_connection=openviking_connection,
),
tool_name=name,
- params=params,
+ params=effective_params,
result=result,
)
result = hook_result.get("result")
if isinstance(result, Exception):
- return f"Error executing {name}: {str(result)}"
- else:
- return result
+ result = f"Error executing {name}: {str(result)}"
+ return ToolExecutionResult(
+ result=result,
+ effective_params=effective_params,
+ skill_uris=skill_uris,
+ )
+
+ async def execute(
+ self,
+ name: str,
+ params: dict[str, Any],
+ session_key: SessionKey,
+ sandbox_manager: SandboxManager | None = None,
+ sender_id: str | None = None,
+ actor_peer_id: str | None = None,
+ memory_peer_ids: list[str] | None = None,
+ memory_owner_user_ids: list[str] | None = None,
+ memory_user_ids: list[str] | None = None,
+ openviking_connection: dict[str, Any] | None = None,
+ channel_metadata: dict[str, Any] | None = None,
+ skill_runtime: Any | None = None,
+ ) -> str:
+ """Execute a tool and return the legacy string result."""
+ outcome = await self.execute_detailed(
+ name,
+ params,
+ session_key,
+ sandbox_manager=sandbox_manager,
+ sender_id=sender_id,
+ actor_peer_id=actor_peer_id,
+ memory_peer_ids=memory_peer_ids,
+ memory_owner_user_ids=memory_owner_user_ids,
+ memory_user_ids=memory_user_ids,
+ openviking_connection=openviking_connection,
+ channel_metadata=channel_metadata,
+ skill_runtime=skill_runtime,
+ )
+ return outcome.result
@property
def tool_names(self) -> list[str]:
diff --git a/bot/vikingbot/config/schema.py b/bot/vikingbot/config/schema.py
index 397d4dfc4..5e172e0fd 100644
--- a/bot/vikingbot/config/schema.py
+++ b/bot/vikingbot/config/schema.py
@@ -846,6 +846,20 @@ class SandboxConfig(BaseModel):
restrict_workspaces: dict[str, str] = Field(default_factory=dict)
+class RemoteSkillsConfig(BaseModel):
+ """OpenViking-backed Skill runtime configuration."""
+
+ discovery_limit: int = Field(default=8, ge=1, le=50)
+ score_threshold: float = Field(default=0.35, ge=0.0, le=1.0)
+ discovery_timeout_seconds: float = Field(default=2.0, gt=0.0, le=30.0)
+ max_files: int = Field(default=128, ge=1)
+ max_file_bytes: int = Field(default=8 * 1024 * 1024, ge=1)
+ max_total_bytes: int = Field(default=32 * 1024 * 1024, ge=1)
+ cache_idle_ttl_seconds: float = Field(default=10 * 60, gt=0.0)
+ cache_max_entries: int = Field(default=32, ge=1)
+ cache_max_bytes: int = Field(default=256 * 1024 * 1024, ge=1)
+
+
class Config(BaseSettings):
"""Root configuration for vikingbot."""
@@ -860,6 +874,7 @@ class Config(BaseSettings):
gateway: GatewayConfig = Field(default_factory=GatewayConfig)
tools: ToolsConfig = Field(default_factory=ToolsConfig)
ov_server: OpenVikingConfig = Field(default_factory=OpenVikingConfig)
+ remote_skills: RemoteSkillsConfig = Field(default_factory=RemoteSkillsConfig)
sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
heartbeat: HeartbeatConfig = Field(default_factory=HeartbeatConfig)
langfuse: LangfuseConfig = Field(default_factory=LangfuseConfig)
diff --git a/bot/vikingbot/hooks/builtins/openviking_hooks.py b/bot/vikingbot/hooks/builtins/openviking_hooks.py
index 201f07f03..ea40f4228 100644
--- a/bot/vikingbot/hooks/builtins/openviking_hooks.py
+++ b/bot/vikingbot/hooks/builtins/openviking_hooks.py
@@ -318,14 +318,14 @@ class OpenVikingPostCallHook(Hook):
else:
ov_client = await self._get_client(workspace_id, config=config)
logger.debug(
- "[SKILL_EXP]: start workspace_id=%s query_len=%d query=%r",
+ "[SKILL_EXP]: start workspace_id={} query_len={} query={!r}",
workspace_id,
len(query),
query_preview,
)
experiences = await ov_client.search_experiences(query, limit=3)
logger.info(
- "[SKILL_EXP]: found %d experiences workspace_id=%s elapsed_ms=%.1f query=%r",
+ "[SKILL_EXP]: found {} experiences workspace_id={} elapsed_ms={:.1f} query={!r}",
len(experiences),
workspace_id,
(time.perf_counter() - started_at) * 1000.0,
@@ -339,7 +339,7 @@ class OpenVikingPostCallHook(Hook):
score = exp.get("score", 0) if isinstance(exp, dict) else getattr(exp, "score", 0)
if score < 0.3:
logger.debug(
- "[SKILL_EXP]: skip low score workspace_id=%s index=%d uri=%s score=%s",
+ "[SKILL_EXP]: skip low score workspace_id={} index={} uri={} score={}",
workspace_id,
index,
uri,
@@ -351,8 +351,8 @@ class OpenVikingPostCallHook(Hook):
content = await ov_client.read_content(uri, level="read")
except Exception as read_exc:
logger.warning(
- "[SKILL_EXP]: failed to read experience workspace_id=%s "
- "index=%d uri=%s score=%s elapsed_ms=%.1f error_type=%s error=%r",
+ "[SKILL_EXP]: failed to read experience workspace_id={} "
+ "index={} uri={} score={} elapsed_ms={:.1f} error_type={} error={!r}",
workspace_id,
index,
uri,
@@ -365,8 +365,8 @@ class OpenVikingPostCallHook(Hook):
if content:
parts.append(content)
logger.debug(
- "[SKILL_EXP]: read experience workspace_id=%s index=%d uri=%s "
- "score=%s chars=%d elapsed_ms=%.1f",
+ "[SKILL_EXP]: read experience workspace_id={} index={} uri={} "
+ "score={} chars={} elapsed_ms={:.1f}",
workspace_id,
index,
uri,
@@ -375,7 +375,7 @@ class OpenVikingPostCallHook(Hook):
(time.perf_counter() - read_started_at) * 1000.0,
)
logger.info(
- "[SKILL_EXP]: finished workspace_id=%s kept=%d/%d elapsed_ms=%.1f query=%r",
+ "[SKILL_EXP]: finished workspace_id={} kept={}/{} elapsed_ms={:.1f} query={!r}",
workspace_id,
len(parts),
len(experiences),
@@ -403,7 +403,11 @@ class OpenVikingPostCallHook(Hook):
await ov_client.close()
async def execute(self, context: HookContext, tool_name, params, result) -> Any:
- if tool_name == "read_file":
+ is_skill_read = tool_name == "read_file" or (
+ tool_name == "openviking_multi_read"
+ and any(str(uri).rstrip("/").endswith("/SKILL.md") for uri in params.get("uris", []))
+ )
+ if is_skill_read:
if result and not isinstance(result, Exception):
match = re.search(r"^---\s*\nname:\s*(.+?)\s*\n", result, re.MULTILINE)
if match:
diff --git a/bot/vikingbot/openviking_mount/ov_server.py b/bot/vikingbot/openviking_mount/ov_server.py
index d31292c48..3a836f08c 100644
--- a/bot/vikingbot/openviking_mount/ov_server.py
+++ b/bot/vikingbot/openviking_mount/ov_server.py
@@ -621,16 +621,35 @@ class VikingClient:
async def download_bytes(self, uri: str) -> bytes:
return await self.client.download_bytes(uri)
+ async def find_skills(
+ self,
+ query: str,
+ *,
+ limit: int = 10,
+ score_threshold: float | None = None,
+ target_uri: str | None = None,
+ ) -> Dict[str, Any]:
+ return await self.client.find_skills(
+ query=query,
+ limit=limit,
+ score_threshold=score_threshold,
+ target_uri=target_uri,
+ )
+
async def get_skill(
self,
skill_name: str,
*,
target_uri: str,
+ include_content: bool = True,
+ include_files: bool = True,
+ include_integrity: bool = False,
) -> Dict[str, Any]:
return await self.client.get_skill(
skill_name,
- include_content=True,
- include_files=True,
+ include_content=include_content,
+ include_files=include_files,
+ include_integrity=include_integrity,
include_source=False,
target_uri=target_uri,
)
@@ -1012,8 +1031,12 @@ class VikingClient:
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:
+ skill_uri = str(tool_info.get("skill_uri") or "").strip()
+ if not skill_uri:
+ explicit_skill_uris = tool_info.get("skill_uris") or []
+ if isinstance(explicit_skill_uris, list) and explicit_skill_uris:
+ skill_uri = str(explicit_skill_uris[0] or "").strip()
+ if not skill_uri and tool_name == "read_file" and result_str:
match = re.search(
r"^---\s*\nname:\s*(.+?)\s*\n",
result_str,
@@ -1041,11 +1064,7 @@ class VikingClient:
"tool_input": tool_input,
"tool_output": result_str,
"tool_status": explicit_status
- or (
- "completed"
- if tool_info.get("execute_success", True)
- else "error"
- ),
+ 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"),
diff --git a/bot/vikingbot/sandbox/backends/aiosandbox.py b/bot/vikingbot/sandbox/backends/aiosandbox.py
index 9fef8f5b0..2174a1b3a 100644
--- a/bot/vikingbot/sandbox/backends/aiosandbox.py
+++ b/bot/vikingbot/sandbox/backends/aiosandbox.py
@@ -1,6 +1,8 @@
"""AIO Sandbox backend implementation using agent-sandbox SDK."""
+import base64
import posixpath
+import shlex
from pathlib import Path
from typing import Any
@@ -108,6 +110,10 @@ class AioSandboxBackend(SandboxBackend):
relative = self._normalize_workspace_path(path)
return self.sandbox_cwd if not relative else f"{self.sandbox_cwd}/{relative}"
+ def local_file_path(self, path: str) -> Path | None:
+ del path
+ return None
+
async def _list_path(self, path: str) -> list[Any]:
if not self._client:
raise SandboxNotStartedError()
@@ -156,6 +162,29 @@ class AioSandboxBackend(SandboxBackend):
logger.error(f"[AioSandbox] Failed to write file {path}: {e}")
raise
+ async def write_file_bytes(self, path: str, content: bytes) -> None:
+ """Write binary content through the AIO Sandbox file API."""
+ if not self._client:
+ raise SandboxNotStartedError()
+ sandbox_path = path if path.startswith("/") else f"/home/gem/{path}"
+ encoded = base64.b64encode(content).decode("ascii")
+ result = await self._client.file.write_file(
+ file=sandbox_path,
+ content=encoded,
+ encoding="base64",
+ )
+ if result.success is False:
+ raise RuntimeError(f"Write failed: {result.message}")
+
+ async def remove_tree(self, path: str) -> None:
+ if not self._client:
+ raise SandboxNotStartedError()
+ if not path or path.startswith("/") or ".." in Path(path).parts:
+ raise PermissionError("remove_tree requires a safe sandbox-relative path")
+ sandbox_path = f"/home/gem/{path}"
+ output = await self.execute(f"rm -rf -- {shlex.quote(sandbox_path)}")
+ self._ensure_command_succeeded(output, "sandbox tree removal")
+
async def list_dir(self, path: str) -> list[tuple[str, bool]]:
"""List directory in AIO Sandbox using SDK."""
try:
@@ -238,3 +267,16 @@ class AioSandboxBackend(SandboxBackend):
self._validate_max_bytes(max_bytes)
stream = self._client.file.download_file(path=self._sandbox_path(path))
return await self._collect_stream_bytes(stream, path, max_bytes)
+
+ async def export_file(
+ self,
+ path: str,
+ destination: Path,
+ *,
+ max_bytes: int | None = None,
+ ) -> int:
+ if not self._client:
+ raise SandboxNotStartedError()
+ self._validate_max_bytes(max_bytes)
+ stream = self._client.file.download_file(path=self._sandbox_path(path))
+ return await self._export_stream_to_local(stream, destination, path, max_bytes)
diff --git a/bot/vikingbot/sandbox/backends/direct.py b/bot/vikingbot/sandbox/backends/direct.py
index 87aafbb0e..d67962297 100644
--- a/bot/vikingbot/sandbox/backends/direct.py
+++ b/bot/vikingbot/sandbox/backends/direct.py
@@ -102,13 +102,22 @@ class DirectBackend(SandboxBackend):
"""Get the current working directory (uses actual host cwd)."""
return str(self._workspace)
- async def read_file_bytes(self, path: str, *, max_bytes: int | None = None) -> bytes:
- self._validate_max_bytes(max_bytes)
+ def local_file_path(self, path: str) -> Path | None:
sandbox_path = Path(path)
if not sandbox_path.is_absolute():
sandbox_path = self._workspace / path
-
self._check_path_restriction(sandbox_path)
+ if not sandbox_path.exists():
+ raise FileNotFoundError(f"File not found: {path}")
+ if not sandbox_path.is_file():
+ raise IOError(f"Not a file: {path}")
+ return sandbox_path
+
+ async def read_file_bytes(self, path: str, *, max_bytes: int | None = None) -> bytes:
+ self._validate_max_bytes(max_bytes)
+ sandbox_path = self.local_file_path(path)
+ if sandbox_path is None:
+ raise IOError("Sandbox file is not accessible from the host")
return await asyncio.to_thread(self._read_local_bytes, sandbox_path, path, max_bytes)
async def read_file(self, path: str) -> str:
diff --git a/bot/vikingbot/sandbox/backends/opensandbox.py b/bot/vikingbot/sandbox/backends/opensandbox.py
index d21720c75..25e79a691 100644
--- a/bot/vikingbot/sandbox/backends/opensandbox.py
+++ b/bot/vikingbot/sandbox/backends/opensandbox.py
@@ -2,6 +2,7 @@
import asyncio
import atexit
+import base64
import json
import os
import posixpath
@@ -302,6 +303,11 @@ class OpenSandboxBackend(SandboxBackend):
relative = self._normalize_workspace_path(path)
return self.sandbox_cwd if not relative else f"{self.sandbox_cwd}/{relative}"
+ def local_file_path(self, path: str) -> Path | None:
+ if self._is_vke:
+ return None
+ return super().local_file_path(path)
+
async def read_file(self, path: str) -> str:
"""Read file from OpenSandbox."""
if not self._sandbox:
@@ -332,6 +338,38 @@ class OpenSandboxBackend(SandboxBackend):
else:
await super().write_file(path, content)
+ async def write_file_bytes(self, path: str, content: bytes) -> None:
+ """Write binary content to OpenSandbox, including remote VKE sandboxes."""
+ if not self._sandbox:
+ raise SandboxNotStartedError()
+ if not self._is_vke:
+ await super().write_file_bytes(path, content)
+ return
+ sandbox_path = path if path.startswith("/") else f"/workspace/{path}"
+ try:
+ await self._sandbox.files.write_file(sandbox_path, content, mode=0o644)
+ except TypeError:
+ encoded_path = f"{sandbox_path}.vikingbot-b64"
+ encoded = base64.b64encode(content).decode("ascii")
+ await self._sandbox.files.write_file(encoded_path, encoded, mode=0o600)
+ output = await self.execute(
+ f"base64 -d {shlex.quote(encoded_path)} > {shlex.quote(sandbox_path)} "
+ f"&& rm -f {shlex.quote(encoded_path)}"
+ )
+ self._ensure_command_succeeded(output, "binary file decode")
+
+ async def remove_tree(self, path: str) -> None:
+ if not self._sandbox:
+ raise SandboxNotStartedError()
+ if not path or path.startswith("/") or ".." in Path(path).parts:
+ raise PermissionError("remove_tree requires a safe sandbox-relative path")
+ if not self._is_vke:
+ await super().remove_tree(path)
+ return
+ sandbox_path = f"/workspace/{path}"
+ output = await self.execute(f"rm -rf -- {shlex.quote(sandbox_path)}")
+ self._ensure_command_succeeded(output, "sandbox tree removal")
+
async def list_dir(self, path: str) -> list[tuple[str, bool]]:
"""List directory in OpenSandbox."""
if not self._sandbox:
@@ -470,3 +508,22 @@ class OpenSandboxBackend(SandboxBackend):
range_header=range_header,
)
return await self._collect_stream_bytes(stream, path, max_bytes)
+
+ async def export_file(
+ self,
+ path: str,
+ destination: Path,
+ *,
+ max_bytes: int | None = None,
+ ) -> int:
+ if not self._is_vke:
+ return await super().export_file(path, destination, max_bytes=max_bytes)
+ if not self._sandbox:
+ raise SandboxNotStartedError()
+ self._validate_max_bytes(max_bytes)
+ range_header = None if max_bytes is None else f"bytes=0-{max_bytes}"
+ stream = await self._sandbox.files.read_bytes_stream(
+ self._sandbox_path(path),
+ range_header=range_header,
+ )
+ return await self._export_stream_to_local(stream, destination, path, max_bytes)
diff --git a/bot/vikingbot/sandbox/base.py b/bot/vikingbot/sandbox/base.py
index c4d775bca..ea380f57d 100644
--- a/bot/vikingbot/sandbox/base.py
+++ b/bot/vikingbot/sandbox/base.py
@@ -3,6 +3,8 @@
import asyncio
import os
import posixpath
+import re
+import shutil
from abc import ABC, abstractmethod
from collections import deque
from collections.abc import AsyncIterator
@@ -126,6 +128,39 @@ class SandboxBackend(ABC):
raise ValueError(f"File exceeds the {max_bytes}-byte read limit: {original_path}")
return data
+ @staticmethod
+ def _copy_local_file(
+ source: Path,
+ destination: Path,
+ original_path: str,
+ max_bytes: int | None,
+ ) -> int:
+ """Copy one host file with bounded memory and remove partial output on failure."""
+ if not source.exists():
+ raise FileNotFoundError(f"File not found: {original_path}")
+ if not source.is_file():
+ raise IOError(f"Not a file: {original_path}")
+ size = source.stat().st_size
+ if max_bytes is not None and size > max_bytes:
+ raise ValueError(f"File exceeds the {max_bytes}-byte export limit: {original_path}")
+ if source.resolve() == destination.resolve():
+ return size
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ total = 0
+ try:
+ with source.open("rb") as input_stream, destination.open("wb") as output_stream:
+ while chunk := input_stream.read(1024 * 1024):
+ total += len(chunk)
+ if max_bytes is not None and total > max_bytes:
+ raise ValueError(
+ f"File exceeds the {max_bytes}-byte export limit: {original_path}"
+ )
+ output_stream.write(chunk)
+ except Exception:
+ destination.unlink(missing_ok=True)
+ raise
+ return total
+
@staticmethod
async def _collect_stream_bytes(
stream: AsyncIterator[bytes],
@@ -154,6 +189,72 @@ class SandboxBackend(ABC):
raise ValueError(f"File exceeds the {max_bytes}-byte read limit: {original_path}")
return bytes(data)
+ @staticmethod
+ async def _export_stream_to_local(
+ stream: AsyncIterator[bytes],
+ destination: Path,
+ original_path: str,
+ max_bytes: int | None,
+ ) -> int:
+ """Write a remote byte stream locally while retaining only one chunk in memory."""
+ await asyncio.to_thread(destination.parent.mkdir, parents=True, exist_ok=True)
+ total = 0
+ output_stream = None
+ try:
+ output_stream = await asyncio.to_thread(destination.open, "wb")
+ async for chunk in stream:
+ if not isinstance(chunk, (bytes, bytearray, memoryview)):
+ raise IOError(f"Sandbox returned invalid file bytes: {original_path}")
+ total += len(chunk)
+ if max_bytes is not None and total > max_bytes:
+ raise ValueError(
+ f"File exceeds the {max_bytes}-byte export limit: {original_path}"
+ )
+ await asyncio.to_thread(output_stream.write, chunk)
+ except BaseException:
+ if output_stream is not None:
+ await asyncio.to_thread(output_stream.close)
+ output_stream = None
+ await asyncio.to_thread(destination.unlink, missing_ok=True)
+ raise
+ finally:
+ if output_stream is not None:
+ await asyncio.to_thread(output_stream.close)
+ close = getattr(stream, "aclose", None)
+ if close is not None:
+ await close()
+ return total
+
+ def local_file_path(self, path: str) -> Path | None:
+ """Return a safe host path when this sandbox workspace is host-accessible."""
+ sandbox_path = self._resolve_path(path)
+ self._check_path_restriction(sandbox_path)
+ if not sandbox_path.exists():
+ raise FileNotFoundError(f"File not found: {path}")
+ if not sandbox_path.is_file():
+ raise IOError(f"Not a file: {path}")
+ return sandbox_path
+
+ async def export_file(
+ self,
+ path: str,
+ destination: Path,
+ *,
+ max_bytes: int | None = None,
+ ) -> int:
+ """Export a sandbox file to the host without materializing it in Bot memory."""
+ self._validate_max_bytes(max_bytes)
+ source = self.local_file_path(path)
+ if source is None:
+ raise IOError("Sandbox does not expose a host file path or streaming exporter")
+ return await asyncio.to_thread(
+ self._copy_local_file,
+ source,
+ destination,
+ path,
+ max_bytes,
+ )
+
async def read_file_bytes(self, path: str, *, max_bytes: int | None = None) -> bytes:
"""Read file bytes from sandbox (default implementation: host filesystem).
@@ -171,8 +272,9 @@ class SandboxBackend(ABC):
PermissionError: If path outside workspace and restriction is enabled
"""
self._validate_max_bytes(max_bytes)
- sandbox_path = self._resolve_path(path)
- self._check_path_restriction(sandbox_path)
+ sandbox_path = self.local_file_path(path)
+ if sandbox_path is None:
+ raise IOError("Sandbox file is not accessible from the host")
return await asyncio.to_thread(self._read_local_bytes, sandbox_path, path, max_bytes)
async def list_files(
@@ -267,6 +369,31 @@ class SandboxBackend(ABC):
sandbox_path.parent.mkdir(parents=True, exist_ok=True)
sandbox_path.write_text(content, encoding="utf-8")
+ async def write_file_bytes(self, path: str, content: bytes) -> None:
+ """Write binary content inside the sandbox workspace."""
+ sandbox_path = self._resolve_path(path)
+ self._check_path_restriction(sandbox_path)
+ sandbox_path.parent.mkdir(parents=True, exist_ok=True)
+ await asyncio.to_thread(sandbox_path.write_bytes, content)
+
+ async def remove_tree(self, path: str) -> None:
+ """Remove one sandbox-relative directory tree."""
+ sandbox_path = self._resolve_path(path)
+ self._check_path_restriction(sandbox_path)
+ if sandbox_path.resolve() == self.workspace.resolve():
+ raise PermissionError("Refusing to remove the sandbox workspace root")
+ if sandbox_path.exists():
+ await asyncio.to_thread(shutil.rmtree, sandbox_path)
+
+ @staticmethod
+ def _ensure_command_succeeded(output: str, operation: str) -> None:
+ """Raise when a backend's rendered command result contains a non-zero exit code."""
+ exit_codes = [
+ int(value) for value in re.findall(r"(?:^|\n)Exit code:\s*(-?\d+)(?:\n|$)", str(output))
+ ]
+ if any(code != 0 for code in exit_codes):
+ raise SandboxExecutionError(f"{operation} failed: {output}")
+
async def list_dir(self, path: str) -> list[tuple[str, bool]]:
"""List directory in sandbox (default implementation: host filesystem).
diff --git a/bot/vikingbot/sandbox/manager.py b/bot/vikingbot/sandbox/manager.py
index d4fe9ab66..ab62c037a 100644
--- a/bot/vikingbot/sandbox/manager.py
+++ b/bot/vikingbot/sandbox/manager.py
@@ -15,10 +15,18 @@ class SandboxManager:
COPY_BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md", "IDENTITY.md"]
def __init__(self, config: Config, sandbox_parent_path: Path, source_workspace_path: Path):
+ from vikingbot.agent.remote_skill_cache import RemoteSkillSnapshotCache
+
self.config = config
self.workspace = sandbox_parent_path
self.source_workspace = source_workspace_path
self._sandboxes: dict[str, SandboxBackend] = {}
+ self.remote_skill_cache = (
+ RemoteSkillSnapshotCache(config)
+ if getattr(config, "remote_skills", None) is not None
+ and getattr(config, "bot_data_path", None) is not None
+ else None
+ )
backend_cls = get_backend(config.sandbox.backend)
if not backend_cls:
raise UnsupportedBackendError(f"Unknown sandbox backend: {config.backend}")
diff --git a/openviking/server/routers/skills.py b/openviking/server/routers/skills.py
index 4fe2cd71d..7a1f8196d 100644
--- a/openviking/server/routers/skills.py
+++ b/openviking/server/routers/skills.py
@@ -3,10 +3,13 @@
"""Agent-scope skill management endpoints for OpenViking HTTP Server."""
import asyncio
+import hashlib
+import json
import shutil
import uuid
+from contextlib import asynccontextmanager
from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, AsyncIterator, Dict, Optional
import yaml
from fastapi import APIRouter, Depends, Request
@@ -30,10 +33,15 @@ from openviking.server.telemetry import run_operation
from openviking.server.temp_upload_store import TempUploadStore
from openviking.telemetry import TelemetryRequest
from openviking.utils.skill_processor import validate_skill_name
-from openviking_cli.exceptions import InvalidArgumentError, NotFoundError
+from openviking_cli.exceptions import InvalidArgumentError, NotFoundError, ResourceExhaustedError
router = APIRouter(prefix="/api/v1/skills", tags=["skills"])
+_SKILL_INTEGRITY_MAX_ENTRIES = 512
+_SKILL_INTEGRITY_MAX_FILE_BYTES = 16 * 1024 * 1024
+_SKILL_INTEGRITY_MAX_TOTAL_BYTES = 64 * 1024 * 1024
+_SKILL_INTEGRITY_READ_CONCURRENCY = 8
+
class UpdateSkillRequest(BaseModel):
"""Replace an existing agent skill with new skill content."""
@@ -81,9 +89,7 @@ def _agent_skills_root(ctx: RequestContext, target_uri: Optional[str] = None) ->
if not target_uri:
return user_root
resolved_uri = resolve_path_variables(target_uri).rstrip("/")
- if resolved_uri == "viking://agent/skills" or resolved_uri.startswith(
- "viking://agent/skills/"
- ):
+ if resolved_uri == "viking://agent/skills" or resolved_uri.startswith("viking://agent/skills/"):
return "viking://agent/skills"
if resolved_uri == user_root or resolved_uri.startswith(f"{user_root}/"):
return user_root
@@ -96,7 +102,9 @@ def _agent_skills_root(ctx: RequestContext, target_uri: Optional[str] = None) ->
)
-async def _list_skills_from_root(service, ctx: RequestContext, root_uri: str) -> list[Dict[str, Any]]:
+async def _list_skills_from_root(
+ service, ctx: RequestContext, root_uri: str
+) -> list[Dict[str, Any]]:
"""List skills from a specific root URI.
Filters out directory entries that do not look like a valid skill — i.e.
@@ -127,9 +135,7 @@ async def _list_skills_from_root(service, ctx: RequestContext, root_uri: str) ->
return results
-async def _entry_looks_like_skill(
- service, ctx: RequestContext, entry: Dict[str, Any]
-) -> bool:
+async def _entry_looks_like_skill(service, ctx: RequestContext, entry: Dict[str, Any]) -> bool:
"""Decide whether a directory entry from ``ls`` represents a real skill."""
entry_uri = entry.get("uri", "")
if not entry_uri:
@@ -158,7 +164,6 @@ async def _entry_looks_like_skill(
return True
-
def _validate_skill_name(skill_name: str) -> str:
return validate_skill_name(skill_name)
@@ -252,7 +257,9 @@ def _skill_root_from_hit_uri(hit_uri: str) -> str:
return trimmed
-async def _require_skill(service, ctx: RequestContext, skill_name: str, target_uri: Optional[str] = None) -> str:
+async def _require_skill(
+ service, ctx: RequestContext, skill_name: str, target_uri: Optional[str] = None
+) -> str:
if target_uri:
resolved_uri = resolve_path_variables(target_uri)
root_uri = _skill_root_uri(ctx, skill_name, resolved_uri)
@@ -332,6 +339,171 @@ async def _list_skill_files(
return entries
+async def _skill_manifest_with_integrity(
+ service,
+ ctx: RequestContext,
+ root_uri: str,
+ *,
+ include_integrity: bool = True,
+ max_entries: int = _SKILL_INTEGRITY_MAX_ENTRIES,
+ max_file_bytes: int = _SKILL_INTEGRITY_MAX_FILE_BYTES,
+ max_total_bytes: int = _SKILL_INTEGRITY_MAX_TOTAL_BYTES,
+) -> tuple[list[Dict[str, Any]], str | None]:
+ """Build a Skill manifest, optionally content-addressed for remote consumers."""
+ entries = await _list_skill_files(
+ service,
+ ctx,
+ root_uri,
+ node_limit=max_entries + 2 if include_integrity else 10000,
+ )
+ visible_entries = [
+ entry
+ for entry in entries
+ if isinstance(entry, dict)
+ and _relative_skill_path(root_uri, str(entry.get("uri") or "")) != SOURCE_METADATA_FILENAME
+ ]
+ if include_integrity and len(visible_entries) > max_entries:
+ raise ResourceExhaustedError(f"Skill integrity manifest exceeds {max_entries} entries")
+ if include_integrity:
+ declared_total = 0
+ for entry in visible_entries:
+ if bool(entry.get("isDir", False)) or entry.get("size") is None:
+ continue
+ declared_size = int(entry["size"])
+ path = _relative_skill_path(root_uri, str(entry.get("uri") or ""))
+ if declared_size > max_file_bytes:
+ raise ResourceExhaustedError(f"Skill file exceeds integrity size limit: {path}")
+ declared_total += declared_size
+ if declared_total > max_total_bytes:
+ raise ResourceExhaustedError(
+ f"Skill integrity manifest exceeds {max_total_bytes} total bytes"
+ )
+
+ async def build_entry(entry: Dict[str, Any]) -> Dict[str, Any] | None:
+ uri = str(entry.get("uri") or "")
+ path = _relative_skill_path(root_uri, uri)
+ if not uri or path == SOURCE_METADATA_FILENAME:
+ return None
+ is_dir = bool(entry.get("isDir", False))
+ item: Dict[str, Any] = {
+ "name": entry.get("name") or _skill_name_from_uri(uri),
+ "uri": uri,
+ "path": path,
+ "is_dir": is_dir,
+ "kind": _skill_file_kind(path, is_dir),
+ }
+ if not is_dir and include_integrity:
+ declared_size = entry.get("size")
+ if declared_size is not None and int(declared_size) > max_file_bytes:
+ raise ResourceExhaustedError(f"Skill file exceeds integrity size limit: {path}")
+ data = await service.fs.read_file_bytes(uri, ctx=ctx)
+ if len(data) > max_file_bytes:
+ raise ResourceExhaustedError(f"Skill file exceeds integrity size limit: {path}")
+ item["size"] = len(data)
+ item["sha256"] = hashlib.sha256(data).hexdigest()
+ return item
+
+ built: list[Dict[str, Any] | None] = []
+ total_bytes = 0
+ for offset in range(0, len(visible_entries), _SKILL_INTEGRITY_READ_CONCURRENCY):
+ batch = visible_entries[offset : offset + _SKILL_INTEGRITY_READ_CONCURRENCY]
+ batch_items = await asyncio.gather(*(build_entry(entry) for entry in batch))
+ for item in batch_items:
+ if item is not None and not item["is_dir"]:
+ total_bytes += int(item.get("size") or 0)
+ if total_bytes > max_total_bytes:
+ raise ResourceExhaustedError(
+ f"Skill integrity manifest exceeds {max_total_bytes} total bytes"
+ )
+ built.extend(batch_items)
+ files = [item for item in built if item is not None]
+ if not include_integrity:
+ return files, None
+ revision_payload = [
+ {
+ "path": item["path"],
+ "is_dir": item["is_dir"],
+ "size": item.get("size"),
+ "sha256": item.get("sha256"),
+ }
+ for item in sorted(files, key=lambda value: value["path"])
+ ]
+ revision = hashlib.sha256(
+ json.dumps(revision_payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+ ).hexdigest()
+ return files, revision
+
+
+@asynccontextmanager
+async def _skill_snapshot_lock(
+ service,
+ ctx: RequestContext,
+ root_uri: str,
+) -> AsyncIterator[None]:
+ """Hold the storage tree lock while one content-addressed Skill view is read."""
+ viking_fs = service.fs._ensure_initialized() # noqa: SLF001
+ viking_fs._ensure_access(root_uri, ctx) # noqa: SLF001
+ path = viking_fs._uri_to_path(root_uri, ctx=ctx) # noqa: SLF001
+ fs_ctx = {"account_id": ctx.account_id}
+ lease = await viking_fs._async_agfs.pathlock_acquire_tree( # noqa: SLF001
+ path,
+ fs_ctx=fs_ctx,
+ )
+ try:
+ yield
+ finally:
+ await viking_fs._async_agfs.pathlock_release(lease, fs_ctx=fs_ctx) # noqa: SLF001
+
+
+async def _read_skill_detail(
+ service,
+ ctx: RequestContext,
+ *,
+ skill_name: str,
+ root_uri: str,
+ include_content: Optional[bool],
+ include_files: bool,
+ include_integrity: bool,
+ include_source: bool,
+ level: Optional[int],
+) -> Dict[str, Any]:
+ """Read one Skill; integrity requests observe a storage-locked package snapshot."""
+
+ async def read_fields() -> Dict[str, Any]:
+ abstract = await service.fs.abstract(root_uri, ctx=ctx)
+ result = _skill_summary_from_meta(skill_name, root_uri, _parse_abstract_meta(abstract))
+ if level is None or level == 0:
+ result["abstract"] = abstract
+ if level is None or level == 1:
+ result["overview"] = await service.fs.overview(root_uri, ctx=ctx)
+ if (
+ level == 2
+ or include_content is True
+ or (level is None and include_content is not False)
+ ):
+ content = await service.fs.read(_skill_md_uri(root_uri), ctx=ctx)
+ result["content"] = content
+ result["content_sha256"] = hashlib.sha256(content.encode("utf-8")).hexdigest()
+ if include_files:
+ files, revision = await _skill_manifest_with_integrity(
+ service,
+ ctx,
+ root_uri,
+ include_integrity=include_integrity,
+ )
+ result["files"] = files
+ if revision is not None:
+ result["revision"] = revision
+ if include_source:
+ result["source"] = await read_skill_source_metadata(service, ctx, root_uri)
+ return result
+
+ if include_integrity:
+ async with _skill_snapshot_lock(service, ctx, root_uri):
+ return await read_fields()
+ return await read_fields()
+
+
async def _restore_skill_privacy(
service,
ctx: RequestContext,
@@ -449,11 +621,15 @@ async def find_skills(
)
user_result = user_execution.result
- user_result_dict = user_result.to_dict() if hasattr(user_result, "to_dict") else dict(user_result or {})
+ user_result_dict = (
+ user_result.to_dict() if hasattr(user_result, "to_dict") else dict(user_result or {})
+ )
user_hits = [_skill_summary_from_hit(hit) for hit in user_result_dict.get("skills", [])]
agent_result = agent_execution.result
- agent_result_dict = agent_result.to_dict() if hasattr(agent_result, "to_dict") else dict(agent_result or {})
+ agent_result_dict = (
+ agent_result.to_dict() if hasattr(agent_result, "to_dict") else dict(agent_result or {})
+ )
agent_hits = [_skill_summary_from_hit(hit) for hit in agent_result_dict.get("skills", [])]
merged_hits = [*user_hits, *agent_hits]
@@ -494,6 +670,7 @@ async def get_skill(
target_uri: Optional[str] = None,
include_content: Optional[bool] = None,
include_files: bool = True,
+ include_integrity: bool = False,
include_source: bool = False,
level: Optional[int] = None,
_ctx: RequestContext = Depends(get_request_context),
@@ -506,33 +683,17 @@ async def get_skill(
)
service = get_service()
root_uri = await _require_skill(service, _ctx, skill_name, target_uri)
- abstract = await service.fs.abstract(root_uri, ctx=_ctx)
- result = _skill_summary_from_meta(skill_name, root_uri, _parse_abstract_meta(abstract))
- if level is None or level == 0:
- result["abstract"] = abstract
- if level is None or level == 1:
- result["overview"] = await service.fs.overview(root_uri, ctx=_ctx)
- if level == 2 or include_content is True or (level is None and include_content is not False):
- result["content"] = await service.fs.read(_skill_md_uri(root_uri), ctx=_ctx)
- if include_files:
- entries = await _list_skill_files(service, _ctx, root_uri)
- result["files"] = [
- {
- "name": entry.get("name") or _skill_name_from_uri(entry.get("uri", "")),
- "uri": entry.get("uri", ""),
- "path": _relative_skill_path(root_uri, entry.get("uri", "")),
- "is_dir": entry.get("isDir", False),
- "kind": _skill_file_kind(
- _relative_skill_path(root_uri, entry.get("uri", "")),
- entry.get("isDir", False),
- ),
- }
- for entry in entries
- if isinstance(entry, dict)
- and _relative_skill_path(root_uri, entry.get("uri", "")) != SOURCE_METADATA_FILENAME
- ]
- if include_source:
- result["source"] = await read_skill_source_metadata(service, _ctx, root_uri)
+ result = await _read_skill_detail(
+ service,
+ _ctx,
+ skill_name=skill_name,
+ root_uri=root_uri,
+ include_content=include_content,
+ include_files=include_files,
+ include_integrity=include_integrity,
+ include_source=include_source,
+ level=level,
+ )
return Response(status="ok", result=result)
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 68ea642a0..5efc30c29 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -401,9 +401,7 @@ class AsyncHTTPClient:
self._ldap_username = config.ldap_username
self._ldap_password = config.ldap_password
self._oidc_token = config.oidc_token
- self._event_hooks = {
- event: list(hooks) for event, hooks in (event_hooks or {}).items()
- }
+ self._event_hooks = {event: list(hooks) for event, hooks in (event_hooks or {}).items()}
self._http: Optional[httpx.AsyncClient] = None
self._observer: Optional[_HTTPObserver] = None
self._snapshot: Optional["AsyncHTTPSnapshotNamespace"] = None
@@ -422,6 +420,7 @@ class AsyncHTTPClient:
# LDAP Basic Auth
if self._auth_mode == "ldap" and self._ldap_username and self._ldap_password:
from .config import get_basic_auth_header
+
headers["Authorization"] = get_basic_auth_header(
self._ldap_username, self._ldap_password
)
@@ -858,9 +857,11 @@ class AsyncHTTPClient:
include_source: bool = False,
level: Optional[int] = None,
target_uri: Optional[str] = None,
+ include_integrity: bool = False,
) -> Dict[str, Any]:
params: Dict[str, Any] = {
"include_files": include_files,
+ "include_integrity": include_integrity,
"include_source": include_source,
}
if include_content is not None:
@@ -2067,12 +2068,14 @@ class SyncHTTPClient:
include_source: bool = False,
level: Optional[int] = None,
target_uri: Optional[str] = None,
+ include_integrity: bool = False,
) -> Dict[str, Any]:
return run_async(
self._async_client.get_skill(
skill_name,
include_content=include_content,
include_files=include_files,
+ include_integrity=include_integrity,
include_source=include_source,
level=level,
target_uri=target_uri,
@@ -2863,9 +2866,7 @@ class SyncHTTPSnapshotNamespace:
from_ref: Optional[str] = None,
) -> Dict[str, Any]:
"""Compare one file between two snapshot refs."""
- return run_async(
- self._ns().diff(path, from_ref=from_ref, to_ref=to_ref)
- )
+ return run_async(self._ns().diff(path, from_ref=from_ref, to_ref=to_ref))
def get_gitignore(self) -> str:
return run_async(self._ns().get_gitignore())
diff --git a/tests/server/test_api_skills.py b/tests/server/test_api_skills.py
index 83fac085d..a72ede6f2 100644
--- a/tests/server/test_api_skills.py
+++ b/tests/server/test_api_skills.py
@@ -75,7 +75,12 @@ async def test_skills_api_list_show_find_and_delete(client):
show_response = await client.get(
"/api/v1/skills/api-skill",
- params={"level": 2, "include_files": True, "include_source": True},
+ params={
+ "level": 2,
+ "include_files": True,
+ "include_integrity": True,
+ "include_source": True,
+ },
)
assert show_response.status_code == 200, show_response.text
shown = show_response.json()["result"]
@@ -84,6 +89,12 @@ async def test_skills_api_list_show_find_and_delete(client):
assert shown["skill_md_uri"].endswith("/skills/api-skill/SKILL.md")
assert "# api-skill" in shown["content"]
assert any(file["name"] == "SKILL.md" for file in shown["files"])
+ assert len(shown["revision"]) == 64
+ assert len(shown["content_sha256"]) == 64
+ assert all(
+ file.get("is_dir") or (file.get("size") is not None and len(file.get("sha256", "")) == 64)
+ for file in shown["files"]
+ )
assert shown["source"]["tracked"] is True
assert shown["source"]["type"] == "api"
assert shown["source"]["source"] == "inline_content"