diff --git a/examples/knowledge_with_vectorstore/run_agent.py b/examples/knowledge_with_vectorstore/run_agent.py
index 329160c..e616067 100644
--- a/examples/knowledge_with_vectorstore/run_agent.py
+++ b/examples/knowledge_with_vectorstore/run_agent.py
@@ -7,10 +7,10 @@
import uuid
from dotenv import load_dotenv
-from trpc_agent.runners import Runner
-from trpc_agent.sessions import InMemorySessionService
-from trpc_agent.types import Content
-from trpc_agent.types import Part
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content
+from trpc_agent_sdk.types import Part
# Load environment variables from the .env file
load_dotenv()
diff --git a/format.py b/format.py
index 290c8aa..cd52ba3 100644
--- a/format.py
+++ b/format.py
@@ -12,35 +12,9 @@
then lexicographical order.
- Keep ``from __future__ import annotations`` at the very top of imports.
-2) audit
- - Report files missing copyright marker ``Copyright @``.
- - Report files missing module docstring.
-
-3) build-package-api
- - Auto-generate per-package ``__init__.py`` export blocks.
- - Skip optional-feature modules inferred from ``pyproject.toml`` extras.
- - De-duplicate against symbols already manually imported in ``__init__.py``.
-
-4) sync-imports-package-api
- - Combined maintenance workflow:
- ensure missing ``__init__.py`` > rename private modules > rewrite imports >
- build package API exports > sort imports.
- - Add copyright marker to Python files when missing.
- - Keep exactly two blank lines after import blocks.
-
-5) rename-private-modules
- - Rename package modules from ``foo.py`` to ``_foo.py``.
- - Rewrite import statements across project files accordingly.
- - Optional: refresh package API blocks after rename.
-
Examples:
python3 format.py sort-imports --root . --dry-run
python3 format.py sort-imports --root .
- python3 format.py audit --root .
- python3 format.py build-package-api --root . --dry-run
- python3 format.py sync-imports-package-api --root . --dry-run
- python3 format.py rename-private-modules --root . --dry-run
- python3 format.py rename-private-modules --root . --build-package-api
python3 format.py check-chinese --root . --dry-run
"""
@@ -50,6 +24,7 @@
import ast
import os
import re
+import subprocess
import sys
import tomllib
from dataclasses import dataclass
@@ -74,14 +49,10 @@
".pytest_cache",
}
-COPYRIGHT_RE = re.compile(r"Copyright\s*@")
STDLIB_COMPANION_MODULES = {"typing_extensions"}
AUTO_EXPORT_BEGIN = "# "
AUTO_EXPORT_END = "# "
CHINESE_RE = re.compile(r"[\u4e00-\u9fff]")
-ENCODING_RE = re.compile(r"^#.*coding[:=]\s*([-\w.]+)")
-DEFAULT_COPYRIGHT_YEAR = "2026"
-DEFAULT_COPYRIGHT_OWNER = "Tencent.com"
@dataclass(frozen=True)
@@ -89,6 +60,7 @@ class ImportLine:
text: str
group: int
kind: int # 0=import, 1=from-import
+ rel_level: int = 0 # relative import level; larger means farther (.. > .)
@dataclass
@@ -157,42 +129,6 @@ def ensure_init_files(root: Path, apply: bool) -> list[Path]:
return created
-def _default_copyright_block() -> list[str]:
- return [
- "# -*- coding: utf-8 -*-",
- "#",
- f"# Copyright @ {DEFAULT_COPYRIGHT_YEAR} {DEFAULT_COPYRIGHT_OWNER}",
- ]
-
-
-def add_copyright_if_missing(source: str) -> tuple[str, bool]:
- if COPYRIGHT_RE.search(source):
- return source, False
-
- lines = source.splitlines()
- insert_at = 0
- out: list[str] = []
-
- if lines and lines[0].startswith("#!"):
- out.append(lines[0])
- insert_at = 1
-
- has_encoding = insert_at < len(lines) and bool(ENCODING_RE.match(lines[insert_at]))
- if has_encoding:
- out.append(lines[insert_at])
- insert_at += 1
- out.extend(["#", f"# Copyright @ {DEFAULT_COPYRIGHT_YEAR} {DEFAULT_COPYRIGHT_OWNER}"])
- else:
- out.extend(_default_copyright_block())
-
- if insert_at < len(lines) and lines[insert_at] != "":
- out.append("")
- out.extend(lines[insert_at:])
-
- new_source = "\n".join(out) + ("\n" if source.endswith("\n") or not source else "")
- return new_source, True
-
-
def read_optional_group_tokens(pyproject_path: Path) -> set[str]:
if not pyproject_path.exists():
return set()
@@ -446,21 +382,14 @@ def _extract_all_names_from_value(node: ast.AST) -> list[str]:
return out
-def merge_init_all_exports(init_path: Path, apply: bool) -> bool:
- """Merge multiple top-level __all__ blocks in __init__.py into one.
-
- Order policy:
- 1) follow top-level import symbol order first (from-import aliases order),
- 2) append remaining legacy __all__ names (deduplicated) in original order.
- """
- if not init_path.exists():
- return False
- original_source = init_path.read_text(encoding="utf-8")
- source = strip_auto_export_markers(original_source)
+def _merge_init_all_exports_source(source: str) -> str | None:
+ """Return merged __all__ source for __init__.py, or None when unchanged."""
+ original_source = source
+ source = strip_auto_export_markers(source)
try:
tree = ast.parse(source)
except SyntaxError:
- return False
+ return None
all_nodes: list[ast.Assign] = []
legacy_all_names: list[str] = []
@@ -473,6 +402,12 @@ def merge_init_all_exports(init_path: Path, apply: bool) -> bool:
if has_all_target:
all_nodes.append(node)
legacy_all_names.extend(_extract_all_names_from_value(node.value))
+ elif isinstance(node, ast.Import):
+ for alias in node.names:
+ sym = alias.asname or alias.name.split(".", 1)[0]
+ if sym not in seen_imports:
+ seen_imports.add(sym)
+ import_symbol_order.append(sym)
elif isinstance(node, ast.ImportFrom):
if node.module == "__future__":
continue
@@ -485,7 +420,7 @@ def merge_init_all_exports(init_path: Path, apply: bool) -> bool:
import_symbol_order.append(sym)
if len(all_nodes) == 0:
- return False
+ return None
final_names: list[str] = []
seen_final: set[str] = set()
@@ -515,7 +450,7 @@ def merge_init_all_exports(init_path: Path, apply: bool) -> bool:
try:
kept_tree = ast.parse(kept_source)
except SyntaxError:
- return False
+ return None
last_import_end = 0
for node in kept_tree.body:
if isinstance(node, (ast.Import, ast.ImportFrom)):
@@ -529,6 +464,17 @@ def merge_init_all_exports(init_path: Path, apply: bool) -> bool:
new_source = "\n".join(merged_lines) + ("\n" if source.endswith("\n") else "")
if new_source == original_source:
+ return None
+ return new_source
+
+
+def merge_init_all_exports(init_path: Path, apply: bool) -> bool:
+ """Merge multiple top-level __all__ blocks in __init__.py into one."""
+ if not init_path.exists():
+ return False
+ original_source = init_path.read_text(encoding="utf-8")
+ new_source = _merge_init_all_exports_source(original_source)
+ if new_source is None:
return False
if apply:
init_path.write_text(new_source, encoding="utf-8")
@@ -767,7 +713,7 @@ def normalize_import_block(
text = f"from {module} import {alias.name}"
if alias.asname:
text += f" as {alias.asname}"
- normalized.append(ImportLine(text=text, group=group, kind=1))
+ normalized.append(ImportLine(text=text, group=group, kind=1, rel_level=node.level))
groups: dict[int, list[ImportLine]] = {1: [], 2: [], 3: [], 4: []}
for item in normalized:
@@ -777,9 +723,13 @@ def normalize_import_block(
# 1) plain imports first
# 2) then from-imports
# 3) lexicographical order inside each kind
+ # 4) for relative imports, farther levels first: .. > .
for k in groups:
uniq = {(item.kind, item.text): item for item in groups[k]}
- groups[k] = sorted(uniq.values(), key=lambda x: (x.kind, x.text))
+ if k == 4:
+ groups[k] = sorted(uniq.values(), key=lambda x: (x.kind, -x.rel_level, x.text))
+ else:
+ groups[k] = sorted(uniq.values(), key=lambda x: (x.kind, x.text))
out: list[str] = []
if future_annotations:
@@ -793,39 +743,79 @@ def normalize_import_block(
return "\n".join(out) + "\n"
+def find_missing_relative_import_targets(init_path: Path, source: str) -> list[tuple[int, str]]:
+ """Check relative import module anchors in __init__.py.
+
+ For statements like ``from .a import b``, validate that ``a`` exists as
+ either ``a.py`` or directory ``a/`` at the resolved relative location.
+ """
+ try:
+ tree = ast.parse(source)
+ except SyntaxError:
+ return []
+
+ missing: list[tuple[int, str]] = []
+ for node in tree.body:
+ if not isinstance(node, ast.ImportFrom):
+ continue
+ if node.level < 1 or not node.module:
+ continue
+ first_seg = node.module.split(".", 1)[0].strip()
+ if not first_seg:
+ continue
+
+ anchor = init_path.parent
+ for _ in range(max(node.level - 1, 0)):
+ anchor = anchor.parent
+ file_candidate = anchor / f"{first_seg}.py"
+ dir_candidate = anchor / first_seg
+ if not (file_candidate.exists() or dir_candidate.exists()):
+ target = "." * node.level + node.module
+ missing.append((node.lineno, target))
+ return missing
+
+
+def run_yapf_on_python_files(root: Path) -> tuple[int, list[str]]:
+ """Run yapf -i for all Python files under root."""
+ formatted = 0
+ errors: list[str] = []
+ for py_file in sorted(iter_python_files(root)):
+ try:
+ result = subprocess.run(
+ ["yapf", "-i", str(py_file)],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ except FileNotFoundError:
+ errors.append("yapf command not found")
+ break
+ if result.returncode != 0:
+ detail = result.stderr.strip() or result.stdout.strip() or f"exit={result.returncode}"
+ errors.append(f"{py_file}: {detail}")
+ continue
+ formatted += 1
+ return formatted, errors
+
+
def process_file(
path: Path,
stdlib_names: set[str],
project_packages: set[str],
apply: bool,
-) -> tuple[bool, bool, bool]:
- """Return (modified, has_copyright, has_module_docstring)."""
+) -> bool:
+ """Return whether file content was modified."""
source = path.read_text(encoding="utf-8")
- has_copyright = bool(COPYRIGHT_RE.search(source))
try:
tree = ast.parse(source)
except SyntaxError:
# Skip files that cannot be parsed.
- return False, has_copyright, False
-
- has_module_docstring = ast.get_docstring(tree, clean=False) is not None
- source_after_copyright, copyright_inserted = add_copyright_if_missing(source)
- if copyright_inserted:
- source = source_after_copyright
- has_copyright = True
- try:
- tree = ast.parse(source)
- except SyntaxError:
- if apply:
- path.write_text(source, encoding="utf-8")
- return True, has_copyright, has_module_docstring
+ return False
import_nodes = extract_leading_import_nodes(tree)
if not import_nodes:
- if copyright_inserted and apply:
- path.write_text(source, encoding="utf-8")
- return copyright_inserted, has_copyright, has_module_docstring
+ return False
start = import_nodes[0].lineno - 1
end = import_nodes[-1].end_lineno or import_nodes[-1].lineno
@@ -850,12 +840,17 @@ def process_file(
new_lines.extend(tail_lines[leading_blank_count:])
new_source = "\n".join(new_lines) + ("\n" if source.endswith("\n") else "")
+ if path.name == "__init__.py":
+ merged_source = _merge_init_all_exports_source(new_source)
+ if merged_source is not None:
+ new_source = merged_source
+
if new_source == source:
- return False, has_copyright, has_module_docstring
+ return False
if apply:
path.write_text(new_source, encoding="utf-8")
- return True, has_copyright, has_module_docstring
+ return True
def _names_from_target(target: ast.AST) -> list[str]:
@@ -1097,9 +1092,14 @@ def run_sort_imports(root: Path, dry_run: bool) -> int:
project_packages = discover_project_packages(root)
py_files = sorted(iter_python_files(root))
modified_files: list[Path] = []
+ missing_relative_targets: list[tuple[Path, int, str]] = []
for path in py_files:
- modified, _has_copyright, _has_module_docstring = process_file(
+ source_for_check = path.read_text(encoding="utf-8")
+ if path.name == "__init__.py":
+ for lineno, target in find_missing_relative_import_targets(path, source_for_check):
+ missing_relative_targets.append((path, lineno, target))
+ modified = process_file(
path=path,
stdlib_names=stdlib_names,
project_packages=project_packages,
@@ -1112,113 +1112,20 @@ def run_sort_imports(root: Path, dry_run: bool) -> int:
print(f"[{mode}] sort-imports scanned: {len(py_files)}, modified: {len(modified_files)}")
for p in modified_files:
print(str(p))
- return 0
-
-
-def run_audit(root: Path, dry_run: bool) -> int:
- stdlib_names = set(getattr(sys, "stdlib_module_names", set()))
- project_packages = discover_project_packages(root)
- py_files = sorted(iter_python_files(root))
- no_copyright_files: list[Path] = []
- no_module_docstring_files: list[Path] = []
-
- for path in py_files:
- _modified, has_copyright, has_module_docstring = process_file(
- path=path,
- stdlib_names=stdlib_names,
- project_packages=project_packages,
- apply=False,
- )
- if not has_copyright:
- no_copyright_files.append(path)
- if not has_module_docstring:
- no_module_docstring_files.append(path)
-
- mode = "DRY_RUN" if dry_run else "APPLY"
- print(f"[{mode}] audit scanned: {len(py_files)}")
- print("Files missing copyright marker (Copyright @):")
- for p in no_copyright_files:
- print(str(p))
- print("Files missing module docstring:")
- for p in no_module_docstring_files:
- print(str(p))
- return 0
-
-
-def run_build_package_api(root: Path, dry_run: bool) -> int:
- changed_init_files = build_package_api_exports(root, apply=not dry_run)
- mode = "DRY_RUN" if dry_run else "APPLY"
- print(f"[{mode}] build-package-api updated: {len(changed_init_files)}")
- for p in changed_init_files:
- print(str(p))
- return 0
+ if missing_relative_targets:
+ print("Missing relative import module targets in __init__.py:")
+ for path, lineno, target in missing_relative_targets:
+ print(f"{path}:{lineno} [missing_relative_import_target] {target}")
+ if not dry_run:
+ formatted_count, yapf_errors = run_yapf_on_python_files(root)
+ print(f"[APPLY] yapf formatted: {formatted_count}")
+ for err in yapf_errors:
+ print(f"[yapf-error] {err}")
+ if yapf_errors:
+ return 1
-def run_sync_imports_and_package_api(root: Path, dry_run: bool) -> int:
- """Combined command: rename/fix imports + build package API + sort imports."""
- apply = not dry_run
- project_packages = discover_project_packages(root)
- py_files = sorted(iter_python_files(root))
- stdlib_names = set(getattr(sys, "stdlib_module_names", set()))
-
- created_init_files = ensure_init_files(root, apply=apply)
- # Refresh package discovery after creating missing __init__.py files.
- project_packages = discover_project_packages(root)
- py_files = sorted(iter_python_files(root))
-
- rename_map = build_private_module_rename_map(root, project_packages)
- rewritten_import_files = rewrite_imports_for_renamed_modules(
- root=root,
- py_files=py_files,
- project_packages=project_packages,
- rename_map=rename_map,
- apply=apply,
- )
- renamed_modules = apply_private_module_renames(rename_map, apply=apply)
-
- # Re-scan file list after module renames.
- py_files = sorted(iter_python_files(root))
- changed_init_files = build_package_api_exports(root, apply=apply)
-
- modified_files: list[Path] = []
- for path in py_files:
- modified, _has_copyright, _has_module_docstring = process_file(
- path=path,
- stdlib_names=stdlib_names,
- project_packages=project_packages,
- apply=apply,
- )
- if modified:
- modified_files.append(path)
-
- # Ensure __all__ follows final import order in __init__.py files.
- merged_init_files: list[Path] = []
- for package_dir in iter_package_dirs(root):
- init_path = package_dir / "__init__.py"
- if merge_init_all_exports(init_path, apply=apply):
- merged_init_files.append(init_path)
-
- mode = "DRY_RUN" if dry_run else "APPLY"
- print(f"[{mode}] sync-imports-package-api")
- print(f"Created __init__.py files: {len(created_init_files)}")
- for p in created_init_files:
- print(str(p))
- print(f"Import files rewritten: {len(rewritten_import_files)}")
- for p in rewritten_import_files:
- print(str(p))
- print(f"Modules renamed: {len(renamed_modules)}")
- for old_path, new_path in renamed_modules:
- print(f"{old_path} -> {new_path}")
- print(f"Package __init__.py refreshed: {len(changed_init_files)}")
- for p in changed_init_files:
- print(str(p))
- print(f"Python files normalized: {len(modified_files)}")
- for p in modified_files:
- print(str(p))
- print(f"__init__.py __all__ merged: {len(merged_init_files)}")
- for p in merged_init_files:
- print(str(p))
- return 0
+ return 1 if missing_relative_targets else 0
def run_report_private_candidates(root: Path, dry_run: bool) -> int:
@@ -1231,37 +1138,6 @@ def run_report_private_candidates(root: Path, dry_run: bool) -> int:
return 0
-def run_rename_private_modules(root: Path, dry_run: bool, build_package_api: bool) -> int:
- project_packages = discover_project_packages(root)
- py_files = sorted(iter_python_files(root))
- rename_map = build_private_module_rename_map(root, project_packages)
- rewritten_import_files = rewrite_imports_for_renamed_modules(
- root=root,
- py_files=py_files,
- project_packages=project_packages,
- rename_map=rename_map,
- apply=not dry_run,
- )
- renamed_modules = apply_private_module_renames(rename_map, apply=not dry_run)
- changed_init_files: list[Path] = []
- if build_package_api:
- changed_init_files = build_package_api_exports(root, apply=not dry_run)
-
- mode = "DRY_RUN" if dry_run else "APPLY"
- print(f"[{mode}] rename-private-modules")
- print(f"Import files rewritten: {len(rewritten_import_files)}")
- for p in rewritten_import_files:
- print(str(p))
- print(f"Modules renamed: {len(renamed_modules)}")
- for old_path, new_path in renamed_modules:
- print(f"{old_path} -> {new_path}")
- if build_package_api:
- print(f"Package __init__.py refreshed: {len(changed_init_files)}")
- for p in changed_init_files:
- print(str(p))
- return 0
-
-
def run_detect_issues(root: Path, dry_run: bool) -> int:
py_files = sorted(iter_python_files(root))
all_issues: list[CheckIssue] = []
@@ -1304,34 +1180,10 @@ def main() -> int:
p_sort.add_argument("--root", default=".", help="Project root directory.")
p_sort.add_argument("--dry-run", action="store_true", help="Preview changes without writing files.")
- p_audit = subparsers.add_parser("audit", help="Report missing copyright/docstring files.")
- p_audit.add_argument("--root", default=".", help="Project root directory.")
- p_audit.add_argument("--dry-run", action="store_true", help="Read-only mode (same output).")
-
- p_api = subparsers.add_parser("build-package-api", help="Refresh package __init__.py export blocks.")
- p_api.add_argument("--root", default=".", help="Project root directory.")
- p_api.add_argument("--dry-run", action="store_true", help="Preview changes without writing files.")
-
- p_sync = subparsers.add_parser(
- "sync-imports-package-api",
- help="Run rename/import-fix + build-package-api + sort-imports in one command.",
- )
- p_sync.add_argument("--root", default=".", help="Project root directory.")
- p_sync.add_argument("--dry-run", action="store_true", help="Preview changes without writing files.")
-
p_report = subparsers.add_parser("report-private-candidates", help="List foo.py -> _foo.py candidates.")
p_report.add_argument("--root", default=".", help="Project root directory.")
p_report.add_argument("--dry-run", action="store_true", help="Read-only mode (same output).")
- p_rename = subparsers.add_parser("rename-private-modules", help="Rename modules and rewrite imports.")
- p_rename.add_argument("--root", default=".", help="Project root directory.")
- p_rename.add_argument("--dry-run", action="store_true", help="Preview changes without writing files.")
- p_rename.add_argument(
- "--build-package-api",
- action="store_true",
- help="Also refresh package __init__.py export blocks after rename.",
- )
-
p_detect = subparsers.add_parser(
"detect-issues",
help=(
@@ -1358,16 +1210,8 @@ def main() -> int:
if args.command == "sort-imports":
return run_sort_imports(root, args.dry_run)
- if args.command == "audit":
- return run_audit(root, args.dry_run)
- if args.command == "build-package-api":
- return run_build_package_api(root, args.dry_run)
- if args.command == "sync-imports-package-api":
- return run_sync_imports_and_package_api(root, args.dry_run)
if args.command == "report-private-candidates":
return run_report_private_candidates(root, args.dry_run)
- if args.command == "rename-private-modules":
- return run_rename_private_modules(root, args.dry_run, args.build_package_api)
if args.command == "detect-issues":
return run_detect_issues(root, args.dry_run)
if args.command == "check-chinese":
diff --git a/pyproject.toml b/pyproject.toml
index 09f2532..2cc41b9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -52,6 +52,7 @@ dependencies = [
"rapidfuzz>=3.0.0",
"charset-normalizer>=3.0.0",
"typer>=0.12.0", # MIT License
+ "watchdog",
]
[project.optional-dependencies]
diff --git a/tests/agents/core/test_agent_transfer_processor.py b/tests/agents/core/test_agent_transfer_processor.py
index 167315b..19d97bd 100644
--- a/tests/agents/core/test_agent_transfer_processor.py
+++ b/tests/agents/core/test_agent_transfer_processor.py
@@ -8,19 +8,26 @@
from __future__ import annotations
import asyncio
-from typing import AsyncGenerator, List
-from unittest.mock import Mock, patch
+from typing import List
+from unittest.mock import Mock
import pytest
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
from trpc_agent_sdk.agents._llm_agent import LlmAgent
-from trpc_agent_sdk.agents._base_agent import BaseAgent
from trpc_agent_sdk.agents.core._agent_transfer_processor import (
AgentTransferProcessor,
default_agent_transfer_processor,
)
from trpc_agent_sdk.context import InvocationContext, create_agent_context
-from trpc_agent_sdk.events import Event
from trpc_agent_sdk.models import LLMModel, LlmRequest, LlmResponse, ModelRegistry
from trpc_agent_sdk.sessions import InMemorySessionService
from trpc_agent_sdk.types import GenerateContentConfig
diff --git a/tests/agents/core/test_code_execution_processor.py b/tests/agents/core/test_code_execution_processor.py
index 0a93a98..46fd21f 100644
--- a/tests/agents/core/test_code_execution_processor.py
+++ b/tests/agents/core/test_code_execution_processor.py
@@ -7,8 +7,6 @@
from __future__ import annotations
-import pytest
-
from trpc_agent_sdk.agents.core._code_execution_processor import (
DataFileUtil,
_DATA_FILE_UTIL_MAP,
diff --git a/tests/agents/core/test_history_processor.py b/tests/agents/core/test_history_processor.py
index 03cb64c..22182b3 100644
--- a/tests/agents/core/test_history_processor.py
+++ b/tests/agents/core/test_history_processor.py
@@ -8,8 +8,6 @@
from __future__ import annotations
import asyncio
-from typing import List
-from unittest.mock import Mock
import pytest
diff --git a/tests/agents/core/test_llm_processor.py b/tests/agents/core/test_llm_processor.py
index d327f28..5779bea 100644
--- a/tests/agents/core/test_llm_processor.py
+++ b/tests/agents/core/test_llm_processor.py
@@ -8,8 +8,8 @@
from __future__ import annotations
import asyncio
-from typing import AsyncGenerator, List
-from unittest.mock import AsyncMock, Mock, patch
+from typing import List
+from unittest.mock import Mock
import pytest
diff --git a/tests/agents/core/test_request_processor.py b/tests/agents/core/test_request_processor.py
index 9e2e36b..e7f4d28 100644
--- a/tests/agents/core/test_request_processor.py
+++ b/tests/agents/core/test_request_processor.py
@@ -8,11 +8,18 @@
from __future__ import annotations
import asyncio
-import copy
from typing import List
-from unittest.mock import AsyncMock, Mock, patch
import pytest
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
from trpc_agent_sdk.agents._llm_agent import LlmAgent
from trpc_agent_sdk.agents.core._request_processor import (
diff --git a/tests/agents/core/test_request_processor_ext.py b/tests/agents/core/test_request_processor_ext.py
index ba25f18..db15b75 100644
--- a/tests/agents/core/test_request_processor_ext.py
+++ b/tests/agents/core/test_request_processor_ext.py
@@ -9,11 +9,19 @@
from __future__ import annotations
import asyncio
-import copy
from typing import List
-from unittest.mock import AsyncMock, MagicMock, Mock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
from trpc_agent_sdk.agents._llm_agent import LlmAgent
from trpc_agent_sdk.agents.core._request_processor import (
@@ -21,7 +29,7 @@
default_request_processor,
)
from trpc_agent_sdk.context import InvocationContext, create_agent_context
-from trpc_agent_sdk.events import Event, EventActions
+from trpc_agent_sdk.events import Event
from trpc_agent_sdk.models import LLMModel, LlmRequest, LlmResponse, ModelRegistry
from trpc_agent_sdk.sessions import InMemorySessionService
from trpc_agent_sdk.types import Content, FunctionCall, FunctionResponse, GenerateContentConfig, Part
@@ -256,7 +264,7 @@ async def test_no_skill_repository_returns_none(self, processor, ctx):
"""Returns None (no error) when agent has no skill_repository."""
ctx.agent.skill_repository = None
request = LlmRequest(model="test-rp-ext-model")
- result = await processor._add_skills_to_request(ctx.agent, ctx, request)
+ result = await processor._add_skills_to_request(ctx.agent, ctx, request, parameters={})
assert result is None
@pytest.mark.asyncio
@@ -268,7 +276,7 @@ async def test_skill_processing_error_returns_event(self, processor, ctx):
instance = MockSRP.return_value
instance.process_llm_request = AsyncMock(side_effect=RuntimeError("skill boom"))
request = LlmRequest(model="test-rp-ext-model")
- result = await processor._add_skills_to_request(ctx.agent, ctx, request)
+ result = await processor._add_skills_to_request(ctx.agent, ctx, request, parameters={})
assert result is not None
assert result.error_code == "skill_processing_error"
diff --git a/tests/agents/core/test_skill_processor.py b/tests/agents/core/test_skill_processor.py
index f850278..7968c40 100644
--- a/tests/agents/core/test_skill_processor.py
+++ b/tests/agents/core/test_skill_processor.py
@@ -3,658 +3,222 @@
# Copyright (C) 2026 Tencent. All rights reserved.
#
# tRPC-Agent-Python is licensed under Apache-2.0.
-"""Unit tests for SkillsRequestProcessor and module-level helpers."""
-from __future__ import annotations
-
-import asyncio
import json
-from typing import List
-from unittest.mock import AsyncMock, MagicMock, Mock, patch
-
-import pytest
-
-from trpc_agent_sdk.agents.core._skill_processor import (
- SKILL_LOAD_MODE_ONCE,
- SKILL_LOAD_MODE_SESSION,
- SKILL_LOAD_MODE_TURN,
- SkillsRequestProcessor,
- _default_knowledge_only_guidance,
- _default_full_tooling_and_workspace_guidance,
- _default_tooling_and_workspace_guidance,
- _is_knowledge_only,
- _normalize_custom_guidance,
- _normalize_load_mode,
- _SKILLS_LOADED_ORDER_STATE_KEY,
- _SKILLS_OVERVIEW_HEADER,
-)
-from trpc_agent_sdk.context import InvocationContext, create_agent_context
-from trpc_agent_sdk.events import EventActions
-from trpc_agent_sdk.models import LLMModel, LlmRequest, LlmResponse, ModelRegistry
-from trpc_agent_sdk.sessions import InMemorySessionService
-from trpc_agent_sdk.skills import (
- SKILL_DOCS_STATE_KEY_PREFIX,
- SKILL_LOADED_STATE_KEY_PREFIX,
- SKILL_TOOLS_STATE_KEY_PREFIX,
- BaseSkillRepository,
- Skill,
- SkillResource,
- SkillSummary,
-)
-from trpc_agent_sdk.types import GenerateContentConfig
-
-
-# ---------------------------------------------------------------------------
-# Helpers and fixtures
-# ---------------------------------------------------------------------------
-
-class _MockLLMModel(LLMModel):
- @classmethod
- def supported_models(cls) -> List[str]:
- return [r"test-sp-.*"]
-
- async def _generate_async_impl(self, request, stream=False, ctx=None):
- yield LlmResponse(content=None)
-
- def validate_request(self, request):
- pass
-
-
-class _StubRepo(BaseSkillRepository):
- """In-memory stub for BaseSkillRepository."""
-
- def __init__(self, skills=None, summaries_list=None, user_prompt_text=""):
- super().__init__(workspace_runtime=MagicMock())
- self._skills = skills or {}
- self._summaries = summaries_list or []
- self._user_prompt_text = user_prompt_text
-
- def summaries(self) -> list[SkillSummary]:
- return self._summaries
-
- def get(self, name: str) -> Skill:
- if name not in self._skills:
- raise ValueError(f"Skill not found: {name}")
- return self._skills[name]
-
- def user_prompt(self) -> str:
- return self._user_prompt_text
-
- def skill_list(self) -> list[str]:
- return list(self._skills.keys())
-
- def path(self, name: str) -> str:
- if name not in self._skills:
- raise ValueError(f"Skill not found: {name}")
- return f"/fake/skills/{name}"
-
- def refresh(self) -> None:
- pass
-
-
-@pytest.fixture(scope="module", autouse=True)
-def register_test_model():
- original_registry = ModelRegistry._registry.copy()
- ModelRegistry.register(_MockLLMModel)
- yield
- ModelRegistry._registry = original_registry
-
-
-@pytest.fixture
-def session_service():
- return InMemorySessionService()
-
-
-@pytest.fixture
-def session(session_service):
- return asyncio.run(
- session_service.create_session(app_name="test", user_id="u1", session_id="sp_sess")
- )
-
-
-@pytest.fixture
-def ctx(session_service, session):
- from trpc_agent_sdk.agents._llm_agent import LlmAgent
- agent = LlmAgent(name="skill_agent", model="test-sp-model")
- return InvocationContext(
- session_service=session_service,
- invocation_id="inv-sp-1",
- agent=agent,
- agent_context=create_agent_context(),
- session=session,
- branch="branch_sp",
- )
-
-
-@pytest.fixture
-def sample_skill():
+from copy import deepcopy
+from unittest.mock import Mock
+
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
+
+from trpc_agent_sdk.agents.core._skill_processor import SkillsRequestProcessor
+from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters
+from trpc_agent_sdk.agents.core._skill_processor import set_skill_processor_parameters
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.models import LlmRequest
+from trpc_agent_sdk.skills import Skill
+from trpc_agent_sdk.skills import SkillResource
+from trpc_agent_sdk.skills import SkillSummary
+from trpc_agent_sdk.skills import docs_key
+from trpc_agent_sdk.skills import docs_session_key
+from trpc_agent_sdk.skills import loaded_key
+from trpc_agent_sdk.skills import loaded_order_key
+from trpc_agent_sdk.skills import loaded_session_key
+from trpc_agent_sdk.skills import loaded_session_order_key
+from trpc_agent_sdk.skills import tool_key
+from trpc_agent_sdk.skills import tool_session_key
+from trpc_agent_sdk.skills._skill_config import DEFAULT_SKILL_CONFIG
+from trpc_agent_sdk.skills._skill_config import set_skill_config
+
+
+def _build_skill(name: str) -> Skill:
return Skill(
- summary=SkillSummary(name="code_review", description="Reviews code"),
- body="# Code Review\nReview PR diffs.",
- resources=[
- SkillResource(path="guide.md", content="Review guide content"),
- SkillResource(path="checklist.md", content="Checklist content"),
- ],
- tools=["lint_check", "format_code"],
- )
-
-
-@pytest.fixture
-def sample_repo(sample_skill):
- return _StubRepo(
- skills={"code_review": sample_skill},
- summaries_list=[SkillSummary(name="code_review", description="Reviews code")],
+ summary=SkillSummary(name=name, description=f"{name} description"),
+ body=f"{name} body",
+ resources=[SkillResource(path="docs/guide.md", content=f"{name} guide")],
+ tools=["tool-a", "tool-b"],
)
-# ---------------------------------------------------------------------------
-# Module-level helpers
-# ---------------------------------------------------------------------------
-
-
-class TestNormalizeLoadMode:
- def test_valid_modes(self):
- """Valid mode strings are returned as-is (lowered)."""
- assert _normalize_load_mode("once") == SKILL_LOAD_MODE_ONCE
- assert _normalize_load_mode("TURN") == SKILL_LOAD_MODE_TURN
- assert _normalize_load_mode("Session") == SKILL_LOAD_MODE_SESSION
-
- def test_invalid_mode_defaults_to_turn(self):
- """Invalid mode falls back to turn."""
- assert _normalize_load_mode("bogus") == SKILL_LOAD_MODE_TURN
-
- def test_empty_mode_defaults_to_turn(self):
- """Empty/None mode falls back to turn."""
- assert _normalize_load_mode("") == SKILL_LOAD_MODE_TURN
- assert _normalize_load_mode(None) == SKILL_LOAD_MODE_TURN
-
-
-class TestIsKnowledgeOnly:
- def test_knowledge_only_profiles(self):
- """Recognized knowledge-only profile strings return True."""
- assert _is_knowledge_only("knowledge_only") is True
- assert _is_knowledge_only("knowledge") is True
- assert _is_knowledge_only("Knowledge-Only") is True
-
- def test_non_knowledge_profiles(self):
- """Non-matching profiles return False."""
- assert _is_knowledge_only("full") is False
- assert _is_knowledge_only("") is False
- assert _is_knowledge_only(None) is False
-
-
-class TestNormalizeCustomGuidance:
- def test_empty_returns_empty(self):
- """Empty string passes through."""
- assert _normalize_custom_guidance("") == ""
-
- def test_adds_leading_newline(self):
- """Leading newline is added if missing."""
- result = _normalize_custom_guidance("hello")
- assert result.startswith("\n")
-
- def test_adds_trailing_newline(self):
- """Trailing newline is added if missing."""
- result = _normalize_custom_guidance("hello")
- assert result.endswith("\n")
-
- def test_existing_newlines_preserved(self):
- """Existing leading/trailing newlines are not doubled."""
- result = _normalize_custom_guidance("\nhello\n")
- assert result == "\nhello\n"
-
-
-class TestGuidanceTextBuilders:
- def test_knowledge_only_guidance_contains_header(self):
- """Knowledge-only guidance includes the tooling guidance header."""
- text = _default_knowledge_only_guidance()
- assert "Tooling and workspace guidance" in text
-
- def test_full_tooling_guidance_exec_enabled(self):
- """Full tooling guidance with exec tools enabled mentions skill_exec."""
- text = _default_full_tooling_and_workspace_guidance(exec_tools_disabled=False)
- assert "skill_exec" in text
-
- def test_full_tooling_guidance_exec_disabled(self):
- """Full tooling guidance with exec tools disabled omits skill_exec mention."""
- text = _default_full_tooling_and_workspace_guidance(exec_tools_disabled=True)
- assert "interactive execution is available" in text
-
- def test_default_routing_knowledge_only(self):
- """Dispatcher routes to knowledge-only guidance for matching profile."""
- text = _default_tooling_and_workspace_guidance("knowledge_only", False)
- assert "progressive disclosure" in text
-
- def test_default_routing_full(self):
- """Dispatcher routes to full guidance for non-matching profile."""
- text = _default_tooling_and_workspace_guidance("", False)
- assert "skill_run" in text
-
-
-# ---------------------------------------------------------------------------
-# SkillsRequestProcessor.__init__
-# ---------------------------------------------------------------------------
-
-
-class TestSkillsRequestProcessorInit:
- def test_defaults(self, sample_repo):
- """Default parameters are applied correctly."""
- proc = SkillsRequestProcessor(sample_repo)
- assert proc._load_mode == SKILL_LOAD_MODE_TURN
- assert proc._tool_result_mode is False
- assert proc._max_loaded_skills == 0
-
- def test_custom_parameters(self, sample_repo):
- """Custom init parameters are stored."""
- proc = SkillsRequestProcessor(
- sample_repo,
- load_mode="once",
- tooling_guidance="custom",
- tool_result_mode=True,
- tool_profile="knowledge_only",
- exec_tools_disabled=True,
- max_loaded_skills=5,
- )
- assert proc._load_mode == SKILL_LOAD_MODE_ONCE
- assert proc._tooling_guidance == "custom"
- assert proc._tool_result_mode is True
- assert proc._tool_profile == "knowledge_only"
- assert proc._exec_tools_disabled is True
- assert proc._max_loaded_skills == 5
-
-
-# ---------------------------------------------------------------------------
-# _get_repository
-# ---------------------------------------------------------------------------
-
-
-class TestGetRepository:
- def test_returns_default_repo(self, sample_repo):
- """Returns default repository when no resolver is set."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx_mock = MagicMock()
- assert proc._get_repository(ctx_mock) is sample_repo
-
- def test_resolver_overrides(self, sample_repo):
- """Repo resolver takes precedence over the default repository."""
- other_repo = _StubRepo()
- proc = SkillsRequestProcessor(sample_repo, repo_resolver=lambda c: other_repo)
- ctx_mock = MagicMock()
- assert proc._get_repository(ctx_mock) is other_repo
-
-
-# ---------------------------------------------------------------------------
-# _snapshot_state / _read_state
-# ---------------------------------------------------------------------------
-
-
-class TestStateHelpers:
- def test_snapshot_merges_delta(self, ctx, sample_repo):
- """Snapshot merges session state with pending delta."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state["key_a"] = "from_session"
- ctx.actions.state_delta["key_b"] = "from_delta"
- snap = proc._snapshot_state(ctx)
- assert snap["key_a"] == "from_session"
- assert snap["key_b"] == "from_delta"
-
- def test_snapshot_delta_none_removes_key(self, ctx, sample_repo):
- """Delta value of None removes the key from snapshot."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state["key_a"] = "exists"
- ctx.actions.state_delta["key_a"] = None
- snap = proc._snapshot_state(ctx)
- assert "key_a" not in snap
-
- def test_read_state_from_delta(self, ctx, sample_repo):
- """read_state prefers delta over session state."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state["k"] = "old"
- ctx.actions.state_delta["k"] = "new"
- assert proc._read_state(ctx, "k") == "new"
-
- def test_read_state_from_session(self, ctx, sample_repo):
- """read_state falls back to session state when delta has no key."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state["k"] = "val"
- assert proc._read_state(ctx, "k") == "val"
-
- def test_read_state_default(self, ctx, sample_repo):
- """read_state returns default when key not in delta or session."""
- proc = SkillsRequestProcessor(sample_repo)
- assert proc._read_state(ctx, "missing", "fallback") == "fallback"
-
-
-# ---------------------------------------------------------------------------
-# _get_loaded_skills
-# ---------------------------------------------------------------------------
-
-
-class TestGetLoadedSkills:
- def test_no_loaded_skills(self, ctx, sample_repo):
- """Returns empty list when no skills are loaded."""
- proc = SkillsRequestProcessor(sample_repo)
- assert proc._get_loaded_skills(ctx) == []
-
- def test_loaded_skills_detected(self, ctx, sample_repo):
- """Skills with state key prefix are detected."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "code_review"] = "1"
- result = proc._get_loaded_skills(ctx)
- assert "code_review" in result
-
- def test_falsy_value_ignored(self, ctx, sample_repo):
- """Skills with falsy state values are not returned."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "empty_skill"] = ""
- assert proc._get_loaded_skills(ctx) == []
-
-
-# ---------------------------------------------------------------------------
-# _inject_overview
-# ---------------------------------------------------------------------------
-
-
-class TestInjectOverview:
- def test_overview_injected(self, sample_repo):
- """Overview is injected into system instruction."""
- proc = SkillsRequestProcessor(sample_repo)
- request = LlmRequest(model="test-sp-model")
- proc._inject_overview(request, sample_repo)
- sys_instr = str(request.config.system_instruction)
- assert "code_review" in sys_instr
- assert "Reviews code" in sys_instr
-
- def test_no_summaries_no_injection(self):
- """No injection when repo has no summaries."""
- repo = _StubRepo(summaries_list=[])
- proc = SkillsRequestProcessor(repo)
- request = LlmRequest(model="test-sp-model")
- proc._inject_overview(request, repo)
- assert request.config is None or request.config.system_instruction is None
-
- def test_double_injection_guard(self, sample_repo):
- """Overview is not injected twice."""
- proc = SkillsRequestProcessor(sample_repo)
- request = LlmRequest(model="test-sp-model")
- proc._inject_overview(request, sample_repo)
- first_instr = str(request.config.system_instruction)
- proc._inject_overview(request, sample_repo)
- second_instr = str(request.config.system_instruction)
- assert first_instr == second_instr
-
- def test_user_prompt_prepended(self):
- """Repository user_prompt is prepended to overview."""
- repo = _StubRepo(
- summaries_list=[SkillSummary(name="s1", description="desc")],
- user_prompt_text="Custom prompt",
- )
- proc = SkillsRequestProcessor(repo)
- request = LlmRequest(model="test-sp-model")
- proc._inject_overview(request, repo)
- sys_instr = str(request.config.system_instruction)
- assert sys_instr.index("Custom prompt") < sys_instr.index("s1")
-
-
-# ---------------------------------------------------------------------------
-# _maybe_clear_skill_state_for_turn
-# ---------------------------------------------------------------------------
-
-
-class TestMaybeClearSkillStateForTurn:
- def test_clears_on_first_invocation(self, ctx, sample_repo):
- """State is cleared on first invocation in turn mode."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="turn")
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "sk1"] = "1"
- proc._maybe_clear_skill_state_for_turn(ctx)
- assert (SKILL_LOADED_STATE_KEY_PREFIX + "sk1") in ctx.actions.state_delta
- assert ctx.actions.state_delta[SKILL_LOADED_STATE_KEY_PREFIX + "sk1"] is None
-
- def test_no_clear_on_second_call_same_invocation(self, ctx, sample_repo):
- """State is NOT cleared on second call within same invocation."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="turn")
- proc._maybe_clear_skill_state_for_turn(ctx)
- ctx.actions.state_delta.clear()
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "sk2"] = "1"
- proc._maybe_clear_skill_state_for_turn(ctx)
- assert (SKILL_LOADED_STATE_KEY_PREFIX + "sk2") not in ctx.actions.state_delta
-
- def test_no_clear_in_session_mode(self, ctx, sample_repo):
- """No clearing in session mode."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="session")
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "sk1"] = "1"
- proc._maybe_clear_skill_state_for_turn(ctx)
- assert (SKILL_LOADED_STATE_KEY_PREFIX + "sk1") not in ctx.actions.state_delta
-
-
-# ---------------------------------------------------------------------------
-# _maybe_offload_loaded_skills
-# ---------------------------------------------------------------------------
-
-
-class TestMaybeOffloadLoadedSkills:
- def test_offloads_in_once_mode(self, ctx, sample_repo):
- """Skill state is cleared after injection in once mode."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="once")
- proc._maybe_offload_loaded_skills(ctx, ["code_review"])
- assert ctx.actions.state_delta[SKILL_LOADED_STATE_KEY_PREFIX + "code_review"] is None
- assert ctx.actions.state_delta[SKILL_DOCS_STATE_KEY_PREFIX + "code_review"] is None
- assert ctx.actions.state_delta[SKILL_TOOLS_STATE_KEY_PREFIX + "code_review"] is None
- assert ctx.actions.state_delta[_SKILLS_LOADED_ORDER_STATE_KEY] is None
-
- def test_no_offload_in_turn_mode(self, ctx, sample_repo):
- """No offloading in turn mode."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="turn")
- proc._maybe_offload_loaded_skills(ctx, ["code_review"])
- assert SKILL_LOADED_STATE_KEY_PREFIX + "code_review" not in ctx.actions.state_delta
-
- def test_no_offload_when_empty(self, ctx, sample_repo):
- """No offloading when loaded list is empty."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="once")
- proc._maybe_offload_loaded_skills(ctx, [])
- assert len(ctx.actions.state_delta) == 0
-
-
-# ---------------------------------------------------------------------------
-# _maybe_cap_loaded_skills
-# ---------------------------------------------------------------------------
-
-
-class TestMaybeCapLoadedSkills:
- def test_no_cap_returns_all(self, ctx, sample_repo):
- """All skills returned when cap is 0 (disabled)."""
- proc = SkillsRequestProcessor(sample_repo, max_loaded_skills=0)
- result = proc._maybe_cap_loaded_skills(ctx, ["a", "b", "c"])
- assert result == ["a", "b", "c"]
-
- def test_under_cap_returns_all(self, ctx, sample_repo):
- """All skills returned when count is at or under cap."""
- proc = SkillsRequestProcessor(sample_repo, max_loaded_skills=5)
- result = proc._maybe_cap_loaded_skills(ctx, ["a", "b"])
- assert result == ["a", "b"]
-
- def test_over_cap_evicts_oldest(self, ctx, sample_repo):
- """Excess skills are evicted, keeping most recent."""
- proc = SkillsRequestProcessor(sample_repo, max_loaded_skills=2)
- ctx.actions.state_delta[_SKILLS_LOADED_ORDER_STATE_KEY] = json.dumps(["a", "b", "c"])
- result = proc._maybe_cap_loaded_skills(ctx, ["a", "b", "c"])
- assert len(result) == 2
- assert "a" not in result
- assert "b" in result
- assert "c" in result
-
-
-# ---------------------------------------------------------------------------
-# _build_docs_text
-# ---------------------------------------------------------------------------
-
-
-class TestBuildDocsText:
- def test_selected_docs_included(self, sample_repo, sample_skill):
- """Only selected docs are included in output."""
- proc = SkillsRequestProcessor(sample_repo)
- text = proc._build_docs_text(sample_skill, ["guide.md"])
- assert "Review guide content" in text
- assert "Checklist content" not in text
-
- def test_no_docs_returns_empty(self, sample_repo):
- """Empty string for skill with no resources."""
- proc = SkillsRequestProcessor(sample_repo)
- empty_skill = Skill(summary=SkillSummary(name="empty", description=""))
- assert proc._build_docs_text(empty_skill, ["any.md"]) == ""
-
- def test_none_skill_returns_empty(self, sample_repo):
- """None skill returns empty string."""
- proc = SkillsRequestProcessor(sample_repo)
- assert proc._build_docs_text(None, ["any.md"]) == ""
-
-
-# ---------------------------------------------------------------------------
-# _merge_into_system
-# ---------------------------------------------------------------------------
-
-
-class TestMergeIntoSystem:
- def test_appends_to_system(self, sample_repo):
- """Content is appended to system instruction."""
- proc = SkillsRequestProcessor(sample_repo)
- request = LlmRequest(model="test-sp-model")
- proc._merge_into_system(request, "extra guidance")
- assert "extra guidance" in str(request.config.system_instruction)
-
- def test_empty_content_no_op(self, sample_repo):
- """Empty string is a no-op."""
- proc = SkillsRequestProcessor(sample_repo)
- request = LlmRequest(model="test-sp-model")
- proc._merge_into_system(request, "")
- assert request.config is None or request.config.system_instruction is None
-
-
-# ---------------------------------------------------------------------------
-# _capability_guidance_text
-# ---------------------------------------------------------------------------
-
-
-class TestCapabilityGuidanceText:
- def test_non_knowledge_profile_empty(self, sample_repo):
- """Non-knowledge profile returns empty string."""
- proc = SkillsRequestProcessor(sample_repo, tool_profile="full")
- assert proc._capability_guidance_text() == ""
-
- def test_knowledge_profile_returns_guidance(self, sample_repo):
- """Knowledge-only profile returns capability guidance."""
- proc = SkillsRequestProcessor(sample_repo, tool_profile="knowledge_only")
- text = proc._capability_guidance_text()
- assert "knowledge loading only" in text
-
- def test_knowledge_profile_with_empty_guidance_suppressed(self, sample_repo):
- """Knowledge profile with explicit empty guidance suppresses capability block."""
- proc = SkillsRequestProcessor(sample_repo, tool_profile="knowledge_only", tooling_guidance="")
- assert proc._capability_guidance_text() == ""
-
-
-# ---------------------------------------------------------------------------
-# process_llm_request (integration)
-# ---------------------------------------------------------------------------
-
-
-class TestProcessLlmRequest:
- @pytest.mark.asyncio
- async def test_none_request_returns_empty(self, ctx, sample_repo):
- """Returns empty list for None request."""
- proc = SkillsRequestProcessor(sample_repo)
- result = await proc.process_llm_request(ctx, None)
- assert result == []
-
- @pytest.mark.asyncio
- async def test_none_ctx_returns_empty(self, sample_repo):
- """Returns empty list for None ctx."""
- proc = SkillsRequestProcessor(sample_repo)
- request = LlmRequest(model="test-sp-model")
- result = await proc.process_llm_request(None, request)
- assert result == []
-
- @pytest.mark.asyncio
- async def test_overview_injected_no_loaded(self, ctx, sample_repo):
- """Overview is injected even when no skills are loaded."""
- proc = SkillsRequestProcessor(sample_repo)
- request = LlmRequest(model="test-sp-model")
- result = await proc.process_llm_request(ctx, request)
- assert result == []
- assert "code_review" in str(request.config.system_instruction)
-
- @pytest.mark.asyncio
- async def test_loaded_skill_body_injected(self, ctx, sample_repo):
- """Loaded skill body is injected into system instruction."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="session")
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "code_review"] = "1"
- request = LlmRequest(model="test-sp-model")
- result = await proc.process_llm_request(ctx, request)
- assert "code_review" in result
- sys_instr = str(request.config.system_instruction)
- assert "Review PR diffs" in sys_instr
-
- @pytest.mark.asyncio
- async def test_tool_result_mode_skips_body_injection(self, ctx, sample_repo):
- """In tool_result_mode, loaded skill bodies are NOT injected."""
- proc = SkillsRequestProcessor(sample_repo, tool_result_mode=True, load_mode="session")
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "code_review"] = "1"
- request = LlmRequest(model="test-sp-model")
- result = await proc.process_llm_request(ctx, request)
- assert "code_review" in result
- sys_instr = str(request.config.system_instruction) if request.config and request.config.system_instruction else ""
- assert "Review PR diffs" not in sys_instr
-
- @pytest.mark.asyncio
- async def test_once_mode_offloads_after_injection(self, ctx, sample_repo):
- """In once mode, skill state is cleared after injection."""
- proc = SkillsRequestProcessor(sample_repo, load_mode="once")
- ctx.session.state[SKILL_LOADED_STATE_KEY_PREFIX + "code_review"] = "1"
- request = LlmRequest(model="test-sp-model")
- await proc.process_llm_request(ctx, request)
- assert ctx.actions.state_delta.get(SKILL_LOADED_STATE_KEY_PREFIX + "code_review") is None
-
- @pytest.mark.asyncio
- async def test_none_repo_returns_empty(self, ctx):
- """Returns empty list when repository resolves to None."""
- proc = SkillsRequestProcessor(
- MagicMock(),
- repo_resolver=lambda c: None,
- )
- request = LlmRequest(model="test-sp-model")
- result = await proc.process_llm_request(ctx, request)
- assert result == []
-
-
-# ---------------------------------------------------------------------------
-# _get_loaded_skill_order
-# ---------------------------------------------------------------------------
-
-
-class TestGetLoadedSkillOrder:
- def test_no_persisted_order(self, ctx, sample_repo):
- """Missing order key returns alphabetical order."""
- proc = SkillsRequestProcessor(sample_repo)
- order = proc._get_loaded_skill_order(ctx, ["beta", "alpha"])
- assert order == ["alpha", "beta"]
-
- def test_persisted_order_respected(self, ctx, sample_repo):
- """Persisted order is respected for known skills."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state[_SKILLS_LOADED_ORDER_STATE_KEY] = json.dumps(["beta", "alpha"])
- order = proc._get_loaded_skill_order(ctx, ["alpha", "beta"])
- assert order == ["beta", "alpha"]
-
- def test_new_skills_appended_alphabetically(self, ctx, sample_repo):
- """Skills not in persisted order are appended alphabetically."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state[_SKILLS_LOADED_ORDER_STATE_KEY] = json.dumps(["beta"])
- order = proc._get_loaded_skill_order(ctx, ["alpha", "beta", "gamma"])
- assert order == ["beta", "alpha", "gamma"]
-
- def test_invalid_json_falls_back(self, ctx, sample_repo):
- """Invalid JSON in order key falls back to alphabetical."""
- proc = SkillsRequestProcessor(sample_repo)
- ctx.session.state[_SKILLS_LOADED_ORDER_STATE_KEY] = "not-json"
- order = proc._get_loaded_skill_order(ctx, ["c", "a", "b"])
- assert order == ["a", "b", "c"]
+def _build_repo(skills: dict[str, Skill]) -> Mock:
+ repo = Mock()
+ repo.summaries.return_value = [skill.summary for skill in skills.values()]
+ repo.user_prompt.return_value = "repo user prompt"
+ repo.get.side_effect = lambda name: skills.get(name)
+ return repo
+
+
+def _build_ctx(state: dict, *, agent_name: str = "demo-agent", load_mode: str = "turn") -> Mock:
+ ctx = Mock(spec=InvocationContext)
+ ctx.agent_name = agent_name
+ ctx.session_state = state
+ ctx.actions = Mock()
+ ctx.actions.state_delta = {}
+ ctx.agent_context = AgentContext()
+ config = deepcopy(DEFAULT_SKILL_CONFIG)
+ config["skill_processor"]["load_mode"] = load_mode
+ set_skill_config(ctx.agent_context, config)
+ ctx.session = Mock()
+ ctx.session.state = state
+ ctx.session.events = []
+ return ctx
+
+
+class TestSkillsRequestProcessor:
+
+ async def test_injects_overview_and_loaded_content(self):
+ skill = _build_skill("demo-skill")
+ repo = _build_repo({"demo-skill": skill})
+ loaded_state_key = loaded_session_key(loaded_key("demo-agent", "demo-skill"))
+ docs_state_key = docs_session_key(docs_key("demo-agent", "demo-skill"))
+ tools_state_key = tool_session_key(tool_key("demo-agent", "demo-skill"))
+ ctx = _build_ctx({
+ loaded_state_key: True,
+ docs_state_key: json.dumps(["docs/guide.md"]),
+ tools_state_key: json.dumps(["tool-a"]),
+ }, load_mode="session")
+ request = LlmRequest(contents=[], tools_dict={})
+ processor = SkillsRequestProcessor(repo, load_mode="session")
+
+ loaded = await processor.process_llm_request(ctx, request)
+
+ assert loaded == ["demo-skill"]
+ assert request.config is not None
+ text = request.config.system_instruction
+ assert "repo user prompt" in text
+ assert "Available skills:" in text
+ assert "- demo-skill: demo-skill description" in text
+ assert "[Loaded] demo-skill" in text
+ assert "Docs loaded: docs/guide.md" in text
+ assert "[Doc] docs/guide.md" in text
+ assert "Tools selected: tool-a" in text
+
+ async def test_tool_result_mode_skips_loaded_materialization(self):
+ skill = _build_skill("demo-skill")
+ repo = _build_repo({"demo-skill": skill})
+ loaded_state_key = loaded_session_key(loaded_key("demo-agent", "demo-skill"))
+ ctx = _build_ctx({loaded_state_key: True}, load_mode="session")
+ request = LlmRequest(contents=[], tools_dict={})
+ processor = SkillsRequestProcessor(repo, tool_result_mode=True, load_mode="session")
+
+ loaded = await processor.process_llm_request(ctx, request)
+
+ assert loaded == ["demo-skill"]
+ assert request.config is not None
+ text = request.config.system_instruction
+ assert "Available skills:" in text
+ assert "[Loaded] demo-skill" not in text
+
+ async def test_once_mode_offloads_loaded_state(self):
+ skill = _build_skill("demo-skill")
+ repo = _build_repo({"demo-skill": skill})
+ ctx = _build_ctx({
+ loaded_key("demo-agent", "demo-skill"): True,
+ docs_key("demo-agent", "demo-skill"): json.dumps(["docs/guide.md"]),
+ tool_key("demo-agent", "demo-skill"): json.dumps(["tool-a"]),
+ })
+ request = LlmRequest(contents=[], tools_dict={})
+ processor = SkillsRequestProcessor(repo, load_mode="once")
+
+ await processor.process_llm_request(ctx, request)
+
+ assert ctx.actions.state_delta[loaded_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[docs_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[tool_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[loaded_order_key("demo-agent")] is None
+
+ async def test_turn_mode_clears_previous_skill_state(self):
+ skill = _build_skill("demo-skill")
+ repo = _build_repo({"demo-skill": skill})
+ ctx = _build_ctx({
+ loaded_key("demo-agent", "demo-skill"): True,
+ docs_key("demo-agent", "demo-skill"): json.dumps(["docs/guide.md"]),
+ tool_key("demo-agent", "demo-skill"): json.dumps(["tool-a"]),
+ loaded_order_key("demo-agent"): json.dumps(["demo-skill"]),
+ })
+ request = LlmRequest(contents=[], tools_dict={})
+ processor = SkillsRequestProcessor(repo, load_mode="turn")
+
+ loaded = await processor.process_llm_request(ctx, request)
+
+ assert loaded == []
+ assert ctx.actions.state_delta[loaded_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[docs_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[tool_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[loaded_order_key("demo-agent")] is None
+ assert ctx.agent_context.get_metadata("processor:skills:turn_init") is True
+
+ async def test_session_mode_uses_temp_only_state(self):
+ skill = _build_skill("demo-skill")
+ repo = _build_repo({"demo-skill": skill})
+ loaded_state_key = loaded_session_key(loaded_key("demo-agent", "demo-skill"))
+ docs_state_key = docs_session_key(docs_key("demo-agent", "demo-skill"))
+ tools_state_key = tool_session_key(tool_key("demo-agent", "demo-skill"))
+ session_order_key = loaded_session_order_key(loaded_order_key("demo-agent"))
+ ctx = _build_ctx({
+ loaded_state_key: True,
+ docs_state_key: json.dumps(["docs/guide.md"]),
+ tools_state_key: json.dumps(["tool-a"]),
+ session_order_key: json.dumps(["demo-skill"]),
+ }, load_mode="session")
+ request = LlmRequest(contents=[], tools_dict={})
+ processor = SkillsRequestProcessor(repo, load_mode="session")
+
+ loaded = await processor.process_llm_request(ctx, request)
+
+ assert loaded == ["demo-skill"]
+ assert loaded_key("demo-agent", "demo-skill") not in ctx.actions.state_delta
+ assert docs_key("demo-agent", "demo-skill") not in ctx.actions.state_delta
+ assert tool_key("demo-agent", "demo-skill") not in ctx.actions.state_delta
+
+ async def test_max_loaded_skills_evicts_lru_skills_in_session_state(self):
+ skill_a = _build_skill("skill-a")
+ skill_b = _build_skill("skill-b")
+ repo = _build_repo({"skill-a": skill_a, "skill-b": skill_b})
+ loaded_a = loaded_session_key(loaded_key("demo-agent", "skill-a"))
+ loaded_b = loaded_session_key(loaded_key("demo-agent", "skill-b"))
+ docs_a = docs_session_key(docs_key("demo-agent", "skill-a"))
+ docs_b = docs_session_key(docs_key("demo-agent", "skill-b"))
+ tools_a = tool_session_key(tool_key("demo-agent", "skill-a"))
+ tools_b = tool_session_key(tool_key("demo-agent", "skill-b"))
+ order_key = loaded_session_order_key(loaded_order_key("demo-agent"))
+ ctx = _build_ctx({
+ loaded_a: True,
+ loaded_b: True,
+ docs_a: json.dumps(["docs/guide.md"]),
+ docs_b: json.dumps(["docs/guide.md"]),
+ tools_a: json.dumps(["tool-a"]),
+ tools_b: json.dumps(["tool-a"]),
+ order_key: json.dumps(["skill-a", "skill-b"]),
+ }, load_mode="session")
+ request = LlmRequest(contents=[], tools_dict={})
+ processor = SkillsRequestProcessor(repo, max_loaded_skills=1, load_mode="session")
+
+ loaded = await processor.process_llm_request(ctx, request)
+
+ assert loaded == ["skill-b"]
+ assert ctx.actions.state_delta[loaded_a] is None
+ assert ctx.actions.state_delta[docs_a] is None
+ assert ctx.actions.state_delta[tools_a] is None
+ assert ctx.actions.state_delta[order_key] == json.dumps(["skill-b"])
+
+
+class TestSkillProcessorParameters:
+
+ def test_set_and_get_skill_processor_parameters(self):
+ agent_context = AgentContext()
+ parameters = {"load_mode": "session", "max_loaded_skills": 3}
+
+ set_skill_processor_parameters(agent_context, parameters)
+ got = get_skill_processor_parameters(agent_context)
+
+ assert got["load_mode"] == "session"
+ assert got["max_loaded_skills"] == 3
diff --git a/tests/agents/core/test_skill_tool_result_processor.py b/tests/agents/core/test_skill_tool_result_processor.py
new file mode 100644
index 0000000..b635677
--- /dev/null
+++ b/tests/agents/core/test_skill_tool_result_processor.py
@@ -0,0 +1,136 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+import json
+from copy import deepcopy
+from unittest.mock import Mock
+
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
+
+from trpc_agent_sdk.agents.core._skills_tool_result_processor import SkillsToolResultRequestProcessor
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.models import LlmRequest
+from trpc_agent_sdk.skills import Skill
+from trpc_agent_sdk.skills import SkillResource
+from trpc_agent_sdk.skills import SkillSummary
+from trpc_agent_sdk.skills import SkillToolsNames
+from trpc_agent_sdk.skills import docs_key
+from trpc_agent_sdk.skills import loaded_key
+from trpc_agent_sdk.skills import loaded_order_key
+from trpc_agent_sdk.skills._skill_config import DEFAULT_SKILL_CONFIG
+from trpc_agent_sdk.skills._skill_config import set_skill_config
+from trpc_agent_sdk.types import Content
+from trpc_agent_sdk.types import Part
+
+
+def _build_context(agent_name: str, state: dict, *, load_mode: str = "turn") -> Mock:
+ ctx = Mock(spec=InvocationContext)
+ ctx.agent_name = agent_name
+ ctx.session_state = state
+ ctx.actions = Mock()
+ ctx.actions.state_delta = {}
+ ctx.agent_context = AgentContext()
+ config = deepcopy(DEFAULT_SKILL_CONFIG)
+ config["skill_processor"]["load_mode"] = load_mode
+ set_skill_config(ctx.agent_context, config)
+ return ctx
+
+
+def _build_skill() -> Skill:
+ return Skill(
+ summary=SkillSummary(name="demo-skill", description="demo"),
+ body="Use this skill body.",
+ resources=[SkillResource(path="docs/guide.md", content="Guide content.")],
+ )
+
+
+class TestSkillsToolResultRequestProcessor:
+
+ async def test_materialize_tool_result_from_skill_load(self):
+ repo = Mock()
+ repo.get.return_value = _build_skill()
+
+ ctx = _build_context(
+ "demo-agent",
+ {
+ loaded_key("demo-agent", "demo-skill"): True,
+ docs_key("demo-agent", "demo-skill"): json.dumps(["docs/guide.md"]),
+ },
+ )
+ processor = SkillsToolResultRequestProcessor(repo)
+
+ call_part = Part.from_function_call(name=SkillToolsNames.LOAD, args={"skill": "demo-skill"})
+ call_part.function_call.id = "call_1"
+ response_part = Part.from_function_response(name=SkillToolsNames.LOAD, response={"result": "skill 'demo-skill' loaded"})
+ response_part.function_response.id = "call_1"
+ request = LlmRequest(
+ contents=[
+ Content(role="model", parts=[call_part]),
+ Content(role="user", parts=[response_part]),
+ ],
+ tools_dict={},
+ )
+
+ loaded = await processor.process_llm_request(ctx, request)
+
+ assert loaded == ["demo-skill"]
+ result = response_part.function_response.response["result"]
+ assert "[Loaded] demo-skill" in result
+ assert "Docs loaded: docs/guide.md" in result
+ assert "[Doc] docs/guide.md" in result
+
+ async def test_fallback_to_system_instruction_when_tool_result_missing(self):
+ repo = Mock()
+ repo.get.return_value = _build_skill()
+ ctx = _build_context(
+ "demo-agent",
+ {loaded_key("demo-agent", "demo-skill"): True},
+ )
+ processor = SkillsToolResultRequestProcessor(repo)
+ request = LlmRequest(contents=[Content(role="user", parts=[Part.from_text(text="hello")])], tools_dict={})
+
+ await processor.process_llm_request(ctx, request)
+
+ assert request.config is not None
+ assert "Loaded skill context:" in request.config.system_instruction
+ assert "[Loaded] demo-skill" in request.config.system_instruction
+
+ async def test_once_mode_offloads_loaded_skill_state(self):
+ repo = Mock()
+ repo.get.return_value = _build_skill()
+ state = {
+ loaded_key("demo-agent", "demo-skill"): True,
+ docs_key("demo-agent", "demo-skill"): json.dumps(["docs/guide.md"]),
+ }
+ ctx = _build_context("demo-agent", state, load_mode="once")
+ processor = SkillsToolResultRequestProcessor(repo)
+
+ call_part = Part.from_function_call(name=SkillToolsNames.LOAD, args={"skill": "demo-skill"})
+ call_part.function_call.id = "call_1"
+ response_part = Part.from_function_response(name=SkillToolsNames.LOAD, response={"result": "skill 'demo-skill' loaded"})
+ response_part.function_response.id = "call_1"
+ request = LlmRequest(
+ contents=[
+ Content(role="model", parts=[call_part]),
+ Content(role="user", parts=[response_part]),
+ ],
+ tools_dict={},
+ )
+
+ await processor.process_llm_request(ctx, request)
+
+ assert ctx.actions.state_delta[loaded_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[docs_key("demo-agent", "demo-skill")] is None
+ assert ctx.actions.state_delta[loaded_order_key("demo-agent")] is None
diff --git a/tests/agents/core/test_tools_processor.py b/tests/agents/core/test_tools_processor.py
index a7c49d5..5ebe512 100644
--- a/tests/agents/core/test_tools_processor.py
+++ b/tests/agents/core/test_tools_processor.py
@@ -12,6 +12,15 @@
from unittest.mock import AsyncMock, Mock, patch
import pytest
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
from trpc_agent_sdk.agents._base_agent import BaseAgent
from trpc_agent_sdk.agents.core._tools_processor import ToolsProcessor
diff --git a/tests/agents/core/test_workspace_exec_processor.py b/tests/agents/core/test_workspace_exec_processor.py
new file mode 100644
index 0000000..4fa100e
--- /dev/null
+++ b/tests/agents/core/test_workspace_exec_processor.py
@@ -0,0 +1,127 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from unittest.mock import Mock
+
+import trpc_agent_sdk.skills as _skills_pkg
+
+if not hasattr(_skills_pkg, "get_skill_processor_parameters"):
+
+ def _compat_get_skill_processor_parameters(agent_context):
+ from trpc_agent_sdk.agents.core._skill_processor import get_skill_processor_parameters as _impl
+ return _impl(agent_context)
+
+ _skills_pkg.get_skill_processor_parameters = _compat_get_skill_processor_parameters
+
+from trpc_agent_sdk.agents.core._workspace_exec_processor import WorkspaceExecRequestProcessor
+from trpc_agent_sdk.agents.core._workspace_exec_processor import get_workspace_exec_processor_parameters
+from trpc_agent_sdk.agents.core._workspace_exec_processor import set_workspace_exec_processor_parameters
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.models import LlmRequest
+
+
+def _build_ctx() -> Mock:
+ ctx = Mock(spec=InvocationContext)
+ ctx.agent_name = "demo-agent"
+ return ctx
+
+
+def _build_request_with_tools(*tool_names: str) -> LlmRequest:
+ request = LlmRequest(contents=[], tools_dict={})
+ config = Mock()
+ config.system_instruction = ""
+ config.tools = []
+ for name in tool_names:
+ declaration = Mock()
+ declaration.name = name
+ tool = Mock()
+ tool.function_declarations = [declaration]
+ config.tools.append(tool)
+ request.config = config
+ return request
+
+
+class TestWorkspaceExecRequestProcessor:
+
+ async def test_injects_guidance_when_workspace_exec_present(self):
+ processor = WorkspaceExecRequestProcessor()
+ ctx = _build_ctx()
+ request = _build_request_with_tools("workspace_exec")
+
+ await processor.process_llm_request(ctx, request)
+
+ assert "Executor workspace guidance:" in request.config.system_instruction
+ assert "workspace_exec" in request.config.system_instruction
+
+ async def test_does_not_duplicate_guidance_header(self):
+ processor = WorkspaceExecRequestProcessor()
+ ctx = _build_ctx()
+ request = _build_request_with_tools("workspace_exec")
+ request.config.system_instruction = "Executor workspace guidance:\nexisting"
+
+ await processor.process_llm_request(ctx, request)
+
+ assert request.config.system_instruction == "Executor workspace guidance:\nexisting"
+
+ async def test_includes_artifact_and_session_hints_when_tools_available(self):
+ processor = WorkspaceExecRequestProcessor()
+ ctx = _build_ctx()
+ request = _build_request_with_tools(
+ "workspace_exec",
+ "workspace_save_artifact",
+ "workspace_write_stdin",
+ "workspace_kill_session",
+ )
+
+ await processor.process_llm_request(ctx, request)
+
+ text = request.config.system_instruction
+ assert "workspace_save_artifact" in text
+ assert "workspace_write_stdin" in text
+ assert "workspace_kill_session" in text
+
+ async def test_includes_skills_repo_hint_via_repo_resolver(self):
+ processor = WorkspaceExecRequestProcessor(repo_resolver=lambda _ctx: object())
+ ctx = _build_ctx()
+ request = _build_request_with_tools("workspace_exec")
+
+ await processor.process_llm_request(ctx, request)
+
+ assert "Paths under skills/" in request.config.system_instruction
+
+ async def test_respects_enabled_resolver(self):
+ processor = WorkspaceExecRequestProcessor(enabled_resolver=lambda _ctx: False)
+ ctx = _build_ctx()
+ request = _build_request_with_tools("workspace_exec")
+
+ await processor.process_llm_request(ctx, request)
+
+ assert request.config.system_instruction == ""
+
+ async def test_sessions_resolver_can_enable_session_guidance_without_session_tools(self):
+ processor = WorkspaceExecRequestProcessor(sessions_resolver=lambda _ctx: True)
+ ctx = _build_ctx()
+ request = _build_request_with_tools("workspace_exec")
+
+ await processor.process_llm_request(ctx, request)
+
+ text = request.config.system_instruction
+ assert "workspace_write_stdin" in text
+ assert "workspace_kill_session" in text
+
+
+class TestWorkspaceExecProcessorParameters:
+
+ def test_set_and_get_workspace_exec_processor_parameters(self):
+ agent_context = AgentContext()
+ parameters = {"session_tools": True, "has_skills_repo": True}
+
+ set_workspace_exec_processor_parameters(agent_context, parameters)
+ got = get_workspace_exec_processor_parameters(agent_context)
+
+ assert got["session_tools"] is True
+ assert got["has_skills_repo"] is True
diff --git a/tests/skills/__init__.py b/tests/skills/__init__.py
index e69de29..8b13789 100644
--- a/tests/skills/__init__.py
+++ b/tests/skills/__init__.py
@@ -0,0 +1 @@
+
diff --git a/tests/skills/stager/__init__.py b/tests/skills/stager/__init__.py
index e69de29..8b13789 100644
--- a/tests/skills/stager/__init__.py
+++ b/tests/skills/stager/__init__.py
@@ -0,0 +1 @@
+
diff --git a/tests/skills/stager/test_base_stager.py b/tests/skills/stager/test_base_stager.py
index c5a8a00..aecc774 100644
--- a/tests/skills/stager/test_base_stager.py
+++ b/tests/skills/stager/test_base_stager.py
@@ -67,14 +67,13 @@ def _make_repository(path="/skills/test-skill"):
return repo
-def _make_request(skill_name="test-skill", runtime=None, repo=None, ws=None, ctx=None):
+def _make_request(skill_name="test-skill", repo=None, ws=None, ctx=None):
from trpc_agent_sdk.skills.stager._types import SkillStageRequest
return SkillStageRequest(
skill_name=skill_name,
repository=repo or _make_repository(),
workspace=ws or _make_workspace(),
ctx=ctx or _make_ctx(),
- engine=runtime,
)
@@ -262,7 +261,7 @@ class TestStageSkill:
async def test_fresh_staging(self, mock_digest):
stager = Stager()
request = _make_request()
- runtime = request.engine or request.repository.workspace_runtime
+ runtime = request.repository.workspace_runtime
mock_file = MagicMock()
mock_file.content = json.dumps({"version": 1, "skills": {}})
@@ -275,7 +274,7 @@ async def test_fresh_staging(self, mock_digest):
async def test_cached_staging_with_links(self, mock_digest):
stager = Stager()
request = _make_request()
- runtime = request.engine or request.repository.workspace_runtime
+ runtime = request.repository.workspace_runtime
md_data = {
"version": 1,
diff --git a/tests/skills/stager/test_types.py b/tests/skills/stager/test_types.py
index efef3ee..b269c9c 100644
--- a/tests/skills/stager/test_types.py
+++ b/tests/skills/stager/test_types.py
@@ -26,7 +26,6 @@ def test_creation(self):
ctx=MagicMock(),
)
assert req.skill_name == "test"
- assert req.engine is None
assert req.timeout == 300.0
def test_custom_timeout(self):
diff --git a/tests/skills/test_common.py b/tests/skills/test_common.py
index a8f7d85..221c7f6 100644
--- a/tests/skills/test_common.py
+++ b/tests/skills/test_common.py
@@ -3,308 +3,530 @@
# Copyright (C) 2026 Tencent. All rights reserved.
#
# tRPC-Agent-Python is licensed under Apache-2.0.
-"""Unit tests for trpc_agent_sdk.skills._common.
-
-Covers:
-- SelectionMode enum
-- BaseSelectionResult model
-- get_state_delta_value
-- get_previous_selection
-- clear_selection, add_selection, replace_selection
-- set_state_delta_for_selection
-- generic_select_items (all modes, edge cases)
-- generic_get_selection (all branches)
-"""
-
-from __future__ import annotations
-
-import json
-from unittest.mock import MagicMock, Mock
import pytest
-from pydantic import BaseModel, Field
+import json
+from unittest.mock import Mock
+from pydantic import Field
from trpc_agent_sdk.skills._common import (
- BaseSelectionResult,
+ get_state_delta_value,
SelectionMode,
- add_selection,
- clear_selection,
- generic_get_selection,
- generic_select_items,
+ BaseSelectionResult,
+ append_loaded_order_state_delta,
get_previous_selection,
- get_state_delta_value,
+ clear_selection,
+ add_selection,
replace_selection,
set_state_delta_for_selection,
+ generic_select_items,
+ generic_get_selection,
)
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.skills._state_keys import loaded_order_key
-class _TestSelectionResult(BaseSelectionResult):
- """Concrete test subclass for BaseSelectionResult."""
+class MockSelectionResult(BaseSelectionResult):
+ """Mock selection result class for testing."""
selected_items: list[str] = Field(default_factory=list)
include_all: bool = Field(default=False)
-def _make_ctx(state_delta=None, session_state=None):
- ctx = MagicMock()
- ctx.actions.state_delta = state_delta or {}
- ctx.session_state = session_state or {}
- return ctx
+@pytest.fixture(autouse=True)
+def _mock_turn_load_mode(monkeypatch):
+ monkeypatch.setattr("trpc_agent_sdk.skills._common.get_skill_load_mode", lambda _ctx: "turn")
+
+
+class TestGetStateDeltaValue:
+ """Test suite for get_state_delta_value function."""
+
+ def test_get_from_state_delta(self):
+ """Test getting value from state_delta."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {"key1": "value1"}
+ mock_ctx.session_state = {"key1": "old_value"}
+ result = get_state_delta_value(mock_ctx, "key1")
+
+ assert result == "value1"
+
+ def test_get_from_session_state(self):
+ """Test getting value from session_state when not in state_delta."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"key1": "value1"}
+
+ result = get_state_delta_value(mock_ctx, "key1")
+
+ assert result == "value1"
+
+ def test_get_nonexistent_key(self):
+ """Test getting nonexistent key returns None."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {}
+
+ result = get_state_delta_value(mock_ctx, "nonexistent")
+
+ assert result is None
-# ---------------------------------------------------------------------------
-# SelectionMode
-# ---------------------------------------------------------------------------
class TestSelectionMode:
- def test_values(self):
- assert SelectionMode.ADD == "add"
- assert SelectionMode.REPLACE == "replace"
- assert SelectionMode.CLEAR == "clear"
+ """Test suite for SelectionMode enum."""
- def test_from_string(self):
+ def test_selection_mode_values(self):
+ """Test SelectionMode enum values."""
+ assert SelectionMode.ADD.value == "add"
+ assert SelectionMode.REPLACE.value == "replace"
+ assert SelectionMode.CLEAR.value == "clear"
+
+ def test_selection_mode_from_string(self):
+ """Test creating SelectionMode from string."""
assert SelectionMode("add") == SelectionMode.ADD
+ assert SelectionMode("replace") == SelectionMode.REPLACE
+ assert SelectionMode("clear") == SelectionMode.CLEAR
+ def test_selection_mode_invalid_string(self):
+ """Test invalid string raises ValueError."""
+ with pytest.raises(ValueError):
+ SelectionMode("invalid")
-# ---------------------------------------------------------------------------
-# get_state_delta_value
-# ---------------------------------------------------------------------------
-class TestGetStateDeltaValue:
- def test_from_state_delta(self):
- ctx = _make_ctx(state_delta={"key": "delta_value"})
- assert get_state_delta_value(ctx, "key") == "delta_value"
+class TestBaseSelectionResult:
+ """Test suite for BaseSelectionResult class."""
- def test_from_session_state(self):
- ctx = _make_ctx(session_state={"key": "session_value"})
- assert get_state_delta_value(ctx, "key") == "session_value"
+ def test_create_base_selection_result(self):
+ """Test creating BaseSelectionResult."""
+ result = BaseSelectionResult(skill="test-skill", mode="replace")
- def test_delta_takes_precedence(self):
- ctx = _make_ctx(state_delta={"k": "delta"}, session_state={"k": "session"})
- assert get_state_delta_value(ctx, "k") == "delta"
+ assert result.skill == "test-skill"
+ assert result.mode == "replace"
- def test_missing_returns_none(self):
- ctx = _make_ctx()
- assert get_state_delta_value(ctx, "missing") is None
+ def test_default_mode(self):
+ """Test default mode is empty string."""
+ result = BaseSelectionResult(skill="test-skill")
+ assert result.mode == ""
-# ---------------------------------------------------------------------------
-# get_previous_selection
-# ---------------------------------------------------------------------------
class TestGetPreviousSelection:
- def test_no_value_returns_empty_list(self):
- ctx = _make_ctx()
- result = get_previous_selection(ctx, "prefix:", "skill")
- assert result == []
+ """Test suite for get_previous_selection function."""
+
+ def test_get_previous_selection_json(self):
+ """Test getting previous selection from JSON."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {"temp:skill:docs:test-skill": json.dumps(["doc1.md", "doc2.md"])}
+
+ result = get_previous_selection(mock_ctx, "temp:skill:docs:", "test-skill")
+
+ assert result == ["doc1.md", "doc2.md"]
+
+ def test_get_previous_selection_all(self):
+ """Test getting previous selection when all items selected."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {"temp:skill:docs:test-skill": '*'}
+
+ result = get_previous_selection(mock_ctx, "temp:skill:docs:", "test-skill")
- def test_star_returns_none(self):
- ctx = _make_ctx(session_state={"prefix:skill": "*"})
- result = get_previous_selection(ctx, "prefix:", "skill")
assert result is None
- def test_json_array(self):
- ctx = _make_ctx(session_state={"prefix:skill": json.dumps(["a", "b"])})
- result = get_previous_selection(ctx, "prefix:", "skill")
- assert result == ["a", "b"]
+ def test_get_previous_selection_not_found(self):
+ """Test getting previous selection when not found."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {}
- def test_invalid_json_returns_empty(self):
- ctx = _make_ctx(session_state={"prefix:skill": "not json"})
- result = get_previous_selection(ctx, "prefix:", "skill")
- assert result == []
+ result = get_previous_selection(mock_ctx, "temp:skill:docs:", "test-skill")
- def test_empty_string_returns_empty(self):
- ctx = _make_ctx(session_state={"prefix:skill": ""})
- result = get_previous_selection(ctx, "prefix:", "skill")
assert result == []
-# ---------------------------------------------------------------------------
-# clear_selection
-# ---------------------------------------------------------------------------
+class TestAppendLoadedOrderStateDelta:
+ """Test suite for append_loaded_order_state_delta function."""
+
+ def test_appends_to_temp_order_when_temp_exists(self):
+ mock_ctx = Mock(spec=InvocationContext)
+ temp_key = loaded_order_key("demo-agent")
+ mock_ctx.session_state = {temp_key: json.dumps(["skill-a"])}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.agent_context = Mock()
+ mock_ctx.agent_context.get_metadata = Mock(side_effect=lambda _key, default=None: default)
+
+ append_loaded_order_state_delta(mock_ctx, "demo-agent", "skill-b")
+
+ assert mock_ctx.actions.state_delta[temp_key] == json.dumps(["skill-a", "skill-b"])
+
+ def test_initializes_order_when_missing(self):
+ mock_ctx = Mock(spec=InvocationContext)
+ temp_key = loaded_order_key("demo-agent")
+ mock_ctx.session_state = {}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.agent_context = Mock()
+ mock_ctx.agent_context.get_metadata = Mock(side_effect=lambda _key, default=None: default)
+
+ append_loaded_order_state_delta(mock_ctx, "demo-agent", "skill-b")
+
+ assert mock_ctx.actions.state_delta[temp_key] == json.dumps(["skill-b"])
+
+ def test_get_previous_selection_invalid_json(self):
+ """Test getting previous selection with invalid JSON."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {"temp:skill:docs:test-skill": "invalid json"}
+
+ result = get_previous_selection(mock_ctx, "temp:skill:docs:", "test-skill")
+
+ assert result == []
+
class TestClearSelection:
- def test_clear(self):
- result = clear_selection("skill", ["a", "b"], True, ["old"], _TestSelectionResult)
- assert result.skill == "skill"
+ """Test suite for clear_selection function."""
+
+ def test_clear_selection(self):
+ """Test clearing selection."""
+ result = clear_selection(skill_name="test-skill",
+ items=["item1"],
+ include_all=False,
+ previous_items=["item1", "item2"],
+ result_class=MockSelectionResult)
+
+ assert isinstance(result, MockSelectionResult)
+ assert result.skill == "test-skill"
+ assert result.mode == "clear"
assert result.selected_items == []
assert result.include_all is False
- assert result.mode == "clear"
-
-# ---------------------------------------------------------------------------
-# add_selection
-# ---------------------------------------------------------------------------
class TestAddSelection:
- def test_add_to_empty(self):
- result = add_selection("skill", ["a", "b"], False, [], _TestSelectionResult)
- assert set(result.selected_items) == {"a", "b"}
- assert result.include_all is False
+ """Test suite for add_selection function."""
+
+ def test_add_selection(self):
+ """Test adding to selection."""
+ result = add_selection(skill_name="test-skill",
+ items=["item2", "item3"],
+ include_all=False,
+ previous_items=["item1"],
+ result_class=MockSelectionResult)
+
+ assert isinstance(result, MockSelectionResult)
+ assert result.skill == "test-skill"
assert result.mode == "add"
+ assert set(result.selected_items) == {"item1", "item2", "item3"}
+ assert result.include_all is False
- def test_add_to_existing(self):
- result = add_selection("skill", ["c"], False, ["a", "b"], _TestSelectionResult)
- assert set(result.selected_items) == {"a", "b", "c"}
-
- def test_add_deduplicate(self):
- result = add_selection("skill", ["a"], False, ["a"], _TestSelectionResult)
- assert result.selected_items == ["a"]
+ def test_add_selection_duplicates(self):
+ """Test adding selection removes duplicates."""
+ result = add_selection(skill_name="test-skill",
+ items=["item1", "item2"],
+ include_all=False,
+ previous_items=["item1"],
+ result_class=MockSelectionResult)
+
+ assert len(result.selected_items) == 2
+ assert result.selected_items.count("item1") == 1
+
+ def test_add_selection_include_all(self):
+ """Test adding selection with include_all."""
+ result = add_selection(skill_name="test-skill",
+ items=["item2"],
+ include_all=True,
+ previous_items=["item1"],
+ result_class=MockSelectionResult)
- def test_add_include_all(self):
- result = add_selection("skill", ["a"], True, ["b"], _TestSelectionResult)
assert result.selected_items == []
assert result.include_all is True
-# ---------------------------------------------------------------------------
-# replace_selection
-# ---------------------------------------------------------------------------
-
class TestReplaceSelection:
- def test_replace(self):
- result = replace_selection("skill", ["x", "y"], False, ["old"], _TestSelectionResult)
- assert result.selected_items == ["x", "y"]
+ """Test suite for replace_selection function."""
+
+ def test_replace_selection(self):
+ """Test replacing selection."""
+ result = replace_selection(skill_name="test-skill",
+ items=["item2", "item3"],
+ include_all=False,
+ previous_items=["item1"],
+ result_class=MockSelectionResult)
+
+ assert isinstance(result, MockSelectionResult)
+ assert result.skill == "test-skill"
assert result.mode == "replace"
+ assert result.selected_items == ["item2", "item3"]
+ assert result.include_all is False
+
+ def test_replace_selection_include_all(self):
+ """Test replacing selection with include_all."""
+ result = replace_selection(skill_name="test-skill",
+ items=["item2"],
+ include_all=True,
+ previous_items=["item1"],
+ result_class=MockSelectionResult)
- def test_replace_include_all(self):
- result = replace_selection("skill", ["x"], True, [], _TestSelectionResult)
assert result.selected_items == []
assert result.include_all is True
-# ---------------------------------------------------------------------------
-# set_state_delta_for_selection
-# ---------------------------------------------------------------------------
-
class TestSetStateDeltaForSelection:
- def test_sets_json_array(self):
- ctx = _make_ctx()
- result = _TestSelectionResult(skill="s", selected_items=["a", "b"], include_all=False)
- set_state_delta_for_selection(ctx, "prefix:", result)
- assert json.loads(ctx.actions.state_delta["prefix:s"]) == ["a", "b"]
+ """Test suite for set_state_delta_for_selection function."""
+
+ def test_set_state_delta_with_items(self):
+ """Test setting state delta with items."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = MockSelectionResult(skill="test-skill",
+ selected_items=["item1", "item2"],
+ include_all=False,
+ mode="replace")
+
+ set_state_delta_for_selection(mock_ctx, "temp:skill:test:", result)
+
+ key = "temp:skill:test:test-skill"
+ assert key in mock_ctx.actions.state_delta
+ assert json.loads(mock_ctx.actions.state_delta[key]) == ["item1", "item2"]
+
+ def test_set_state_delta_include_all(self):
+ """Test setting state delta with include_all."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = MockSelectionResult(skill="test-skill", selected_items=[], include_all=True, mode="replace")
+
+ set_state_delta_for_selection(mock_ctx, "temp:skill:test:", result)
- def test_sets_star_for_include_all(self):
- ctx = _make_ctx()
- result = _TestSelectionResult(skill="s", selected_items=[], include_all=True)
- set_state_delta_for_selection(ctx, "prefix:", result)
- assert ctx.actions.state_delta["prefix:s"] == "*"
+ key = "temp:skill:test:test-skill"
+ assert mock_ctx.actions.state_delta[key] == '*'
- def test_no_skill_is_noop(self):
- ctx = _make_ctx()
- result = _TestSelectionResult(skill="", selected_items=[])
- set_state_delta_for_selection(ctx, "prefix:", result)
- assert len(ctx.actions.state_delta) == 0
+ def test_set_state_delta_empty_skill(self):
+ """Test setting state delta with empty skill name does nothing."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ result = MockSelectionResult(skill="", selected_items=["item1"], include_all=False, mode="replace")
+
+ set_state_delta_for_selection(mock_ctx, "temp:skill:test:", result)
+
+ assert len(mock_ctx.actions.state_delta) == 0
-# ---------------------------------------------------------------------------
-# generic_select_items
-# ---------------------------------------------------------------------------
class TestGenericSelectItems:
- def test_replace_mode(self):
- ctx = _make_ctx()
- result = generic_select_items(
- ctx, "skill", ["a", "b"], False, "replace", "prefix:", _TestSelectionResult
- )
- assert result.selected_items == ["a", "b"]
+ """Test suite for generic_select_items function."""
+
+ def test_generic_select_items_replace(self):
+ """Test generic select items with replace mode."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = generic_select_items(tool_context=mock_ctx,
+ skill_name="test-skill",
+ items=["item1", "item2"],
+ include_all=False,
+ mode="replace",
+ state_key_prefix="temp:skill:test:",
+ result_class=MockSelectionResult)
+
+ assert isinstance(result, MockSelectionResult)
+ assert result.skill == "test-skill"
assert result.mode == "replace"
+ assert result.selected_items == ["item1", "item2"]
+
+ def test_generic_select_items_add(self):
+ """Test generic select items with add mode."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {"temp:skill:test:test-skill": json.dumps(["item1"])}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = generic_select_items(tool_context=mock_ctx,
+ skill_name="test-skill",
+ items=["item2"],
+ include_all=False,
+ mode="add",
+ state_key_prefix="temp:skill:test:",
+ result_class=MockSelectionResult)
- def test_add_mode(self):
- ctx = _make_ctx(session_state={"prefix:skill": json.dumps(["a"])})
- result = generic_select_items(
- ctx, "skill", ["b"], False, "add", "prefix:", _TestSelectionResult
- )
- assert set(result.selected_items) == {"a", "b"}
assert result.mode == "add"
+ assert set(result.selected_items) == {"item1", "item2"}
+
+ def test_generic_select_items_clear(self):
+ """Test generic select items with clear mode."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {"temp:skill:test:test-skill": json.dumps(["item1"])}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = generic_select_items(tool_context=mock_ctx,
+ skill_name="test-skill",
+ items=None,
+ include_all=False,
+ mode="clear",
+ state_key_prefix="temp:skill:test:",
+ result_class=MockSelectionResult)
- def test_clear_mode(self):
- ctx = _make_ctx(session_state={"prefix:skill": json.dumps(["a"])})
- result = generic_select_items(
- ctx, "skill", [], False, "clear", "prefix:", _TestSelectionResult
- )
- assert result.selected_items == []
assert result.mode == "clear"
+ assert result.selected_items == []
+
+ def test_generic_select_items_invalid_mode(self):
+ """Test generic select items with invalid mode defaults to replace."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = generic_select_items(tool_context=mock_ctx,
+ skill_name="test-skill",
+ items=["item1"],
+ include_all=False,
+ mode="invalid",
+ state_key_prefix="temp:skill:test:",
+ result_class=MockSelectionResult)
- def test_invalid_mode_defaults_to_replace(self):
- ctx = _make_ctx()
- result = generic_select_items(
- ctx, "skill", ["x"], False, "invalid_mode", "prefix:", _TestSelectionResult
- )
assert result.mode == "replace"
- def test_previous_star_and_not_clearing_keeps_include_all(self):
- ctx = _make_ctx(session_state={"prefix:skill": "*"})
- result = generic_select_items(
- ctx, "skill", ["a"], False, "add", "prefix:", _TestSelectionResult
- )
+ def test_generic_select_items_previous_all(self):
+ """Test generic select items when previous was all."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {"temp:skill:test:test-skill": '*'}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+
+ result = generic_select_items(tool_context=mock_ctx,
+ skill_name="test-skill",
+ items=["item1"],
+ include_all=False,
+ mode="add",
+ state_key_prefix="temp:skill:test:",
+ result_class=MockSelectionResult)
+
+ # Should maintain include_all=True
assert result.include_all is True
- def test_previous_star_and_clear(self):
- ctx = _make_ctx(session_state={"prefix:skill": "*"})
- result = generic_select_items(
- ctx, "skill", [], False, "clear", "prefix:", _TestSelectionResult
- )
- assert result.include_all is False
- assert result.selected_items == []
+ def test_generic_select_items_updates_state(self):
+ """Test generic select items updates state delta."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.session_state = {}
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
- def test_none_items_treated_as_empty(self):
- ctx = _make_ctx()
- result = generic_select_items(
- ctx, "skill", None, False, "replace", "prefix:", _TestSelectionResult
- )
- assert result.selected_items == []
-
- def test_updates_state_delta(self):
- ctx = _make_ctx()
- generic_select_items(
- ctx, "skill", ["a"], False, "replace", "prefix:", _TestSelectionResult
- )
- assert "prefix:skill" in ctx.actions.state_delta
+ result = generic_select_items(tool_context=mock_ctx,
+ skill_name="test-skill",
+ items=["item1"],
+ include_all=False,
+ mode="replace",
+ state_key_prefix="temp:skill:test:",
+ result_class=MockSelectionResult)
+ key = "temp:skill:test:test-skill"
+ assert key in mock_ctx.actions.state_delta
-# ---------------------------------------------------------------------------
-# generic_get_selection
-# ---------------------------------------------------------------------------
class TestGenericGetSelection:
- def test_no_value_returns_empty(self):
- ctx = _make_ctx()
- assert generic_get_selection(ctx, "skill", "prefix:") == []
-
- def test_json_array(self):
- ctx = _make_ctx(state_delta={"prefix:skill": json.dumps(["a", "b"])})
- assert generic_get_selection(ctx, "skill", "prefix:") == ["a", "b"]
-
- def test_star_with_callback(self):
- ctx = _make_ctx(state_delta={"prefix:skill": "*"})
- callback = Mock(return_value=["all_a", "all_b"])
- result = generic_get_selection(ctx, "skill", "prefix:", callback)
- assert result == ["all_a", "all_b"]
- callback.assert_called_once_with("skill")
-
- def test_star_without_callback(self):
- ctx = _make_ctx(state_delta={"prefix:skill": "*"})
- assert generic_get_selection(ctx, "skill", "prefix:") == []
-
- def test_star_callback_exception_returns_empty(self):
- ctx = _make_ctx(state_delta={"prefix:skill": "*"})
- callback = Mock(side_effect=RuntimeError("boom"))
- assert generic_get_selection(ctx, "skill", "prefix:", callback) == []
-
- def test_invalid_json_returns_empty(self):
- ctx = _make_ctx(state_delta={"prefix:skill": "not_json"})
- assert generic_get_selection(ctx, "skill", "prefix:") == []
-
- def test_bytes_value_decoded(self):
- ctx = _make_ctx(state_delta={"prefix:skill": json.dumps(["x"]).encode("utf-8")})
- assert generic_get_selection(ctx, "skill", "prefix:") == ["x"]
-
- def test_bytes_star_with_callback(self):
- ctx = _make_ctx(state_delta={"prefix:skill": b"*"})
- callback = Mock(return_value=["all"])
- result = generic_get_selection(ctx, "skill", "prefix:", callback)
- assert result == ["all"]
-
- def test_non_list_json_returns_empty(self):
- ctx = _make_ctx(state_delta={"prefix:skill": json.dumps({"not": "list"})})
- assert generic_get_selection(ctx, "skill", "prefix:") == []
+ """Test suite for generic_get_selection function."""
+
+ def test_generic_get_selection_json_array(self):
+ """Test getting selection from JSON array."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": json.dumps(["item1", "item2"])}
+
+ result = generic_get_selection(ctx=mock_ctx, skill_name="test-skill", state_key_prefix="temp:skill:test:")
+
+ assert result == ["item1", "item2"]
+
+ def test_generic_get_selection_all_with_callback(self):
+ """Test getting selection with '*' and callback."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": '*'}
+
+ def get_all_items(skill_name):
+ return ["item1", "item2", "item3"]
+
+ result = generic_get_selection(ctx=mock_ctx,
+ skill_name="test-skill",
+ state_key_prefix="temp:skill:test:",
+ get_all_items_callback=get_all_items)
+
+ assert result == ["item1", "item2", "item3"]
+
+ def test_generic_get_selection_all_without_callback(self):
+ """Test getting selection with '*' but no callback."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": '*'}
+
+ result = generic_get_selection(ctx=mock_ctx, skill_name="test-skill", state_key_prefix="temp:skill:test:")
+
+ assert result == []
+
+ def test_generic_get_selection_not_found(self):
+ """Test getting selection when not found."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {}
+
+ result = generic_get_selection(ctx=mock_ctx, skill_name="test-skill", state_key_prefix="temp:skill:test:")
+
+ assert result == []
+
+ def test_generic_get_selection_invalid_json(self):
+ """Test getting selection with invalid JSON."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": "invalid json"}
+
+ result = generic_get_selection(ctx=mock_ctx, skill_name="test-skill", state_key_prefix="temp:skill:test:")
+
+ assert result == []
+
+ def test_generic_get_selection_bytes_value(self):
+ """Test getting selection when value is bytes."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": json.dumps(["item1"]).encode('utf-8')}
+
+ result = generic_get_selection(ctx=mock_ctx, skill_name="test-skill", state_key_prefix="temp:skill:test:")
+
+ assert result == ["item1"]
+
+ def test_generic_get_selection_callback_exception(self):
+ """Test getting selection when callback raises exception."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": '*'}
+
+ def get_all_items_error(skill_name):
+ raise Exception("Test error")
+
+ result = generic_get_selection(ctx=mock_ctx,
+ skill_name="test-skill",
+ state_key_prefix="temp:skill:test:",
+ get_all_items_callback=get_all_items_error)
+
+ assert result == []
+
+ def test_generic_get_selection_from_state_delta(self):
+ """Test getting selection prefers state_delta over session_state."""
+ mock_ctx = Mock(spec=InvocationContext)
+ mock_ctx.actions = Mock()
+ mock_ctx.actions.state_delta = {"temp:skill:test:test-skill": json.dumps(["item_new"])}
+ mock_ctx.session_state = {"temp:skill:test:test-skill": json.dumps(["item_old"])}
+
+ result = generic_get_selection(ctx=mock_ctx, skill_name="test-skill", state_key_prefix="temp:skill:test:")
+
+ assert result == ["item_new"]
diff --git a/tests/skills/test_constants.py b/tests/skills/test_constants.py
new file mode 100644
index 0000000..26b80fa
--- /dev/null
+++ b/tests/skills/test_constants.py
@@ -0,0 +1,23 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from trpc_agent_sdk.skills._constants import SKILL_FILE
+from trpc_agent_sdk.skills._constants import SKILL_LOAD_MODE_VALUES
+from trpc_agent_sdk.skills._constants import SKILL_TOOLS_NAMES
+from trpc_agent_sdk.skills._constants import SkillLoadModeNames
+from trpc_agent_sdk.skills._constants import SkillToolsNames
+
+
+def test_skill_file_constant():
+ assert SKILL_FILE == "SKILL.md"
+
+
+def test_skill_tools_names_matches_enum():
+ assert SKILL_TOOLS_NAMES == [item.value for item in SkillToolsNames]
+
+
+def test_skill_load_mode_values_matches_enum():
+ assert SKILL_LOAD_MODE_VALUES == [item.value for item in SkillLoadModeNames]
diff --git a/tests/skills/test_dynamic_toolset.py b/tests/skills/test_dynamic_toolset.py
index 26cd3b8..df65fb8 100644
--- a/tests/skills/test_dynamic_toolset.py
+++ b/tests/skills/test_dynamic_toolset.py
@@ -23,12 +23,19 @@
import pytest
from trpc_agent_sdk.skills._dynamic_toolset import DynamicSkillToolSet
+from trpc_agent_sdk.skills._common import loaded_state_key
+from trpc_agent_sdk.skills._common import tool_state_key
+from trpc_agent_sdk.skills._constants import SKILL_CONFIG_KEY
+from trpc_agent_sdk.skills._skill_config import DEFAULT_SKILL_CONFIG
def _make_ctx(state_delta=None, session_state=None):
ctx = MagicMock()
ctx.actions.state_delta = state_delta or {}
ctx.session_state = session_state or {}
+ ctx.agent_name = ""
+ ctx.agent_context.get_metadata = MagicMock(
+ side_effect=lambda key, default=None: DEFAULT_SKILL_CONFIG if key == SKILL_CONFIG_KEY else default)
return ctx
@@ -113,10 +120,9 @@ def test_no_loaded_skills(self, *_):
def test_loaded_skills_from_session_and_delta(self, *_):
repo = _make_mock_repository()
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(
- session_state={"temp:skill:loaded:skill-a": True},
- state_delta={"temp:skill:loaded:skill-b": True},
- )
+ ctx = _make_ctx()
+ ctx.session_state = {loaded_state_key(ctx, "skill-a"): True}
+ ctx.actions.state_delta = {loaded_state_key(ctx, "skill-b"): True}
result = ts._get_loaded_skills_from_state(ctx)
assert set(result) == {"skill-a", "skill-b"}
@@ -139,7 +145,7 @@ def test_no_active_skills(self, *_):
def test_active_from_loaded(self, *_):
repo = _make_mock_repository()
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:loaded:s1": True})
+ ctx = _make_ctx(state_delta={loaded_state_key(_make_ctx(), "s1"): True})
result = ts._get_active_skills_from_delta(ctx)
assert "s1" in result
@@ -148,7 +154,7 @@ def test_active_from_loaded(self, *_):
def test_active_from_tools_modified(self, *_):
repo = _make_mock_repository()
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s2": json.dumps(["t1"])})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s2"): json.dumps(["t1"])})
result = ts._get_active_skills_from_delta(ctx)
assert "s2" in result
@@ -157,7 +163,7 @@ def test_active_from_tools_modified(self, *_):
def test_falsy_loaded_value_ignored(self, *_):
repo = _make_mock_repository()
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:loaded:s1": False})
+ ctx = _make_ctx(state_delta={loaded_state_key(_make_ctx(), "s1"): False})
assert ts._get_active_skills_from_delta(ctx) == []
@@ -173,7 +179,7 @@ def test_json_array(self, *_):
skill.tools = ["default_tool"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s1": json.dumps(["tool_a", "tool_b"])})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s1"): json.dumps(["tool_a", "tool_b"])})
result = ts._get_tools_selection(ctx, "s1")
assert result == ["tool_a", "tool_b"]
@@ -184,7 +190,7 @@ def test_star_returns_defaults(self, *_):
skill.tools = ["default_tool"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s1": "*"})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s1"): "*"})
result = ts._get_tools_selection(ctx, "s1")
assert result == ["default_tool"]
@@ -206,7 +212,7 @@ def test_invalid_json_falls_back(self, *_):
skill.tools = ["fallback"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s1": "not_json"})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s1"): "not_json"})
result = ts._get_tools_selection(ctx, "s1")
assert result == ["fallback"]
@@ -301,7 +307,7 @@ async def test_active_skills_with_tools(self, *_):
mock_tool = _make_mock_tool("my_tool")
ts._available_tools["my_tool"] = mock_tool
- ctx = _make_ctx(state_delta={"temp:skill:loaded:s1": True})
+ ctx = _make_ctx(state_delta={loaded_state_key(_make_ctx(), "s1"): True})
result = await ts.get_tools(ctx)
assert len(result) == 1
assert result[0] is mock_tool
@@ -316,7 +322,7 @@ async def test_only_active_false_uses_all_loaded(self, *_):
mock_tool = _make_mock_tool("tool_a")
ts._available_tools["tool_a"] = mock_tool
- ctx = _make_ctx(session_state={"temp:skill:loaded:s1": True})
+ ctx = _make_ctx(session_state={loaded_state_key(_make_ctx(), "s1"): True})
result = await ts.get_tools(ctx)
assert len(result) == 1
@@ -332,9 +338,10 @@ async def test_deduplicates_tools(self, *_):
mock_tool = _make_mock_tool("shared_tool")
ts._available_tools["shared_tool"] = mock_tool
+ key_ctx = _make_ctx()
ctx = _make_ctx(session_state={
- "temp:skill:loaded:s1": True,
- "temp:skill:loaded:s2": True,
+ loaded_state_key(key_ctx, "s1"): True,
+ loaded_state_key(key_ctx, "s2"): True,
})
result = await ts.get_tools(ctx)
assert len(result) == 1
@@ -349,7 +356,7 @@ async def test_fallback_to_loaded_when_no_active(self, *_):
mock_tool = _make_mock_tool("fallback_tool")
ts._available_tools["fallback_tool"] = mock_tool
- ctx = _make_ctx(session_state={"temp:skill:loaded:s1": True})
+ ctx = _make_ctx(session_state={loaded_state_key(_make_ctx(), "s1"): True})
result = await ts.get_tools(ctx)
assert len(result) == 1
@@ -360,7 +367,7 @@ async def test_unresolvable_tool_skipped(self, *_):
skill.tools = ["nonexistent_tool"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:loaded:s1": True})
+ ctx = _make_ctx(state_delta={loaded_state_key(_make_ctx(), "s1"): True})
result = await ts.get_tools(ctx)
assert len(result) == 0
@@ -371,7 +378,7 @@ async def test_no_tools_for_skill(self, *_):
skill.tools = []
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:loaded:s1": True})
+ ctx = _make_ctx(state_delta={loaded_state_key(_make_ctx(), "s1"): True})
result = await ts.get_tools(ctx)
assert result == []
@@ -439,7 +446,7 @@ def test_bytes_json_value(self, *_):
skill.tools = ["default"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s1": json.dumps(["t1"]).encode()})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s1"): json.dumps(["t1"]).encode()})
result = ts._get_tools_selection(ctx, "s1")
assert result == ["t1"]
@@ -450,7 +457,7 @@ def test_bytes_star_value(self, *_):
skill.tools = ["default"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s1": b"*"})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s1"): b"*"})
result = ts._get_tools_selection(ctx, "s1")
assert result == ["default"]
@@ -461,6 +468,6 @@ def test_non_list_json_falls_back(self, *_):
skill.tools = ["default"]
repo = _make_mock_repository({"s1": skill})
ts = DynamicSkillToolSet(skill_repository=repo)
- ctx = _make_ctx(state_delta={"temp:skill:tools:s1": json.dumps({"not": "list"})})
+ ctx = _make_ctx(state_delta={tool_state_key(_make_ctx(), "s1"): json.dumps({"not": "list"})})
result = ts._get_tools_selection(ctx, "s1")
assert result == ["default"]
diff --git a/tests/skills/test_hot_reload.py b/tests/skills/test_hot_reload.py
new file mode 100644
index 0000000..bc8411b
--- /dev/null
+++ b/tests/skills/test_hot_reload.py
@@ -0,0 +1,35 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from pathlib import Path
+
+from trpc_agent_sdk.skills._hot_reload import SkillHotReloadTracker
+
+
+def test_mark_changed_path_only_tracks_skill_file(tmp_path: Path):
+ root = tmp_path / "skills"
+ skill_dir = root / "demo"
+ skill_dir.mkdir(parents=True)
+ tracker = SkillHotReloadTracker("SKILL.md")
+
+ tracker.mark_changed_path(str(skill_dir / "notes.txt"), is_directory=False, skill_roots=[str(root)])
+ assert tracker.pop_changed_dirs(str(root.resolve())) == []
+
+ tracker.mark_changed_path(str(skill_dir / "SKILL.md"), is_directory=False, skill_roots=[str(root)])
+ changed = tracker.pop_changed_dirs(str(root.resolve()))
+ assert changed == [skill_dir.resolve()]
+
+
+def test_resolve_root_key_and_normalize_targets(tmp_path: Path):
+ root = tmp_path / "skills"
+ nested = root / "a" / "b"
+ nested.mkdir(parents=True)
+
+ key = SkillHotReloadTracker.resolve_root_key(nested, [str(root)])
+ assert key == str(root.resolve())
+
+ deduped = SkillHotReloadTracker.normalize_scan_targets([root / "a", nested, root / "c"])
+ assert deduped == [root / "a", root / "c"]
diff --git a/tests/skills/test_repository.py b/tests/skills/test_repository.py
index 22a6ad7..6f24581 100644
--- a/tests/skills/test_repository.py
+++ b/tests/skills/test_repository.py
@@ -27,11 +27,9 @@
BASE_DIR_PLACEHOLDER,
BaseSkillRepository,
FsSkillRepository,
- _is_doc_file,
- _parse_tools_from_body,
- _split_front_matter,
create_default_skill_repository,
)
+from trpc_agent_sdk.skills._utils import is_doc_file
# ---------------------------------------------------------------------------
@@ -40,54 +38,54 @@
class TestSplitFrontMatter:
def test_no_front_matter(self):
- fm, body = _split_front_matter("# Hello\nworld")
+ fm, body = FsSkillRepository.from_markdown("# Hello\nworld")
assert fm == {}
assert body == "# Hello\nworld"
def test_with_front_matter(self):
content = "---\nname: test\ndescription: Test skill\n---\n# Body"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm["name"] == "test"
assert fm["description"] == "Test skill"
assert body == "# Body"
def test_crlf_normalization(self):
content = "---\r\nname: test\r\n---\r\nbody"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm["name"] == "test"
assert body == "body"
def test_invalid_yaml_returns_empty_dict(self):
content = "---\n: : : invalid\n---\nbody"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert body == "body"
def test_non_dict_yaml_returns_empty_dict(self):
content = "---\n- item1\n- item2\n---\nbody"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm == {}
assert body == "body"
def test_unclosed_front_matter(self):
content = "---\nname: test\nno closing"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm == {}
assert body == content
def test_none_values_become_empty_string(self):
content = "---\nname:\n---\nbody"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm["name"] == ""
def test_none_key_converted_to_string(self):
content = "---\nname: test\n---\nbody"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm["name"] == "test"
assert body == "body"
def test_no_dash_prefix(self):
content = "no front matter at all"
- fm, body = _split_front_matter(content)
+ fm, body = FsSkillRepository.from_markdown(content)
assert fm == {}
assert body == content
@@ -99,29 +97,29 @@ def test_no_dash_prefix(self):
class TestParseToolsFromBody:
def test_basic_tools_section(self):
body = "Tools:\n- tool_a\n- tool_b\n\nOverview"
- tools = _parse_tools_from_body(body)
+ tools = FsSkillRepository._parse_tools_from_body(body)
assert tools == ["tool_a", "tool_b"]
def test_no_tools_section(self):
body = "# Just markdown\nNo tools here"
- assert _parse_tools_from_body(body) == []
+ assert FsSkillRepository._parse_tools_from_body(body) == []
def test_tools_section_stops_at_next_section(self):
body = "Tools:\n- tool_a\nOverview\nMore content"
- tools = _parse_tools_from_body(body)
+ tools = FsSkillRepository._parse_tools_from_body(body)
assert tools == ["tool_a"]
def test_tools_section_skips_headings(self):
body = "Tools:\n# Comment\n- tool_a\n"
- tools = _parse_tools_from_body(body)
+ tools = FsSkillRepository._parse_tools_from_body(body)
assert tools == ["tool_a"]
def test_empty_body(self):
- assert _parse_tools_from_body("") == []
+ assert FsSkillRepository._parse_tools_from_body("") == []
def test_tools_with_description_colon(self):
body = "Tools:\n- tool_a\nDescription: something\n"
- tools = _parse_tools_from_body(body)
+ tools = FsSkillRepository._parse_tools_from_body(body)
assert tools == ["tool_a"]
@@ -131,16 +129,16 @@ def test_tools_with_description_colon(self):
class TestIsDocFile:
def test_markdown(self):
- assert _is_doc_file("readme.md") is True
- assert _is_doc_file("README.MD") is True
+ assert is_doc_file("readme.md") is True
+ assert is_doc_file("README.MD") is True
def test_text(self):
- assert _is_doc_file("notes.txt") is True
- assert _is_doc_file("NOTES.TXT") is True
+ assert is_doc_file("notes.txt") is True
+ assert is_doc_file("NOTES.TXT") is True
def test_non_doc(self):
- assert _is_doc_file("script.py") is False
- assert _is_doc_file("data.json") is False
+ assert is_doc_file("script.py") is False
+ assert is_doc_file("data.json") is False
# ---------------------------------------------------------------------------
@@ -374,10 +372,42 @@ def test_read_docs_error_handling(self, tmp_path):
class TestBaseSkillRepositoryAbstract:
def test_user_prompt_default(self):
- repo = MagicMock(spec=BaseSkillRepository)
- BaseSkillRepository.user_prompt(repo)
+ class _Repo(BaseSkillRepository):
+ def summaries(self):
+ return []
+
+ def get(self, name: str):
+ raise ValueError(name)
+
+ def skill_list(self, mode: str = "all"):
+ return []
+
+ def path(self, name: str) -> str:
+ return ""
+
+ def refresh(self) -> None:
+ return None
+
+ repo = _Repo(workspace_runtime=MagicMock())
+ assert BaseSkillRepository.user_prompt(repo) == ""
def test_skill_run_env_default(self):
- repo = MagicMock(spec=BaseSkillRepository)
+ class _Repo(BaseSkillRepository):
+ def summaries(self):
+ return []
+
+ def get(self, name: str):
+ raise ValueError(name)
+
+ def skill_list(self, mode: str = "all"):
+ return []
+
+ def path(self, name: str) -> str:
+ return ""
+
+ def refresh(self) -> None:
+ return None
+
+ repo = _Repo(workspace_runtime=MagicMock())
result = BaseSkillRepository.skill_run_env(repo, "skill")
assert result == {}
diff --git a/tests/skills/test_run_tool.py b/tests/skills/test_run_tool.py
deleted file mode 100644
index 9e4f577..0000000
--- a/tests/skills/test_run_tool.py
+++ /dev/null
@@ -1,364 +0,0 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
-#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
-
-from unittest.mock import AsyncMock
-from unittest.mock import Mock
-from unittest.mock import patch
-
-import pytest
-from trpc_agent_sdk.code_executors import BaseProgramRunner
-from trpc_agent_sdk.code_executors import BaseWorkspaceFS
-from trpc_agent_sdk.code_executors import BaseWorkspaceManager
-from trpc_agent_sdk.code_executors import BaseWorkspaceRuntime
-from trpc_agent_sdk.code_executors import CodeFile
-from trpc_agent_sdk.code_executors import WorkspaceInfo
-from trpc_agent_sdk.code_executors import WorkspaceRunResult
-from trpc_agent_sdk.context import InvocationContext
-from trpc_agent_sdk.skills import BaseSkillRepository
-from trpc_agent_sdk.skills.tools import ArtifactInfo
-from trpc_agent_sdk.skills.tools import SkillRunFile
-from trpc_agent_sdk.skills.tools import SkillRunInput
-from trpc_agent_sdk.skills.tools import SkillRunOutput
-from trpc_agent_sdk.skills.tools import SkillRunTool
-from trpc_agent_sdk.skills.tools._skill_run import _inline_json_schema_refs
-
-
-class TestInlineJsonSchemaRefs:
- """Test suite for _inline_json_schema_refs function."""
-
- def test_inline_json_schema_refs_no_refs(self):
- """Test inlining schema with no $ref references."""
- schema = {
- "type": "object",
- "properties": {
- "name": {"type": "string"}
- }
- }
-
- result = _inline_json_schema_refs(schema)
-
- assert result == schema
-
- def test_inline_json_schema_refs_with_refs(self):
- """Test inlining schema with $ref references."""
- schema = {
- "type": "object",
- "properties": {
- "item": {"$ref": "#/$defs/Item"}
- },
- "$defs": {
- "Item": {
- "type": "object",
- "properties": {
- "name": {"type": "string"}
- }
- }
- }
- }
-
- result = _inline_json_schema_refs(schema)
-
- assert "$defs" not in result
- assert "$ref" not in str(result)
- assert "name" in str(result)
-
- def test_inline_json_schema_refs_nested_refs(self):
- """Test inlining schema with nested $ref references."""
- schema = {
- "type": "object",
- "properties": {
- "item": {"$ref": "#/$defs/Item"}
- },
- "$defs": {
- "Item": {
- "type": "object",
- "properties": {
- "nested": {"$ref": "#/$defs/Nested"}
- }
- },
- "Nested": {
- "type": "string"
- }
- }
- }
-
- result = _inline_json_schema_refs(schema)
-
- assert "$defs" not in result
- assert "$ref" not in str(result)
-
-
-class TestSkillRunInput:
- """Test suite for SkillRunInput class."""
-
- def test_create_skill_run_input(self):
- """Test creating skill run input."""
- input_data = SkillRunInput(
- skill="test-skill",
- command="python script.py",
- cwd="work",
- env={"VAR": "value"},
- output_files=["out/*.txt"],
- timeout=30,
- save_as_artifacts=True,
- )
-
- assert input_data.skill == "test-skill"
- assert input_data.command == "python script.py"
- assert input_data.cwd == "work"
- assert input_data.env == {"VAR": "value"}
- assert input_data.output_files == ["out/*.txt"]
- assert input_data.timeout == 30
- assert input_data.save_as_artifacts is True
-
- def test_create_skill_run_input_defaults(self):
- """Test creating skill run input with defaults."""
- input_data = SkillRunInput(skill="test-skill", command="echo hello")
-
- assert input_data.skill == "test-skill"
- assert input_data.command == "echo hello"
- assert input_data.cwd == ""
- assert input_data.env == {}
- assert input_data.output_files == []
- assert input_data.timeout == 0
- assert input_data.save_as_artifacts is False
-
-
-class TestSkillRunOutput:
- """Test suite for SkillRunOutput class."""
-
- def test_create_skill_run_output(self):
- """Test creating skill run output."""
- output_files = [SkillRunFile(name="output.txt", content="content", mime_type="text/plain")]
- artifact_files = [ArtifactInfo(name="artifact.txt", version=1)]
-
- output = SkillRunOutput(
- stdout="output",
- stderr="error",
- exit_code=0,
- timed_out=False,
- duration_ms=1000,
- output_files=output_files,
- artifact_files=artifact_files,
- )
-
- assert output.stdout == "output"
- assert output.stderr == "error"
- assert output.exit_code == 0
- assert output.timed_out is False
- assert output.duration_ms == 1000
- assert len(output.output_files) == 1
- assert len(output.artifact_files) == 1
-
- def test_create_skill_run_output_defaults(self):
- """Test creating skill run output with defaults."""
- output = SkillRunOutput()
-
- assert output.stdout == ""
- assert output.stderr == ""
- assert output.exit_code == 0
- assert output.timed_out is False
- assert output.duration_ms == 0
- assert output.output_files == []
- assert output.artifact_files == []
-
-
-class TestArtifactInfo:
- """Test suite for ArtifactInfo class."""
-
- def test_create_artifact_info(self):
- """Test creating artifact info."""
- info = ArtifactInfo(name="artifact.txt", version=1)
-
- assert info.name == "artifact.txt"
- assert info.version == 1
-
- def test_create_artifact_info_defaults(self):
- """Test creating artifact info with defaults."""
- info = ArtifactInfo()
-
- assert info.name == ""
- assert info.version == 0
-
-
-class TestSkillRunTool:
- """Test suite for SkillRunTool class."""
-
- def setup_method(self):
- """Set up test fixtures before each test."""
- self.mock_repository = Mock(spec=BaseSkillRepository)
- self.mock_runtime = Mock(spec=BaseWorkspaceRuntime)
- self.mock_manager = Mock(spec=BaseWorkspaceManager)
- self.mock_fs = Mock(spec=BaseWorkspaceFS)
- self.mock_runner = Mock(spec=BaseProgramRunner)
- self.mock_repository.workspace_runtime = self.mock_runtime
- self.mock_runtime.manager = Mock(return_value=self.mock_manager)
- self.mock_runtime.fs = Mock(return_value=self.mock_fs)
- self.mock_runtime.runner = Mock(return_value=self.mock_runner)
-
- self.mock_ctx = Mock(spec=InvocationContext)
- self.mock_ctx.agent_context = Mock()
- self.mock_ctx.agent_context.get_metadata = Mock(return_value=None)
- self.mock_ctx.session = Mock()
- self.mock_ctx.session.id = "session-123"
- self.mock_ctx.actions = Mock()
- self.mock_ctx.actions.state_delta = {}
-
- def test_init(self):
- """Test SkillRunTool initialization."""
- tool = SkillRunTool(repository=self.mock_repository)
-
- assert tool.name == "skill_run"
- assert tool._repository == self.mock_repository
-
- def test_get_declaration(self):
- """Test getting function declaration."""
- tool = SkillRunTool(repository=self.mock_repository)
-
- declaration = tool._get_declaration()
-
- assert declaration.name == "skill_run"
- assert declaration.parameters is not None
- assert declaration.response is not None
-
- def test_get_repository_from_instance(self):
- """Test getting repository from instance."""
- tool = SkillRunTool(repository=self.mock_repository)
-
- result = tool._get_repository(self.mock_ctx)
-
- assert result == self.mock_repository
-
- def test_get_repository_from_context(self):
- """Test getting repository from context."""
- tool = SkillRunTool(repository=None)
- self.mock_ctx.agent_context.get_metadata = Mock(return_value=self.mock_repository)
-
- result = tool._get_repository(self.mock_ctx)
-
- assert result == self.mock_repository
-
- @pytest.mark.asyncio
- async def test_run_async_impl_success(self):
- """Test running skill_run tool successfully."""
- from trpc_agent_sdk.skills.stager import SkillStageResult
-
- mock_stager = AsyncMock()
- mock_stager.stage_skill = AsyncMock(return_value=SkillStageResult(workspace_skill_dir="skills/test-skill"))
- tool = SkillRunTool(repository=self.mock_repository, skill_stager=mock_stager)
-
- workspace = WorkspaceInfo(id="ws-123", path="/tmp/workspace")
- self.mock_repository.path = Mock(return_value="/path/to/skill")
- self.mock_repository.skill_run_env = Mock(return_value={})
- self.mock_manager.create_workspace = AsyncMock(return_value=workspace)
- self.mock_fs.stage_directory = AsyncMock()
- self.mock_fs.stage_inputs = AsyncMock()
- self.mock_fs.collect_outputs = AsyncMock(return_value=Mock(files=[]))
- self.mock_runner.run_program = AsyncMock(return_value=WorkspaceRunResult(
- stdout="output",
- stderr="",
- exit_code=0,
- duration=1.0,
- timed_out=False
- ))
-
- args = {
- "skill": "test-skill",
- "command": "echo hello"
- }
- result = await tool._run_async_impl(tool_context=self.mock_ctx, args=args)
-
- assert isinstance(result, dict)
- assert result["stdout"] == "output"
- assert result["exit_code"] == 0
-
- @pytest.mark.asyncio
- async def test_run_async_impl_with_output_files(self):
- """Test running skill_run tool with output files."""
- from trpc_agent_sdk.skills.stager import SkillStageResult
-
- mock_stager = AsyncMock()
- mock_stager.stage_skill = AsyncMock(return_value=SkillStageResult(workspace_skill_dir="skills/test-skill"))
- tool = SkillRunTool(repository=self.mock_repository, skill_stager=mock_stager)
-
- workspace = WorkspaceInfo(id="ws-123", path="/tmp/workspace")
- self.mock_repository.path = Mock(return_value="/path/to/skill")
- self.mock_repository.skill_run_env = Mock(return_value={})
- self.mock_manager.create_workspace = AsyncMock(return_value=workspace)
- self.mock_fs.stage_directory = AsyncMock()
- self.mock_fs.stage_inputs = AsyncMock()
- self.mock_fs.collect = AsyncMock(return_value=[CodeFile(name="output.txt", content="content", mime_type="text/plain")])
- self.mock_runner.run_program = AsyncMock(return_value=WorkspaceRunResult(
- stdout="output",
- stderr="",
- exit_code=0,
- duration=1.0,
- timed_out=False
- ))
-
- from trpc_agent_sdk.code_executors._types import ManifestOutput, ManifestFileRef
- mock_output = ManifestOutput(files=[
- ManifestFileRef(name="output.txt", content="content", mime_type="text/plain")
- ])
- self.mock_fs.collect_outputs = AsyncMock(return_value=mock_output)
-
- args = {
- "skill": "test-skill",
- "command": "echo hello",
- "output_files": ["out/*.txt"]
- }
- result = await tool._run_async_impl(tool_context=self.mock_ctx, args=args)
-
- assert len(result["output_files"]) == 1
-
- @pytest.mark.asyncio
- async def test_run_async_impl_invalid_args(self):
- """Test running skill_run tool with invalid arguments."""
- tool = SkillRunTool(repository=self.mock_repository)
-
- args = {
- "skill": "test-skill",
- # Missing required 'command' field
- }
-
- with pytest.raises(ValueError, match="Invalid skill_run arguments"):
- await tool._run_async_impl(tool_context=self.mock_ctx, args=args)
-
- @pytest.mark.asyncio
- async def test_run_async_impl_with_kwargs(self):
- """Test running skill_run tool with kwargs."""
- from trpc_agent_sdk.skills.stager import SkillStageResult
-
- mock_stager = AsyncMock()
- mock_stager.stage_skill = AsyncMock(return_value=SkillStageResult(workspace_skill_dir="skills/test-skill"))
- tool = SkillRunTool(repository=self.mock_repository, timeout=30, skill_stager=mock_stager)
-
- workspace = WorkspaceInfo(id="ws-123", path="/tmp/workspace")
- self.mock_repository.path = Mock(return_value="/path/to/skill")
- self.mock_repository.skill_run_env = Mock(return_value={})
- self.mock_manager.create_workspace = AsyncMock(return_value=workspace)
- self.mock_fs.stage_directory = AsyncMock()
- self.mock_fs.stage_inputs = AsyncMock()
- self.mock_fs.collect_outputs = AsyncMock(return_value=Mock(files=[]))
- self.mock_runner.run_program = AsyncMock(return_value=WorkspaceRunResult(
- stdout="output",
- stderr="",
- exit_code=0,
- duration=1.0,
- timed_out=False
- ))
-
- args = {
- "skill": "test-skill",
- "command": "echo hello"
- }
-
- result = await tool._run_async_impl(tool_context=self.mock_ctx, args=args)
-
- assert isinstance(result, dict)
- assert result["stdout"] == "output"
- assert result["exit_code"] == 0
-
diff --git a/tests/skills/test_skill_config.py b/tests/skills/test_skill_config.py
new file mode 100644
index 0000000..b8284dd
--- /dev/null
+++ b/tests/skills/test_skill_config.py
@@ -0,0 +1,42 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from unittest.mock import MagicMock
+
+from trpc_agent_sdk.skills._constants import SKILL_CONFIG_KEY
+from trpc_agent_sdk.skills._constants import SkillLoadModeNames
+from trpc_agent_sdk.skills._skill_config import DEFAULT_SKILL_CONFIG
+from trpc_agent_sdk.skills._skill_config import get_skill_config
+from trpc_agent_sdk.skills._skill_config import get_skill_load_mode
+from trpc_agent_sdk.skills._skill_config import is_exist_skill_config
+from trpc_agent_sdk.skills._skill_config import set_skill_config
+
+
+def test_get_skill_config_uses_metadata_default():
+ agent_ctx = MagicMock()
+ agent_ctx.get_metadata = MagicMock(return_value=DEFAULT_SKILL_CONFIG)
+ assert get_skill_config(agent_ctx) == DEFAULT_SKILL_CONFIG
+
+
+def test_set_skill_config_writes_metadata():
+ agent_ctx = MagicMock()
+ config = {"skill_processor": {"load_mode": "session"}}
+ set_skill_config(agent_ctx, config)
+ agent_ctx.with_metadata.assert_called_once_with(SKILL_CONFIG_KEY, config)
+
+
+def test_get_skill_load_mode_fallback_turn_on_invalid():
+ agent_ctx = MagicMock()
+ agent_ctx.get_metadata = MagicMock(return_value={"skill_processor": {"load_mode": "bad"}})
+ ctx = MagicMock()
+ ctx.agent_context = agent_ctx
+ assert get_skill_load_mode(ctx) == SkillLoadModeNames.TURN.value
+
+
+def test_is_exist_skill_config_checks_key():
+ agent_ctx = MagicMock()
+ agent_ctx.metadata = {SKILL_CONFIG_KEY: {}}
+ assert is_exist_skill_config(agent_ctx) is True
diff --git a/tests/skills/test_skill_profile.py b/tests/skills/test_skill_profile.py
new file mode 100644
index 0000000..b091c15
--- /dev/null
+++ b/tests/skills/test_skill_profile.py
@@ -0,0 +1,41 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+import pytest
+
+from trpc_agent_sdk.skills._constants import SkillProfileNames
+from trpc_agent_sdk.skills._skill_profile import SkillProfileFlags
+
+
+def test_normalize_profile():
+ assert SkillProfileFlags.normalize_profile("knowledge_only") == SkillProfileNames.KNOWLEDGE_ONLY.value
+ assert SkillProfileFlags.normalize_profile("unknown") == SkillProfileNames.FULL.value
+
+
+def test_preset_flags_knowledge_only():
+ flags = SkillProfileFlags.preset_flags("knowledge_only")
+ assert flags.has_knowledge_tools() is True
+ assert flags.requires_execution_tools() is False
+
+
+def test_resolve_flags_with_forbidden_tool():
+ flags = SkillProfileFlags.resolve_flags("full", forbidden_tools=["skill_write_stdin"])
+ assert flags.exec is True
+ assert flags.write_stdin is False
+
+
+def test_validate_dependency_error():
+ flags = SkillProfileFlags(run=False, exec=True)
+ with pytest.raises(ValueError, match="requires"):
+ flags.validate()
+
+
+def test_without_interactive_execution():
+ flags = SkillProfileFlags.resolve_flags("full")
+ narrowed = flags.without_interactive_execution()
+ assert narrowed.run is True
+ assert narrowed.exec is False
+ assert narrowed.poll_session is False
diff --git a/tests/skills/test_state_keys.py b/tests/skills/test_state_keys.py
new file mode 100644
index 0000000..e8df27f
--- /dev/null
+++ b/tests/skills/test_state_keys.py
@@ -0,0 +1,35 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from trpc_agent_sdk.skills._state_keys import docs_key
+from trpc_agent_sdk.skills._state_keys import docs_prefix
+from trpc_agent_sdk.skills._state_keys import loaded_key
+from trpc_agent_sdk.skills._state_keys import loaded_order_key
+from trpc_agent_sdk.skills._state_keys import loaded_prefix
+from trpc_agent_sdk.skills._state_keys import to_persistent_prefix
+from trpc_agent_sdk.skills._state_keys import tool_key
+from trpc_agent_sdk.skills._state_keys import tool_prefix
+
+
+def test_loaded_key_legacy_fallback():
+ assert loaded_key("", "demo") == "temp:skill:loaded:demo"
+
+
+def test_scoped_keys_escape_agent_name():
+ assert loaded_key("agent/a", "demo") == "temp:skill:loaded_by_agent:agent%2Fa/demo"
+ assert docs_key("agent/a", "demo") == "temp:skill:docs_by_agent:agent%2Fa/demo"
+ assert tool_key("agent/a", "demo") == "temp:skill:tools_by_agent:agent%2Fa/demo"
+
+
+def test_prefix_helpers():
+ assert loaded_prefix("") == "temp:skill:loaded:"
+ assert docs_prefix("") == "temp:skill:docs:"
+ assert tool_prefix("") == "temp:skill:tools:"
+ assert loaded_order_key("agent/a") == "temp:skill:loaded_order_by_agent:agent%2Fa"
+
+
+def test_to_persistent_prefix():
+ assert to_persistent_prefix("temp:skill:loaded:demo") == "skill:loaded:demo"
diff --git a/tests/skills/test_state_migration.py b/tests/skills/test_state_migration.py
new file mode 100644
index 0000000..02495a3
--- /dev/null
+++ b/tests/skills/test_state_migration.py
@@ -0,0 +1,71 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Tests for legacy skill state migration."""
+
+from unittest.mock import Mock
+
+from trpc_agent_sdk.skills._constants import SKILL_DOCS_STATE_KEY_PREFIX
+from trpc_agent_sdk.skills._constants import SKILL_LOADED_STATE_KEY_PREFIX
+from trpc_agent_sdk.skills._state_keys import docs_key
+from trpc_agent_sdk.skills._state_keys import loaded_key
+from trpc_agent_sdk.skills._state_migration import SKILLS_LEGACY_MIGRATION_STATE_KEY
+from trpc_agent_sdk.skills._state_migration import maybe_migrate_legacy_skill_state
+
+
+def _build_ctx(*, state=None, delta=None, agent_name: str = "agent-a") -> Mock:
+ ctx = Mock()
+ ctx.session = Mock()
+ ctx.session.state = dict(state or {})
+ ctx.session.events = []
+ ctx.actions = Mock()
+ ctx.actions.state_delta = dict(delta or {})
+ ctx.agent = Mock()
+ ctx.agent.name = agent_name
+ return ctx
+
+
+class TestMaybeMigrateLegacySkillState:
+ def test_migrates_loaded_legacy_key_to_temp(self):
+ legacy_key = f"{SKILL_LOADED_STATE_KEY_PREFIX}demo-skill"
+ temp_key = loaded_key("agent-a", "demo-skill")
+ ctx = _build_ctx(state={legacy_key: "1"})
+
+ maybe_migrate_legacy_skill_state(ctx)
+
+ assert ctx.actions.state_delta[SKILLS_LEGACY_MIGRATION_STATE_KEY] is True
+ assert ctx.actions.state_delta[temp_key] == "1"
+ assert ctx.actions.state_delta[legacy_key] is None
+
+ def test_migrates_docs_legacy_key_to_temp(self):
+ legacy_key = f"{SKILL_DOCS_STATE_KEY_PREFIX}demo-skill"
+ temp_key = docs_key("agent-a", "demo-skill")
+ value = '["README.md"]'
+ ctx = _build_ctx(state={legacy_key: value})
+
+ maybe_migrate_legacy_skill_state(ctx)
+
+ assert ctx.actions.state_delta[SKILLS_LEGACY_MIGRATION_STATE_KEY] is True
+ assert ctx.actions.state_delta[temp_key] == value
+ assert ctx.actions.state_delta[legacy_key] is None
+
+ def test_existing_scoped_key_skips_copy_and_only_clears_legacy(self):
+ legacy_key = f"{SKILL_LOADED_STATE_KEY_PREFIX}demo-skill"
+ temp_key = loaded_key("agent-a", "demo-skill")
+ ctx = _build_ctx(state={legacy_key: "legacy", temp_key: "existing"})
+
+ maybe_migrate_legacy_skill_state(ctx)
+
+ assert ctx.actions.state_delta[SKILLS_LEGACY_MIGRATION_STATE_KEY] is True
+ assert ctx.actions.state_delta[legacy_key] is None
+ assert temp_key not in ctx.actions.state_delta
+
+ def test_migration_is_idempotent_when_marker_exists(self):
+ legacy_key = f"{SKILL_LOADED_STATE_KEY_PREFIX}demo-skill"
+ ctx = _build_ctx(state={legacy_key: "1", SKILLS_LEGACY_MIGRATION_STATE_KEY: True})
+
+ maybe_migrate_legacy_skill_state(ctx)
+
+ assert ctx.actions.state_delta == {}
diff --git a/tests/skills/test_state_order.py b/tests/skills/test_state_order.py
new file mode 100644
index 0000000..360d58b
--- /dev/null
+++ b/tests/skills/test_state_order.py
@@ -0,0 +1,24 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from trpc_agent_sdk.skills._state_order import marshal_loaded_order
+from trpc_agent_sdk.skills._state_order import parse_loaded_order
+from trpc_agent_sdk.skills._state_order import touch_loaded_order
+
+
+def test_parse_loaded_order_from_json_and_bytes():
+ assert parse_loaded_order('["a","b","a",""]') == ["a", "b"]
+ assert parse_loaded_order(b'["x","y"]') == ["x", "y"]
+ assert parse_loaded_order(b"\xff") == []
+
+
+def test_marshal_loaded_order_normalizes():
+ assert marshal_loaded_order(["a", "a", " ", "b"]) == '["a", "b"]'
+ assert marshal_loaded_order([]) == ""
+
+
+def test_touch_loaded_order_moves_items_to_tail():
+ assert touch_loaded_order(["a", "b", "c"], "b", "a") == ["c", "b", "a"]
diff --git a/tests/skills/test_tools.py b/tests/skills/test_tools.py
deleted file mode 100644
index 6c49fdd..0000000
--- a/tests/skills/test_tools.py
+++ /dev/null
@@ -1,553 +0,0 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
-#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
-
-import json
-from unittest.mock import Mock
-
-import pytest
-from trpc_agent_sdk.context import InvocationContext
-from trpc_agent_sdk.skills.tools import SkillSelectDocsResult
-from trpc_agent_sdk.skills.tools import SkillSelectToolsResult
-from trpc_agent_sdk.skills import skill_list
-from trpc_agent_sdk.skills import skill_list_docs
-from trpc_agent_sdk.skills import skill_list_tools
-from trpc_agent_sdk.skills import skill_load
-from trpc_agent_sdk.skills import skill_select_docs
-from trpc_agent_sdk.skills import skill_select_tools
-from trpc_agent_sdk.skills.tools._skill_load import _set_state_delta_for_skill_load
-from trpc_agent_sdk.skills.tools._skill_load import _set_state_delta_for_skill_tools
-from trpc_agent_sdk.skills import Skill
-from trpc_agent_sdk.skills import SkillResource
-
-
-class TestSkillList:
- """Test suite for skill_list function."""
-
- def test_skill_list_success(self):
- """Test listing all skills."""
- mock_repository = Mock()
- mock_repository.skill_list.return_value = ["skill1", "skill2", "skill3"]
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list(mock_ctx)
-
- assert len(result) == 3
- assert "skill1" in result
- assert "skill2" in result
- assert "skill3" in result
-
- def test_skill_list_empty(self):
- """Test listing skills when none exist."""
- mock_repository = Mock()
- mock_repository.skill_list.return_value = []
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list(mock_ctx)
-
- assert result == []
-
- def test_skill_list_repository_not_found(self):
- """Test listing skills when repository not found."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=None)
-
- with pytest.raises(ValueError, match="repository not found"):
- skill_list(mock_ctx)
-
-
-class TestSkillListDocs:
- """Test suite for skill_list_docs function."""
-
- def test_skill_list_docs_success(self):
- """Test listing docs for a skill."""
- mock_repository = Mock()
- skill = Skill(
- resources=[
- SkillResource(path="doc1.md", content="content1"),
- SkillResource(path="doc2.md", content="content2"),
- ]
- )
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list_docs(mock_ctx, "test-skill")
-
- assert len(result["docs"]) == 2
- assert "doc1.md" in result["docs"]
- assert "doc2.md" in result["docs"]
-
- def test_skill_list_docs_no_resources(self):
- """Test listing docs for skill with no resources."""
- mock_repository = Mock()
- skill = Skill(resources=[])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list_docs(mock_ctx, "test-skill")
-
- assert result["docs"] == []
-
- def test_skill_list_docs_skill_not_found(self):
- """Test listing docs for nonexistent skill."""
- mock_repository = Mock()
- mock_repository.get.return_value = None
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list_docs(mock_ctx, "nonexistent-skill")
-
- assert result["docs"] == []
-
- def test_skill_list_docs_repository_not_found(self):
- """Test listing docs when repository not found."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=None)
-
- with pytest.raises(ValueError, match="repository not found"):
- skill_list_docs(mock_ctx, "test-skill")
-
-
-class TestSkillListTools:
- """Test suite for skill_list_tools function."""
-
- def test_skill_list_tools_success(self):
- """Test listing tools for a skill."""
- mock_repository = Mock()
- skill = Skill(tools=["tool1", "tool2", "tool3"])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list_tools(mock_ctx, "test-skill")
-
- assert len(result["tools"]) == 3
- assert "tool1" in result["tools"]
- assert "tool2" in result["tools"]
- assert "tool3" in result["tools"]
-
- def test_skill_list_tools_no_tools(self):
- """Test listing tools for skill with no tools."""
- mock_repository = Mock()
- skill = Skill(tools=[])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list_tools(mock_ctx, "test-skill")
-
- assert result["tools"] == []
-
- def test_skill_list_tools_skill_not_found(self):
- """Test listing tools for nonexistent skill."""
- mock_repository = Mock()
- mock_repository.get.return_value = None
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_list_tools(mock_ctx, "nonexistent-skill")
-
- assert result["tools"] == []
-
- def test_skill_list_tools_repository_not_found(self):
- """Test listing tools when repository not found."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=None)
-
- with pytest.raises(ValueError, match="repository not found"):
- skill_list_tools(mock_ctx, "test-skill")
-
-
-class TestSkillLoad:
- """Test suite for skill_load function."""
-
- def test_skill_load_success(self):
- """Test loading a skill."""
- mock_repository = Mock()
- skill = Skill(body="skill body", tools=[])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_load(mock_ctx, "test-skill")
-
- assert "loaded" in result
- assert "test-skill" in result
-
- def test_skill_load_with_tools(self):
- """Test loading a skill with tools."""
- mock_repository = Mock()
- skill = Skill(body="skill body", tools=["tool1", "tool2"])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_load(mock_ctx, "test-skill")
-
- assert "loaded" in result
- # Check that tools state was set
- tools_key = "temp:skill:tools:test-skill"
- assert tools_key in mock_ctx.actions.state_delta
- assert json.loads(mock_ctx.actions.state_delta[tools_key]) == ["tool1", "tool2"]
-
- def test_skill_load_with_docs(self):
- """Test loading a skill with specific docs."""
- mock_repository = Mock()
- skill = Skill(body="skill body", tools=[])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_load(mock_ctx, "test-skill", docs=["doc1.md"])
-
- assert "loaded" in result
- docs_key = "temp:skill:docs:test-skill"
- assert docs_key in mock_ctx.actions.state_delta
-
- def test_skill_load_with_include_all_docs(self):
- """Test loading a skill with include_all_docs=True."""
- mock_repository = Mock()
- skill = Skill(body="skill body", tools=[])
- mock_repository.get.return_value = skill
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_load(mock_ctx, "test-skill", include_all_docs=True)
-
- assert "loaded" in result
- assert mock_ctx.actions.state_delta.get("temp:skill:docs:test-skill") == '*'
-
- def test_skill_load_skill_not_found(self):
- """Test loading nonexistent skill."""
- mock_repository = Mock()
- mock_repository.get.return_value = None
-
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=mock_repository)
-
- result = skill_load(mock_ctx, "nonexistent-skill")
-
- assert "not found" in result
-
- def test_skill_load_repository_not_found(self):
- """Test loading skill when repository not found."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.agent_context = Mock()
- mock_ctx.agent_context.get_metadata = Mock(return_value=None)
-
- with pytest.raises(ValueError, match="repository not found"):
- skill_load(mock_ctx, "test-skill")
-
-
-class TestSkillSelectDocs:
- """Test suite for skill_select_docs function."""
-
- def test_skill_select_docs_replace_mode(self):
- """Test selecting docs with replace mode."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {}
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_docs(mock_ctx, "test-skill", docs=["doc1.md"], mode="replace")
-
- assert isinstance(result, SkillSelectDocsResult)
- assert result.skill == "test-skill"
- assert result.mode == "replace"
- assert "doc1.md" in result.selected_docs
-
- def test_skill_select_docs_add_mode(self):
- """Test selecting docs with add mode."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {
- "temp:skill:docs:test-skill": json.dumps(["doc1.md"])
- }
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_docs(mock_ctx, "test-skill", docs=["doc2.md"], mode="add")
-
- assert result.mode == "add"
- assert "doc1.md" in result.selected_docs
- assert "doc2.md" in result.selected_docs
-
- def test_skill_select_docs_clear_mode(self):
- """Test selecting docs with clear mode."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {
- "temp:skill:docs:test-skill": json.dumps(["doc1.md"])
- }
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_docs(mock_ctx, "test-skill", mode="clear")
-
- assert result.mode == "clear"
- assert result.include_all_docs is False
- assert result.selected_docs == []
-
- def test_skill_select_docs_with_include_all(self):
- """Test selecting docs with include_all_docs=True."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {}
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_docs(mock_ctx, "test-skill", include_all_docs=True, mode="replace")
-
- assert result.include_all_docs is True
- assert result.selected_docs == []
-
- def test_skill_select_docs_invalid_mode(self):
- """Test selecting docs with invalid mode defaults to replace."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {}
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_docs(mock_ctx, "test-skill", docs=["doc1.md"], mode="invalid")
-
- assert result.mode == "replace"
-
- def test_skill_select_docs_previous_all_docs(self):
- """Test selecting docs when previous state has all docs."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {
- "temp:skill:docs:test-skill": '*'
- }
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_docs(mock_ctx, "test-skill", docs=["doc1.md"], mode="add")
-
- assert result.include_all_docs is True
-
-
-class TestSkillSelectTools:
- """Test suite for skill_select_tools function."""
-
- def test_skill_select_tools_replace_mode(self):
- """Test selecting tools with replace mode."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {}
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_tools(mock_ctx, "test-skill", tools=["tool1"], mode="replace")
-
- assert isinstance(result, SkillSelectToolsResult)
- assert result.skill == "test-skill"
- assert result.mode == "replace"
- assert "tool1" in result.selected_tools
-
- def test_skill_select_tools_add_mode(self):
- """Test selecting tools with add mode."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {
- "temp:skill:tools:test-skill": json.dumps(["tool1"])
- }
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_tools(mock_ctx, "test-skill", tools=["tool2"], mode="add")
-
- assert result.mode == "add"
- assert "tool1" in result.selected_tools
- assert "tool2" in result.selected_tools
-
- def test_skill_select_tools_clear_mode(self):
- """Test selecting tools with clear mode."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {
- "temp:skill:tools:test-skill": json.dumps(["tool1"])
- }
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_tools(mock_ctx, "test-skill", mode="clear")
-
- assert result.mode == "clear"
- assert result.include_all_tools is False
- assert result.selected_tools == []
-
- def test_skill_select_tools_with_include_all(self):
- """Test selecting tools with include_all_tools=True."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {}
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_tools(mock_ctx, "test-skill", include_all_tools=True, mode="replace")
-
- assert result.include_all_tools is True
- assert result.selected_tools == []
-
- def test_skill_select_tools_invalid_mode(self):
- """Test selecting tools with invalid mode defaults to replace."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {}
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_tools(mock_ctx, "test-skill", tools=["tool1"], mode="invalid")
-
- assert result.mode == "replace"
-
- def test_skill_select_tools_previous_all_tools(self):
- """Test selecting tools when previous state has all tools."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.session_state = {
- "temp:skill:tools:test-skill": '*'
- }
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- result = skill_select_tools(mock_ctx, "test-skill", tools=["tool1"], mode="add")
-
- assert result.include_all_tools is True
-
-
-class TestSkillSelectDocsResult:
- """Test suite for SkillSelectDocsResult class."""
-
- def test_create_result(self):
- """Test creating SkillSelectDocsResult."""
- result = SkillSelectDocsResult(
- skill="test-skill",
- selected_docs=["doc1.md"],
- include_all_docs=True,
- mode="replace"
- )
-
- assert result.skill == "test-skill"
- assert result.selected_docs == ["doc1.md"]
- assert result.include_all_docs is True
- assert result.mode == "replace"
-
- def test_create_result_with_alias_fields(self):
- """Test creating SkillSelectDocsResult with alias fields."""
- result = SkillSelectDocsResult(
- skill="test-skill",
- selected_items=["doc1.md", "doc2.md"],
- include_all=True,
- mode="replace"
- )
-
- # Alias fields should be mapped to actual fields
- assert result.selected_docs == ["doc1.md", "doc2.md"]
- assert result.include_all_docs is True
-
-
-class TestSkillSelectToolsResult:
- """Test suite for SkillSelectToolsResult class."""
-
- def test_create_result(self):
- """Test creating SkillSelectToolsResult."""
- result = SkillSelectToolsResult(
- skill="test-skill",
- selected_tools=["tool1"],
- include_all_tools=True,
- mode="replace"
- )
-
- assert result.skill == "test-skill"
- assert result.selected_tools == ["tool1"]
- assert result.include_all_tools is True
- assert result.mode == "replace"
-
- def test_create_result_with_alias_fields(self):
- """Test creating SkillSelectToolsResult with alias fields."""
- result = SkillSelectToolsResult(
- skill="test-skill",
- selected_items=["tool1", "tool2"],
- include_all=True,
- mode="replace"
- )
-
- # Alias fields should be mapped to actual fields
- assert result.selected_tools == ["tool1", "tool2"]
- assert result.include_all_tools is True
-
-
-class TestStateDeltaHelpers:
- """Test suite for state delta helper functions."""
-
- def test_set_state_delta_for_skill_load(self):
- """Test setting state delta for skill load."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- _set_state_delta_for_skill_load(mock_ctx, "test-skill", ["doc1.md"], False)
-
- loaded_key = "temp:skill:loaded:test-skill"
- docs_key = "temp:skill:docs:test-skill"
-
- assert loaded_key in mock_ctx.actions.state_delta
- assert docs_key in mock_ctx.actions.state_delta
- assert json.loads(mock_ctx.actions.state_delta[docs_key]) == ["doc1.md"]
-
- def test_set_state_delta_for_skill_load_include_all(self):
- """Test setting state delta with include_all_docs."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- _set_state_delta_for_skill_load(mock_ctx, "test-skill", [], True)
-
- docs_key = "temp:skill:docs:test-skill"
- assert mock_ctx.actions.state_delta[docs_key] == '*'
-
- def test_set_state_delta_for_skill_tools(self):
- """Test setting state delta for skill tools."""
- mock_ctx = Mock(spec=InvocationContext)
- mock_ctx.actions = Mock()
- mock_ctx.actions.state_delta = {}
-
- _set_state_delta_for_skill_tools(mock_ctx, "test-skill", ["tool1", "tool2"])
-
- tools_key = "temp:skill:tools:test-skill"
- assert tools_key in mock_ctx.actions.state_delta
- assert json.loads(mock_ctx.actions.state_delta[tools_key]) == ["tool1", "tool2"]
diff --git a/tests/skills/tools/__init__.py b/tests/skills/tools/__init__.py
index e69de29..8b13789 100644
--- a/tests/skills/tools/__init__.py
+++ b/tests/skills/tools/__init__.py
@@ -0,0 +1 @@
+
diff --git a/tests/skills/tools/test_common.py b/tests/skills/tools/test_common.py
new file mode 100644
index 0000000..52d712f
--- /dev/null
+++ b/tests/skills/tools/test_common.py
@@ -0,0 +1,31 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from trpc_agent_sdk.skills.tools._common import get_staged_workspace_dir
+from trpc_agent_sdk.skills.tools._common import inline_json_schema_refs
+from trpc_agent_sdk.skills.tools._common import require_non_empty
+from trpc_agent_sdk.skills.tools._common import set_staged_workspace_dir
+
+
+def test_require_non_empty():
+ assert require_non_empty(" ok ", field_name="x") == "ok"
+ with pytest.raises(ValueError, match="x is required"):
+ require_non_empty(" ", field_name="x")
+
+
+def test_inline_json_schema_refs():
+ schema = {"$defs": {"S": {"type": "string"}}, "properties": {"name": {"$ref": "#/$defs/S"}}}
+ out = inline_json_schema_refs(schema)
+ assert "$defs" not in out
+ assert out["properties"]["name"]["type"] == "string"
+
+
+def test_staged_workspace_dir_round_trip():
+ metadata = {}
+ ctx = MagicMock()
+ ctx.agent_context.get_metadata = MagicMock(side_effect=lambda key, default=None: metadata.get(key, default))
+ ctx.agent_context.with_metadata = MagicMock(side_effect=lambda key, value: metadata.__setitem__(key, value))
+
+ set_staged_workspace_dir(ctx, "skill-a", "skills/skill-a")
+ assert get_staged_workspace_dir(ctx, "skill-a") == "skills/skill-a"
diff --git a/tests/skills/tools/test_save_artifact.py b/tests/skills/tools/test_save_artifact.py
new file mode 100644
index 0000000..837b771
--- /dev/null
+++ b/tests/skills/tools/test_save_artifact.py
@@ -0,0 +1,49 @@
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from trpc_agent_sdk.skills._constants import SKILL_ARTIFACTS_STATE_KEY
+from trpc_agent_sdk.skills.tools._save_artifact import SaveArtifactTool
+from trpc_agent_sdk.skills.tools._save_artifact import _apply_artifact_state_delta
+from trpc_agent_sdk.skills.tools._save_artifact import _artifact_save_skip_reason
+from trpc_agent_sdk.skills.tools._save_artifact import _normalize_artifact_path
+from trpc_agent_sdk.skills.tools._save_artifact import _normalize_workspace_prefix
+
+
+def test_normalize_workspace_prefix():
+ assert _normalize_workspace_prefix("workspace://work/a.txt") == "work/a.txt"
+ assert _normalize_workspace_prefix("$WORK_DIR/a.txt") == "work/a.txt"
+
+
+def test_normalize_artifact_path_valid_and_invalid(tmp_path: Path):
+ workspace_root = str(tmp_path)
+ rel, abs_path = _normalize_artifact_path("work/a.txt", workspace_root)
+ assert rel == "work/a.txt"
+ assert abs_path.endswith("work/a.txt")
+
+ with pytest.raises(ValueError, match="stay within the workspace"):
+ _normalize_artifact_path("../a.txt", workspace_root)
+
+
+def test_artifact_save_skip_reason_and_state_delta():
+ ctx = MagicMock()
+ ctx.artifact_service = object()
+ ctx.session = object()
+ ctx.app_name = "app"
+ ctx.user_id = "u"
+ ctx.session_id = "s"
+ ctx.function_call_id = "fc-1"
+ ctx.actions.state_delta = {}
+ assert _artifact_save_skip_reason(ctx) == ""
+
+ _apply_artifact_state_delta(ctx, "work/a.txt", 2, "artifact://work/a.txt@2")
+ value = ctx.actions.state_delta[SKILL_ARTIFACTS_STATE_KEY]
+ assert value["tool_call_id"] == "fc-1"
+ assert value["artifacts"][0]["version"] == 2
+
+
+def test_save_artifact_declaration_name():
+ declaration = SaveArtifactTool()._get_declaration()
+ assert declaration is not None
+ assert declaration.name == "workspace_save_artifact"
diff --git a/tests/skills/tools/test_skill_exec.py b/tests/skills/tools/test_skill_exec.py
index 82a0ecb..1593e5d 100644
--- a/tests/skills/tools/test_skill_exec.py
+++ b/tests/skills/tools/test_skill_exec.py
@@ -3,887 +3,107 @@
# Copyright (C) 2026 Tencent. All rights reserved.
#
# tRPC-Agent-Python is licensed under Apache-2.0.
-"""Unit tests for trpc_agent_sdk.skills.tools._skill_exec.
-Covers:
-- Pydantic I/O models: ExecInput, WriteStdinInput, PollSessionInput,
- KillSessionInput, SessionInteraction, ExecOutput, SessionKillOutput
-- Helper functions: _last_non_empty_line, _has_selection_items,
- _detect_interaction, _build_exec_env, _resolve_abs_cwd
-- SkillExecTool: session management, declarations
-- create_exec_tools factory
-- _close_session
-"""
-
-from __future__ import annotations
-
-import asyncio
-import os
-from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock
+from unittest.mock import MagicMock
import pytest
-
-from trpc_agent_sdk.skills.tools._skill_exec import (
- DEFAULT_EXEC_YIELD_MS,
- DEFAULT_IO_YIELD_MS,
- DEFAULT_POLL_LINES,
- DEFAULT_SESSION_TTL,
- ExecInput,
- ExecOutput,
- KillSessionInput,
- KillSessionTool,
- PollSessionInput,
- PollSessionTool,
- SessionInteraction,
- SessionKillOutput,
- SkillExecTool,
- WriteStdinInput,
- WriteStdinTool,
- _close_session,
- _detect_interaction,
- _has_selection_items,
- _last_non_empty_line,
- _resolve_abs_cwd,
- create_exec_tools,
-)
-
-
-# ---------------------------------------------------------------------------
-# _last_non_empty_line
-# ---------------------------------------------------------------------------
-
-class TestLastNonEmptyLine:
- def test_normal(self):
- assert _last_non_empty_line("line1\nline2\nline3") == "line3"
-
- def test_trailing_empty_lines(self):
- assert _last_non_empty_line("line1\nline2\n\n\n") == "line2"
-
- def test_all_empty(self):
- assert _last_non_empty_line("\n\n") == ""
-
- def test_empty_string(self):
- assert _last_non_empty_line("") == ""
-
- def test_single_line(self):
- assert _last_non_empty_line("hello") == "hello"
-
- def test_whitespace_lines(self):
- assert _last_non_empty_line(" \n \n content \n ") == "content"
-
-
-# ---------------------------------------------------------------------------
-# _has_selection_items
-# ---------------------------------------------------------------------------
-
-class TestHasSelectionItems:
- def test_numbered_list(self):
- text = "Choose an option:\n1. Option A\n2. Option B\n3. Option C"
- assert _has_selection_items(text) is True
-
- def test_numbered_paren(self):
- text = "1) Option A\n2) Option B"
- assert _has_selection_items(text) is True
-
- def test_no_numbers(self):
- text = "No numbered items here"
- assert _has_selection_items(text) is False
-
- def test_single_number(self):
- text = "1. Only one item"
- assert _has_selection_items(text) is False
-
- def test_empty(self):
- assert _has_selection_items("") is False
-
-
-# ---------------------------------------------------------------------------
-# _detect_interaction
-# ---------------------------------------------------------------------------
-
-class TestDetectInteraction:
- def test_exited_returns_none(self):
- assert _detect_interaction("exited", "some output") is None
-
- def test_empty_output_returns_none(self):
- assert _detect_interaction("running", "") is None
-
- def test_colon_prompt(self):
- result = _detect_interaction("running", "Enter your name:")
- assert result is not None
- assert result.needs_input is True
- assert result.kind == "prompt"
-
- def test_question_mark_prompt(self):
- result = _detect_interaction("running", "Continue?")
- assert result is not None
- assert result.needs_input is True
-
- def test_press_enter(self):
- result = _detect_interaction("running", "Press Enter to continue")
- assert result is not None
- assert result.needs_input is True
-
- def test_selection_detection(self):
- text = "Choose a number:\n1. Option A\n2. Option B\nEnter the number:"
- result = _detect_interaction("running", text)
- assert result is not None
- assert result.kind == "selection"
-
- def test_normal_output(self):
- result = _detect_interaction("running", "Processing data...\nDone.")
- assert result is None
-
- def test_type_your_prompt(self):
- result = _detect_interaction("running", "Type your answer here")
- assert result is not None
- assert result.needs_input is True
-
-
-# ---------------------------------------------------------------------------
-# _resolve_abs_cwd
-# ---------------------------------------------------------------------------
-
-class TestResolveAbsCwd:
- def test_relative_cwd(self, tmp_path):
- result = _resolve_abs_cwd(str(tmp_path), "sub")
- assert os.path.isabs(result)
- assert os.path.isdir(result)
-
- def test_absolute_cwd(self, tmp_path):
- result = _resolve_abs_cwd(str(tmp_path), str(tmp_path / "abs"))
- assert result == str(tmp_path / "abs")
-
- def test_empty_cwd(self, tmp_path):
- result = _resolve_abs_cwd(str(tmp_path), "")
- assert os.path.isabs(result)
-
-
-# ---------------------------------------------------------------------------
-# Pydantic I/O models
-# ---------------------------------------------------------------------------
-
-class TestExecModels:
- def test_exec_input_required(self):
- inp = ExecInput(skill="test", command="ls")
- assert inp.skill == "test"
- assert inp.command == "ls"
+from trpc_agent_sdk.code_executors import DEFAULT_EXEC_YIELD_MS
+from trpc_agent_sdk.code_executors import DEFAULT_IO_YIELD_MS
+from trpc_agent_sdk.code_executors import DEFAULT_POLL_LINES
+from trpc_agent_sdk.code_executors import DEFAULT_SESSION_TTL_SEC
+from trpc_agent_sdk.skills.tools._skill_exec import ExecInput
+from trpc_agent_sdk.skills.tools._skill_exec import PollSessionTool
+from trpc_agent_sdk.skills.tools._skill_exec import SkillExecTool
+from trpc_agent_sdk.skills.tools._skill_exec import WriteStdinTool
+from trpc_agent_sdk.skills.tools._skill_exec import _close_session
+from trpc_agent_sdk.skills.tools._skill_exec import _detect_interaction
+from trpc_agent_sdk.skills.tools._skill_exec import _has_selection_items
+from trpc_agent_sdk.skills.tools._skill_exec import _last_non_empty_line
+from trpc_agent_sdk.skills.tools._skill_exec import create_exec_tools
+
+
+def _make_exec_tool() -> SkillExecTool:
+ run_tool = MagicMock()
+ run_tool._repository = MagicMock()
+ run_tool._timeout = 300.0
+ run_tool._resolve_cwd = MagicMock(return_value="skills/test")
+ run_tool._build_command = MagicMock(return_value=("bash", ["-lc", "echo hello"]))
+ run_tool._prepare_outputs = AsyncMock(return_value=([], None))
+ run_tool._attach_artifacts_if_requested = AsyncMock()
+ run_tool._merge_manifest_artifact_refs = MagicMock()
+ return SkillExecTool(run_tool)
+
+
+class TestHelpers:
+ def test_last_non_empty_line(self):
+ assert _last_non_empty_line("a\n\nb\n") == "b"
+
+ def test_has_selection_items(self):
+ assert _has_selection_items("1. a\n2. b") is True
+ assert _has_selection_items("1. a") is False
+
+ def test_detect_interaction_prompt(self):
+ ret = _detect_interaction("running", "Enter your name:")
+ assert ret is not None
+ assert ret.needs_input is True
+
+ def test_detect_interaction_selection(self):
+ ret = _detect_interaction("running", "Choose:\n1. A\n2. B\nEnter the number:")
+ assert ret is not None
+ assert ret.kind == "selection"
+
+
+class TestModelsAndConstants:
+ def test_exec_input_defaults(self):
+ inp = ExecInput(skill="s", command="echo hi")
+ assert inp.yield_time_ms == 0
+ assert inp.poll_lines == 0
assert inp.tty is False
- assert inp.yield_ms == 0
-
- def test_write_stdin_input(self):
- inp = WriteStdinInput(session_id="abc")
- assert inp.session_id == "abc"
- assert inp.chars == ""
- assert inp.submit is False
-
- def test_poll_session_input(self):
- inp = PollSessionInput(session_id="abc")
- assert inp.session_id == "abc"
-
- def test_kill_session_input(self):
- inp = KillSessionInput(session_id="abc")
- assert inp.session_id == "abc"
-
- def test_session_interaction(self):
- si = SessionInteraction(needs_input=True, kind="prompt", hint="Enter:")
- assert si.needs_input is True
- assert si.kind == "prompt"
-
- def test_exec_output_defaults(self):
- out = ExecOutput()
- assert out.status == "running"
- assert out.session_id == ""
- assert out.output == ""
- assert out.exit_code is None
-
- def test_session_kill_output(self):
- out = SessionKillOutput(ok=True, session_id="abc", status="killed")
- assert out.ok is True
-
-
-# ---------------------------------------------------------------------------
-# Constants
-# ---------------------------------------------------------------------------
-
-class TestExecConstants:
- def test_defaults(self):
- assert DEFAULT_EXEC_YIELD_MS == 300
- assert DEFAULT_IO_YIELD_MS == 100
- assert DEFAULT_POLL_LINES == 50
- assert DEFAULT_SESSION_TTL == 300.0
-
-
-# ---------------------------------------------------------------------------
-# SkillExecTool — session management
-# ---------------------------------------------------------------------------
-
-class TestSkillExecToolSessions:
- def _make_exec_tool(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- return SkillExecTool(run_tool)
-
- async def test_put_and_get_session(self):
- tool = self._make_exec_tool()
- mock_session = MagicMock()
- mock_session.exited_at = None
- await tool._put_session("s1", mock_session)
- result = await tool.get_session("s1")
- assert result is mock_session
-
- async def test_get_unknown_session_raises(self):
- tool = self._make_exec_tool()
- with pytest.raises(ValueError, match="unknown session_id"):
- await tool.get_session("nonexistent")
-
- async def test_remove_session(self):
- tool = self._make_exec_tool()
- mock_session = MagicMock()
- mock_session.exited_at = None
- await tool._put_session("s1", mock_session)
- result = await tool.remove_session("s1")
- assert result is mock_session
-
- async def test_remove_unknown_session_raises(self):
- tool = self._make_exec_tool()
- with pytest.raises(ValueError, match="unknown session_id"):
- await tool.remove_session("nonexistent")
-
- def test_declaration(self):
- tool = self._make_exec_tool()
- decl = tool._get_declaration()
- assert decl.name == "skill_exec"
-
-
-# ---------------------------------------------------------------------------
-# WriteStdinTool, PollSessionTool, KillSessionTool — declarations
-# ---------------------------------------------------------------------------
-
-class TestSubToolDeclarations:
- def _make_exec_tool(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- return SkillExecTool(run_tool)
- def test_write_stdin_declaration(self):
- exec_tool = self._make_exec_tool()
- tool = WriteStdinTool(exec_tool)
- decl = tool._get_declaration()
- assert decl.name == "skill_write_stdin"
+ def test_default_constants(self):
+ assert DEFAULT_EXEC_YIELD_MS > 0
+ assert DEFAULT_IO_YIELD_MS > 0
+ assert DEFAULT_POLL_LINES > 0
+ assert DEFAULT_SESSION_TTL_SEC > 0
- def test_poll_session_declaration(self):
- exec_tool = self._make_exec_tool()
- tool = PollSessionTool(exec_tool)
- decl = tool._get_declaration()
- assert decl.name == "skill_poll_session"
- def test_kill_session_declaration(self):
- exec_tool = self._make_exec_tool()
- tool = KillSessionTool(exec_tool)
- decl = tool._get_declaration()
- assert decl.name == "skill_kill_session"
-
-
-# ---------------------------------------------------------------------------
-# create_exec_tools
-# ---------------------------------------------------------------------------
+class TestSessionStore:
+ @pytest.mark.asyncio
+ async def test_put_get_remove(self):
+ tool = _make_exec_tool()
+ sess = MagicMock()
+ sess.exited_at = None
+ sess.proc.state = AsyncMock(return_value=MagicMock(status="running", exit_code=None))
+ await tool._put_session("s1", sess)
+ got = await tool._get_session("s1")
+ assert got is sess
+ removed = await tool._remove_session("s1")
+ assert removed is sess
-class TestCreateExecTools:
- def test_creates_four_tools(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- result = create_exec_tools(run_tool)
- assert len(result) == 4
- exec_tool, write_tool, poll_tool, kill_tool = result
- assert isinstance(exec_tool, SkillExecTool)
- assert isinstance(write_tool, WriteStdinTool)
- assert isinstance(poll_tool, PollSessionTool)
- assert isinstance(kill_tool, KillSessionTool)
- def test_custom_ttl(self):
+class TestFactoryAndDeclarations:
+ def test_create_exec_tools(self):
run_tool = MagicMock()
run_tool._repository = MagicMock()
run_tool._timeout = 300.0
- exec_tool, *_ = create_exec_tools(run_tool, session_ttl=60.0)
- assert exec_tool._ttl == 60.0
+ tools = create_exec_tools(run_tool)
+ assert len(tools) == 4
+ assert isinstance(tools[0], SkillExecTool)
+ assert isinstance(tools[1], WriteStdinTool)
+ assert isinstance(tools[2], PollSessionTool)
+ def test_declaration_names(self):
+ exec_tool = _make_exec_tool()
+ assert exec_tool._get_declaration().name == "skill_exec"
+ assert WriteStdinTool(exec_tool)._get_declaration().name == "skill_write_stdin"
+ assert PollSessionTool(exec_tool)._get_declaration().name == "skill_poll_session"
-# ---------------------------------------------------------------------------
-# _close_session
-# ---------------------------------------------------------------------------
class TestCloseSession:
- def test_close_with_reader_task(self):
- sess = MagicMock()
- sess.reader_task = MagicMock()
- sess.reader_task.done = MagicMock(return_value=False)
- sess.master_fd = None
- sess.proc.stdin = None
- _close_session(sess)
- sess.reader_task.cancel.assert_called_once()
-
- def test_close_with_master_fd(self):
- sess = MagicMock()
- sess.reader_task = None
- sess.master_fd = 42
- sess.proc.stdin = None
- with patch("os.close") as mock_close:
- _close_session(sess)
- mock_close.assert_called_once_with(42)
- assert sess.master_fd is None
-
- def test_close_with_stdin(self):
- sess = MagicMock()
- sess.reader_task = None
- sess.master_fd = None
- sess.proc.stdin = MagicMock()
- sess.proc.stdin.is_closing = MagicMock(return_value=False)
- _close_session(sess)
- sess.proc.stdin.close.assert_called_once()
-
- def test_close_already_done(self):
+ @pytest.mark.asyncio
+ async def test_close_session(self):
sess = MagicMock()
- sess.reader_task = MagicMock()
- sess.reader_task.done = MagicMock(return_value=True)
- sess.master_fd = None
- sess.proc.stdin = None
- _close_session(sess)
- sess.reader_task.cancel.assert_not_called()
-
- def test_close_no_reader_task(self):
- sess = MagicMock()
- sess.reader_task = None
- sess.master_fd = None
- sess.proc.stdin = None
- _close_session(sess)
-
- def test_close_master_fd_oserror(self):
- sess = MagicMock()
- sess.reader_task = None
- sess.master_fd = 42
- sess.proc.stdin = None
- with patch("os.close", side_effect=OSError("test")):
- _close_session(sess)
- assert sess.master_fd is None
-
- def test_close_stdin_closing(self):
- sess = MagicMock()
- sess.reader_task = None
- sess.master_fd = None
- sess.proc.stdin = MagicMock()
- sess.proc.stdin.is_closing = MagicMock(return_value=True)
- _close_session(sess)
- sess.proc.stdin.close.assert_not_called()
-
-
-# ---------------------------------------------------------------------------
-# _ExecSession
-# ---------------------------------------------------------------------------
-
-class TestExecSession:
- async def test_append_and_total_output(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = None
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo hello")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- await sess.append_output("hello ")
- await sess.append_output("world")
- total = await sess.total_output()
- assert total == "hello world"
-
- async def test_yield_output_exited(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo hello")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- await sess.append_output("output text")
- status, chunk, offset, next_offset = await sess.yield_output(50, 0)
- assert status == "exited"
- assert "output text" in chunk
- assert sess.exit_code == 0
-
-
-# ---------------------------------------------------------------------------
-# _build_exec_env
-# ---------------------------------------------------------------------------
-
-class TestBuildExecEnv:
- def test_builds_env(self, tmp_path):
- from trpc_agent_sdk.skills.tools._skill_exec import _build_exec_env
- ws = MagicMock()
- ws.path = str(tmp_path)
- env = _build_exec_env(ws, {"MY_VAR": "test"})
- assert "MY_VAR" in env
- assert env["MY_VAR"] == "test"
-
- def test_sets_workspace_dirs(self, tmp_path):
- from trpc_agent_sdk.skills.tools._skill_exec import _build_exec_env
- ws = MagicMock()
- ws.path = str(tmp_path)
- env = _build_exec_env(ws, {})
- assert any("skills" in v.lower() or "SKILLS" in k for k, v in env.items())
-
-
-# ---------------------------------------------------------------------------
-# GC expired sessions
-# ---------------------------------------------------------------------------
-
-class TestGcExpired:
- async def test_gc_expired_sessions(self):
- import time
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- tool = SkillExecTool(run_tool, session_ttl=1.0)
-
- mock_session = MagicMock()
- mock_session.exited_at = time.time() - 100
- mock_session.reader_task = None
- mock_session.master_fd = None
- mock_session.proc.stdin = None
- tool._sessions["expired_session"] = mock_session
-
- # gc is called within put_session
- new_session = MagicMock()
- new_session.exited_at = None
- await tool._put_session("new", new_session)
-
- assert "expired_session" not in tool._sessions
- assert "new" in tool._sessions
-
- async def test_gc_ttl_zero_skips(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- tool = SkillExecTool(run_tool, session_ttl=0)
-
- mock_session = MagicMock()
- mock_session.exited_at = 1.0
- tool._sessions["s1"] = mock_session
-
- new_session = MagicMock()
- new_session.exited_at = None
- await tool._put_session("s2", new_session)
-
- assert "s1" in tool._sessions
-
-
-# ---------------------------------------------------------------------------
-# _write_stdin helper
-# ---------------------------------------------------------------------------
-
-class TestWriteStdin:
- async def test_write_pipe(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _write_stdin, _ExecSession
- proc = MagicMock()
- proc.returncode = None
- proc.stdin = MagicMock()
- proc.stdin.write = MagicMock()
- proc.stdin.drain = AsyncMock()
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- await _write_stdin(sess, "hello", submit=True)
- proc.stdin.write.assert_called_once()
- written = proc.stdin.write.call_args[0][0]
- assert b"hello\n" == written
-
- async def test_write_pipe_no_submit(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _write_stdin, _ExecSession
- proc = MagicMock()
- proc.returncode = None
- proc.stdin = MagicMock()
- proc.stdin.write = MagicMock()
- proc.stdin.drain = AsyncMock()
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- await _write_stdin(sess, "hello", submit=False)
- written = proc.stdin.write.call_args[0][0]
- assert b"hello" == written
-
- async def test_write_pipe_error_handled(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _write_stdin, _ExecSession
- proc = MagicMock()
- proc.returncode = None
- proc.stdin = MagicMock()
- proc.stdin.write = MagicMock(side_effect=RuntimeError("broken"))
- proc.stdin.drain = AsyncMock()
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- await _write_stdin(sess, "test", submit=False)
-
- async def test_write_pty(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _write_stdin, _ExecSession
- proc = MagicMock()
- proc.returncode = None
- proc.stdin = None
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- sess.master_fd = 42
-
- with patch("os.write") as mock_write:
- await _write_stdin(sess, "hello", submit=True)
- mock_write.assert_called_once_with(42, b"hello\n")
-
- async def test_write_pty_error(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _write_stdin, _ExecSession
- proc = MagicMock()
- proc.returncode = None
- proc.stdin = None
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- sess.master_fd = 42
-
- with patch("os.write", side_effect=OSError("broken")):
- await _write_stdin(sess, "hello", submit=False)
-
- async def test_write_no_stdin_no_pty(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _write_stdin, _ExecSession
- proc = MagicMock()
- proc.returncode = None
- proc.stdin = None
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- await _write_stdin(sess, "hello", submit=True)
-
-
-# ---------------------------------------------------------------------------
-# _collect_final_result
-# ---------------------------------------------------------------------------
-
-class TestCollectFinalResult:
- async def test_already_finalized(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _collect_final_result, _ExecSession
- from trpc_agent_sdk.skills.tools._skill_run import SkillRunOutput
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- sess.finalized = True
- expected = SkillRunOutput(stdout="cached")
- sess.final_result = expected
-
- ctx = MagicMock()
- run_tool = MagicMock()
- result = await _collect_final_result(ctx, sess, run_tool)
- assert result is expected
-
- async def test_collect_with_outputs(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _collect_final_result, _ExecSession
- from trpc_agent_sdk.skills.tools._skill_run import SkillRunFile
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo", output_files=["out/*.txt"])
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- sess.exit_code = 0
- await sess.append_output("test output")
-
- ctx = MagicMock()
- ctx.artifact_service = None
- run_tool = MagicMock()
- run_tool._prepare_outputs = AsyncMock(return_value=([], None))
- run_tool._attach_artifacts_if_requested = AsyncMock()
- run_tool._merge_manifest_artifact_refs = MagicMock()
-
- result = await _collect_final_result(ctx, sess, run_tool)
- assert result is not None
- assert result.stdout == "test output"
- assert sess.finalized is True
-
- async def test_collect_prepare_outputs_error(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _collect_final_result, _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- sess.exit_code = 0
- await sess.append_output("output")
-
- ctx = MagicMock()
- ctx.artifact_service = None
- run_tool = MagicMock()
- run_tool._prepare_outputs = AsyncMock(side_effect=RuntimeError("fail"))
- run_tool._attach_artifacts_if_requested = AsyncMock()
- run_tool._merge_manifest_artifact_refs = MagicMock()
-
- result = await _collect_final_result(ctx, sess, run_tool)
- assert result is not None
- assert sess.finalized is True
-
-
-# ---------------------------------------------------------------------------
-# _ExecSession — yield_output more tests
-# ---------------------------------------------------------------------------
-
-class TestExecSessionYieldOutput:
- async def test_yield_with_poll_lines_limit(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- long_output = "\n".join([f"line {i}" for i in range(100)])
- await sess.append_output(long_output)
-
- status, chunk, offset, next_offset = await sess.yield_output(10, 5)
- lines = chunk.strip().split("\n")
- assert len(lines) <= 5
-
- async def test_yield_incremental(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- await sess.append_output("first")
- _, chunk1, _, _ = await sess.yield_output(10, 0)
- assert "first" in chunk1
-
- await sess.append_output("second")
- _, chunk2, _, _ = await sess.yield_output(10, 0)
- assert "second" in chunk2
- assert "first" not in chunk2
-
-
-# ---------------------------------------------------------------------------
-# _read_pipe
-# ---------------------------------------------------------------------------
-
-class TestReadPipe:
- async def test_read_pipe_empty(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _read_pipe, _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- proc.wait = AsyncMock()
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- stream = AsyncMock()
- stream.read = AsyncMock(return_value=b"")
-
- await _read_pipe(sess, stream)
-
- async def test_read_pipe_with_data(self):
- from trpc_agent_sdk.skills.tools._skill_exec import _read_pipe, _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- proc.wait = AsyncMock()
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- stream = AsyncMock()
- stream.read = AsyncMock(side_effect=[b"hello", b""])
-
- await _read_pipe(sess, stream)
- total = await sess.total_output()
- assert "hello" in total
-
-
-# ---------------------------------------------------------------------------
-# KillSessionTool._run_async_impl
-# ---------------------------------------------------------------------------
-
-class TestKillSessionToolRun:
- def _make_exec_tool(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- return SkillExecTool(run_tool)
-
- async def test_kill_exited_session(self):
- exec_tool = self._make_exec_tool()
- kill_tool = KillSessionTool(exec_tool)
-
- mock_session = MagicMock()
- mock_session.proc.returncode = 0
- mock_session.exited_at = None
- mock_session.reader_task = None
- mock_session.master_fd = None
- mock_session.proc.stdin = None
-
- await exec_tool._put_session("s1", mock_session)
-
- ctx = MagicMock()
- result = await kill_tool._run_async_impl(
- tool_context=ctx,
- args={"session_id": "s1"},
- )
- assert result["ok"] is True
- assert result["status"] == "exited"
-
- async def test_kill_running_session(self):
- exec_tool = self._make_exec_tool()
- kill_tool = KillSessionTool(exec_tool)
-
- mock_session = MagicMock()
- mock_session.proc.returncode = None
- mock_session.proc.kill = MagicMock()
- mock_session.proc.wait = AsyncMock()
- mock_session.exited_at = None
- mock_session.reader_task = None
- mock_session.master_fd = None
- mock_session.proc.stdin = None
-
- await exec_tool._put_session("s1", mock_session)
-
- ctx = MagicMock()
- result = await kill_tool._run_async_impl(
- tool_context=ctx,
- args={"session_id": "s1"},
- )
- assert result["ok"] is True
- assert result["status"] == "killed"
- mock_session.proc.kill.assert_called_once()
-
- async def test_kill_invalid_args_raises(self):
- exec_tool = self._make_exec_tool()
- kill_tool = KillSessionTool(exec_tool)
- ctx = MagicMock()
- with pytest.raises(ValueError, match="Invalid"):
- await kill_tool._run_async_impl(tool_context=ctx, args={})
-
- async def test_kill_unknown_session_raises(self):
- exec_tool = self._make_exec_tool()
- kill_tool = KillSessionTool(exec_tool)
- ctx = MagicMock()
- with pytest.raises(ValueError, match="unknown session_id"):
- await kill_tool._run_async_impl(
- tool_context=ctx,
- args={"session_id": "nonexistent"},
- )
-
-
-# ---------------------------------------------------------------------------
-# PollSessionTool._run_async_impl
-# ---------------------------------------------------------------------------
-
-class TestPollSessionToolRun:
- async def test_poll_running_session(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- exec_tool = SkillExecTool(run_tool)
- poll_tool = PollSessionTool(exec_tool)
-
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="echo")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- await sess.append_output("poll output")
-
- await exec_tool._put_session("s1", sess)
-
- ctx = MagicMock()
- ctx.artifact_service = None
- result = await poll_tool._run_async_impl(
- tool_context=ctx,
- args={"session_id": "s1", "yield_ms": 10},
- )
- assert result["status"] == "exited"
- assert "poll output" in result["output"]
-
- async def test_poll_invalid_args_raises(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- exec_tool = SkillExecTool(run_tool)
- poll_tool = PollSessionTool(exec_tool)
- ctx = MagicMock()
- with pytest.raises(ValueError, match="Invalid"):
- await poll_tool._run_async_impl(tool_context=ctx, args={})
-
-
-# ---------------------------------------------------------------------------
-# WriteStdinTool._run_async_impl
-# ---------------------------------------------------------------------------
-
-class TestWriteStdinToolRun:
- async def test_write_and_poll(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- exec_tool = SkillExecTool(run_tool)
- write_tool = WriteStdinTool(exec_tool)
-
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- proc.stdin = MagicMock()
- proc.stdin.write = MagicMock()
- proc.stdin.drain = AsyncMock()
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
- await sess.append_output("response")
-
- await exec_tool._put_session("s1", sess)
-
- ctx = MagicMock()
- ctx.artifact_service = None
- result = await write_tool._run_async_impl(
- tool_context=ctx,
- args={"session_id": "s1", "chars": "input", "submit": True, "yield_ms": 10},
- )
- assert result["status"] == "exited"
-
- async def test_write_empty_chars(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- exec_tool = SkillExecTool(run_tool)
- write_tool = WriteStdinTool(exec_tool)
-
- from trpc_agent_sdk.skills.tools._skill_exec import _ExecSession
- proc = MagicMock()
- proc.returncode = 0
- ws = MagicMock()
- in_data = ExecInput(skill="test", command="cat")
- sess = _ExecSession(proc=proc, ws=ws, in_data=in_data)
-
- await exec_tool._put_session("s1", sess)
-
- ctx = MagicMock()
- ctx.artifact_service = None
- result = await write_tool._run_async_impl(
- tool_context=ctx,
- args={"session_id": "s1", "yield_ms": 10},
- )
- assert "status" in result
-
- async def test_write_invalid_args_raises(self):
- run_tool = MagicMock()
- run_tool._repository = MagicMock()
- run_tool._timeout = 300.0
- exec_tool = SkillExecTool(run_tool)
- write_tool = WriteStdinTool(exec_tool)
- ctx = MagicMock()
- with pytest.raises(ValueError, match="Invalid"):
- await write_tool._run_async_impl(tool_context=ctx, args={})
+ sess.proc.close = AsyncMock()
+ await _close_session(sess)
+ sess.proc.close.assert_awaited_once()
diff --git a/tests/skills/tools/test_skill_list_docs.py b/tests/skills/tools/test_skill_list_docs.py
index 33e6a76..26999d9 100644
--- a/tests/skills/tools/test_skill_list_docs.py
+++ b/tests/skills/tools/test_skill_list_docs.py
@@ -42,8 +42,7 @@ def test_returns_docs(self):
ctx = _make_ctx(repository=repo)
result = skill_list_docs(ctx, "test")
- assert result["docs"] == ["guide.md", "api.md"]
- assert result["body_loaded"] is True
+ assert result == ["guide.md", "api.md"]
def test_no_body(self):
skill = Skill(summary=SkillSummary(name="test"), body="")
@@ -52,17 +51,16 @@ def test_no_body(self):
ctx = _make_ctx(repository=repo)
result = skill_list_docs(ctx, "test")
- assert result["body_loaded"] is False
+ assert result == []
def test_skill_not_found(self):
repo = MagicMock()
- repo.get = MagicMock(return_value=None)
+ repo.get = MagicMock(side_effect=ValueError("not found"))
ctx = _make_ctx(repository=repo)
- result = skill_list_docs(ctx, "nonexistent")
- assert result == {"docs": [], "body_loaded": False}
+ with pytest.raises(ValueError, match="unknown skill"):
+ skill_list_docs(ctx, "nonexistent")
def test_no_repository_raises(self):
ctx = _make_ctx(repository=None)
- with pytest.raises(ValueError, match="repository not found"):
- skill_list_docs(ctx, "test")
+ assert skill_list_docs(ctx, "test") == []
diff --git a/tests/skills/tools/test_skill_list_tool.py b/tests/skills/tools/test_skill_list_tool.py
index 38769d4..220524a 100644
--- a/tests/skills/tools/test_skill_list_tool.py
+++ b/tests/skills/tools/test_skill_list_tool.py
@@ -3,13 +3,7 @@
# Copyright (C) 2026 Tencent. All rights reserved.
#
# tRPC-Agent-Python is licensed under Apache-2.0.
-"""Unit tests for trpc_agent_sdk.skills.tools._skill_list_tool.
-
-Covers:
-- _extract_shell_examples_from_skill_body: Command section parsing
-- skill_list_tools: returns tools and command examples
-- skill_list_tools: handles missing skill / repository
-"""
+"""Unit tests for trpc_agent_sdk.skills.tools._skill_list_tool."""
from __future__ import annotations
@@ -19,79 +13,10 @@
from trpc_agent_sdk.skills._types import Skill, SkillSummary
from trpc_agent_sdk.skills.tools._skill_list_tool import (
- _extract_shell_examples_from_skill_body,
skill_list_tools,
)
-# ---------------------------------------------------------------------------
-# _extract_shell_examples_from_skill_body
-# ---------------------------------------------------------------------------
-
-class TestExtractShellExamples:
- def test_empty_body(self):
- assert _extract_shell_examples_from_skill_body("") == []
-
- def test_command_section(self):
- body = "Command:\n python scripts/run.py --input data.csv\n\nOverview"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) >= 1
- assert "python scripts/run.py" in result[0]
-
- def test_limit(self):
- body = ""
- for i in range(10):
- body += f"Command:\n cmd_{i} --arg\n\n"
- result = _extract_shell_examples_from_skill_body(body, limit=3)
- assert len(result) <= 3
-
- def test_stops_at_section_break(self):
- body = "Command:\n python run.py\n\nOutput files\nMore content"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) == 1
-
- def test_multiline_command(self):
- body = "Command:\n python scripts/long.py \\\n --arg1 val1 \\\n --arg2 val2\n\n"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) >= 1
-
- def test_no_command_section(self):
- body = "# Overview\nJust a description.\n"
- result = _extract_shell_examples_from_skill_body(body)
- assert result == []
-
- def test_deduplication(self):
- body = "Command:\n python run.py\n\nCommand:\n python run.py\n"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) == 1
-
- def test_rejects_non_command_starting_chars(self):
- body = "Command:\n !not_a_command\n\n"
- result = _extract_shell_examples_from_skill_body(body)
- assert result == []
-
- def test_command_with_numbered_break(self):
- body = "Command:\n python run.py\n\n1) Next section\n"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) == 1
-
- def test_skips_empty_lines_before_command(self):
- body = "Command:\n\n\n python run.py\n\nEnd"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) >= 1
-
- def test_stops_at_tools_section(self):
- body = "Command:\n python run.py\n\ntools:\n- tool1"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) == 1
-
- def test_whitespace_normalization(self):
- body = "Command:\n python run.py --arg val\n\n"
- result = _extract_shell_examples_from_skill_body(body)
- assert len(result) == 1
- assert " " not in result[0]
-
-
# ---------------------------------------------------------------------------
# skill_list_tools
# ---------------------------------------------------------------------------
@@ -103,7 +28,7 @@ def _make_ctx(repository=None):
class TestSkillListTools:
- def test_returns_tools_and_examples(self):
+ def test_returns_tools(self):
skill = Skill(
summary=SkillSummary(name="test"),
body="Command:\n python run.py\n\nOverview",
@@ -114,8 +39,7 @@ def test_returns_tools_and_examples(self):
ctx = _make_ctx(repository=repo)
result = skill_list_tools(ctx, "test")
- assert result["tools"] == ["get_weather", "get_data"]
- assert len(result["command_examples"]) >= 1
+ assert result["available_tools"] == ["get_weather", "get_data"]
def test_skill_not_found(self):
repo = MagicMock()
@@ -123,7 +47,7 @@ def test_skill_not_found(self):
ctx = _make_ctx(repository=repo)
result = skill_list_tools(ctx, "nonexistent")
- assert result == {"tools": [], "command_examples": []}
+ assert result == {"available_tools": []}
def test_no_repository_raises(self):
ctx = _make_ctx(repository=None)
@@ -137,4 +61,4 @@ def test_no_tools_or_examples(self):
ctx = _make_ctx(repository=repo)
result = skill_list_tools(ctx, "test")
- assert result["tools"] == []
+ assert result["available_tools"] == []
diff --git a/tests/skills/tools/test_skill_load.py b/tests/skills/tools/test_skill_load.py
index 3bb87f5..7c4987b 100644
--- a/tests/skills/tools/test_skill_load.py
+++ b/tests/skills/tools/test_skill_load.py
@@ -14,17 +14,22 @@
from __future__ import annotations
+import asyncio
import json
+from unittest.mock import AsyncMock
from unittest.mock import MagicMock
+from unittest.mock import patch
import pytest
+from trpc_agent_sdk.skills._common import docs_state_key
+from trpc_agent_sdk.skills._common import loaded_state_key
+from trpc_agent_sdk.skills._common import set_state_delta
+from trpc_agent_sdk.skills._common import tool_state_key
+from trpc_agent_sdk.skills._constants import SKILL_REPOSITORY_KEY
from trpc_agent_sdk.skills._types import Skill, SkillSummary
from trpc_agent_sdk.skills.tools._skill_load import (
- _set_state_delta,
- _set_state_delta_for_skill_load,
- _set_state_delta_for_skill_tools,
- skill_load,
+ SkillLoadTool,
)
@@ -32,9 +37,44 @@ def _make_ctx(repository=None):
ctx = MagicMock()
ctx.actions.state_delta = {}
ctx.agent_context.get_metadata = MagicMock(return_value=repository)
+ ctx.agent_name = ""
return ctx
+def _set_state_delta_for_skill_load(ctx, skill_name: str, docs: list[str], include_all_docs: bool = False):
+ set_state_delta(ctx, loaded_state_key(ctx, skill_name), True)
+ set_state_delta(
+ ctx,
+ docs_state_key(ctx, skill_name),
+ "*" if include_all_docs else json.dumps(docs or []),
+ )
+
+
+def _set_state_delta_for_skill_tools(ctx, skill_name: str, tools: list[str]):
+ set_state_delta(ctx, tool_state_key(ctx, skill_name), json.dumps(tools or []))
+
+
+def _set_state_delta(ctx, key: str, value: str):
+ set_state_delta(ctx, key, value)
+
+
+def skill_load(ctx, skill_name: str, docs: list[str] | None = None, include_all_docs: bool = False) -> str:
+ repository = ctx.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
+ if repository is None:
+ raise ValueError("repository not found")
+ tool = SkillLoadTool(repository=repository)
+ with patch.object(SkillLoadTool, "_ensure_staged", new=AsyncMock(return_value=None)):
+ return asyncio.run(
+ tool._run_async_impl(
+ tool_context=ctx,
+ args={
+ "skill_name": skill_name,
+ "docs": docs or [],
+ "include_all_docs": include_all_docs,
+ },
+ ))
+
+
# ---------------------------------------------------------------------------
# _set_state_delta
# ---------------------------------------------------------------------------
@@ -55,21 +95,24 @@ class TestSetStateDeltaForSkillLoad:
def test_sets_loaded_flag(self):
ctx = MagicMock()
ctx.actions.state_delta = {}
+ ctx.agent_name = ""
_set_state_delta_for_skill_load(ctx, "test-skill", [])
- assert ctx.actions.state_delta["temp:skill:loaded:test-skill"] is True
+ assert ctx.actions.state_delta[loaded_state_key(ctx, "test-skill")] is True
def test_sets_docs_as_json(self):
ctx = MagicMock()
ctx.actions.state_delta = {}
+ ctx.agent_name = ""
_set_state_delta_for_skill_load(ctx, "test-skill", ["doc1.md", "doc2.md"])
- docs_value = ctx.actions.state_delta["temp:skill:docs:test-skill"]
+ docs_value = ctx.actions.state_delta[docs_state_key(ctx, "test-skill")]
assert json.loads(docs_value) == ["doc1.md", "doc2.md"]
def test_include_all_docs_sets_star(self):
ctx = MagicMock()
ctx.actions.state_delta = {}
+ ctx.agent_name = ""
_set_state_delta_for_skill_load(ctx, "test-skill", [], include_all_docs=True)
- assert ctx.actions.state_delta["temp:skill:docs:test-skill"] == "*"
+ assert ctx.actions.state_delta[docs_state_key(ctx, "test-skill")] == "*"
# ---------------------------------------------------------------------------
@@ -80,15 +123,17 @@ class TestSetStateDeltaForSkillTools:
def test_sets_tools_as_json(self):
ctx = MagicMock()
ctx.actions.state_delta = {}
+ ctx.agent_name = ""
_set_state_delta_for_skill_tools(ctx, "test-skill", ["tool_a", "tool_b"])
- tools_value = ctx.actions.state_delta["temp:skill:tools:test-skill"]
+ tools_value = ctx.actions.state_delta[tool_state_key(ctx, "test-skill")]
assert json.loads(tools_value) == ["tool_a", "tool_b"]
def test_empty_tools(self):
ctx = MagicMock()
ctx.actions.state_delta = {}
+ ctx.agent_name = ""
_set_state_delta_for_skill_tools(ctx, "test-skill", [])
- tools_value = ctx.actions.state_delta["temp:skill:tools:test-skill"]
+ tools_value = ctx.actions.state_delta[tool_state_key(ctx, "test-skill")]
assert json.loads(tools_value) == []
@@ -105,15 +150,15 @@ def test_load_success(self):
result = skill_load(ctx, "test")
assert "loaded" in result
- assert ctx.actions.state_delta["temp:skill:loaded:test"] is True
+ assert ctx.actions.state_delta[loaded_state_key(ctx, "test")] is True
def test_load_not_found(self):
repo = MagicMock()
- repo.get = MagicMock(return_value=None)
+ repo.get = MagicMock(side_effect=ValueError("not found"))
ctx = _make_ctx(repository=repo)
- result = skill_load(ctx, "nonexistent")
- assert "not found" in result
+ with pytest.raises(ValueError, match="not found"):
+ skill_load(ctx, "nonexistent")
def test_load_no_repository_raises(self):
ctx = _make_ctx(repository=None)
@@ -131,7 +176,7 @@ def test_load_with_tools_sets_tools_state(self):
ctx = _make_ctx(repository=repo)
skill_load(ctx, "test")
- tools_key = "temp:skill:tools:test"
+ tools_key = tool_state_key(ctx, "test")
assert tools_key in ctx.actions.state_delta
assert json.loads(ctx.actions.state_delta[tools_key]) == ["get_weather", "get_data"]
@@ -142,7 +187,7 @@ def test_load_without_tools_does_not_set_tools_state(self):
ctx = _make_ctx(repository=repo)
skill_load(ctx, "test")
- assert "temp:skill:tools:test" not in ctx.actions.state_delta
+ assert tool_state_key(ctx, "test") not in ctx.actions.state_delta
def test_load_with_docs(self):
skill = Skill(summary=SkillSummary(name="test"), body="# Body")
@@ -151,7 +196,7 @@ def test_load_with_docs(self):
ctx = _make_ctx(repository=repo)
skill_load(ctx, "test", docs=["doc1.md"])
- docs_key = "temp:skill:docs:test"
+ docs_key = docs_state_key(ctx, "test")
assert json.loads(ctx.actions.state_delta[docs_key]) == ["doc1.md"]
def test_load_include_all_docs(self):
@@ -161,5 +206,5 @@ def test_load_include_all_docs(self):
ctx = _make_ctx(repository=repo)
skill_load(ctx, "test", include_all_docs=True)
- docs_key = "temp:skill:docs:test"
+ docs_key = docs_state_key(ctx, "test")
assert ctx.actions.state_delta[docs_key] == "*"
diff --git a/tests/skills/tools/test_skill_run.py b/tests/skills/tools/test_skill_run.py
index c7489c2..b1e43ae 100644
--- a/tests/skills/tools/test_skill_run.py
+++ b/tests/skills/tools/test_skill_run.py
@@ -3,1050 +3,122 @@
# Copyright (C) 2026 Tencent. All rights reserved.
#
# tRPC-Agent-Python is licensed under Apache-2.0.
-"""Unit tests for trpc_agent_sdk.skills.tools._skill_run.
-
-Covers:
-- Module-level helpers:
- _inline_json_schema_refs, _is_text_mime, _should_inline_file_content,
- _truncate_output, _workspace_ref, _filter_failed_empty_outputs,
- _select_primary_output, _split_command_line, _build_editor_wrapper_script
-- Pydantic models: SkillRunFile, SkillRunInput, SkillRunOutput, ArtifactInfo
-- SkillRunTool:
- _resolve_cwd, _build_command, _wrap_with_venv, _is_skill_loaded,
- _get_repository, _is_missing_command_result, _extract_command_path_candidates,
- _extract_shell_examples_from_skill_body, _with_missing_command_hint
-"""
-
-from __future__ import annotations
import os
-from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import MagicMock
import pytest
-
-from trpc_agent_sdk.skills.tools._skill_run import (
- ArtifactInfo,
- SkillRunFile,
- SkillRunInput,
- SkillRunOutput,
- SkillRunTool,
- _build_editor_wrapper_script,
- _filter_failed_empty_outputs,
- _inline_json_schema_refs,
- _is_text_mime,
- _select_primary_output,
- _should_inline_file_content,
- _split_command_line,
- _truncate_output,
- _workspace_ref,
-)
-
-
-# ---------------------------------------------------------------------------
-# _inline_json_schema_refs
-# ---------------------------------------------------------------------------
-
-class TestInlineJsonSchemaRefs:
- def test_no_refs(self):
- schema = {"type": "object", "properties": {"name": {"type": "string"}}}
- result = _inline_json_schema_refs(schema)
- assert result == schema
-
- def test_with_refs(self):
- schema = {
- "$defs": {"Foo": {"type": "object", "properties": {"x": {"type": "integer"}}}},
- "properties": {"foo": {"$ref": "#/$defs/Foo"}},
- }
- result = _inline_json_schema_refs(schema)
- assert "$defs" not in result
- assert result["properties"]["foo"]["type"] == "object"
-
- def test_nested_refs(self):
- schema = {
- "$defs": {"Bar": {"type": "string"}},
- "properties": {"items": {"type": "array", "items": {"$ref": "#/$defs/Bar"}}},
- }
- result = _inline_json_schema_refs(schema)
- assert result["properties"]["items"]["items"]["type"] == "string"
-
-
-# ---------------------------------------------------------------------------
-# _is_text_mime
-# ---------------------------------------------------------------------------
-
-class TestIsTextMime:
- def test_text_plain(self):
+from trpc_agent_sdk.skills._common import loaded_state_key
+from trpc_agent_sdk.skills.tools._common import inline_json_schema_refs
+from trpc_agent_sdk.skills.tools._skill_run import ArtifactInfo
+from trpc_agent_sdk.skills.tools._skill_run import SkillRunFile
+from trpc_agent_sdk.skills.tools._skill_run import SkillRunInput
+from trpc_agent_sdk.skills.tools._skill_run import SkillRunOutput
+from trpc_agent_sdk.skills.tools._skill_run import SkillRunTool
+from trpc_agent_sdk.skills.tools._skill_run import _build_editor_wrapper_script
+from trpc_agent_sdk.skills.tools._skill_run import _filter_failed_empty_outputs
+from trpc_agent_sdk.skills.tools._skill_run import _is_text_mime
+from trpc_agent_sdk.skills.tools._skill_run import _select_primary_output
+from trpc_agent_sdk.skills.tools._skill_run import _should_inline_file_content
+from trpc_agent_sdk.skills.tools._skill_run import _split_command_line
+from trpc_agent_sdk.skills.tools._skill_run import _truncate_output
+from trpc_agent_sdk.skills.tools._skill_run import _workspace_ref
+
+
+def _make_tool() -> SkillRunTool:
+ repo = MagicMock()
+ repo.workspace_runtime = MagicMock()
+ return SkillRunTool(repository=repo)
+
+
+class TestSchemaHelpers:
+ def test_inline_json_schema_refs(self):
+ schema = {"$defs": {"X": {"type": "string"}}, "properties": {"x": {"$ref": "#/$defs/X"}}}
+ out = inline_json_schema_refs(schema)
+ assert "$defs" not in out
+ assert out["properties"]["x"]["type"] == "string"
+
+
+class TestModuleHelpers:
+ def test_is_text_mime(self):
assert _is_text_mime("text/plain") is True
-
- def test_text_html(self):
- assert _is_text_mime("text/html") is True
-
- def test_application_json(self):
assert _is_text_mime("application/json") is True
-
- def test_application_yaml(self):
- assert _is_text_mime("application/yaml") is True
-
- def test_application_xml(self):
- assert _is_text_mime("application/xml") is True
-
- def test_image_png(self):
assert _is_text_mime("image/png") is False
- def test_empty_string_is_text(self):
- assert _is_text_mime("") is True
-
- def test_with_charset(self):
- assert _is_text_mime("application/json; charset=utf-8") is True
-
- def test_octet_stream(self):
- assert _is_text_mime("application/octet-stream") is False
-
-
-# ---------------------------------------------------------------------------
-# _should_inline_file_content
-# ---------------------------------------------------------------------------
-
-class TestShouldInlineFileContent:
- def test_text_file(self):
- from trpc_agent_sdk.code_executors import CodeFile
- f = CodeFile(name="test.txt", content="hello", mime_type="text/plain", size_bytes=5)
- assert _should_inline_file_content(f) is True
-
- def test_binary_file(self):
+ def test_should_inline_file_content(self):
from trpc_agent_sdk.code_executors import CodeFile
- f = CodeFile(name="test.png", content="data", mime_type="image/png", size_bytes=4)
- assert _should_inline_file_content(f) is False
-
- def test_null_bytes_rejected(self):
- from trpc_agent_sdk.code_executors import CodeFile
- f = CodeFile(name="test.txt", content="hello\x00world", mime_type="text/plain", size_bytes=11)
- assert _should_inline_file_content(f) is False
-
- def test_empty_content(self):
- from trpc_agent_sdk.code_executors import CodeFile
- f = CodeFile(name="empty.txt", content="", mime_type="text/plain", size_bytes=0)
+ f = CodeFile(name="a.txt", content="ok", mime_type="text/plain", size_bytes=2)
assert _should_inline_file_content(f) is True
-
-# ---------------------------------------------------------------------------
-# _truncate_output
-# ---------------------------------------------------------------------------
-
-class TestTruncateOutput:
- def test_short_string(self):
- s, truncated = _truncate_output("hello")
- assert s == "hello"
- assert truncated is False
-
- def test_long_string(self):
+ def test_truncate_output(self):
s, truncated = _truncate_output("x" * 20000)
assert truncated is True
assert len(s) <= 16 * 1024
- def test_exact_limit(self):
- s, truncated = _truncate_output("x" * (16 * 1024))
- assert truncated is False
-
+ def test_workspace_ref(self):
+ assert _workspace_ref("a.txt") == "workspace://a.txt"
-# ---------------------------------------------------------------------------
-# _workspace_ref
-# ---------------------------------------------------------------------------
+ def test_filter_failed_empty_outputs(self):
+ files = [SkillRunFile(name="a.txt", content="", size_bytes=0)]
+ kept, warns = _filter_failed_empty_outputs(1, False, files)
+ assert kept == []
+ assert warns
-class TestWorkspaceRef:
- def test_with_name(self):
- assert _workspace_ref("out/file.txt") == "workspace://out/file.txt"
-
- def test_empty_name(self):
- assert _workspace_ref("") == ""
-
-
-# ---------------------------------------------------------------------------
-# _filter_failed_empty_outputs
-# ---------------------------------------------------------------------------
-
-class TestFilterFailedEmptyOutputs:
- def test_success_no_filter(self):
- files = [SkillRunFile(name="a.txt", content="data", size_bytes=4)]
- result, warns = _filter_failed_empty_outputs(0, False, files)
- assert len(result) == 1
- assert warns == []
-
- def test_failure_removes_empty(self):
- files = [
- SkillRunFile(name="a.txt", content="data", size_bytes=4),
- SkillRunFile(name="empty.txt", content="", size_bytes=0),
- ]
- result, warns = _filter_failed_empty_outputs(1, False, files)
- assert len(result) == 1
- assert result[0].name == "a.txt"
- assert len(warns) == 1
-
- def test_failure_all_have_content(self):
- files = [SkillRunFile(name="a.txt", content="data", size_bytes=4)]
- result, warns = _filter_failed_empty_outputs(1, False, files)
- assert len(result) == 1
- assert warns == []
-
- def test_timeout_removes_empty(self):
- files = [SkillRunFile(name="e.txt", content="", size_bytes=0)]
- result, warns = _filter_failed_empty_outputs(0, True, files)
- assert len(result) == 0
- assert len(warns) == 1
-
-
-# ---------------------------------------------------------------------------
-# _select_primary_output
-# ---------------------------------------------------------------------------
-
-class TestSelectPrimaryOutput:
- def test_picks_smallest_text_file(self):
+ def test_select_primary_output(self):
files = [
- SkillRunFile(name="b.txt", content="bbb", mime_type="text/plain"),
- SkillRunFile(name="a.txt", content="aaa", mime_type="text/plain"),
+ SkillRunFile(name="b.txt", content="2", mime_type="text/plain"),
+ SkillRunFile(name="a.txt", content="1", mime_type="text/plain"),
]
- result = _select_primary_output(files)
- assert result.name == "a.txt"
-
- def test_skips_empty_content(self):
- files = [SkillRunFile(name="a.txt", content="", mime_type="text/plain")]
- result = _select_primary_output(files)
- assert result is None
-
- def test_skips_binary(self):
- files = [SkillRunFile(name="a.png", content="data", mime_type="image/png")]
- result = _select_primary_output(files)
- assert result is None
-
- def test_empty_files(self):
- assert _select_primary_output([]) is None
-
- def test_skips_too_large(self):
- content = "x" * (32 * 1024 + 1)
- files = [SkillRunFile(name="big.txt", content=content, mime_type="text/plain")]
- assert _select_primary_output(files) is None
+ best = _select_primary_output(files)
+ assert best is not None
+ assert best.name == "a.txt"
-
-# ---------------------------------------------------------------------------
-# _split_command_line
-# ---------------------------------------------------------------------------
-
-class TestSplitCommandLine:
- def test_simple_command(self):
+ def test_split_command_line(self):
assert _split_command_line("python run.py") == ["python", "run.py"]
+ with pytest.raises(ValueError):
+ _split_command_line("a | b")
- def test_quoted_args(self):
- result = _split_command_line("echo 'hello world'")
- assert result == ["echo", "hello world"]
-
- def test_double_quoted(self):
- result = _split_command_line('echo "hello world"')
- assert result == ["echo", "hello world"]
-
- def test_empty_raises(self):
- with pytest.raises(ValueError, match="empty"):
- _split_command_line("")
-
- def test_whitespace_only_raises(self):
- with pytest.raises(ValueError, match="empty"):
- _split_command_line(" ")
-
- def test_shell_metachar_rejected(self):
- with pytest.raises(ValueError, match="metacharacter"):
- _split_command_line("cmd1 | cmd2")
-
- def test_semicolon_rejected(self):
- with pytest.raises(ValueError, match="metacharacter"):
- _split_command_line("cmd1; cmd2")
-
- def test_redirect_rejected(self):
- with pytest.raises(ValueError, match="metacharacter"):
- _split_command_line("cmd > file")
-
- def test_unterminated_quote_raises(self):
- with pytest.raises(ValueError, match="unterminated"):
- _split_command_line("echo 'hello")
-
- def test_trailing_escape_raises(self):
- with pytest.raises(ValueError, match="trailing"):
- _split_command_line("echo hello\\")
-
- def test_escaped_char(self):
- result = _split_command_line("echo hello\\ world")
- assert result == ["echo", "hello world"]
-
- def test_newline_rejected(self):
- with pytest.raises(ValueError, match="metacharacter"):
- _split_command_line("cmd1\ncmd2")
-
-
-# ---------------------------------------------------------------------------
-# _build_editor_wrapper_script
-# ---------------------------------------------------------------------------
-
-class TestBuildEditorWrapperScript:
- def test_contains_shebang(self):
- script = _build_editor_wrapper_script("/tmp/content.txt")
+ def test_build_editor_wrapper_script(self):
+ script = _build_editor_wrapper_script("/tmp/file")
assert script.startswith("#!/bin/sh")
+ assert "/tmp/file" in script
- def test_contains_content_path(self):
- script = _build_editor_wrapper_script("/tmp/content.txt")
- assert "/tmp/content.txt" in script
-
-# ---------------------------------------------------------------------------
-# Pydantic models
-# ---------------------------------------------------------------------------
-
-class TestSkillRunModels:
- def test_skill_run_file_defaults(self):
- f = SkillRunFile()
- assert f.name == ""
- assert f.content == ""
- assert f.size_bytes == 0
-
- def test_skill_run_input_required_fields(self):
- inp = SkillRunInput(skill="test", command="python run.py")
- assert inp.skill == "test"
- assert inp.command == "python run.py"
- assert inp.env == {}
- assert inp.output_files == []
-
- def test_skill_run_output_defaults(self):
+class TestModels:
+ def test_run_models(self):
+ inp = SkillRunInput(skill="s", command="echo hi")
out = SkillRunOutput()
- assert out.stdout == ""
+ art = ArtifactInfo(name="a.txt", version=1)
+ assert inp.skill == "s"
assert out.exit_code == 0
- assert out.timed_out is False
- assert out.output_files == []
-
- def test_artifact_info(self):
- a = ArtifactInfo(name="test.txt", version=1)
- assert a.name == "test.txt"
- assert a.version == 1
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — helpers
-# ---------------------------------------------------------------------------
-
-class TestSkillRunToolHelpers:
- def _make_run_tool(self, **kwargs):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo, **kwargs)
-
- def test_resolve_cwd_empty(self):
- tool = self._make_run_tool()
- assert tool._resolve_cwd("", "skills/test") == "skills/test"
-
- def test_resolve_cwd_relative(self):
- tool = self._make_run_tool()
- result = tool._resolve_cwd("sub/dir", "skills/test")
- assert result == os.path.join("skills/test", "sub/dir")
+ assert art.version == 1
- def test_resolve_cwd_absolute(self):
- tool = self._make_run_tool()
- assert tool._resolve_cwd("/abs/path", "skills/test") == "/abs/path"
- def test_resolve_cwd_skills_dir_env(self):
- tool = self._make_run_tool()
- result = tool._resolve_cwd("$SKILLS_DIR/test", "skills/test")
- assert "skills" in result
+class TestSkillRunToolBasics:
+ def test_resolve_cwd(self):
+ tool = _make_tool()
+ assert tool._resolve_cwd("", "skills/x") == "skills/x"
+ assert tool._resolve_cwd("sub", "skills/x") == os.path.join("skills/x", "sub")
- def test_build_command_no_restrictions(self):
- tool = self._make_run_tool()
- cmd, args = tool._build_command("python run.py", "/ws", "skills/test")
+ def test_build_command(self):
+ tool = _make_tool()
+ cmd, args = tool._build_command("python run.py", "/tmp/ws", "skills/x")
assert cmd == "bash"
assert "-c" in args
- def test_build_command_with_allowed_cmds(self):
- tool = self._make_run_tool(allowed_cmds=["python"])
- cmd, args = tool._build_command("python run.py", "/ws", "skills/test")
- assert cmd == "python"
- assert args == ["run.py"]
-
- def test_build_command_denied_cmd_raises(self):
- tool = self._make_run_tool(denied_cmds=["rm"])
- with pytest.raises(ValueError, match="denied"):
- tool._build_command("rm -rf /", "/ws", "skills/test")
-
- def test_build_command_not_in_allowed_raises(self):
- tool = self._make_run_tool(allowed_cmds=["python"])
- with pytest.raises(ValueError, match="not in allowed"):
- tool._build_command("bash script.sh", "/ws", "skills/test")
-
- def test_is_skill_loaded_true(self):
- tool = self._make_run_tool()
- ctx = MagicMock()
- ctx.session_state = {"temp:skill:loaded:test": True}
- assert tool._is_skill_loaded(ctx, "test") is True
-
- def test_is_skill_loaded_false(self):
- tool = self._make_run_tool()
- ctx = MagicMock()
- ctx.session_state = {}
- assert tool._is_skill_loaded(ctx, "test") is False
-
- def test_is_skill_loaded_exception_defaults_true(self):
- tool = self._make_run_tool()
- ctx = MagicMock()
- ctx.session_state = MagicMock()
- ctx.session_state.get = MagicMock(side_effect=RuntimeError("oops"))
- assert tool._is_skill_loaded(ctx, "test") is True
-
- def test_get_repository_from_tool(self):
+ def test_get_repository(self):
repo = MagicMock()
repo.workspace_runtime = MagicMock()
tool = SkillRunTool(repository=repo)
ctx = MagicMock()
assert tool._get_repository(ctx) is repo
- def test_is_missing_command_result_true(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- ret = WorkspaceRunResult(
- stdout="", stderr="bash: foo: command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- assert SkillRunTool._is_missing_command_result(ret) is True
-
- def test_is_missing_command_result_false(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- ret = WorkspaceRunResult(
- stdout="", stderr="error", exit_code=1, duration=0, timed_out=False,
- )
- assert SkillRunTool._is_missing_command_result(ret) is False
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _extract_shell_examples_from_skill_body
-# ---------------------------------------------------------------------------
-
-class TestExtractShellExamplesFromBody:
- def test_fenced_code_block(self):
- body = "# Usage\n```\npython scripts/run.py --input data.csv\n```\n"
- result = SkillRunTool._extract_shell_examples_from_skill_body(body)
- assert any("python" in r for r in result)
-
- def test_command_section(self):
- body = "Command:\n python scripts/analyze.py\n\nOverview"
- result = SkillRunTool._extract_shell_examples_from_skill_body(body)
- assert len(result) >= 1
-
- def test_empty_body(self):
- assert SkillRunTool._extract_shell_examples_from_skill_body("") == []
-
- def test_limit(self):
- body = ""
- for i in range(10):
- body += f"```\ncmd_{i}\n```\n"
- result = SkillRunTool._extract_shell_examples_from_skill_body(body, limit=3)
- assert len(result) <= 3
-
- def test_skips_function_calls(self):
- body = "```\nmy_function(arg='value')\n```\n"
- result = SkillRunTool._extract_shell_examples_from_skill_body(body)
- assert not any("my_function" in r for r in result)
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _extract_command_path_candidates
-# ---------------------------------------------------------------------------
-
-class TestExtractCommandPathCandidates:
- def test_relative_path(self):
- result = SkillRunTool._extract_command_path_candidates("python scripts/run.py")
- assert "scripts/run.py" in result
-
- def test_no_path_like_tokens(self):
- result = SkillRunTool._extract_command_path_candidates("ls -la")
- assert result == []
-
- def test_absolute_path_excluded(self):
- result = SkillRunTool._extract_command_path_candidates("python /abs/path.py")
- assert result == []
-
- def test_flags_excluded(self):
- result = SkillRunTool._extract_command_path_candidates("python --version")
- assert result == []
-
- def test_script_extensions(self):
- result = SkillRunTool._extract_command_path_candidates("bash setup.sh")
- assert "setup.sh" in result
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _with_missing_command_hint
-# ---------------------------------------------------------------------------
-
-class TestWithMissingCommandHint:
- def test_adds_hint_for_missing_command(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- ret = WorkspaceRunResult(
- stdout="", stderr="bash: nonexist: command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- inp = SkillRunInput(skill="test", command="nonexist")
- updated = SkillRunTool._with_missing_command_hint(ret, inp)
- assert "hint" in updated.stderr.lower()
-
- def test_no_hint_for_success(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- ret = WorkspaceRunResult(
- stdout="ok", stderr="", exit_code=0, duration=0, timed_out=False,
- )
- inp = SkillRunInput(skill="test", command="python run.py")
- updated = SkillRunTool._with_missing_command_hint(ret, inp)
- assert updated.stderr == ""
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — skill_stager property
-# ---------------------------------------------------------------------------
-
-class TestSkillRunToolProperties:
- def test_skill_stager_property(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- tool = SkillRunTool(repository=repo)
- assert tool.skill_stager is not None
-
- def test_custom_stager(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- custom_stager = MagicMock()
- tool = SkillRunTool(repository=repo, skill_stager=custom_stager)
- assert tool.skill_stager is custom_stager
-
- def test_declaration(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- tool = SkillRunTool(repository=repo)
- decl = tool._get_declaration()
- assert decl.name == "skill_run"
-
- def test_declaration_with_allowed_cmds(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- tool = SkillRunTool(repository=repo, allowed_cmds=["python", "bash"])
- decl = tool._get_declaration()
- assert "python" in decl.description
-
- def test_declaration_with_denied_cmds(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- tool = SkillRunTool(repository=repo, denied_cmds=["rm"])
- decl = tool._get_declaration()
- assert "Restrictions" in decl.description
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _wrap_with_venv
-# ---------------------------------------------------------------------------
-
-class TestWrapWithVenv:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- def test_wraps_command(self):
- tool = self._make_tool()
- result = tool._wrap_with_venv("python run.py", "/ws", "skills/test")
- assert "VIRTUAL_ENV" in result
- assert "python run.py" in result
- assert ".venv" in result
-
- def test_non_skills_cwd(self):
- tool = self._make_tool()
- result = tool._wrap_with_venv("echo hi", "/ws", "work/custom")
- assert "echo hi" in result
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _with_skill_doc_command_hint
-# ---------------------------------------------------------------------------
-
-class TestWithSkillDocCommandHint:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- def test_adds_hint_for_missing_command(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="", stderr="bash: nonexist: command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- skill = MagicMock()
- skill.body = "```\npython scripts/run.py\n```\n"
- skill.tools = ["get_weather"]
- repo = MagicMock()
- repo.get = MagicMock(return_value=skill)
- inp = SkillRunInput(skill="test", command="nonexist")
- updated = tool._with_skill_doc_command_hint(ret, repo, inp)
- assert "SKILL.md" in updated.stderr
-
- def test_no_hint_for_success(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="ok", stderr="", exit_code=0, duration=0, timed_out=False,
- )
- repo = MagicMock()
- inp = SkillRunInput(skill="test", command="python run.py")
- updated = tool._with_skill_doc_command_hint(ret, repo, inp)
- assert updated.stderr == ""
-
- def test_repo_exception_returns_unchanged(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="", stderr="bash: x: command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- repo = MagicMock()
- repo.get = MagicMock(side_effect=RuntimeError("fail"))
- inp = SkillRunInput(skill="test", command="x")
- updated = tool._with_skill_doc_command_hint(ret, repo, inp)
- assert updated is ret
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _suggest_commands/_suggest_tools
-# ---------------------------------------------------------------------------
-
-class TestSuggestMethods:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- def test_suggest_commands_for_missing(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="", stderr="command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- skill = MagicMock()
- skill.body = "```\npython run.py\n```\n"
- repo = MagicMock()
- repo.get = MagicMock(return_value=skill)
- result = tool._suggest_commands_for_missing_command(ret, repo, "test")
- assert result is not None
-
- def test_suggest_commands_no_missing(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="ok", stderr="", exit_code=0, duration=0, timed_out=False,
- )
- repo = MagicMock()
- result = tool._suggest_commands_for_missing_command(ret, repo, "test")
- assert result is None
-
- def test_suggest_tools_for_missing(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="", stderr="command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- skill = MagicMock()
- skill.tools = ["get_data"]
- repo = MagicMock()
- repo.get = MagicMock(return_value=skill)
- result = tool._suggest_tools_for_missing_command(ret, repo, "test")
- assert result == ["get_data"]
-
- def test_suggest_tools_no_tools(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="", stderr="command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- skill = MagicMock()
- skill.tools = []
- repo = MagicMock()
- repo.get = MagicMock(return_value=skill)
- result = tool._suggest_tools_for_missing_command(ret, repo, "test")
- assert result is None
-
- def test_suggest_commands_repo_error(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- tool = self._make_tool()
- ret = WorkspaceRunResult(
- stdout="", stderr="command not found",
- exit_code=127, duration=0, timed_out=False,
- )
- repo = MagicMock()
- repo.get = MagicMock(side_effect=RuntimeError("fail"))
- result = tool._suggest_commands_for_missing_command(ret, repo, "test")
- assert result is None
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _precheck_inline_python_rewrite
-# ---------------------------------------------------------------------------
-
-class TestPrecheckInlinePythonRewrite:
- def test_not_blocked_when_disabled(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- tool = SkillRunTool(repository=repo, block_inline_python_rewrite=False)
- inp = SkillRunInput(skill="test", command="python -c 'print(1)'")
- assert tool._precheck_inline_python_rewrite(repo, inp) is None
-
- def test_not_python_c(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- tool = SkillRunTool(repository=repo, block_inline_python_rewrite=True)
- inp = SkillRunInput(skill="test", command="python run.py")
- assert tool._precheck_inline_python_rewrite(repo, inp) is None
-
- def test_blocked_with_script_examples(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- skill = MagicMock()
- skill.body = "```\npython3 scripts/analyze.py --input data\n```\n"
- repo.get = MagicMock(return_value=skill)
- tool = SkillRunTool(repository=repo, block_inline_python_rewrite=True)
- inp = SkillRunInput(skill="test", command="python -c 'import sys; print(sys.argv)'")
- result = tool._precheck_inline_python_rewrite(repo, inp)
- assert result is not None
- assert result.exit_code == 2
-
- def test_not_blocked_without_script_examples(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- skill = MagicMock()
- skill.body = "```\necho hello\n```\n"
- repo.get = MagicMock(return_value=skill)
- tool = SkillRunTool(repository=repo, block_inline_python_rewrite=True)
- inp = SkillRunInput(skill="test", command="python -c 'print(1)'")
- result = tool._precheck_inline_python_rewrite(repo, inp)
- assert result is None
-
- def test_repo_error_returns_none(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- repo.get = MagicMock(side_effect=RuntimeError("fail"))
- tool = SkillRunTool(repository=repo, block_inline_python_rewrite=True)
- inp = SkillRunInput(skill="test", command="python -c 'print(1)'")
- result = tool._precheck_inline_python_rewrite(repo, inp)
- assert result is None
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _list_entrypoint_suggestions
-# ---------------------------------------------------------------------------
-
-class TestListEntrypointSuggestions:
- def test_finds_scripts(self, tmp_path):
- scripts = tmp_path / "scripts"
- scripts.mkdir()
- (scripts / "run.py").write_text("#!/usr/bin/env python")
- result = SkillRunTool._list_entrypoint_suggestions(tmp_path)
- assert any("run.py" in r for r in result)
-
- def test_empty_dir(self, tmp_path):
- assert SkillRunTool._list_entrypoint_suggestions(tmp_path) == []
-
- def test_limit(self, tmp_path):
- scripts = tmp_path / "scripts"
- scripts.mkdir()
- for i in range(30):
- (scripts / f"script_{i}.py").write_text(f"# script {i}")
- result = SkillRunTool._list_entrypoint_suggestions(tmp_path, limit=5)
- assert len(result) <= 5
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _with_missing_entrypoint_hint
-# ---------------------------------------------------------------------------
-
-class TestWithMissingEntrypointHint:
- def test_adds_hint_for_missing_file(self, tmp_path):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- scripts = tmp_path / "skills" / "test" / "scripts"
- scripts.mkdir(parents=True)
- (scripts / "real.py").write_text("# real")
- ws = MagicMock()
- ws.path = str(tmp_path)
- ret = WorkspaceRunResult(
- stdout="", stderr="No such file or directory",
- exit_code=1, duration=0, timed_out=False,
- )
- inp = SkillRunInput(skill="test", command="python scripts/missing.py")
- updated = SkillRunTool._with_missing_entrypoint_hint(ret, inp, ws, "skills/test")
- assert "hint" in updated.stderr.lower() or "entrypoint" in updated.stderr.lower()
-
- def test_no_hint_for_success(self):
- from trpc_agent_sdk.code_executors import WorkspaceRunResult
- ret = WorkspaceRunResult(
- stdout="ok", stderr="", exit_code=0, duration=0, timed_out=False,
- )
- ws = MagicMock()
- ws.path = "/tmp/ws"
- inp = SkillRunInput(skill="test", command="python run.py")
- updated = SkillRunTool._with_missing_entrypoint_hint(ret, inp, ws, "skills/test")
- assert updated is ret
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _merge_manifest_artifact_refs
-# ---------------------------------------------------------------------------
-
-class TestMergeManifestArtifactRefs:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- def test_none_manifest_noop(self):
- tool = self._make_tool()
- output = SkillRunOutput()
- tool._merge_manifest_artifact_refs(None, output)
- assert output.artifact_files == []
-
- def test_already_has_artifacts_noop(self):
- tool = self._make_tool()
- output = SkillRunOutput(artifact_files=[ArtifactInfo(name="x", version=1)])
- manifest = MagicMock()
- tool._merge_manifest_artifact_refs(manifest, output)
- assert len(output.artifact_files) == 1
-
- def test_merges_from_manifest(self):
- tool = self._make_tool()
- output = SkillRunOutput()
- manifest = MagicMock()
- fr = MagicMock()
- fr.saved_as = "artifact.txt"
- fr.version = 2
- manifest.files = [fr]
- tool._merge_manifest_artifact_refs(manifest, output)
- assert len(output.artifact_files) == 1
- assert output.artifact_files[0].name == "artifact.txt"
-
- def test_skips_unsaved(self):
- tool = self._make_tool()
- output = SkillRunOutput()
- manifest = MagicMock()
- fr = MagicMock()
- fr.saved_as = ""
- manifest.files = [fr]
- tool._merge_manifest_artifact_refs(manifest, output)
- assert output.artifact_files == []
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _to_run_file / _to_run_files
-# ---------------------------------------------------------------------------
-
-class TestToRunFile:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- def test_text_file(self):
- from trpc_agent_sdk.code_executors import CodeFile
- tool = self._make_tool()
- cf = CodeFile(name="test.txt", content="hello", mime_type="text/plain", size_bytes=5)
- rf = tool._to_run_file(cf)
- assert rf.name == "test.txt"
- assert rf.content == "hello"
- assert rf.ref == "workspace://test.txt"
-
- def test_binary_file_omits_content(self):
- from trpc_agent_sdk.code_executors import CodeFile
- tool = self._make_tool()
- cf = CodeFile(name="img.png", content="binary", mime_type="image/png", size_bytes=100)
- rf = tool._to_run_file(cf)
- assert rf.content == ""
-
- def test_to_run_files(self):
- from trpc_agent_sdk.code_executors import CodeFile
- tool = self._make_tool()
- files = [
- CodeFile(name="a.txt", content="a", mime_type="text/plain", size_bytes=1),
- CodeFile(name="b.txt", content="b", mime_type="text/plain", size_bytes=1),
- ]
- result = tool._to_run_files(files)
- assert len(result) == 2
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _prepare_editor_env
-# ---------------------------------------------------------------------------
-
-class TestPrepareEditorEnv:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- async def test_empty_editor_text_noop(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ws = MagicMock()
- ws.path = "/tmp/ws"
- env = {}
- await tool._prepare_editor_env(ctx, ws, env, "")
- assert "EDITOR" not in env
-
- async def test_editor_env_conflict_raises(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ws = MagicMock()
- ws.path = "/tmp/ws"
- env = {"EDITOR": "/usr/bin/vim"}
- with pytest.raises(ValueError, match="editor_text cannot be combined"):
- await tool._prepare_editor_env(ctx, ws, env, "some text")
-
- async def test_visual_env_conflict_raises(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ws = MagicMock()
- ws.path = "/tmp/ws"
- env = {"VISUAL": "/usr/bin/vim"}
- with pytest.raises(ValueError, match="editor_text cannot be combined"):
- await tool._prepare_editor_env(ctx, ws, env, "some text")
-
- async def test_stages_editor_files(self, tmp_path):
- repo = MagicMock()
- fs = MagicMock()
- fs.put_files = AsyncMock()
- runtime = MagicMock()
- runtime.fs = MagicMock(return_value=fs)
- repo.workspace_runtime = runtime
- tool = SkillRunTool(repository=repo)
-
+ def test_is_skill_loaded(self):
+ tool = _make_tool()
ctx = MagicMock()
- ws = MagicMock()
- ws.path = str(tmp_path)
- env = {}
- await tool._prepare_editor_env(ctx, ws, env, "editor content")
- assert "EDITOR" in env
- assert "VISUAL" in env
-
- async def test_fallback_to_local_write(self, tmp_path):
- repo = MagicMock()
- fs = MagicMock()
- fs.put_files = AsyncMock(side_effect=RuntimeError("workspace unavailable"))
- runtime = MagicMock()
- runtime.fs = MagicMock(return_value=fs)
- repo.workspace_runtime = runtime
- tool = SkillRunTool(repository=repo)
-
- ctx = MagicMock()
- ws = MagicMock()
- ws.path = str(tmp_path)
- env = {}
- await tool._prepare_editor_env(ctx, ws, env, "editor content")
- assert "EDITOR" in env
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _attach_artifacts_if_requested
-# ---------------------------------------------------------------------------
-
-class TestAttachArtifacts:
- def _make_tool(self):
- repo = MagicMock()
- repo.workspace_runtime = MagicMock()
- return SkillRunTool(repository=repo)
-
- async def test_no_files_noop(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo", save_as_artifacts=True)
- output = SkillRunOutput()
- await tool._attach_artifacts_if_requested(ctx, ws, inp, output, [])
-
- async def test_not_requested_noop(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo", save_as_artifacts=False)
- output = SkillRunOutput()
- files = [SkillRunFile(name="a.txt", content="hello")]
- await tool._attach_artifacts_if_requested(ctx, ws, inp, output, files)
- assert output.artifact_files == []
-
- async def test_no_artifact_service_warns(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ctx.artifact_service = None
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo", save_as_artifacts=True)
- output = SkillRunOutput()
- files = [SkillRunFile(name="a.txt", content="hello")]
- await tool._attach_artifacts_if_requested(ctx, ws, inp, output, files)
- assert any("not configured" in w for w in output.warnings)
-
- async def test_save_artifacts(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ctx.artifact_service = MagicMock()
- ctx.save_artifact = AsyncMock(return_value=1)
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo", save_as_artifacts=True)
- output = SkillRunOutput()
- files = [SkillRunFile(name="a.txt", content="hello", mime_type="text/plain")]
- await tool._attach_artifacts_if_requested(ctx, ws, inp, output, files)
- assert len(output.artifact_files) == 1
- assert output.artifact_files[0].name == "a.txt"
-
- async def test_save_artifacts_with_prefix(self):
- tool = self._make_tool()
- ctx = MagicMock()
- ctx.artifact_service = MagicMock()
- ctx.save_artifact = AsyncMock(return_value=1)
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo", save_as_artifacts=True, artifact_prefix="out/")
- output = SkillRunOutput()
- files = [SkillRunFile(name="a.txt", content="hello", mime_type="text/plain")]
- await tool._attach_artifacts_if_requested(ctx, ws, inp, output, files)
- assert output.artifact_files[0].name == "out/a.txt"
-
-
-# ---------------------------------------------------------------------------
-# SkillRunTool — _prepare_outputs
-# ---------------------------------------------------------------------------
-
-class TestPrepareOutputs:
- def _make_tool(self):
- repo = MagicMock()
- fs = MagicMock()
- runtime = MagicMock()
- runtime.fs = MagicMock(return_value=fs)
- repo.workspace_runtime = runtime
- return SkillRunTool(repository=repo), fs
-
- async def test_no_outputs(self):
- tool, fs = self._make_tool()
- ctx = MagicMock()
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo")
- files, manifest = await tool._prepare_outputs(ctx, ws, inp)
- assert files == []
- assert manifest is None
-
- async def test_output_files_patterns(self):
- tool, fs = self._make_tool()
- from trpc_agent_sdk.code_executors import CodeFile
- fs.collect = AsyncMock(return_value=[
- CodeFile(name="out/a.txt", content="hello", mime_type="text/plain", size_bytes=5)
- ])
- ctx = MagicMock()
- ws = MagicMock()
- inp = SkillRunInput(skill="test", command="echo", output_files=["out/*.txt"])
- files, manifest = await tool._prepare_outputs(ctx, ws, inp)
- assert len(files) == 1
- assert manifest is None
+ ctx.agent_name = ""
+ ctx.actions = MagicMock()
+ key = loaded_state_key(ctx, "test")
+ ctx.actions.state_delta = {key: True}
+ ctx.session_state = {}
+ assert tool._is_skill_loaded(ctx, "test") is True
diff --git a/tests/skills/tools/test_skill_select_docs.py b/tests/skills/tools/test_skill_select_docs.py
index f52660b..1d8577e 100644
--- a/tests/skills/tools/test_skill_select_docs.py
+++ b/tests/skills/tools/test_skill_select_docs.py
@@ -17,16 +17,22 @@
import pytest
+from trpc_agent_sdk.skills._constants import SKILL_CONFIG_KEY
from trpc_agent_sdk.skills.tools._skill_select_docs import (
SkillSelectDocsResult,
skill_select_docs,
)
+from trpc_agent_sdk.skills._common import docs_state_key
+from trpc_agent_sdk.skills._skill_config import DEFAULT_SKILL_CONFIG
def _make_ctx(state_delta=None, session_state=None):
ctx = MagicMock()
ctx.actions.state_delta = state_delta or {}
ctx.session_state = session_state or {}
+ ctx.agent_name = ""
+ ctx.agent_context.get_metadata = MagicMock(
+ side_effect=lambda key, default=None: DEFAULT_SKILL_CONFIG if key == SKILL_CONFIG_KEY else default)
return ctx
@@ -76,18 +82,16 @@ def test_replace_mode(self):
assert result.selected_docs == ["doc1.md", "doc2.md"]
def test_add_mode(self):
- ctx = _make_ctx(session_state={
- "temp:skill:docs:test-skill": json.dumps(["existing.md"]),
- })
+ ctx = _make_ctx()
+ ctx.session_state = {docs_state_key(ctx, "test-skill"): json.dumps(["existing.md"])}
result = skill_select_docs(ctx, "test-skill", docs=["new.md"], mode="add")
assert result.mode == "add"
assert "existing.md" in result.selected_docs
assert "new.md" in result.selected_docs
def test_clear_mode(self):
- ctx = _make_ctx(session_state={
- "temp:skill:docs:test-skill": json.dumps(["some.md"]),
- })
+ ctx = _make_ctx()
+ ctx.session_state = {docs_state_key(ctx, "test-skill"): json.dumps(["some.md"])}
result = skill_select_docs(ctx, "test-skill", mode="clear")
assert result.mode == "clear"
assert result.selected_docs == []
@@ -100,5 +104,5 @@ def test_include_all_docs(self):
def test_updates_state_delta(self):
ctx = _make_ctx()
skill_select_docs(ctx, "test-skill", docs=["a.md"], mode="replace")
- key = "temp:skill:docs:test-skill"
+ key = docs_state_key(ctx, "test-skill")
assert key in ctx.actions.state_delta
diff --git a/tests/skills/tools/test_skill_select_tools.py b/tests/skills/tools/test_skill_select_tools.py
index 6bd2489..9b9fe98 100644
--- a/tests/skills/tools/test_skill_select_tools.py
+++ b/tests/skills/tools/test_skill_select_tools.py
@@ -17,16 +17,22 @@
import pytest
+from trpc_agent_sdk.skills._constants import SKILL_CONFIG_KEY
from trpc_agent_sdk.skills.tools._skill_select_tools import (
SkillSelectToolsResult,
skill_select_tools,
)
+from trpc_agent_sdk.skills._common import tool_state_key
+from trpc_agent_sdk.skills._skill_config import DEFAULT_SKILL_CONFIG
def _make_ctx(state_delta=None, session_state=None):
ctx = MagicMock()
ctx.actions.state_delta = state_delta or {}
ctx.session_state = session_state or {}
+ ctx.agent_name = ""
+ ctx.agent_context.get_metadata = MagicMock(
+ side_effect=lambda key, default=None: DEFAULT_SKILL_CONFIG if key == SKILL_CONFIG_KEY else default)
return ctx
@@ -74,18 +80,16 @@ def test_replace_mode(self):
assert result.selected_tools == ["tool_a", "tool_b"]
def test_add_mode(self):
- ctx = _make_ctx(session_state={
- "temp:skill:tools:test-skill": json.dumps(["existing_tool"]),
- })
+ ctx = _make_ctx()
+ ctx.session_state = {tool_state_key(ctx, "test-skill"): json.dumps(["existing_tool"])}
result = skill_select_tools(ctx, "test-skill", tools=["new_tool"], mode="add")
assert result.mode == "add"
assert "existing_tool" in result.selected_tools
assert "new_tool" in result.selected_tools
def test_clear_mode(self):
- ctx = _make_ctx(session_state={
- "temp:skill:tools:test-skill": json.dumps(["tool"]),
- })
+ ctx = _make_ctx()
+ ctx.session_state = {tool_state_key(ctx, "test-skill"): json.dumps(["tool"])}
result = skill_select_tools(ctx, "test-skill", mode="clear")
assert result.mode == "clear"
assert result.selected_tools == []
@@ -98,5 +102,5 @@ def test_include_all_tools(self):
def test_updates_state_delta(self):
ctx = _make_ctx()
skill_select_tools(ctx, "test-skill", tools=["t1"], mode="replace")
- key = "temp:skill:tools:test-skill"
+ key = tool_state_key(ctx, "test-skill")
assert key in ctx.actions.state_delta
diff --git a/tests/skills/tools/test_workspace_exec.py b/tests/skills/tools/test_workspace_exec.py
new file mode 100644
index 0000000..467e6a9
--- /dev/null
+++ b/tests/skills/tools/test_workspace_exec.py
@@ -0,0 +1,34 @@
+import pytest
+
+from trpc_agent_sdk.code_executors import PROGRAM_STATUS_RUNNING
+from trpc_agent_sdk.code_executors import ProgramPoll
+from trpc_agent_sdk.skills.tools._workspace_exec import _combine_output
+from trpc_agent_sdk.skills.tools._workspace_exec import _exec_timeout_seconds
+from trpc_agent_sdk.skills.tools._workspace_exec import _exec_yield_seconds
+from trpc_agent_sdk.skills.tools._workspace_exec import _normalize_cwd
+from trpc_agent_sdk.skills.tools._workspace_exec import _poll_output
+from trpc_agent_sdk.skills.tools._workspace_exec import _write_yield_seconds
+
+
+def test_normalize_cwd():
+ assert _normalize_cwd("") == "."
+ assert _normalize_cwd("work/demo") == "work/demo"
+ with pytest.raises(ValueError, match="within the workspace"):
+ _normalize_cwd("../demo")
+
+
+def test_timeout_and_yield_helpers():
+ assert _exec_timeout_seconds(0) > 0
+ assert _exec_timeout_seconds(3) == 3.0
+ assert _exec_yield_seconds(background=True, raw_ms=None) == 0.0
+ assert _exec_yield_seconds(background=False, raw_ms=100) == 0.1
+ assert _write_yield_seconds(None) > 0.0
+ assert _write_yield_seconds(-1) == 0.0
+
+
+def test_poll_output_and_combine_output():
+ poll = ProgramPoll(status=PROGRAM_STATUS_RUNNING, output="ok", offset=1, next_offset=2)
+ out = _poll_output("sid-1", poll)
+ assert out["session_id"] == "sid-1"
+ assert out["output"] == "ok"
+ assert _combine_output("a", "b") == "ab"
diff --git a/trpc_agent_sdk/agents/core/README.md b/trpc_agent_sdk/agents/core/README.md
new file mode 100644
index 0000000..4dbbaa2
--- /dev/null
+++ b/trpc_agent_sdk/agents/core/README.md
@@ -0,0 +1,249 @@
+# trpc_agent/agents/core 说明
+
+本文档面向读者解释 [`trpc_agent/agents/core`](./) 中与 Skills 相关的请求处理逻辑，重点覆盖三个处理器：
+
+- `SkillsRequestProcessor`（[`_skill_processor.py`](./_skill_processor.py)）
+- `WorkspaceExecRequestProcessor`（[`_workspace_exec_processor.py`](./_workspace_exec_processor.py)）
+- `SkillsToolResultRequestProcessor`（[`_skills_tool_result_processor.py`](./_skills_tool_result_processor.py)）
+
+文档目标是回答三个问题：
+
+1. 每个处理器解决什么问题
+2. 处理器在请求流水线中的位置与协作关系
+3. 如何在运行时判断“功能已生效”
+
+## 1. 请求流水线中的职责划分
+
+在 `RequestProcessor` 的技能相关路径中（简化）：
+
+1. 组装基础 instruction
+2. 注入 tools
+3. `SkillsRequestProcessor`：注入 skills 总览与（可选）已加载内容
+4. `WorkspaceExecRequestProcessor`：注入 `workspace_exec` guidance
+5. 注入会话历史
+6. `SkillsToolResultRequestProcessor`：在 post-history 阶段做 tool result 物化
+7. 其他能力（planning/output schema 等）
+
+可理解为：
+
+- `SkillsRequestProcessor` 负责“技能上下文主编排”
+- `WorkspaceExecRequestProcessor` 负责“执行器工具选择引导”
+- `SkillsToolResultRequestProcessor` 负责“tool_result_mode 下的内容物化补强”
+
+## 2. SkillsRequestProcessor（核心入口）
+
+主入口：
+
+- `SkillsRequestProcessor.process_llm_request(ctx, request)`
+
+### 2.1 解决的问题
+
+模型在多技能场景需要两类信息：
+
+- 可用 skill 总览（有哪些技能、各自做什么）
+- 已加载 skill 的正文/文档/工具选择（当前上下文真正可用什么）
+
+`SkillsRequestProcessor` 提供统一策略来管理这些信息，并在 `turn/once/session` 三种加载模式下保持行为一致。
+
+### 2.2 核心行为
+
+一次调用中，典型流程如下：
+
+1. 获取 skill repo（支持 `repo_resolver(ctx)` 动态仓库）
+2. 执行旧状态迁移（兼容历史 key）与 turn 模式清理
+3. 注入 skill 概览（始终执行）
+4. 读取 loaded skills 并按 `max_loaded_skills` 裁剪
+5. `load_mode=session` 在 temp-only 设计下与 `turn` 读取语义一致
+6. 根据 `tool_result_mode` 分流：
+ - `False`：直接向 system instruction 注入 `[Loaded]`、`Docs loaded`、`[Doc]`
+ - `True`：跳过注入，交给 `SkillsToolResultRequestProcessor` 处理
+7. `load_mode=once` 时清理 loaded/docs/tools/order 状态（offload）
+
+### 2.3 状态语义
+
+- `turn`
+ - 每次 invocation 开始清理一次技能状态
+ - 对应：`_maybe_clear_skill_state_for_turn`
+- `once`
+ - 本轮用完后清理，避免持续占用上下文
+ - 对应：`_maybe_offload_loaded_skills`
+- `session`
+ - 在 temp-only 状态模型下，不再维护 `user:skill:*` 双键
+ - 对应：`_maybe_promote_skill_state_for_session`（当前为 no-op）
+
+读取策略为单一 temp key 读取（`session_state + state_delta` 视图）。
+
+### 2.4 关键参数
+
+- `load_mode`: `turn` / `once` / `session`
+- `tool_result_mode`: 是否改为 tool result materialization 路径
+- `tool_profile` / `allowed_skill_tools` / `tool_flags`: 限制可用技能工具能力面
+- `exec_tools_disabled`: 关闭交互执行 guidance
+- `repo_resolver`: invocation 级仓库解析
+- `max_loaded_skills`: loaded 上限（超限按顺序淘汰）
+
+参数入口：
+
+- `set_skill_processor_parameters(agent_context, parameters)`
+
+## 3. WorkspaceExecRequestProcessor（workspace_exec guidance）
+
+对应实现：
+
+- [`trpc_agent/agents/core/_workspace_exec_processor.py`](./_workspace_exec_processor.py)
+
+### 3.1 解决的问题
+
+在多工具场景下，模型容易混淆：
+
+- 什么时候使用 `workspace_exec`（通用 shell）
+- 什么时候使用 `skill_run`（技能内部执行）
+- `workspace_exec` 的路径边界、会话工具、artifact 保存边界
+
+处理器通过注入统一 guidance，降低误用和误判。
+
+### 3.2 主要行为
+
+`process_llm_request(ctx, request)` 典型步骤：
+
+1. 判断是否启用 guidance
+ - 默认按 request tools 是否包含 `workspace_exec`
+ - 支持 `enabled_resolver` 动态开关
+2. 生成 guidance 主体
+ - 通用 `workspace_exec` 使用建议
+ - `work/out/runs` 路径建议
+ - “先用小命令验证环境限制”的原则
+3. 按能力追加段落
+ - 有 `workspace_save_artifact`：追加 artifact 保存边界说明
+ - 有 skills repo：提示 `skills/` 目录并非自动 stage
+ - 有会话工具：追加 `workspace_write_stdin` / `workspace_kill_session` 生命周期提示
+4. 去重注入
+ - 若已存在 `Executor workspace guidance:` header，则不重复追加
+
+### 3.3 行为示例
+
+当工具列表包含：
+
+- `workspace_exec`
+- `workspace_write_stdin`
+- `workspace_kill_session`
+- `workspace_save_artifact`
+
+且 agent 绑定 skill repository 时，system instruction 会引导模型：
+
+- 通用 shell 优先走 `workspace_exec`
+- 路径优先 `work/`、`out/`、`runs/`
+- 限制不先假设，先验证
+- 仅在需要稳定引用时再调用 `workspace_save_artifact`
+
+### 3.4 常见误区
+
+- 误区：`workspace_exec` 会自动准备 `skills/` 内容
+ 实际：是否存在 `skills/...` 取决于是否有其他工具先 stage
+
+- 误区：遇到限制直接下结论“环境不支持”
+ 实际：应先做有界验证
+
+- 误区：所有输出都必须保存 artifact
+ 实际：应按稳定引用需求再保存
+
+### 3.5 如何验证生效
+
+优先看“发给模型前的请求”而非仅看终端事件：
+
+1. `request.config.system_instruction` 是否包含 `Executor workspace guidance:`
+2. 是否只注入一次（无重复 header）
+3. 工具选择行为是否符合预期（通用 shell 走 `workspace_exec`）
+
+## 4. SkillsToolResultRequestProcessor（tool result 物化）
+
+对应实现：
+
+- [`trpc_agent/agents/core/_skills_tool_result_processor.py`](./_skills_tool_result_processor.py)
+
+### 4.1 解决的问题
+
+仅靠 `skill_load` 的短回包（例如 `"skill 'python-math' loaded"`），模型往往拿不到可执行细节。
+这个处理器负责把“已加载 skill 的实质内容”物化到模型当前请求上下文。
+
+### 4.2 主要行为
+
+处理器会：
+
+1. 从 `session_state + state_delta` 读取已加载 skill
+2. 在 `LlmRequest.contents` 中定位最近的 `skill_load` / `skill_select_docs` response
+3. 条件满足时改写 response，注入：
+ - `[Loaded] `
+ - `Docs loaded: ...`
+ - `[Doc] ...`
+4. 若本轮没有可改写 response，fallback 到 system instruction 追加 `Loaded skill context:`
+5. `load_mode=once` 时按策略清理 loaded/docs 状态
+
+### 4.3 与 SkillsRequestProcessor 的分工
+
+- `tool_result_mode=False`
+ - 由 `SkillsRequestProcessor` 直接注入 loaded 内容
+- `tool_result_mode=True`
+ - `SkillsRequestProcessor` 不注入 loaded 内容
+ - `SkillsToolResultRequestProcessor` 在 post-history 做物化
+
+### 4.4 最小示例
+
+进入处理器前：
+
+- function call: `skill_load(demo-skill)`
+- function response: `{"result":"skill 'demo-skill' loaded"}`
+
+处理器后（示意）：
+
+```text
+{
+ "result": "[Loaded] demo-skill\n\n\n\nDocs loaded: docs/guide.md\n\n[Doc] docs/guide.md\n\n"
+}
+```
+
+即使没有对应 tool response 可改写，也会通过 system instruction fallback 注入已加载上下文。
+
+### 4.5 什么时候会被误判为“没生效”
+
+最常见误区：只看终端工具即时回包。
+该处理器真实生效点是“发给模型前的请求内容”，与外层事件流并不总是 1:1。
+
+建议观察：
+
+- `request.config.system_instruction`
+- `request.contents` 里的 function response 是否已被改写
+
+### 4.6 参数入口
+
+- `load_mode`
+- `skip_fallback_on_session_summary`
+- `repo_resolver`
+
+通过：
+
+- `set_skill_tool_result_processor_parameters(agent_context, {...})`
+
+注入请求构建链路。
+
+## 5. 测试语义映射（与 examples 对齐）
+
+可配合 [`examples/skills/run_agent.py`](../../../examples/skills/run_agent.py) 与
+[`examples/skills/README.md`](../../../examples/skills/README.md) 观察实际行为。
+
+- `workspace_exec_guidance` 类测试
+ - 关注工具选择行为是否被 guidance 纠偏
+ - 核心断言是 `workspace_exec` 与 `skill_run` 调用分布
+
+- `skills_tool_result_mode` 类测试
+ - 关注 materialization 信号是否出现（`[Loaded]` / `Docs loaded` / `[Doc]`）
+ - 允许“请求层可见但终端不完全回显”的情况
+
+## 6. 给读者的排障建议
+
+1. 先确认模式参数：`load_mode`、`tool_result_mode`
+2. 再确认状态读写：`state_delta` 与 `session_state` 是否符合预期
+3. 最后看请求最终形态：
+ - 是否注入了 guidance
+ - 是否注入了 loaded context
+ - 是否发生了 offload/clear
diff --git a/trpc_agent_sdk/agents/core/__init__.py b/trpc_agent_sdk/agents/core/__init__.py
index 5797916..c8b5922 100644
--- a/trpc_agent_sdk/agents/core/__init__.py
+++ b/trpc_agent_sdk/agents/core/__init__.py
@@ -23,7 +23,13 @@
from ._request_processor import RequestProcessor
from ._request_processor import default_request_processor
from ._skill_processor import SkillsRequestProcessor
+from ._skill_processor import get_skill_processor_parameters
+from ._skill_processor import set_skill_processor_parameters
+from ._skills_tool_result_processor import get_skill_tool_result_processor_parameters
+from ._skills_tool_result_processor import set_skill_tool_result_processor_parameters
from ._tools_processor import ToolsProcessor
+from ._workspace_exec_processor import get_workspace_exec_processor_parameters
+from ._workspace_exec_processor import set_workspace_exec_processor_parameters
__all__ = [
"AgentTransferProcessor",
@@ -40,5 +46,11 @@
"RequestProcessor",
"default_request_processor",
"SkillsRequestProcessor",
+ "get_skill_processor_parameters",
+ "set_skill_processor_parameters",
+ "get_skill_tool_result_processor_parameters",
+ "set_skill_tool_result_processor_parameters",
"ToolsProcessor",
+ "get_workspace_exec_processor_parameters",
+ "set_workspace_exec_processor_parameters",
]
diff --git a/trpc_agent_sdk/agents/core/_code_execution_processor.py b/trpc_agent_sdk/agents/core/_code_execution_processor.py
index 976712e..e164135 100644
--- a/trpc_agent_sdk/agents/core/_code_execution_processor.py
+++ b/trpc_agent_sdk/agents/core/_code_execution_processor.py
@@ -1,8 +1,6 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+# -*- coding: utf-8 -*-
#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
+# Copyright @ 2025 Tencent.com
"""Code execution processor for TRPC Agent framework.
This module provides code execution processing capabilities for LLM agents,
@@ -264,7 +262,8 @@ async def _run_post_processor(
# content to the part with the first code block.
response_content = llm_response.content
code_blocks = CodeExecutionUtils.extract_code_and_truncate_content(response_content,
- code_executor.code_block_delimiters)
+ code_executor.code_block_delimiters,
+ code_executor.ignore_codes)
# Terminal state: no code to execute.
if not code_blocks:
return
diff --git a/trpc_agent_sdk/agents/core/_request_processor.py b/trpc_agent_sdk/agents/core/_request_processor.py
index 4640f43..0e414ae 100644
--- a/trpc_agent_sdk/agents/core/_request_processor.py
+++ b/trpc_agent_sdk/agents/core/_request_processor.py
@@ -1,8 +1,6 @@
# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
+# Copyright @ 2025 Tencent.com
"""Request Processor implementation for TRPC Agent framework.
This module provides the RequestProcessor class which handles building LlmRequest
@@ -24,6 +22,7 @@
import copy
import inspect
import re
+from typing import Any
from typing import List
from typing import Optional
@@ -32,6 +31,7 @@
from trpc_agent_sdk.log import logger
from trpc_agent_sdk.models import LlmRequest
from trpc_agent_sdk.planners import default_planning_processor
+from trpc_agent_sdk.skills import get_skill_processor_parameters
from trpc_agent_sdk.tools import FunctionTool
from trpc_agent_sdk.tools import transfer_to_agent
from trpc_agent_sdk.types import Content
@@ -43,7 +43,12 @@
from ._history_processor import HistoryProcessor
from ._history_processor import TimelineFilterMode
from ._skill_processor import SkillsRequestProcessor
+from ._skill_processor import get_skill_processor_parameters
+from ._skills_tool_result_processor import SkillsToolResultRequestProcessor
+from ._skills_tool_result_processor import get_skill_tool_result_processor_parameters
from ._tools_processor import ToolsProcessor
+from ._workspace_exec_processor import WorkspaceExecRequestProcessor
+from ._workspace_exec_processor import get_workspace_exec_processor_parameters
class RequestProcessor:
@@ -124,11 +129,18 @@ async def build_request(
return error_event
# 5. Add skills to the request
- error_event = await self._add_skills_to_request(agent, ctx, request)
+ skill_parameters = get_skill_processor_parameters(ctx.agent_context)
+ error_event = await self._add_skills_to_request(agent, ctx, request, skill_parameters)
+ if error_event:
+ return error_event
+
+ # 6. Add workspace_exec guidance (after skills, before history)
+ workspace_exec_parameters = get_workspace_exec_processor_parameters(ctx.agent_context)
+ error_event = await self._add_workspace_exec_guidance(agent, ctx, request, workspace_exec_parameters)
if error_event:
return error_event
- # 6. Add conversation history (includes current user message in correct order)
+ # 7. Add conversation history (includes current user message in correct order)
if override_messages is not None:
# Use provided messages directly (for TeamAgent member control)
for content in override_messages:
@@ -150,12 +162,18 @@ async def build_request(
if error_event:
return error_event
- # 7. Process planning if planner is available
+ # 8. Materialize loaded-skill content into tool results (post-history).
+ skill_tool_result_parameters = get_skill_tool_result_processor_parameters(ctx.agent_context)
+ error_event = await self._add_skills_tool_results(agent, ctx, request, skill_tool_result_parameters)
+ if error_event:
+ return error_event
+
+ # 9. Process planning if planner is available
error_event = await self._add_planning_capabilities(agent, ctx, request)
if error_event:
return error_event
- # 8. Process output schema if needed (when tools are also present)
+ # 10. Process output schema if needed (when tools are also present)
error_event = await self._add_output_schema_capabilities(agent, ctx, request)
if error_event:
return error_event
@@ -303,8 +321,8 @@ async def _add_tools_to_request(self, agent: BaseAgent, ctx: InvocationContext,
return None # Success
- async def _add_skills_to_request(self, agent: BaseAgent, ctx: InvocationContext,
- request: LlmRequest) -> Optional[Event]:
+ async def _add_skills_to_request(self, agent: BaseAgent, ctx: InvocationContext, request: LlmRequest,
+ parameters: dict[str, Any]) -> Optional[Event]:
"""Add skills to the model request.
Args:
@@ -318,13 +336,58 @@ async def _add_skills_to_request(self, agent: BaseAgent, ctx: InvocationContext,
skill_repository = getattr(agent, 'skill_repository', None)
if skill_repository:
try:
- skills_processor = SkillsRequestProcessor(skill_repository)
+ skills_processor = SkillsRequestProcessor(skill_repository, **parameters)
skill_names = await skills_processor.process_llm_request(ctx, request)
logger.debug("Processed %s skills for agent: %s", len(skill_names), agent.name)
return None # Success
except Exception as ex: # pylint: disable=broad-except
logger.error("Error processing skills for agent %s: %s", agent.name, ex)
return self._create_error_event(ctx, "skill_processing_error", f"Failed to process skills: {str(ex)}")
+ return None
+
+ async def _add_workspace_exec_guidance(self, agent: BaseAgent, ctx: InvocationContext, request: LlmRequest,
+ parameters: dict[str, Any]) -> Optional[Event]:
+ """Inject workspace_exec guidance after skills and before history."""
+ try:
+ skill_repository = getattr(agent, "skill_repository", None)
+ repo_resolver = parameters.get("repo_resolver")
+ processor = WorkspaceExecRequestProcessor(
+ has_skills_repo=bool(skill_repository),
+ repo_resolver=repo_resolver if callable(repo_resolver) else None,
+ )
+ await processor.process_llm_request(ctx, request)
+ return None
+ except Exception as ex: # pylint: disable=broad-except
+ logger.error("Error injecting workspace_exec guidance for agent %s: %s", agent.name, ex)
+ return self._create_error_event(
+ ctx,
+ "workspace_exec_guidance_error",
+ f"Failed to inject workspace_exec guidance: {str(ex)}",
+ )
+
+ async def _add_skills_tool_results(self, agent: BaseAgent, ctx: InvocationContext, request: LlmRequest,
+ parameters: dict[str, Any]) -> Optional[Event]:
+ """Materialize loaded skills into tool results after history is attached."""
+ if not parameters.get("tool_result_mode"):
+ return None
+ skill_repository = getattr(agent, "skill_repository", None)
+ if skill_repository is None:
+ return None
+ try:
+ processor = SkillsToolResultRequestProcessor(
+ skill_repository,
+ skip_fallback_on_session_summary=parameters.get("skip_fallback_on_session_summary", True),
+ repo_resolver=parameters.get("repo_resolver"),
+ )
+ await processor.process_llm_request(ctx, request)
+ return None
+ except Exception as ex: # pylint: disable=broad-except
+ logger.error("Error processing skill tool results for agent %s: %s", agent.name, ex)
+ return self._create_error_event(
+ ctx,
+ "skill_tool_result_processing_error",
+ f"Failed to process skill tool results: {str(ex)}",
+ )
async def _add_agent_transfer_capabilities(self, agent: BaseAgent, ctx: InvocationContext,
request: LlmRequest) -> Optional[Event]:
@@ -879,7 +942,7 @@ def _apply_template_substitution(self, instruction: str, ctx: InvocationContext)
{session_key}, etc. with actual values from the session state.
This implementation is inspired by adk-python's inject_session_state but
- adapted for trpc_agent_sdk's architecture.
+ adapted for trpc_agent's architecture.
Args:
instruction: The instruction string containing template placeholders
@@ -920,7 +983,6 @@ def replace_placeholder(match):
# This follows the behavior of the original SafeFormatter approach
return match.group()
- # Use regex pattern similar to adk-python but simpler for trpc_agent_sdk
# This matches {variable_name} patterns including optional ones with ?
pattern = r'\{[^{}]*\}'
result = re.sub(pattern, replace_placeholder, instruction)
diff --git a/trpc_agent_sdk/agents/core/_skill_processor.py b/trpc_agent_sdk/agents/core/_skill_processor.py
index c34f6d8..1e1fbc2 100644
--- a/trpc_agent_sdk/agents/core/_skill_processor.py
+++ b/trpc_agent_sdk/agents/core/_skill_processor.py
@@ -4,55 +4,40 @@
#
# tRPC-Agent-Python is licensed under Apache-2.0.
"""SkillsRequestProcessor — injects skill overviews and loaded contents.
-
-Mirrors ``internal/flow/processor/skills.go`` from trpc-agent-go, while
-retaining Python-unique features (user_prompt, tools-selection summary).
-
-Behavior
---------
-- Overview : always injected (skill names + descriptions).
-- Loaded skills: full SKILL.md body injected into system prompt (or
- deferred to tool-result mode).
-- Docs : doc texts selected via session state keys.
-- Tools : (Python-unique) tool selection summary for each loaded skill.
-
-Skill load modes
-----------------
-- ``turn`` (default) – loaded skill content is available for all LLM
- calls within the current invocation, then cleared at the start of the
- next invocation.
-- ``once`` – loaded skill content is injected once, then offloaded
- (state keys cleared) immediately after injection.
-- ``session`` – loaded skill content persists across invocations until
- the session expires or state is cleared explicitly.
"""
from __future__ import annotations
import json
+from typing import Any
from typing import Callable
from typing import List
from typing import Optional
+from trpc_agent_sdk.context import AgentContext
from trpc_agent_sdk.context import InvocationContext
from trpc_agent_sdk.log import logger
from trpc_agent_sdk.models import LlmRequest
from trpc_agent_sdk.skills import BaseSkillRepository
-from trpc_agent_sdk.skills import SKILL_DOCS_STATE_KEY_PREFIX
-from trpc_agent_sdk.skills import SKILL_LOADED_STATE_KEY_PREFIX
-from trpc_agent_sdk.skills import SKILL_TOOLS_STATE_KEY_PREFIX
from trpc_agent_sdk.skills import Skill
-from trpc_agent_sdk.skills import generic_get_selection
-
-# ---------------------------------------------------------------------------
-# Load mode constants (mirrors Go SkillLoadModeXxx)
-# ---------------------------------------------------------------------------
-
-SKILL_LOAD_MODE_ONCE = "once"
-SKILL_LOAD_MODE_TURN = "turn"
-SKILL_LOAD_MODE_SESSION = "session"
-
-_DEFAULT_SKILL_LOAD_MODE = SKILL_LOAD_MODE_TURN
+from trpc_agent_sdk.skills import SkillLoadModeNames
+from trpc_agent_sdk.skills import SkillProfileFlags
+from trpc_agent_sdk.skills import SkillProfileNames
+from trpc_agent_sdk.skills import SkillToolsNames
+from trpc_agent_sdk.skills import docs_scan_prefix
+from trpc_agent_sdk.skills import docs_state_key
+from trpc_agent_sdk.skills import get_skill_config
+from trpc_agent_sdk.skills import loaded_order_state_key
+from trpc_agent_sdk.skills import loaded_scan_prefix
+from trpc_agent_sdk.skills import loaded_state_key
+from trpc_agent_sdk.skills import marshal_loaded_order
+from trpc_agent_sdk.skills import parse_loaded_order
+from trpc_agent_sdk.skills import set_skill_config
+from trpc_agent_sdk.skills import tool_scan_prefix
+from trpc_agent_sdk.skills import tool_state_key
+from trpc_agent_sdk.skills import touch_loaded_order
+
+from ._skills_tool_result_processor import SKILL_LOADED_RE
# ---------------------------------------------------------------------------
# Prompt section headers (mirrors Go const block)
@@ -62,49 +47,93 @@
_SKILLS_CAPABILITY_HEADER = "Skill tool availability:"
_SKILLS_TOOLING_GUIDANCE_HEADER = "Tooling and workspace guidance:"
-# ---------------------------------------------------------------------------
-# Internal state keys
-# ---------------------------------------------------------------------------
+_SKILLS_TURN_INIT_STATE_KEY = "processor:skills:turn_init"
+
+
+def normalize_load_mode(mode: str) -> str:
+ value = (mode or "").strip().lower()
+ if value in (SkillLoadModeNames.ONCE, SkillLoadModeNames.TURN, SkillLoadModeNames.SESSION):
+ return value
+ return SkillLoadModeNames.TURN
+
+
+def _append_knowledge_guidance(lines: list[str], flags: SkillProfileFlags) -> None:
+ """Append docs-loading guidance mirroring Go's appendKnowledgeGuidance."""
+ has_list_docs = flags.list_docs
+ has_select_docs = flags.select_docs
+ if has_list_docs and has_select_docs:
+ lines.append("- Use the available doc listing and selection helpers to keep"
+ " documentation loads targeted.\n")
+ elif has_list_docs:
+ lines.append("- Use the available doc listing helper to discover doc names,"
+ " then load only the docs you need.\n")
+ elif has_select_docs:
+ lines.append("- If doc names are already known, use the available doc"
+ " selection helper to keep loaded docs targeted.\n")
+ else:
+ lines.append("- If you need docs, request them directly with skill_load.docs"
+ " or include_all_docs.\n")
+ lines.append("- Avoid include_all_docs unless the user asks or the task genuinely"
+ " needs the full doc set.\n")
-# JSON array of skill names in load order — used by the max-cap eviction.
-_SKILLS_LOADED_ORDER_STATE_KEY = "temp:skill:loaded_order"
# ---------------------------------------------------------------------------
-# Normalization helpers
+# Guidance text builders (mirrors Go defaultXxxGuidance functions)
# ---------------------------------------------------------------------------
-def _normalize_load_mode(mode: str) -> str:
- m = (mode or "").strip().lower()
- if m in (SKILL_LOAD_MODE_ONCE, SKILL_LOAD_MODE_TURN, SKILL_LOAD_MODE_SESSION):
- return m
- return _DEFAULT_SKILL_LOAD_MODE
-
-
-def _is_knowledge_only(profile: str) -> bool:
- """Return True for profiles that support knowledge lookup only."""
- p = (profile or "").strip().lower().replace("-", "_")
- return p in ("knowledge_only", "knowledge")
+def _default_catalog_only_guidance() -> str:
+ return ("\n" + _SKILLS_TOOLING_GUIDANCE_HEADER + "\n" +
+ "- Use the skill overview as a catalog only. Built-in skill tools are"
+ " unavailable in this configuration; if a task depends on loading or"
+ " executing a skill, use other registered tools or explain the"
+ " limitation clearly.\n")
-# ---------------------------------------------------------------------------
-# Guidance text builders (mirrors Go defaultXxxGuidance functions)
-# ---------------------------------------------------------------------------
+def _default_doc_helpers_only_guidance(flags: SkillProfileFlags) -> str:
+ lines = [
+ "\n",
+ _SKILLS_TOOLING_GUIDANCE_HEADER,
+ "\n",
+ ]
+ has_list_docs = flags.list_docs
+ has_select_docs = flags.select_docs
+ if has_list_docs and has_select_docs:
+ lines.append("- Use skills only to inspect available doc names or adjust"
+ " doc selection state.\n")
+ elif has_list_docs:
+ lines.append("- Use skills only to inspect available doc names.\n")
+ elif has_select_docs:
+ lines.append("- Use skills only to adjust doc selection when doc names are"
+ " already known.\n")
+ lines.append("- Built-in skill loading is unavailable, so doc helpers do not"
+ " inject SKILL.md or doc contents into context; if the task needs"
+ " loaded content or execution, use other registered tools or"
+ " explain the limitation clearly.\n")
+ return "".join(lines)
-def _default_knowledge_only_guidance() -> str:
- return ("\n" + _SKILLS_TOOLING_GUIDANCE_HEADER + "\n" +
- "- Use skills for progressive disclosure only: load SKILL.md first,"
- " then inspect only the documentation needed for the current task.\n" +
- "- Avoid include_all_docs unless the user asks or the task genuinely"
- " needs the full doc set.\n" + "- Treat loaded skill content as domain guidance. Do not claim you"
- " executed scripts, shell commands, or interactive flows described by"
- " the skill.\n" + "- If a skill depends on execution to complete the task, switch to"
- " other registered tools (for example, MCP tools) or explain the"
- " limitation clearly.\n")
+def _default_knowledge_only_guidance(flags: SkillProfileFlags) -> str:
+ lines = [
+ "\n",
+ _SKILLS_TOOLING_GUIDANCE_HEADER,
+ "\n",
+ "- Use skills for progressive disclosure only: load SKILL.md first,"
+ " then inspect only the documentation needed for the current task.\n",
+ ]
+ _append_knowledge_guidance(lines, flags)
+ lines += [
+ "- Treat loaded skill content as domain guidance. Do not claim you"
+ " executed scripts, shell commands, or interactive flows described by"
+ " the skill.\n",
+ "- If a skill depends on execution to complete the task, switch to"
+ " other registered tools (for example, MCP tools) or explain the"
+ " limitation clearly.\n",
+ ]
+ return "".join(lines)
-def _default_full_tooling_and_workspace_guidance(exec_tools_disabled: bool) -> str:
+def _default_full_tooling_and_workspace_guidance(flags: SkillProfileFlags) -> str:
lines: list[str] = [
"\n",
_SKILLS_TOOLING_GUIDANCE_HEADER,
@@ -132,6 +161,9 @@ def _default_full_tooling_and_workspace_guidance(exec_tools_disabled: bool) -> s
"- Prefer writing new files under $OUTPUT_DIR or a skill's out/"
" directory and include output_files globs (or an outputs spec) so"
" files can be collected or saved as artifacts.\n",
+ "- Use stdout/stderr for logs or short status text. If the model needs"
+ " large or structured text, write it to files under $OUTPUT_DIR and"
+ " return it via output_files or outputs.\n",
"- For Python skills that need third-party packages, create a virtualenv"
" under the skill's .venv/ directory (it is writable inside the"
" workspace).\n",
@@ -153,69 +185,78 @@ def _default_full_tooling_and_workspace_guidance(exec_tools_disabled: bool) -> s
"- When chaining multiple skills, read previous results from $OUTPUT_DIR"
" (or a skill's out/ directory) instead of copying them back into inputs"
" directories.\n",
- "- Treat loaded skill docs as guidance, not perfect truth; when runtime"
- " help or stderr disagrees, trust observed runtime behavior.\n",
- "- Loading a skill gives you instructions and bundled resources; it does"
- " not execute the skill by itself.\n",
- "- The skill summaries above are routing summaries only; they do not"
- " replace SKILL.md or other loaded docs.\n",
- "- If the loaded content already provides enough guidance to answer or"
- " produce the requested result, respond directly.\n",
- "- A skill can still be executable even when it has no extra docs"
- " or no custom tools. If SKILL.md provides runnable commands,"
- " proceed with skill_run using those commands.\n",
- "- If a skill is not loaded, call skill_load; you may pass docs or"
- " include_all_docs.\n",
- "- If the body is loaded and docs are missing, treat docs as optional"
- " unless the task explicitly requires extra references; then call"
- " skill_select_docs or skill_load again to add docs.\n",
- "- If the skill defines tools in its SKILL.md, they will be"
- " automatically selected when you load the skill. You can refine tool"
- " selection with skill_select_tools.\n",
- "- If you decide to use a skill, load SKILL.md before",
]
- if exec_tools_disabled:
- lines.append(" the first skill_run for that skill, then load only"
- " the docs you still need.\n")
+ if flags.load:
+ lines += [
+ "- Treat loaded skill docs as guidance, not perfect truth; when runtime"
+ " help or stderr disagrees, trust observed runtime behavior.\n",
+ "- Loading a skill gives you instructions and bundled resources; it does"
+ " not execute the skill by itself.\n",
+ "- The skill summaries above are routing summaries only; they do not"
+ " replace SKILL.md or other loaded docs.\n",
+ "- If the loaded content already provides enough guidance to answer or"
+ " produce the requested result, respond directly.\n",
+ "- If you decide to use a skill, load SKILL.md before",
+ ]
+ if flags.requires_exec_session_tools():
+ lines.append(" the first skill_run or skill_exec for that skill, then load"
+ " only the docs you still need.\n")
+ else:
+ lines.append(" the first skill_run for that skill, then load only the docs"
+ " you still need.\n")
+ lines += [
+ "- Do not infer commands, script entrypoints, or resource layouts from"
+ " the short summary alone.\n",
+ ]
+ _append_knowledge_guidance(lines, flags)
+ elif flags.has_doc_helpers():
+ lines += [
+ "- Built-in skill loading is unavailable in this configuration. Doc"
+ " listing or selection helpers can inspect doc names or selection"
+ " state, but they do not inject SKILL.md or doc contents into"
+ " context.\n",
+ ]
else:
- lines.append(" the first skill_run or skill_exec for that skill,"
- " then load only the docs you still need.\n")
+ lines += [
+ "- Built-in skill loading is unavailable in this configuration; do not"
+ " assume SKILL.md or doc contents are in context.\n",
+ ]
+
lines += [
- "- Do not infer commands, script entrypoints, or resource layouts"
- " from the short summary alone.\n",
- "- For docs, prefer skill_list_docs + skill_select_docs to load only"
- " what you need.\n",
- "- Avoid include_all_docs unless you need every doc or the user asks.\n",
- "- Use execution tools only when running a command will reveal or"
- " produce information or files you still need.\n",
+ "- Use execution tools only when running a command will reveal or produce"
+ " information or files you still need.\n",
]
- if not exec_tools_disabled:
+ if flags.requires_exec_session_tools():
lines.append("- Use skill_exec only when a command needs incremental stdin or"
" TTY-style interaction; otherwise prefer one-shot execution.\n")
else:
lines.append("- Do not assume interactive execution is available when only"
" one-shot execution tools are present.\n")
lines += [
- "- Prefer script-based commands from SKILL.md examples (for example,"
- " python3 scripts/foo.py) instead of ad-hoc python -c rewrites"
- " unless the skill explicitly recommends inline execution.\n",
- "- skill_run is a command runner inside the skill workspace, not a"
- " magic capability. It does not automatically add the skill directory"
- " to PATH or install dependencies; invoke scripts via an explicit"
- " interpreter and path (e.g., python3 scripts/foo.py).\n",
- "- When you execute, follow the tool description, loaded skill docs,"
- " bundled scripts, and observed runtime behavior rather than inventing"
- " shell syntax or command arguments.\n",
- "- If skill_list_tools returns command_examples, execute one of those"
- " commands directly before trying ad-hoc shell alternatives.\n",
+ "- skill_run is a command runner inside the skill workspace, not a magic"
+ " capability. It does not automatically add the skill directory to PATH"
+ " or install dependencies; invoke scripts via an explicit interpreter and"
+ " path (e.g., python3 scripts/foo.py).\n",
+ "- When you execute, follow the tool description, ",
]
+ if flags.load:
+ lines[-1] += "loaded skill docs, "
+ lines[
+ -1] += "bundled scripts, and observed runtime behavior rather than inventing shell syntax or command arguments.\n"
return "".join(lines)
-def _default_tooling_and_workspace_guidance(profile: str, exec_tools_disabled: bool) -> str:
- if _is_knowledge_only(profile):
- return _default_knowledge_only_guidance()
- return _default_full_tooling_and_workspace_guidance(exec_tools_disabled)
+def _default_tooling_and_workspace_guidance(flags: SkillProfileFlags) -> str:
+ if not flags.is_any():
+ return _default_catalog_only_guidance()
+
+ if not flags.run:
+ if flags.load:
+ return _default_knowledge_only_guidance(flags)
+ if flags.has_doc_helpers():
+ return _default_doc_helpers_only_guidance(flags)
+ return _default_catalog_only_guidance()
+ return _default_full_tooling_and_workspace_guidance(flags)
def _normalize_custom_guidance(guidance: str) -> str:
@@ -236,8 +277,6 @@ def _normalize_custom_guidance(guidance: str) -> str:
class SkillsRequestProcessor:
"""Injects skill overviews and loaded contents into LLM requests.
- Mirrors Go's ``SkillsRequestProcessor``.
-
Args:
skill_repository: Default skill repository.
load_mode: ``"turn"`` (default), ``"once"``, or ``"session"``.
@@ -247,6 +286,9 @@ class SkillsRequestProcessor:
tool_result_mode: When ``True``, skip loaded-skill injection here
(content is materialized into tool results instead).
tool_profile: Profile string (e.g. ``"knowledge_only"``).
+ forbidden_tools: Optional explicit blacklist of built-in skill tools.
+ tool_flags: Optional resolved flags; when set, takes precedence
+ over ``tool_profile``/``forbidden_tools``.
exec_tools_disabled: When ``True``, omit skill_exec guidance lines.
repo_resolver: Optional ``(ctx) -> BaseSkillRepository`` callable
that returns an invocation-specific repository.
@@ -257,25 +299,30 @@ def __init__(
self,
skill_repository: BaseSkillRepository,
*,
- load_mode: str = SKILL_LOAD_MODE_TURN,
+ load_mode: str = str(SkillLoadModeNames.TURN),
tooling_guidance: Optional[str] = None,
tool_result_mode: bool = False,
- tool_profile: str = "",
+ tool_profile: str = str(SkillProfileNames.FULL),
+ forbidden_tools: Optional[list[str]] = None,
+ tool_flags: Optional[SkillProfileFlags] = None,
exec_tools_disabled: bool = False,
repo_resolver: Optional[Callable[[InvocationContext], BaseSkillRepository]] = None,
max_loaded_skills: int = 0,
) -> None:
self._skill_repository = skill_repository
- self._load_mode = _normalize_load_mode(load_mode)
+ self._load_mode = normalize_load_mode(load_mode)
self._tooling_guidance = tooling_guidance
self._tool_result_mode = tool_result_mode
- self._tool_profile = (tool_profile or "").strip()
- self._exec_tools_disabled = exec_tools_disabled
+ try:
+ resolved_flags = tool_flags or SkillProfileFlags.resolve_flags(tool_profile, forbidden_tools)
+ except ValueError as ex:
+ logger.warning("skills: invalid skill tool flags config, fallback to full profile: %s", ex)
+ resolved_flags = SkillProfileFlags.preset_flags(tool_profile, forbidden_tools)
+ if exec_tools_disabled:
+ resolved_flags = resolved_flags.without_interactive_execution()
+ self._tool_flags = resolved_flags
self._repo_resolver = repo_resolver
self._max_loaded_skills = max_loaded_skills
- # Tracks which invocation IDs have already had their turn-init clearing
- # applied. This is ephemeral instance state — not persisted to session.
- self._initialized_invocations: set[str] = set()
# ------------------------------------------------------------------
# Public entry point
@@ -301,17 +348,17 @@ async def process_llm_request(
self._maybe_clear_skill_state_for_turn(ctx)
# 1) Always inject overview (names + descriptions).
- self._inject_overview(request, repo)
+ self._inject_overview(ctx, request, repo)
loaded = self._get_loaded_skills(ctx)
loaded = self._maybe_cap_loaded_skills(ctx, loaded)
if self._tool_result_mode:
- # Loaded skill bodies/docs are injected into tool results by a
- # separate post-content processor — skip injection here.
+ # Materialization is handled by a dedicated post-history processor
+ # in request pipeline (Go-aligned ordering).
return loaded
- # 2) Loaded skills: full body + docs + tools (sorted for stable prompts).
+ # 2) Loaded skills: full body + docs (sorted for stable prompts).
loaded.sort()
parts: list[str] = []
@@ -338,8 +385,6 @@ async def process_llm_request(
doc_text = self._build_docs_text(sk, sel)
if doc_text:
parts.append(doc_text)
-
- # Tools (Python-unique: skill_select_tools integration)
tool_sel = self._get_tools_selection(ctx, name)
parts.append("Tools selected: ")
if not tool_sel:
@@ -373,38 +418,36 @@ def _maybe_clear_skill_state_for_turn(self, ctx: InvocationContext) -> None:
Uses ``ctx.invocation_id`` to detect when a new invocation has started
without persisting an extra key to session state.
"""
- if self._load_mode != SKILL_LOAD_MODE_TURN:
+ if self._load_mode != SkillLoadModeNames.TURN:
return
- inv_id = ctx.invocation_id
- if inv_id in self._initialized_invocations:
+ if ctx.agent_context.get_metadata(_SKILLS_TURN_INIT_STATE_KEY):
return
- self._initialized_invocations.add(inv_id)
- # Bound the set size to avoid unbounded growth across long-running servers.
- if len(self._initialized_invocations) > 2000:
- oldest = list(self._initialized_invocations)[:1000]
- for old_id in oldest:
- self._initialized_invocations.discard(old_id)
+ ctx.agent_context.with_metadata(_SKILLS_TURN_INIT_STATE_KEY, True)
self._clear_skill_state(ctx)
def _clear_skill_state(self, ctx: InvocationContext) -> None:
"""Clear all loaded-skill state keys from the session."""
+ loaded_state_prefix = loaded_scan_prefix(ctx)
+ docs_state_prefix = docs_scan_prefix(ctx)
+ tools_state_prefix = tool_scan_prefix(ctx)
+ order_state_key = loaded_order_state_key(ctx)
state = self._snapshot_state(ctx)
for k, v in state.items():
if not v:
continue
- if (k.startswith(SKILL_LOADED_STATE_KEY_PREFIX) or k.startswith(SKILL_DOCS_STATE_KEY_PREFIX)
- or k.startswith(SKILL_TOOLS_STATE_KEY_PREFIX) or k == _SKILLS_LOADED_ORDER_STATE_KEY):
+ if (k.startswith(loaded_state_prefix) or k.startswith(docs_state_prefix) or k.startswith(tools_state_prefix)
+ or k == order_state_key):
ctx.actions.state_delta[k] = None
def _maybe_offload_loaded_skills(self, ctx: InvocationContext, loaded: list[str]) -> None:
"""After injection, clear skill state for once mode."""
- if self._load_mode != SKILL_LOAD_MODE_ONCE or not loaded:
+ if self._load_mode != SkillLoadModeNames.ONCE or not loaded:
return
for name in loaded:
- ctx.actions.state_delta[SKILL_LOADED_STATE_KEY_PREFIX + name] = None
- ctx.actions.state_delta[SKILL_DOCS_STATE_KEY_PREFIX + name] = None
- ctx.actions.state_delta[SKILL_TOOLS_STATE_KEY_PREFIX + name] = None
- ctx.actions.state_delta[_SKILLS_LOADED_ORDER_STATE_KEY] = None
+ ctx.actions.state_delta[loaded_state_key(ctx, name)] = None
+ ctx.actions.state_delta[docs_state_key(ctx, name)] = None
+ ctx.actions.state_delta[tool_state_key(ctx, name)] = None
+ ctx.actions.state_delta[loaded_order_state_key(ctx)] = None
# ------------------------------------------------------------------
# Max-loaded-skills cap
@@ -416,40 +459,31 @@ def _maybe_cap_loaded_skills(self, ctx: InvocationContext, loaded: list[str]) ->
return loaded
order = self._get_loaded_skill_order(ctx, loaded)
- # Keep the most recently touched skills (tail of the order list).
+ if not order:
+ return loaded
keep_count = self._max_loaded_skills
- keep_set = set(order[-keep_count:]) if len(order) >= keep_count else set(order)
+ keep_set = set(order[-keep_count:])
kept: list[str] = []
for name in loaded:
if name in keep_set:
kept.append(name)
else:
- ctx.actions.state_delta[SKILL_LOADED_STATE_KEY_PREFIX + name] = None
- ctx.actions.state_delta[SKILL_DOCS_STATE_KEY_PREFIX + name] = None
- ctx.actions.state_delta[SKILL_TOOLS_STATE_KEY_PREFIX + name] = None
-
+ ctx.actions.state_delta[loaded_state_key(ctx, name)] = None
+ ctx.actions.state_delta[docs_state_key(ctx, name)] = None
+ ctx.actions.state_delta[tool_state_key(ctx, name)] = None
new_order = [n for n in order if n in keep_set]
- ctx.actions.state_delta[_SKILLS_LOADED_ORDER_STATE_KEY] = json.dumps(new_order)
+ encoded_order = marshal_loaded_order(new_order)
+ ctx.actions.state_delta[loaded_order_state_key(ctx)] = encoded_order
return kept
def _get_loaded_skill_order(self, ctx: InvocationContext, loaded: list[str]) -> list[str]:
- """Return skill names in load order (oldest first, most-recent last).
-
- Reads the persisted order key; fills in any missing names
- alphabetically (mirrors Go's fillLoadedSkillOrderAlphabetically).
- """
- loaded_set = set(loaded)
- raw = self._read_state(ctx, _SKILLS_LOADED_ORDER_STATE_KEY)
- order: list[str] = []
- if raw:
- try:
- parsed = json.loads(raw) if isinstance(raw, str) else raw
- if isinstance(parsed, list):
- order = [n for n in parsed if n in loaded_set]
- except (json.JSONDecodeError, TypeError, ValueError):
- pass
-
+ loaded_set = self._loaded_skill_set(loaded)
+ if not loaded_set:
+ return []
+ order = self._loaded_skill_order_from_state(ctx, loaded_set)
+ if len(order) < len(loaded_set):
+ order = self._append_skills_to_order_from_events(ctx, order, loaded_set)
seen = set(order)
for name in sorted(n for n in loaded_set if n not in seen):
order.append(name)
@@ -459,7 +493,7 @@ def _get_loaded_skill_order(self, ctx: InvocationContext, loaded: list[str]) ->
# Overview injection
# ------------------------------------------------------------------
- def _inject_overview(self, request: LlmRequest, repo: BaseSkillRepository) -> None:
+ def _inject_overview(self, ctx: InvocationContext, request: LlmRequest, repo: BaseSkillRepository) -> None:
sums = repo.summaries()
if not sums:
return
@@ -501,23 +535,44 @@ def _inject_overview(self, request: LlmRequest, repo: BaseSkillRepository) -> No
def _tooling_guidance_text(self) -> str:
if self._tooling_guidance is None:
- return _default_tooling_and_workspace_guidance(self._tool_profile, self._exec_tools_disabled)
- return _normalize_custom_guidance(self._tooling_guidance)
+ tool_prompt = _default_tooling_and_workspace_guidance(self._tool_flags)
+ else:
+ tool_prompt = _normalize_custom_guidance(self._tooling_guidance)
+ if self._tool_flags.has_select_tools():
+ tool_prompt += """
+ - Use the skill_select_tools tool to select tools for the current task only when user asks for it."
+ """
+ if self._tool_flags.list_skills:
+ tool_prompt += """
+ - Use the skill_list_skills tool to list skills for the current task only when user asks for it."
+ """
+ return tool_prompt
def _capability_guidance_text(self) -> str:
- """Inject capability block for knowledge-only profiles."""
- if not _is_knowledge_only(self._tool_profile):
- return ""
+ """Inject capability block for constrained skill-tool profiles."""
# Omit when caller explicitly cleared guidance.
- if self._tooling_guidance is not None and self._tooling_guidance == "":
+ if self._tooling_guidance == "" or self._tool_flags.run:
return ""
+ if self._tool_flags.load:
+ return ("\n" + _SKILLS_CAPABILITY_HEADER + "\n" +
+ "- This configuration supports skill discovery and knowledge loading only.\n" +
+ "- Built-in skill execution tools are unavailable in the current mode.\n" +
+ "- If a loaded skill describes scripts, shell commands, workspace paths,"
+ " generated files, or interactive flows, treat that content as reference"
+ " only. Use other registered tools for real actions, or explain that"
+ " execution is unavailable in the current mode.\n")
+ if self._tool_flags.has_doc_helpers():
+ return ("\n" + _SKILLS_CAPABILITY_HEADER + "\n" +
+ "- This configuration supports skill discovery and skill doc inspection only.\n" +
+ "- Built-in skill loading and execution tools are unavailable in the"
+ " current mode.\n- Listing or selecting docs does not inject SKILL.md or doc contents"
+ " into model context by itself.\n")
return ("\n" + _SKILLS_CAPABILITY_HEADER + "\n" +
- "- This profile supports skill discovery and knowledge loading only.\n" +
- "- Execution-oriented skill tools are unavailable in the current mode.\n" +
- "- If a loaded skill describes scripts, shell commands, workspace paths,"
- " generated files, or interactive flows, treat that content as reference"
- " only. Use other registered tools for real actions, or explain that"
- " execution is unavailable in the current mode.\n")
+ "- This configuration exposes skill summaries only. Built-in skill tools"
+ " are unavailable in the current mode.\n" +
+ "- Treat the skill overview as a catalog of possible capabilities. Use"
+ " other registered tools, or explain the limitation clearly when the task"
+ " depends on skill loading or execution.\n")
# ------------------------------------------------------------------
# State helpers
@@ -547,57 +602,150 @@ def _get_loaded_skills(self, ctx: InvocationContext) -> list[str]:
"""Return names of all currently loaded skills."""
names: list[str] = []
state = self._snapshot_state(ctx)
+ scan_prefix = loaded_scan_prefix(ctx)
for k, v in state.items():
- if not k.startswith(SKILL_LOADED_STATE_KEY_PREFIX) or not v:
+ if not k.startswith(scan_prefix) or not v:
continue
- name = k[len(SKILL_LOADED_STATE_KEY_PREFIX):]
- names.append(name)
- return names
+ name = k[len(scan_prefix):].strip()
+ if name:
+ names.append(name)
+ if names:
+ return sorted(set(names))
+ return []
# ------------------------------------------------------------------
- # Docs and tools selection
+ # Docs / tools selection
# ------------------------------------------------------------------
def _get_docs_selection(self, ctx: InvocationContext, name: str) -> list[str]:
-
- def get_all_docs(skill_name: str) -> list[str]:
+ value = self._read_state(ctx, docs_state_key(ctx, name), default=None)
+ if not value:
+ return []
+ if isinstance(value, bytes):
try:
- repo = self._get_repository(ctx)
- sk = repo.get(skill_name) if repo else None
- if sk is None:
- return []
- return [d.path for d in sk.resources]
+ value = value.decode("utf-8")
+ except UnicodeDecodeError:
+ return []
+ if value == "*":
+ repo = self._get_repository(ctx)
+ if repo is None:
+ return []
+ try:
+ sk = repo.get(name)
+ return [doc.path for doc in sk.resources]
except Exception as ex: # pylint: disable=broad-except
- logger.warning("Failed to get docs for skill '%s': %s", skill_name, ex)
+ logger.warning("Failed to get docs for skill '%s': %s", name, ex)
return []
-
- return generic_get_selection(
- ctx=ctx,
- skill_name=name,
- state_key_prefix=SKILL_DOCS_STATE_KEY_PREFIX,
- get_all_items_callback=get_all_docs,
- )
+ if not isinstance(value, str):
+ return []
+ try:
+ arr = json.loads(value)
+ except json.JSONDecodeError:
+ return []
+ if not isinstance(arr, list):
+ return []
+ return [doc for doc in arr if isinstance(doc, str) and doc.strip()]
def _get_tools_selection(self, ctx: InvocationContext, name: str) -> list[str]:
- """Python-unique: return selected tool names for *name*."""
-
- def get_all_tools(skill_name: str) -> list[str]:
+ value = self._read_state(ctx, tool_state_key(ctx, name), default=None)
+ if not value:
+ return []
+ if isinstance(value, bytes):
try:
- repo = self._get_repository(ctx)
- sk = repo.get(skill_name) if repo else None
- if sk is None:
- return []
+ value = value.decode("utf-8")
+ except UnicodeDecodeError:
+ return []
+ if value == "*":
+ repo = self._get_repository(ctx)
+ if repo is None:
+ return []
+ try:
+ sk = repo.get(name)
return sk.tools
except Exception as ex: # pylint: disable=broad-except
- logger.warning("Failed to get tools for skill '%s': %s", skill_name, ex)
+ logger.warning("Failed to get tools for skill '%s': %s", name, ex)
return []
+ if not isinstance(value, str):
+ return []
+ try:
+ arr = json.loads(value)
+ except json.JSONDecodeError:
+ return []
+ if not isinstance(arr, list):
+ return []
+ return [tool for tool in arr if isinstance(tool, str) and tool.strip()]
+
+ def _loaded_skill_set(self, loaded: list[str]) -> set[str]:
+ out: set[str] = set()
+ for name in loaded:
+ candidate = (name or "").strip()
+ if candidate:
+ out.add(candidate)
+ return out
+
+ def _loaded_skill_order_from_state(self, ctx: InvocationContext, loaded_set: set[str]) -> list[str]:
+ order = parse_loaded_order(self._read_state(ctx, loaded_order_state_key(ctx)))
+ if not order:
+ return []
+ out: list[str] = []
+ seen: set[str] = set()
+ for name in order:
+ if name not in loaded_set or name in seen:
+ continue
+ out.append(name)
+ seen.add(name)
+ return out
- return generic_get_selection(
- ctx=ctx,
- skill_name=name,
- state_key_prefix=SKILL_TOOLS_STATE_KEY_PREFIX,
- get_all_items_callback=get_all_tools,
- )
+ def _append_skills_to_order_from_events(
+ self,
+ ctx: InvocationContext,
+ order: list[str],
+ loaded_set: set[str],
+ ) -> list[str]:
+ events = list(getattr(ctx.session, "events", []) or [])
+ if not events:
+ return order
+ for event in events:
+ if ctx.agent_name and getattr(event, "author", "") != ctx.agent_name:
+ continue
+ content = getattr(event, "content", None)
+ if content is None or not getattr(content, "parts", None):
+ continue
+ for part in content.parts:
+ response = getattr(part, "function_response", None)
+ if response is None:
+ continue
+ tool_name = (getattr(response, "name", "") or "").strip()
+ if tool_name not in (SkillToolsNames.LOAD, SkillToolsNames.SELECT_DOCS):
+ continue
+ skill_name = self._skill_name_from_tool_response(tool_name, getattr(response, "response", None))
+ if not skill_name or skill_name not in loaded_set:
+ continue
+ order = touch_loaded_order(order, skill_name)
+ return order
+
+ def _skill_name_from_tool_response(self, tool_name: str, response: Any) -> str:
+ if tool_name == str(SkillToolsNames.SELECT_DOCS) and isinstance(response, dict):
+ for key in ("skill", "skill_name", "name"):
+ value = response.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return ""
+ if tool_name == SkillToolsNames.LOAD:
+ if isinstance(response, dict):
+ for key in ("skill", "skill_name", "name", "result"):
+ value = response.get(key)
+ if isinstance(value, str) and value.strip():
+ match = SKILL_LOADED_RE.search(value)
+ if match:
+ return match.group(1).strip()
+ if key in ("skill", "skill_name", "name"):
+ return value.strip()
+ if isinstance(response, str):
+ match = SKILL_LOADED_RE.search(response)
+ if match:
+ return match.group(1).strip()
+ return ""
# ------------------------------------------------------------------
# Doc text assembly
@@ -623,3 +771,28 @@ def _merge_into_system(self, request: LlmRequest, content: str) -> None:
if not content:
return
request.append_instructions([content])
+
+
+def set_skill_processor_parameters(agent_context: AgentContext, parameters: dict[str, Any]) -> None:
+ """Set the parameters of a skill processor by agent context.
+
+ Args:
+ agent_context: AgentContext object
+ parameters: Parameters to set
+ """
+ skill_config = get_skill_config(agent_context)
+ skill_config["skill_processor"].update(parameters)
+ set_skill_config(agent_context, skill_config)
+
+
+def get_skill_processor_parameters(agent_context: AgentContext) -> dict[str, Any]:
+ """Get the parameters of a skill processor.
+
+ Args:
+ invocation_context: InvocationContext object
+
+ Returns:
+ Parameters of the skill processor
+ """
+ skill_config = get_skill_config(agent_context)
+ return skill_config["skill_processor"]
diff --git a/trpc_agent_sdk/agents/core/_skills_tool_result_processor.py b/trpc_agent_sdk/agents/core/_skills_tool_result_processor.py
new file mode 100644
index 0000000..fcd38fe
--- /dev/null
+++ b/trpc_agent_sdk/agents/core/_skills_tool_result_processor.py
@@ -0,0 +1,375 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Materialize loaded skill context into skill tool results."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+from typing import Callable
+from typing import Optional
+from typing import Tuple
+
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.log import logger
+from trpc_agent_sdk.models import LlmRequest
+from trpc_agent_sdk.skills import BaseSkillRepository
+from trpc_agent_sdk.skills import Skill
+from trpc_agent_sdk.skills import SkillLoadModeNames
+from trpc_agent_sdk.skills import SkillToolsNames
+from trpc_agent_sdk.skills import docs_state_key
+from trpc_agent_sdk.skills import get_skill_config
+from trpc_agent_sdk.skills import get_skill_load_mode
+from trpc_agent_sdk.skills import loaded_order_state_key
+from trpc_agent_sdk.skills import loaded_scan_prefix
+from trpc_agent_sdk.skills import loaded_state_key
+from trpc_agent_sdk.skills import set_skill_config
+
+_SKILLS_LOADED_CONTEXT_HEADER = "Loaded skill context:"
+_SESSION_SUMMARY_PREFIX = "Here is a brief summary of your previous interactions:"
+SKILL_LOADED_RE = re.compile(r"skill\s+'([^']+)'\s+loaded", re.IGNORECASE)
+
+
+class SkillsToolResultRequestProcessor:
+ """Materialize loaded skill content into skill tool results."""
+
+ def __init__(
+ self,
+ skill_repository: BaseSkillRepository,
+ *,
+ skip_fallback_on_session_summary: bool = True,
+ repo_resolver: Optional[Callable[[InvocationContext], BaseSkillRepository]] = None,
+ ) -> None:
+ self._skill_repository = skill_repository
+ self._repo_resolver = repo_resolver
+ self._skip_fallback_on_session_summary = skip_fallback_on_session_summary
+
+ async def process_llm_request(self, ctx: InvocationContext, request: LlmRequest) -> list[str]:
+ """Apply loaded-skill materialization to tool results and fallback prompt."""
+ if request is None or ctx is None:
+ return []
+ repo = self._get_repository(ctx)
+ if repo is None:
+ return []
+
+ loaded = self._get_loaded_skills(ctx)
+ if not loaded:
+ return []
+ loaded.sort()
+
+ tool_calls = self._index_tool_calls(request)
+ last_tool_parts = self._last_skill_tool_parts(request, tool_calls)
+
+ materialized: set[str] = set()
+ for skill_name, (content_idx, part_idx) in last_tool_parts.items():
+ content = request.contents[content_idx]
+ part = content.parts[part_idx]
+ function_response = part.function_response
+ if function_response is None:
+ continue
+ base = self._response_to_text(getattr(function_response, "response", None))
+ rendered = self._build_tool_result_content(ctx, repo, skill_name, base)
+ if not rendered:
+ continue
+ function_response.response = {"result": rendered}
+ materialized.add(skill_name)
+
+ fallback = self._build_fallback_system_content(ctx, repo, loaded, materialized)
+ if fallback:
+ if not (self._skip_fallback_on_session_summary and self._has_session_summary(request)
+ and not last_tool_parts):
+ request.append_instructions([fallback])
+
+ self._maybe_offload_loaded_skills(ctx, loaded)
+ return loaded
+
+ def _get_repository(self, ctx: InvocationContext) -> Optional[BaseSkillRepository]:
+ if self._repo_resolver is not None:
+ return self._repo_resolver(ctx)
+ return self._skill_repository
+
+ def _snapshot_state(self, ctx: InvocationContext) -> dict[str, Any]:
+ state = dict(ctx.session_state)
+ for key, value in ctx.actions.state_delta.items():
+ if value is None:
+ state.pop(key, None)
+ else:
+ state[key] = value
+ return state
+
+ def _read_state(self, ctx: InvocationContext, key: str, default=None):
+ if key in ctx.actions.state_delta:
+ return ctx.actions.state_delta[key]
+ return ctx.session_state.get(key, default)
+
+ def _get_loaded_skills(self, ctx: InvocationContext) -> list[str]:
+ names_set: set[str] = set()
+ state = self._snapshot_state(ctx)
+ scan_prefix = loaded_scan_prefix(ctx)
+ for key, value in state.items():
+ if not key.startswith(scan_prefix) or not value:
+ continue
+ name = key[len(scan_prefix):].strip()
+ if name:
+ names_set.add(name)
+ return sorted(names_set)
+
+ def _index_tool_calls(self, request: LlmRequest) -> dict[str, Any]:
+ out: dict[str, Any] = {}
+ for content in request.contents:
+ if content.role not in ("model", "assistant") or not content.parts:
+ continue
+ for part in content.parts:
+ function_call = getattr(part, "function_call", None)
+ if function_call is None:
+ continue
+ call_id = (getattr(function_call, "id", "") or "").strip()
+ if not call_id:
+ continue
+ out[call_id] = function_call
+ return out
+
+ def _last_skill_tool_parts(
+ self,
+ request: LlmRequest,
+ tool_calls: dict[str, Any],
+ ) -> dict[str, Tuple[int, int]]:
+ out: dict[str, Tuple[int, int]] = {}
+ for content_idx, content in enumerate(request.contents):
+ if content.role != "user" or not content.parts:
+ continue
+ for part_idx, part in enumerate(content.parts):
+ function_response = getattr(part, "function_response", None)
+ if function_response is None:
+ continue
+ tool_name = (getattr(function_response, "name", "") or "").strip()
+ if tool_name not in (SkillToolsNames.LOAD, SkillToolsNames.SELECT_DOCS):
+ continue
+ skill_name = self._skill_name_from_tool_response(function_response, tool_calls)
+ if not skill_name:
+ continue
+ out[skill_name] = (content_idx, part_idx)
+ return out
+
+ def _skill_name_from_tool_response(self, function_response: Any, tool_calls: dict[str, Any]) -> str:
+ response = getattr(function_response, "response", None)
+ if isinstance(response, dict):
+ for key in ("skill", "skill_name", "name"):
+ value = response.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+
+ call_id = (getattr(function_response, "id", "") or "").strip()
+ if call_id and call_id in tool_calls:
+ function_call = tool_calls[call_id]
+ args = getattr(function_call, "args", None)
+ for key in ("skill", "skill_name", "name"):
+ value = self._get_arg_value(args, key)
+ if value:
+ return value
+
+ return self._parse_loaded_skill_from_text(self._response_to_text(response))
+
+ def _get_arg_value(self, args: Any, key: str) -> str:
+ if isinstance(args, str):
+ try:
+ args = json.loads(args)
+ except json.JSONDecodeError:
+ return ""
+ if isinstance(args, dict):
+ value = args.get(key)
+ if isinstance(value, str):
+ return value.strip()
+ return ""
+
+ def _parse_loaded_skill_from_text(self, content: str) -> str:
+ text = (content or "").strip()
+ if not text:
+ return ""
+ match = SKILL_LOADED_RE.search(text)
+ if match:
+ return match.group(1).strip()
+ lower = text.lower()
+ if lower.startswith("loaded:"):
+ return text[len("loaded:"):].strip()
+ return ""
+
+ def _response_to_text(self, response: Any) -> str:
+ if response is None:
+ return ""
+ if isinstance(response, str):
+ return response.strip()
+ if isinstance(response, dict):
+ result = response.get("result")
+ if isinstance(result, str):
+ return result.strip()
+ if result is not None:
+ return str(result).strip()
+ return json.dumps(response, ensure_ascii=False).strip()
+ return str(response).strip()
+
+ def _is_loaded_tool_stub(self, tool_output: str, skill_name: str) -> bool:
+ loaded = self._parse_loaded_skill_from_text(tool_output)
+ if not loaded:
+ return False
+ return loaded.lower() == skill_name.lower()
+
+ def _build_tool_result_content(
+ self,
+ ctx: InvocationContext,
+ repo: BaseSkillRepository,
+ skill_name: str,
+ tool_output: str,
+ ) -> str:
+ try:
+ sk = repo.get(skill_name)
+ except Exception as ex: # pylint: disable=broad-except
+ logger.warning("skills: get %s failed: %s", skill_name, ex)
+ return ""
+ if sk is None:
+ logger.warning("skills: get %s failed: skill not found", skill_name)
+ return ""
+
+ parts: list[str] = []
+ base = tool_output.strip()
+ if base and self._is_loaded_tool_stub(base, skill_name):
+ base = ""
+ if base:
+ parts.append(base)
+ parts.append("\n\n")
+
+ if sk.body.strip():
+ parts.append(f"[Loaded] {skill_name}\n\n{sk.body}\n")
+
+ selected_docs = self._get_docs_selection(ctx, skill_name, repo)
+ parts.append("Docs loaded: ")
+ if not selected_docs:
+ parts.append("none\n")
+ else:
+ parts.append(", ".join(selected_docs) + "\n")
+ docs_text = self._build_docs_text(sk, selected_docs)
+ if docs_text:
+ parts.append(docs_text)
+ return "".join(parts).strip()
+
+ def _build_fallback_system_content(
+ self,
+ ctx: InvocationContext,
+ repo: BaseSkillRepository,
+ loaded: list[str],
+ materialized: set[str],
+ ) -> str:
+ missing = [name for name in loaded if name not in materialized]
+ if not missing:
+ return ""
+
+ parts: list[str] = [_SKILLS_LOADED_CONTEXT_HEADER, "\n"]
+ appended = False
+ for name in missing:
+ try:
+ sk = repo.get(name)
+ except Exception as ex: # pylint: disable=broad-except
+ logger.warning("skills: get %s failed: %s", name, ex)
+ continue
+ if sk is None:
+ logger.warning("skills: get %s failed: skill not found", name)
+ continue
+ if sk.body.strip():
+ parts.append(f"\n[Loaded] {name}\n\n{sk.body}\n")
+ appended = True
+ selected_docs = self._get_docs_selection(ctx, name, repo)
+ parts.append("Docs loaded: ")
+ if not selected_docs:
+ parts.append("none\n")
+ else:
+ parts.append(", ".join(selected_docs) + "\n")
+ docs_text = self._build_docs_text(sk, selected_docs)
+ if docs_text:
+ parts.append(docs_text)
+ appended = True
+ if not appended:
+ return ""
+ return "".join(parts).strip()
+
+ def _has_session_summary(self, request: LlmRequest) -> bool:
+ if request is None or request.config is None:
+ return False
+ system_instruction = str(request.config.system_instruction or "")
+ return _SESSION_SUMMARY_PREFIX in system_instruction
+
+ def _get_docs_selection(self, ctx: InvocationContext, skill_name: str, repo: BaseSkillRepository) -> list[str]:
+ value = self._read_state(ctx, docs_state_key(ctx, skill_name), default=None)
+ if not value:
+ return []
+ if isinstance(value, bytes):
+ try:
+ value = value.decode("utf-8")
+ except UnicodeDecodeError:
+ return []
+ if value == "*":
+ try:
+ sk = repo.get(skill_name)
+ except Exception as ex: # pylint: disable=broad-except
+ logger.warning("skills: get %s failed: %s", skill_name, ex)
+ return []
+ if sk is None:
+ return []
+ return [doc.path for doc in sk.resources]
+ if not isinstance(value, str):
+ return []
+ try:
+ arr = json.loads(value)
+ except json.JSONDecodeError:
+ return []
+ if not isinstance(arr, list):
+ return []
+ return [doc for doc in arr if isinstance(doc, str) and doc.strip()]
+
+ def _build_docs_text(self, sk: Skill, wanted: list[str]) -> str:
+ if sk is None or not sk.resources:
+ return ""
+ want = set(wanted)
+ parts: list[str] = []
+ for resource in sk.resources:
+ if resource.path not in want or not resource.content:
+ continue
+ parts.append(f"\n[Doc] {resource.path}\n\n{resource.content}\n")
+ return "".join(parts)
+
+ def _maybe_offload_loaded_skills(self, ctx: InvocationContext, loaded: list[str]) -> None:
+ if get_skill_load_mode(ctx) != SkillLoadModeNames.ONCE or not loaded:
+ return
+ for skill_name in loaded:
+ ctx.actions.state_delta[loaded_state_key(ctx, skill_name)] = None
+ ctx.actions.state_delta[docs_state_key(ctx, skill_name)] = None
+ ctx.actions.state_delta[loaded_order_state_key(ctx)] = None
+
+
+def set_skill_tool_result_processor_parameters(agent_context: AgentContext, parameters: dict[str, Any]) -> None:
+ """Set the parameters of a skill tool result processor by agent context.
+
+ Args:
+ agent_context: AgentContext object
+ parameters: Parameters to set
+ """
+ skill_config = get_skill_config(agent_context)
+ skill_config["skills_tool_result_processor"].update(parameters)
+ set_skill_config(agent_context, skill_config)
+
+
+def get_skill_tool_result_processor_parameters(agent_context: AgentContext) -> dict[str, Any]:
+ """Get the parameters of a skill tool result processor.
+
+ Args:
+ agent_context: AgentContext object
+
+ Returns:
+ Parameters of the skill tool result processor
+ """
+ skill_config = get_skill_config(agent_context)
+ return skill_config["skills_tool_result_processor"]
diff --git a/trpc_agent_sdk/agents/core/_workspace_exec_processor.py b/trpc_agent_sdk/agents/core/_workspace_exec_processor.py
new file mode 100644
index 0000000..fc2d4d9
--- /dev/null
+++ b/trpc_agent_sdk/agents/core/_workspace_exec_processor.py
@@ -0,0 +1,153 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Inject workspace_exec guidance into request system instructions.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Callable
+from typing import Optional
+
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.models import LlmRequest
+from trpc_agent_sdk.skills import BaseSkillRepository
+from trpc_agent_sdk.skills import get_skill_config
+from trpc_agent_sdk.skills import set_skill_config
+
+_WORKSPACE_EXEC_GUIDANCE_HEADER = "Executor workspace guidance:"
+
+
+class WorkspaceExecRequestProcessor:
+ """Request processor for workspace_exec guidance injection."""
+
+ def __init__(
+ self,
+ *,
+ session_tools: bool = False,
+ has_skills_repo: bool = False,
+ repo_resolver: Optional[Callable[[InvocationContext], Optional[BaseSkillRepository]]] = None,
+ enabled_resolver: Optional[Callable[[InvocationContext], bool]] = None,
+ sessions_resolver: Optional[Callable[[InvocationContext], bool]] = None,
+ ) -> None:
+ self._session_tools = session_tools
+ self._static_skills_repo = has_skills_repo
+ self._repo_resolver = repo_resolver
+ self._enabled_resolver = enabled_resolver
+ self._sessions_resolver = sessions_resolver
+
+ async def process_llm_request(self, ctx: InvocationContext, request: LlmRequest) -> None:
+ """Inject workspace guidance into request.config.system_instruction."""
+ if ctx is None or request is None:
+ return
+ guidance = self._guidance_text(ctx, request)
+ if not guidance:
+ return
+
+ existing = ""
+ if request.config and request.config.system_instruction:
+ existing = str(request.config.system_instruction)
+ if _WORKSPACE_EXEC_GUIDANCE_HEADER in existing:
+ return
+ request.append_instructions([guidance])
+
+ def _guidance_text(self, ctx: InvocationContext, request: LlmRequest) -> str:
+ if not self._enabled_for_invocation(ctx, request):
+ return ""
+ lines: list[str] = [
+ _WORKSPACE_EXEC_GUIDANCE_HEADER,
+ "- Treat workspace_exec as the default general shell runner for shared "
+ "executor-side work. It runs inside the current executor workspace, not "
+ "on the agent host; workspace is its scope, not its capability limit.",
+ "- workspace_exec starts at the workspace root by default. Prefer work/, "
+ "out/, and runs/ for shared executor-side work, and treat cwd as a "
+ "workspace-relative path.",
+ "- Network access depends on the current executor environment. If you "
+ "need a network command such as curl, use a small bounded command to "
+ "verify whether that environment allows it.",
+ "- When a limitation depends on the executor environment and a small "
+ "bounded command can verify it, verify first before claiming the "
+ "limitation. This applies to checks such as command availability, file "
+ "presence, or access to a known URL.",
+ ]
+ if self._supports_artifact_save(request):
+ lines.append("- Use workspace_save_artifact only when you need a stable artifact "
+ "reference for an already existing file in work/, out/, or runs/. "
+ "Intermediate files usually stay in the workspace.")
+ if self._has_skills_repo(ctx):
+ lines.append("- Paths under skills/ are only useful when some other tool has "
+ "already placed content there. workspace_exec does not stage skills "
+ "automatically.")
+ if self._session_tools_for_invocation(ctx, request):
+ lines.append("- When workspace_exec starts a command that keeps running or waits "
+ "for stdin, continue with workspace_write_stdin. When chars is empty, "
+ "workspace_write_stdin acts like a poll. Use workspace_kill_session "
+ "to stop a running workspace_exec session.")
+ lines.append("- Interactive workspace_exec sessions are only guaranteed within the "
+ "current invocation. Do not assume a later user message can resume "
+ "the same session.")
+ return "\n".join(lines).strip()
+
+ def _enabled_for_invocation(self, ctx: InvocationContext, request: LlmRequest) -> bool:
+ if self._enabled_resolver is not None:
+ return bool(self._enabled_resolver(ctx))
+ return self._has_tool(request, "workspace_exec")
+
+ def _session_tools_for_invocation(self, ctx: InvocationContext, request: LlmRequest) -> bool:
+ if self._sessions_resolver is not None:
+ return bool(self._sessions_resolver(ctx))
+ if self._session_tools:
+ return True
+ return self._has_tool(request, "workspace_write_stdin") and self._has_tool(request, "workspace_kill_session")
+
+ def _has_skills_repo(self, ctx: InvocationContext) -> bool:
+ if self._repo_resolver is not None:
+ return self._repo_resolver(ctx) is not None
+ return self._static_skills_repo
+
+ def _supports_artifact_save(self, request: LlmRequest) -> bool:
+ return self._has_tool(request, "workspace_save_artifact")
+
+ @staticmethod
+ def _has_tool(request: LlmRequest, tool_name: str) -> bool:
+ if request is None or request.config is None or not request.config.tools:
+ return False
+ target = (tool_name or "").strip()
+ if not target:
+ return False
+ for tool in request.config.tools:
+ declarations = getattr(tool, "function_declarations", None) or []
+ for declaration in declarations:
+ name = getattr(declaration, "name", "")
+ if (name or "").strip() == target:
+ return True
+ return False
+
+
+def set_workspace_exec_processor_parameters(agent_context: AgentContext, parameters: dict[str, Any]) -> None:
+ """Set the parameters of a workspace exec processor by agent context.
+
+ Args:
+ agent_context: AgentContext object
+ parameters: Parameters to set
+ """
+ skill_config = get_skill_config(agent_context)
+ skill_config["workspace_exec_processor"].update(parameters)
+ set_skill_config(agent_context, skill_config)
+
+
+def get_workspace_exec_processor_parameters(agent_context: AgentContext) -> dict[str, Any]:
+ """Get the parameters of a workspace exec processor.
+
+ Args:
+ agent_context: AgentContext object
+
+ Returns:
+ Parameters of the workspace exec processor
+ """
+ skill_config = get_skill_config(agent_context)
+ return skill_config["workspace_exec_processor"]
diff --git a/trpc_agent_sdk/artifacts/_in_memory_artifact_service.py b/trpc_agent_sdk/artifacts/_in_memory_artifact_service.py
index add9962..ab6c5aa 100644
--- a/trpc_agent_sdk/artifacts/_in_memory_artifact_service.py
+++ b/trpc_agent_sdk/artifacts/_in_memory_artifact_service.py
@@ -1,8 +1,6 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+# -*- coding: utf-8 -*-
#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
+# Copyright @ 2025 Tencent.com
#
# Directly reuse the types from adk-python
# Below code are copy and modified from https://github.com/google/adk-python.git
@@ -27,7 +25,6 @@
from pydantic import BaseModel
from pydantic import Field
-
from trpc_agent_sdk.abc import ArtifactEntry
from trpc_agent_sdk.abc import ArtifactId
from trpc_agent_sdk.abc import ArtifactServiceABC
@@ -80,7 +77,7 @@ async def save_artifact(
else:
raise ValueError("Not supported artifact type.")
- self.artifacts[path].append(ArtifactEntry(data=artifact, artifact_version=artifact_version))
+ self.artifacts[path].append(ArtifactEntry(data=artifact, version=artifact_version))
return version
@override
@@ -125,6 +122,8 @@ async def load_artifact(
if (artifact_data == Part() or artifact_data == Part(text="")
or (artifact_data.inline_data and not artifact_data.inline_data.data)):
return None
+ if artifact_entry.version.mime_type is None:
+ artifact_entry.version.mime_type = "application/octet-stream"
return artifact_entry
@override
@@ -175,7 +174,7 @@ async def list_artifact_versions(
entries = self.artifacts.get(path)
if not entries:
return []
- return [entry.artifact_version for entry in entries]
+ return [entry.version for entry in entries]
@override
async def get_artifact_version(
@@ -192,6 +191,6 @@ async def get_artifact_version(
if version is None:
version = -1
try:
- return entries[version].artifact_version
+ return entries[version].version
except IndexError:
return None
diff --git a/trpc_agent_sdk/artifacts/_utils.py b/trpc_agent_sdk/artifacts/_utils.py
index b9f0656..ee1444e 100644
--- a/trpc_agent_sdk/artifacts/_utils.py
+++ b/trpc_agent_sdk/artifacts/_utils.py
@@ -29,7 +29,6 @@
from typing import Optional
from google.genai import types
-
from trpc_agent_sdk.abc import ArtifactId
diff --git a/trpc_agent_sdk/code_executors/__init__.py b/trpc_agent_sdk/code_executors/__init__.py
index d16645e..276f4db 100644
--- a/trpc_agent_sdk/code_executors/__init__.py
+++ b/trpc_agent_sdk/code_executors/__init__.py
@@ -9,13 +9,9 @@
including base classes and implementations.
"""
-from ._artifacts import artifact_service_from_context
-from ._artifacts import artifact_session_from_context
from ._artifacts import load_artifact_helper
from ._artifacts import parse_artifact_ref
from ._artifacts import save_artifact_helper
-from ._artifacts import with_artifact_service
-from ._artifacts import with_artifact_session
from ._base_code_executor import BaseCodeExecutor
from ._base_workspace_runtime import BaseProgramRunner
from ._base_workspace_runtime import BaseWorkspaceFS
@@ -47,6 +43,20 @@
from ._constants import META_FILE_NAME
from ._constants import TMP_FILE_NAME
from ._constants import WORKSPACE_ENV_DIR_KEY
+from ._program_session import BaseProgramSession
+from ._program_session import DEFAULT_EXEC_YIELD_MS
+from ._program_session import DEFAULT_IO_YIELD_MS
+from ._program_session import DEFAULT_POLL_LINES
+from ._program_session import DEFAULT_SESSION_KILL_SEC
+from ._program_session import DEFAULT_SESSION_TTL_SEC
+from ._program_session import PROGRAM_STATUS_EXITED
+from ._program_session import PROGRAM_STATUS_RUNNING
+from ._program_session import ProgramLog
+from ._program_session import ProgramPoll
+from ._program_session import ProgramState
+from ._program_session import poll_line_limit
+from ._program_session import wait_for_program_output
+from ._program_session import yield_duration_ms
from ._types import CodeBlock
from ._types import CodeBlockDelimiter
from ._types import CodeExecutionInput
@@ -82,13 +92,9 @@
from .utils import CodeExecutionUtils
__all__ = [
- "artifact_service_from_context",
- "artifact_session_from_context",
"load_artifact_helper",
"parse_artifact_ref",
"save_artifact_helper",
- "with_artifact_service",
- "with_artifact_session",
"BaseCodeExecutor",
"BaseProgramRunner",
"BaseWorkspaceFS",
@@ -120,6 +126,20 @@
"META_FILE_NAME",
"TMP_FILE_NAME",
"WORKSPACE_ENV_DIR_KEY",
+ "BaseProgramSession",
+ "DEFAULT_EXEC_YIELD_MS",
+ "DEFAULT_IO_YIELD_MS",
+ "DEFAULT_POLL_LINES",
+ "DEFAULT_SESSION_KILL_SEC",
+ "DEFAULT_SESSION_TTL_SEC",
+ "PROGRAM_STATUS_EXITED",
+ "PROGRAM_STATUS_RUNNING",
+ "ProgramLog",
+ "ProgramPoll",
+ "ProgramState",
+ "poll_line_limit",
+ "wait_for_program_output",
+ "yield_duration_ms",
"CodeBlock",
"CodeBlockDelimiter",
"CodeExecutionInput",
diff --git a/trpc_agent_sdk/code_executors/_artifacts.py b/trpc_agent_sdk/code_executors/_artifacts.py
index 08e0cda..3c1087b 100644
--- a/trpc_agent_sdk/code_executors/_artifacts.py
+++ b/trpc_agent_sdk/code_executors/_artifacts.py
@@ -10,11 +10,9 @@
through context, enabling artifact resolution without importing higher-level packages.
"""
-from typing import Any
from typing import Optional
from typing import Tuple
-from trpc_agent_sdk.abc import ArtifactServiceABC
from trpc_agent_sdk.context import InvocationContext
from trpc_agent_sdk.types import Blob
from trpc_agent_sdk.types import Part
@@ -36,6 +34,8 @@ async def load_artifact_helper(ctx: InvocationContext,
Returns:
The artifact.
"""
+ if not ctx:
+ raise ValueError("ctx is required")
artifact_entry = await ctx.load_artifact(name, version)
if artifact_entry is None:
return None
@@ -55,17 +55,20 @@ def parse_artifact_ref(ref: str) -> Tuple[str, Optional[int]]:
The artifact name and version.
"""
parts = ref.split("@")
+ name = parts[0]
+ if not name:
+ raise ValueError(f"invalid ref: {ref}")
if len(parts) == 1:
- return parts[0], None
+ return name, None
- if len(parts) == 2:
+ if len(parts) >= 2:
# Try to parse version as integer
- version_str = parts[1]
+ version_str = "".join(parts[1:])
if not version_str.isdigit():
- raise ValueError(f"invalid version: {version_str}")
+ return name, None
- return parts[0], int(version_str)
+ return name, int(version_str)
raise ValueError(f"invalid ref: {ref}")
@@ -85,51 +88,3 @@ async def save_artifact_helper(ctx: InvocationContext, filename: str, data: byte
"""
artifact = Part(inline_data=Blob(data=data, mime_type=mime), )
return await ctx.save_artifact(filename, artifact)
-
-
-def with_artifact_service(ctx: InvocationContext, svc: ArtifactServiceABC) -> InvocationContext:
- """
- Store an artifact.Service in the context.
-
- Callers retrieve it in lower layers to load/save artifacts
- without importing higher-level packages.
-
- Args:
- ctx: The context to store the service in
- svc: The artifact service
-
- Returns:
- Updated context with artifact service
- """
- ctx.artifact_service = svc
- return ctx
-
-
-def artifact_service_from_context(ctx: InvocationContext) -> Optional[ArtifactServiceABC]:
- """
- Fetch the artifact.Service previously stored by with_artifact_service.
-
- Args:
- ctx: The context to retrieve the service from
-
- Returns:
- Tuple of (service, ok) where ok indicates presence
- """
- return ctx.artifact_service
-
-
-def with_artifact_session(ctx: InvocationContext, info: Any) -> InvocationContext:
- assert False, "Not implemented"
-
-
-def artifact_session_from_context(ctx: InvocationContext) -> Any:
- """
- Retrieve artifact session info from context.
-
- Args:
- ctx: The context to retrieve the session info from
-
- Returns:
- SessionInfo object (empty if not found)
- """
- assert False, "Not implemented"
diff --git a/trpc_agent_sdk/code_executors/_base_code_executor.py b/trpc_agent_sdk/code_executors/_base_code_executor.py
index 17ea06d..f7c6b06 100644
--- a/trpc_agent_sdk/code_executors/_base_code_executor.py
+++ b/trpc_agent_sdk/code_executors/_base_code_executor.py
@@ -16,7 +16,6 @@
from typing import Optional
from pydantic import BaseModel
-
from trpc_agent_sdk.context import InvocationContext
from ._base_workspace_runtime import BaseWorkspaceRuntime
@@ -82,6 +81,9 @@ class BaseCodeExecutor(BaseModel):
workspace_runtime: Optional[BaseWorkspaceRuntime] = None
"""The workspace runtime for the code execution."""
+ ignore_codes: list[str] = []
+ """The list of codes to ignore in the code execution."""
+
@abc.abstractmethod
async def execute_code(
self,
diff --git a/trpc_agent_sdk/code_executors/_base_workspace_runtime.py b/trpc_agent_sdk/code_executors/_base_workspace_runtime.py
index b57b6a9..3ee1e1e 100644
--- a/trpc_agent_sdk/code_executors/_base_workspace_runtime.py
+++ b/trpc_agent_sdk/code_executors/_base_workspace_runtime.py
@@ -12,10 +12,12 @@
from abc import ABC
from abc import abstractmethod
+from typing import Callable
from typing import List
from typing import Optional
from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.log import logger
from ._types import CodeFile
from ._types import ManifestOutput
@@ -28,6 +30,8 @@
from ._types import WorkspaceRunResult
from ._types import WorkspaceStageOptions
+RunEnvProvider = Callable[[Optional[InvocationContext]], dict[str, str]]
+
class BaseWorkspaceManager(ABC):
"""
@@ -130,6 +134,40 @@ class BaseProgramRunner(ABC):
Executes programs within a workspace.
"""
+ def __init__(
+ self,
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False,
+ ) -> None:
+ self._run_env_provider = provider
+ self._enable_provider_env = bool(enable_provider_env and provider)
+
+ def _apply_provider_env(
+ self,
+ spec: WorkspaceRunProgramSpec,
+ ctx: Optional[InvocationContext] = None,
+ ) -> WorkspaceRunProgramSpec:
+ """Return spec with provider env merged when enabled.
+
+ Provider values never override keys already present in ``spec.env``.
+ The input ``spec`` is not mutated.
+ """
+ provider = getattr(self, "_run_env_provider", None)
+ if not getattr(self, "_enable_provider_env", False) or provider is None:
+ return spec
+ try:
+ extra = provider(ctx) or {}
+ except Exception as ex: # pylint: disable=broad-except
+ logger.warning("run env provider failed: %s", ex)
+ return spec
+ if not extra:
+ return spec
+ merged = dict(spec.env or {})
+ for key, value in extra.items():
+ if key not in merged:
+ merged[key] = value
+ return spec.model_copy(update={"env": merged}, deep=True)
+
@abstractmethod
async def run_program(
self,
diff --git a/trpc_agent_sdk/code_executors/_program_session.py b/trpc_agent_sdk/code_executors/_program_session.py
new file mode 100644
index 0000000..177a00a
--- /dev/null
+++ b/trpc_agent_sdk/code_executors/_program_session.py
@@ -0,0 +1,167 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright @ 2026 Tencent.com
+"""Program-session helpers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from abc import ABC
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from ._types import WorkspaceRunResult
+
+# Default wait windows (milliseconds).
+DEFAULT_EXEC_YIELD_MS = 1_000
+DEFAULT_IO_YIELD_MS = 400
+DEFAULT_POLL_LINES = 40
+
+# Poll pacing / settle windows (seconds).
+DEFAULT_POLL_WAIT_SEC = 0.05
+DEFAULT_POLL_SETTLE_SEC = 0.075
+
+# Session lifecycle defaults (seconds).
+DEFAULT_SESSION_TTL_SEC = 30 * 60
+DEFAULT_SESSION_KILL_SEC = 2.0
+
+PROGRAM_STATUS_RUNNING = "running"
+PROGRAM_STATUS_EXITED = "exited"
+
+
+@dataclass
+class ProgramPoll:
+ """Incremental output chunk for a running or exited session."""
+
+ status: str = PROGRAM_STATUS_RUNNING
+ output: str = ""
+ offset: int = 0
+ next_offset: int = 0
+ exit_code: Optional[int] = None
+
+
+@dataclass
+class ProgramLog:
+ """Non-destructive output window from a specific offset."""
+
+ output: str = ""
+ offset: int = 0
+ next_offset: int = 0
+
+
+@dataclass
+class ProgramState:
+ """Non-streaming session status without cursor mutation."""
+
+ status: str = PROGRAM_STATUS_RUNNING
+ exit_code: Optional[int] = None
+
+
+class BaseProgramSession(ABC):
+ """Base class for program sessions."""
+
+ @abstractmethod
+ def id(self) -> str:
+ """Return stable session id."""
+
+ @abstractmethod
+ async def poll(self, limit: Optional[int] = None) -> ProgramPoll:
+ """Advance cursor and return incremental output."""
+
+ @abstractmethod
+ async def log(self, offset: Optional[int] = None, limit: Optional[int] = None) -> ProgramLog:
+ """Read output from offset without advancing cursor."""
+
+ @abstractmethod
+ async def write(self, data: str, newline: bool) -> None:
+ """Write input to session."""
+
+ @abstractmethod
+ async def kill(self, grace_seconds: float) -> None:
+ """Terminate session, escalating after grace period."""
+
+ @abstractmethod
+ async def close(self) -> None:
+ """Release resources and stop background routines."""
+
+ @abstractmethod
+ async def state(self) -> ProgramState:
+ """Return current state snapshot."""
+
+ @abstractmethod
+ async def run_result(self) -> WorkspaceRunResult:
+ """Return final run result after session exits."""
+
+
+def yield_duration_ms(ms: int, fallback_ms: int) -> float:
+ """Normalize milliseconds into seconds with fallback and clamping."""
+ if ms < 0:
+ ms = 0
+ if ms == 0:
+ ms = fallback_ms
+ return ms / 1000.0
+
+
+def poll_line_limit(lines: int) -> int:
+ """Return a positive poll-line limit with default fallback."""
+ if lines <= 0:
+ lines = DEFAULT_POLL_LINES
+ return lines
+
+
+async def wait_for_program_output(
+ proc: BaseProgramSession,
+ yield_seconds: float,
+ limit: Optional[int],
+) -> ProgramPoll:
+ """Poll until session exits or output settles within the yield window."""
+ deadline = time.monotonic()
+ if yield_seconds > 0:
+ deadline += yield_seconds
+
+ out_parts: list[str] = []
+ offset = 0
+ next_offset = 0
+ have_chunk = False
+ settle_deadline = 0.0
+
+ while True:
+ poll = await proc.poll(limit)
+ if poll.output:
+ if not have_chunk:
+ offset = poll.offset
+ have_chunk = True
+ out_parts.append(poll.output)
+ next_offset = poll.next_offset
+ settle_deadline = time.monotonic() + DEFAULT_POLL_SETTLE_SEC
+ if yield_seconds <= 0:
+ deadline = settle_deadline
+ elif not have_chunk:
+ offset = poll.offset
+ next_offset = poll.next_offset
+ else:
+ next_offset = poll.next_offset
+
+ if poll.status == PROGRAM_STATUS_EXITED:
+ poll.output = "".join(out_parts)
+ poll.offset = offset
+ poll.next_offset = next_offset
+ return poll
+
+ now = time.monotonic()
+ if settle_deadline and now > settle_deadline:
+ poll.output = "".join(out_parts)
+ poll.offset = offset
+ poll.next_offset = next_offset
+ return poll
+
+ if yield_seconds > 0 and now > deadline:
+ poll.output = "".join(out_parts)
+ poll.offset = offset
+ poll.next_offset = next_offset
+ return poll
+
+ await asyncio.sleep(DEFAULT_POLL_WAIT_SEC)
diff --git a/trpc_agent_sdk/code_executors/_types.py b/trpc_agent_sdk/code_executors/_types.py
index 3323201..5130d48 100644
--- a/trpc_agent_sdk/code_executors/_types.py
+++ b/trpc_agent_sdk/code_executors/_types.py
@@ -11,7 +11,6 @@
from pydantic import BaseModel
from pydantic import Field
-
from trpc_agent_sdk.types import CodeExecutionResult
from trpc_agent_sdk.types import Outcome
@@ -149,6 +148,9 @@ class WorkspaceRunProgramSpec(BaseModel):
limits: WorkspaceResourceLimits = Field(default_factory=WorkspaceResourceLimits)
""" resource limits"""
+ tty: bool = Field(default=False, description="Allocate pseudo-TTY")
+ """ whether to allocate pseudo-TTY"""
+
class WorkspaceRunResult(BaseModel):
"""
diff --git a/trpc_agent_sdk/code_executors/container/_container_cli.py b/trpc_agent_sdk/code_executors/container/_container_cli.py
index 2e06d0c..39447ad 100644
--- a/trpc_agent_sdk/code_executors/container/_container_cli.py
+++ b/trpc_agent_sdk/code_executors/container/_container_cli.py
@@ -1,8 +1,6 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+# -*- coding: utf-8 -*-
#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
+# Copyright @ 2025 Tencent.com
"""Container code executor for TRPC Agent framework.
This module provides a code executor that uses a custom container to execute code.
@@ -14,12 +12,15 @@
import asyncio
import atexit
import os
+import socket as pysocket
from dataclasses import dataclass
from typing import Optional
import docker
from docker.models.containers import Container
-
+from docker.utils.socket import consume_socket_output
+from docker.utils.socket import demux_adaptor
+from docker.utils.socket import frames_iter
from trpc_agent_sdk.log import logger
from trpc_agent_sdk.utils import CommandExecResult
@@ -48,6 +49,8 @@ class CommandArgs:
"""The environment variables for the command execution."""
timeout: Optional[float] = None
"""The timeout for the command execution in seconds."""
+ stdin: Optional[str] = None
+ """Optional stdin content to write once before reading output."""
class ContainerClient:
@@ -151,6 +154,16 @@ def _init_container(self):
# docker SDK `run` supports bind specs via `volumes`.
run_kwargs["volumes"] = binds
logger.info("Container bind mounts enabled: %s", binds)
+ command = self.host_config.get("command", ["tail", "-f", "/dev/null"])
+ stdin = self.host_config.get("stdin", True)
+ working_dir = self.host_config.get("working_dir", "/")
+ network_mode = self.host_config.get("network_mode", "none")
+ auto_remove = self.host_config.get("auto_remove", True)
+ run_kwargs.setdefault("command", command)
+ run_kwargs.setdefault("stdin_open", stdin)
+ run_kwargs.setdefault("working_dir", working_dir)
+ run_kwargs.setdefault("network_mode", network_mode)
+ run_kwargs.setdefault("auto_remove", auto_remove)
self._container = self._client.containers.run(
image=self.image,
detach=True,
@@ -189,23 +202,100 @@ def _cleanup_container(self):
return
logger.info("[Cleanup] Stopping the container...")
- self._container.stop()
- self._container.remove()
+ try:
+ self._container.stop()
+ except Exception: # pylint: disable=broad-except
+ pass
+ try:
+ self._container.remove()
+ except Exception: # pylint: disable=broad-except
+ pass
logger.info("Container %s stopped and removed.", self._container.id)
# self._container = None
+ def _exec_run_with_stdin(
+ self,
+ cmd: list[str],
+ environment: dict[str, str],
+ stdin: str,
+ ) -> CommandExecResult:
+ """Execute command with attached stdin, similar to docker exec attach."""
+ resp = self.container.client.api.exec_create(
+ self.container.container.id,
+ cmd=cmd[:],
+ stdout=True,
+ stderr=True,
+ stdin=True,
+ tty=False,
+ environment=environment,
+ )
+ exec_id = resp["Id"]
+ sock = self.container.client.api.exec_start(
+ exec_id,
+ detach=False,
+ tty=False,
+ stream=False,
+ socket=True,
+ demux=False,
+ )
+ try:
+ data = (stdin or "").encode("utf-8")
+ if data:
+ try:
+ sock.sendall(data)
+ except Exception: # pylint: disable=broad-except
+ # Some transports expose the real socket as _sock.
+ sock._sock.sendall(data) # pylint: disable=protected-access
+
+ try:
+ sock.shutdown(pysocket.SHUT_WR)
+ except Exception: # pylint: disable=broad-except
+ close_write = getattr(sock, "close_write", None)
+ if callable(close_write):
+ close_write()
+
+ frames = frames_iter(sock, tty=False)
+ demux_frames = (demux_adaptor(*frame) for frame in frames)
+ output = consume_socket_output(demux_frames, demux=True)
+ stdout = output[0].decode("utf-8") if output and output[0] else ""
+ stderr = output[1].decode("utf-8") if output and output[1] else ""
+ finally:
+ try:
+ sock.close()
+ except Exception: # pylint: disable=broad-except
+ pass
+
+ inspect = self.container.client.api.exec_inspect(exec_id)
+ exit_code = int(inspect.get("ExitCode", -1))
+ return CommandExecResult(stdout=stdout, stderr=stderr, exit_code=exit_code, is_timeout=False)
+
async def exec_run(self, cmd: list[str], command_args: CommandArgs) -> CommandExecResult:
"""Execute command in container."""
timeout = command_args.timeout
try:
loop = asyncio.get_event_loop()
- co = loop.run_in_executor(
- None,
- lambda: self.container.exec_run(cmd=cmd[:], demux=True, environment=command_args.environment or {}))
+ if command_args.stdin:
+ co = loop.run_in_executor(
+ None,
+ lambda: self._exec_run_with_stdin(
+ cmd,
+ command_args.environment or {},
+ command_args.stdin or "",
+ ),
+ )
+ else:
+ co = loop.run_in_executor(
+ None,
+ lambda: self.container.exec_run(cmd=cmd[:], demux=True, environment=command_args.environment or {}))
if command_args.timeout:
- exit_code, output = await asyncio.wait_for(co, timeout=command_args.timeout)
+ result = await asyncio.wait_for(co, timeout=command_args.timeout)
else:
- exit_code, output = await co
+ result = await co
+
+ if command_args.stdin:
+ return result
+
+ exit_code, output = result
stdout = output[0].decode('utf-8') if output[0] else ""
stderr = output[1].decode('utf-8') if output[1] else ""
except asyncio.TimeoutError:
diff --git a/trpc_agent_sdk/code_executors/container/_container_code_executor.py b/trpc_agent_sdk/code_executors/container/_container_code_executor.py
index 13ba145..56eec06 100644
--- a/trpc_agent_sdk/code_executors/container/_container_code_executor.py
+++ b/trpc_agent_sdk/code_executors/container/_container_code_executor.py
@@ -15,7 +15,6 @@
from typing_extensions import override
from pydantic import Field
-
from trpc_agent_sdk.context import InvocationContext
from .._base_code_executor import BaseCodeExecutor
diff --git a/trpc_agent_sdk/code_executors/container/_container_ws_runtime.py b/trpc_agent_sdk/code_executors/container/_container_ws_runtime.py
index 7bf5b34..ce9fb0f 100644
--- a/trpc_agent_sdk/code_executors/container/_container_ws_runtime.py
+++ b/trpc_agent_sdk/code_executors/container/_container_ws_runtime.py
@@ -15,12 +15,15 @@
"""
import io
+import json
import os
import tarfile
import time
from dataclasses import dataclass
from dataclasses import field
+from datetime import datetime
from pathlib import Path
+from typing import Any
from typing import Dict
from typing import List
from typing import Optional
@@ -37,9 +40,13 @@
from .._base_workspace_runtime import BaseWorkspaceFS
from .._base_workspace_runtime import BaseWorkspaceManager
from .._base_workspace_runtime import BaseWorkspaceRuntime
+from .._base_workspace_runtime import RunEnvProvider
from .._constants import DEFAULT_INPUTS_CONTAINER
+from .._constants import DEFAULT_MAX_FILES
+from .._constants import DEFAULT_MAX_TOTAL_BYTES
from .._constants import DEFAULT_RUN_CONTAINER_BASE
from .._constants import DEFAULT_SKILLS_CONTAINER
+from .._constants import DEFAULT_TIMEOUT_SEC
from .._constants import DIR_OUT
from .._constants import DIR_RUNS
from .._constants import DIR_SKILLS
@@ -62,7 +69,10 @@
from .._types import WorkspaceRunProgramSpec
from .._types import WorkspaceRunResult
from .._types import WorkspaceStageOptions
+from ..utils import InputRecordMeta
+from ..utils import WorkspaceMetadata
from ..utils import get_rel_path
+from ..utils import normalize_globs
from ._container_cli import CommandArgs
from ._container_cli import ContainerClient
from ._container_cli import ContainerConfig
@@ -78,10 +88,16 @@ class RuntimeConfig:
run_container_base: str = DEFAULT_RUN_CONTAINER_BASE
inputs_host_base: str = ""
inputs_container_base: str = DEFAULT_INPUTS_CONTAINER
- auto_map_inputs: bool = False
+ auto_map_inputs: bool = True
command_args: CommandArgs = field(default_factory=CommandArgs)
+def _shell_quote(s: str) -> str:
+ if not s:
+ return "''"
+ return "'" + s.replace("'", "'\\''") + "'"
+
+
class ContainerWorkspaceManager(BaseWorkspaceManager):
"""
Docker container-based workspace manager implementation.
@@ -124,12 +140,15 @@ async def create_workspace(self, exec_id: str, ctx: Optional[InvocationContext]
ws_path = str(Path(self.config.run_container_base) / f"ws_{safe_id}_{suffix}")
# Create standard directory layout
- cmd_parts = [
- f"mkdir -p '{ws_path}'", f"'{ws_path}/{DIR_SKILLS}'", f"'{ws_path}/{DIR_WORK}'", f"'{ws_path}/{DIR_RUNS}'",
- f"'{ws_path}/{DIR_OUT}'",
- f"&& [ -f '{ws_path}/{META_FILE_NAME}' ] || echo '{{}}' > '{ws_path}/{META_FILE_NAME}'"
- ]
- cmd = ["/bin/bash", "-lc", " ".join(cmd_parts)]
+ cmd_str = ("set -e; "
+ f"mkdir -p {_shell_quote(ws_path)} "
+ f"{_shell_quote(str(Path(ws_path) / DIR_SKILLS))} "
+ f"{_shell_quote(str(Path(ws_path) / DIR_WORK))} "
+ f"{_shell_quote(str(Path(ws_path) / DIR_RUNS))} "
+ f"{_shell_quote(str(Path(ws_path) / DIR_OUT))}; "
+ f"[ -f {_shell_quote(str(Path(ws_path) / META_FILE_NAME))} ] || "
+ f"echo '{{}}' > {_shell_quote(str(Path(ws_path) / META_FILE_NAME))}")
+ cmd = ["/bin/bash", "-lc", cmd_str]
result = await self.container.exec_run(cmd=cmd, command_args=self.config.command_args)
if result.exit_code != 0:
@@ -268,8 +287,8 @@ async def stage_directory(self,
cmd = ["/bin/bash", "-lc", cmd_str]
result = await self.container.exec_run(cmd=cmd, command_args=self.config.command_args)
if result.exit_code != 0:
- logger.debug("Failed to stage directory: %s", result.stderr)
- logger.debug("Staged directory using mount: %s -> %s", container_src, container_dst)
+ raise RuntimeError(f"Failed to stage directory: {result.stderr}")
+ return
# Fallback: tar copy
await self._put_directory(ws, src_abs_path, dst)
@@ -327,8 +346,15 @@ async def collect(self,
continue
seen.add(rel_path)
- data, mime = self._copy_file_out(line)
- files.append(CodeFile(name=rel_path, content=data.decode('utf-8', errors='replace'), mime_type=mime))
+ data, size_bytes, mime = self._copy_file_out(line)
+ files.append(
+ CodeFile(
+ name=rel_path,
+ content=data.decode('utf-8', errors='replace'),
+ mime_type=mime,
+ size_bytes=size_bytes,
+ truncated=size_bytes > len(data),
+ ))
logger.info("Collected %s files from workspace", len(files))
return files
@@ -349,32 +375,56 @@ async def stage_inputs(self,
Raises:
RuntimeError: If staging fails
"""
+ md = await self._load_workspace_metadata(ws)
for spec in specs:
- mode = spec.mode.lower().strip() or "copy"
- dst = spec.dst.strip() or str(Path(DIR_WORK) / "inputs" / self._input_base(spec.src))
- dst = os.path.join(ws.path, dst)
+ mode = (spec.mode or "").lower().strip() or "copy"
+ dst_rel = (spec.dst or "").strip() or str(Path(DIR_WORK) / "inputs" / self._input_base(spec.src))
+ dst_abs = str(Path(ws.path) / dst_rel)
+
+ resolved = ""
+ version: Optional[int] = None
if spec.src.startswith("artifact://"):
- name = spec.src.removeprefix("artifact://")
- resolved, ver = parse_artifact_ref(name)
if not ctx:
raise ValueError("Context is required to load artifacts")
- content, ver = await load_artifact_helper(ctx, resolved, ver)
- await self._put_bytes_tar(content, dst)
+ name = spec.src.removeprefix("artifact://")
+ artifact_name, requested_ver = parse_artifact_ref(name)
+ use_ver = requested_ver
+ if use_ver is None and spec.pin:
+ use_ver = self._pinned_artifact_version(md, artifact_name, dst_rel)
+ content, actual_ver = await load_artifact_helper(ctx, artifact_name, use_ver)
+ await self._put_bytes_tar(content, dst_abs)
+ resolved = artifact_name
+ version = use_ver if use_ver is not None else actual_ver
elif spec.src.startswith("host://"):
host_path = spec.src.removeprefix("host://")
- await self._stage_host_input(ws, host_path, dst, mode)
+ await self._stage_host_input(ws, host_path, dst_abs, mode, dst_rel)
+ resolved = host_path
elif spec.src.startswith("workspace://"):
rel = spec.src.removeprefix("workspace://")
src = str(Path(ws.path) / rel)
- await self._stage_workspace_input(src, dst, mode)
+ await self._stage_workspace_input(src, dst_abs, mode)
+ resolved = rel
elif spec.src.startswith("skill://"):
rest = spec.src.removeprefix("skill://")
src = str(Path(ws.path) / DIR_SKILLS / rest)
- await self._stage_workspace_input(src, dst, mode)
+ await self._stage_workspace_input(src, dst_abs, mode)
+ resolved = src
else:
raise RuntimeError(f"Unsupported input: {spec.src}")
+ md.inputs.append(
+ InputRecordMeta(
+ src=spec.src,
+ dst=dst_rel,
+ resolved=resolved,
+ version=version,
+ mode=mode,
+ timestamp=datetime.now(),
+ ))
+
+ await self._save_workspace_metadata(ws, md)
+
logger.info("Staged %s inputs into workspace", len(specs))
@override
@@ -409,13 +459,15 @@ async def collect_outputs(self,
raise RuntimeError(f"Failed to collect outputs: {result.stderr}")
stdout = result.stdout
- max_files = spec.max_files or 100
+ max_files = spec.max_files or DEFAULT_MAX_FILES
max_file_bytes = spec.max_file_bytes or MAX_READ_SIZE_BYTES
- max_total = spec.max_total_bytes or 64 * 1024 * 1024
+ max_total = spec.max_total_bytes or DEFAULT_MAX_TOTAL_BYTES
manifest = ManifestOutput()
total_bytes = 0
count = 0
+ saved_names: list[str] = []
+ saved_versions: list[int] = []
for line in stdout.strip().split('\n'):
line = line.strip()
if not line:
@@ -425,14 +477,25 @@ async def collect_outputs(self,
manifest.limits_hit = True
break
- data, mime = self._copy_file_out(line)
+ data, raw_size, mime = self._copy_file_out(line)
if len(data) > max_file_bytes:
data = data[:max_file_bytes]
manifest.limits_hit = True
+ if total_bytes + len(data) > max_total:
+ remain = max_total - total_bytes
+ if remain <= 0:
+ manifest.limits_hit = True
+ break
+ data = data[:remain]
+ manifest.limits_hit = True
+
total_bytes += len(data)
rel_path = line.removeprefix(f"{ws.path}/")
+ truncated = raw_size > len(data)
+ if truncated and spec.save:
+ raise RuntimeError(f"cannot save truncated output file: {rel_path}")
file_ref = ManifestFileRef(name=rel_path, mime_type=mime)
if spec.inline:
@@ -446,6 +509,8 @@ async def collect_outputs(self,
version = await save_artifact_helper(ctx, save_name, data, mime)
file_ref.saved_as = save_name
file_ref.version = version
+ saved_names.append(save_name)
+ saved_versions.append(version)
manifest.files.append(file_ref)
count += 1
@@ -455,6 +520,8 @@ async def collect_outputs(self,
async def _put_directory(self, ws: WorkspaceInfo, src: str, dst: str) -> None:
"""Copy directory to container using tar."""
+ if not src or not str(src).strip():
+ raise ValueError("source path is empty")
abs_src = os.path.abspath(src)
container_dst = str(Path(ws.path) / dst) if dst else ws.path
if self.config.skills_host_base:
@@ -464,8 +531,9 @@ async def _put_directory(self, ws: WorkspaceInfo, src: str, dst: str) -> None:
# Create destination directory
cmd = ["/bin/bash", "-lc", f"mkdir -p '{container_dst}' && cp -a '{container_src}/.' '{container_dst}'"]
result = await self.container.exec_run(cmd=cmd, command_args=self.config.command_args)
- if result.exit_code:
- logger.debug("Failed to stage directory: %s", result.stderr)
+ if result.exit_code == 0:
+ return None
+ logger.debug("Failed to stage directory via mount copy, fallback to tar: %s", result.stderr)
cmd = ["/bin/bash", "-lc", f"[ -e '{container_dst}' ] || mkdir -p '{container_dst}'"]
result = await self.container.exec_run(cmd=cmd, command_args=self.config.command_args)
@@ -507,7 +575,7 @@ async def _put_bytes_tar(self, data: bytes, dest: str, mode: int = 0o644) -> Non
if not success:
raise RuntimeError(f"Failed to copy bytes to {dest}")
- async def _stage_host_input(self, ws: WorkspaceInfo, host: str, dst: str, mode: str) -> None:
+ async def _stage_host_input(self, ws: WorkspaceInfo, host: str, dst: str, mode: str, dst_rel: str) -> None:
"""Stage input from host path."""
if self.config.inputs_host_base:
rel_path = get_rel_path(self.config.inputs_host_base, host)
@@ -525,11 +593,11 @@ async def _stage_host_input(self, ws: WorkspaceInfo, host: str, dst: str, mode:
cmd = ["/bin/bash", "-lc", cmd_str]
result = await self.container.exec_run(cmd=cmd, command_args=self.config.command_args)
- if result.exit_code:
- logger.debug("Failed to stage input: %s", result.stderr)
+ if result.exit_code != 0:
+ raise RuntimeError(f"Failed to stage host input: {result.stderr}")
return
# Fallback to tar copy
- await self._put_directory(ws, host, str(Path(dst).parent))
+ await self._put_directory(ws, host, str(Path(dst_rel).parent))
async def _stage_workspace_input(self, src: str, dst: str, mode: str) -> None:
"""Stage input from workspace path."""
@@ -547,7 +615,7 @@ async def _stage_workspace_input(self, src: str, dst: str, mode: str) -> None:
if result.exit_code:
raise RuntimeError(f"Failed to stage input: {result.stderr}")
- def _copy_file_out(self, full_path: str) -> Tuple[bytes, str]:
+ def _copy_file_out(self, full_path: str) -> Tuple[bytes, int, str]:
"""
Copy file out of container.
@@ -555,7 +623,7 @@ def _copy_file_out(self, full_path: str) -> Tuple[bytes, str]:
full_path: Full path to file in container
Returns:
- Tuple of (file_data, mime_type)
+ Tuple of (file_data, size_bytes, mime_type)
Raises:
RuntimeError: If copy fails
@@ -570,7 +638,7 @@ def _copy_file_out(self, full_path: str) -> Tuple[bytes, str]:
f = tar.extractfile(member)
data = f.read(MAX_READ_SIZE_BYTES)
mime = self._detect_mime_type(data)
- return data, mime
+ return data, member.size, mime
raise RuntimeError(f"No file found in archive: {full_path}")
@@ -597,24 +665,75 @@ def _create_tar_from_files(files: List[WorkspacePutFileInfo]) -> io.BytesIO:
@staticmethod
def _normalize_globs(patterns: List[str]) -> List[str]:
"""Normalize glob patterns."""
- normalized = []
- for p in patterns:
- p = p.strip()
- if p:
- # Simple normalization - replace environment variables
- p = p.replace("$OUTPUT_DIR", DIR_OUT)
- p = p.replace("${OUTPUT_DIR}", DIR_OUT)
- p = p.replace("$WORK_DIR", DIR_WORK)
- p = p.replace("${WORK_DIR}", DIR_WORK)
- p = p.replace("$WORKSPACE_DIR", ".")
- p = p.replace("${WORKSPACE_DIR}", ".")
- normalized.append(p)
- return normalized
+ return normalize_globs(patterns)
@staticmethod
- def _input_base(path: str) -> str:
+ def _input_base(src: str) -> str:
"""Extract base name from input path."""
- return Path(path).name
+ s = (src or "").strip()
+ if s.startswith("artifact://"):
+ ref = s.removeprefix("artifact://")
+ try:
+ name, _ = parse_artifact_ref(ref)
+ base = Path(name.strip()).name
+ if base and base not in (".", "..", "/"):
+ return base
+ except Exception: # pylint: disable=broad-except
+ pass
+ return Path(s).name
+
+ @staticmethod
+ def _pinned_artifact_version(md: Any, artifact_name: str, dst: str) -> Optional[int]:
+ for record in reversed(md.inputs or []):
+ if (record.dst or "") != dst:
+ continue
+ if record.version is None:
+ continue
+ if (record.resolved or "") == artifact_name:
+ return record.version
+ src = record.src or ""
+ if not src.startswith("artifact://"):
+ continue
+ try:
+ name, _ = parse_artifact_ref(src.removeprefix("artifact://"))
+ except Exception: # pylint: disable=broad-except
+ continue
+ if name == artifact_name:
+ return record.version
+ return None
+
+ async def _load_workspace_metadata(self, ws: WorkspaceInfo):
+ now = datetime.now()
+ cmd = ["/bin/bash", "-lc", f"cat {_shell_quote(str(Path(ws.path) / META_FILE_NAME))}"]
+ result = await self.container.exec_run(cmd=cmd, command_args=self.config.command_args)
+ if result.exit_code != 0 or not result.stdout.strip():
+ return WorkspaceMetadata(version=1, created_at=now, updated_at=now, last_access=now, skills={})
+ try:
+ data = json.loads(result.stdout)
+ md = WorkspaceMetadata(**data)
+ except Exception as ex: # pylint: disable=broad-except
+ raise RuntimeError(f"Failed to parse workspace metadata: {ex}") from ex
+ if not md.version:
+ md.version = 1
+ if md.created_at is None:
+ md.created_at = now
+ md.last_access = now
+ if md.skills is None:
+ md.skills = {}
+ return md
+
+ async def _save_workspace_metadata(self, ws: WorkspaceInfo, md: Any) -> None:
+ now = datetime.now()
+ if not md.version:
+ md.version = 1
+ if md.created_at is None:
+ md.created_at = now
+ md.updated_at = now
+ md.last_access = now
+ if md.skills is None:
+ md.skills = {}
+ payload = json.dumps(md.model_dump(exclude_none=True, by_alias=True, mode="json"), ensure_ascii=False, indent=2)
+ await self._put_bytes_tar(payload.encode("utf-8"), str(Path(ws.path) / META_FILE_NAME), mode=0o600)
@staticmethod
def _detect_mime_type(data: bytes) -> str:
@@ -637,7 +756,13 @@ class ContainerProgramRunner(BaseProgramRunner):
Docker container-based program runner implementation.
"""
- def __init__(self, container: ContainerClient, config: RuntimeConfig):
+ def __init__(
+ self,
+ container: ContainerClient,
+ config: RuntimeConfig,
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False,
+ ):
"""
Initialize container program runner.
@@ -646,6 +771,7 @@ def __init__(self, container: ContainerClient, config: RuntimeConfig):
container: Docker container to use
config: Runtime configuration
"""
+ super().__init__(provider=provider, enable_provider_env=enable_provider_env)
self.container = container
self.config = config
@@ -667,6 +793,7 @@ async def run_program(self,
Raises:
RuntimeError: If execution fails
"""
+ spec = self._apply_provider_env(spec, ctx)
cwd = f"{ws.path}/{spec.cwd}" if spec.cwd else ws.path
# Prepare directories
@@ -685,35 +812,41 @@ async def run_program(self,
}
env_parts = []
+ user_env = dict(spec.env or {})
for k, v in base_env.items():
- if k not in spec.env:
- env_parts.append(f"{k}={self._shell_quote(v)}")
+ if k not in user_env:
+ env_parts.append(f"{k}={_shell_quote(v)}")
- for k, v in spec.env.items():
- env_parts.append(f"{k}={self._shell_quote(v)}")
+ for k, v in user_env.items():
+ env_parts.append(f"{k}={_shell_quote(v)}")
env_str = " ".join(env_parts)
# Build command line
cmd_parts = [
- f"mkdir -p {self._shell_quote(run_dir)} {self._shell_quote(out_dir)}", f"&& cd {self._shell_quote(cwd)}",
+ f"mkdir -p {_shell_quote(run_dir)} {_shell_quote(out_dir)}", f"&& cd {_shell_quote(cwd)}",
"&& env" if env_str else "", env_str,
- self._shell_quote(spec.cmd)
+ _shell_quote(spec.cmd)
]
for arg in spec.args:
- cmd_parts.append(self._shell_quote(arg))
+ cmd_parts.append(_shell_quote(arg))
cmd_str = " ".join(filter(None, cmd_parts))
cmd = ["/bin/bash", "-lc", cmd_str]
start_time = time.time()
- timeout = spec.timeout or self.config.command_args.timeout
- if timeout is None:
+ if spec.timeout and spec.timeout > 0:
timeout = spec.timeout
+ elif self.config.command_args.timeout and self.config.command_args.timeout > 0:
+ timeout = self.config.command_args.timeout
else:
- timeout = min(timeout, spec.timeout)
- command_args = CommandArgs(environment=None, timeout=timeout)
+ timeout = float(DEFAULT_TIMEOUT_SEC)
+ command_args = CommandArgs(
+ environment=None,
+ timeout=timeout,
+ stdin=spec.stdin or None,
+ )
result = await self.container.exec_run(cmd=cmd, command_args=command_args)
return WorkspaceRunResult(stdout=result.stdout,
stderr=result.stderr,
@@ -721,28 +854,20 @@ async def run_program(self,
duration=time.time() - start_time,
timed_out=result.is_timeout)
- @staticmethod
- def _shell_quote(s: str) -> str:
- """
- Quote string for safe shell usage.
-
- Args:
- s: String to quote
-
- Returns:
- Quoted string
- """
- if not s:
- return "''"
- return "'" + s.replace("'", "'\\''") + "'"
-
class ContainerWorkspaceRuntime(BaseWorkspaceRuntime):
"""
Docker container-based execution engine.
"""
- def __init__(self, container: ContainerClient, host_config: Optional[Dict] = None, auto_inputs: bool = False):
+ def __init__(
+ self,
+ container: ContainerClient,
+ host_config: Optional[Dict] = None,
+ auto_inputs: bool = True,
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False,
+ ):
"""
Initialize container engine.
@@ -763,7 +888,12 @@ def __init__(self, container: ContainerClient, host_config: Optional[Dict] = Non
self._fs = ContainerWorkspaceFS(self.container, config)
self._manager = ContainerWorkspaceManager(self.container, config, self._fs)
- self._runner = ContainerProgramRunner(self.container, config)
+ self._runner = ContainerProgramRunner(
+ self.container,
+ config,
+ provider=provider,
+ enable_provider_env=enable_provider_env,
+ )
@override
def manager(self, ctx: Optional[InvocationContext] = None) -> ContainerWorkspaceManager:
@@ -797,8 +927,8 @@ def _find_bind_source(binds: List[str], dest: str) -> str:
if len(parts) < 2:
continue
- # Handle format: source:dest[:mode]
- bind_dest = parts[-2] if len(parts) >= 2 else ""
+ # Handle format: source:dest[:mode], parse from right.
+ bind_dest = parts[-2]
if bind_dest == dest:
source = ':'.join(parts[:-2]) if len(parts) > 2 else parts[0]
if Path(source).is_dir():
@@ -820,7 +950,9 @@ def describe(self, ctx: Optional[InvocationContext] = None) -> WorkspaceCapabili
def create_container_workspace_runtime(
container_config: Optional[ContainerConfig] = None,
host_config: Optional[Dict] = None,
- auto_inputs: bool = False,
+ auto_inputs: bool = True,
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False,
) -> ContainerWorkspaceRuntime:
"""Create a new container workspace runtime.
Args:
@@ -838,4 +970,10 @@ def create_container_workspace_runtime(
container = ContainerClient(config=cfg)
else:
container = ContainerClient(config=ContainerConfig(host_config=host_config))
- return ContainerWorkspaceRuntime(container=container, host_config=host_config, auto_inputs=auto_inputs)
+ return ContainerWorkspaceRuntime(
+ container=container,
+ host_config=host_config,
+ auto_inputs=auto_inputs,
+ provider=provider,
+ enable_provider_env=enable_provider_env,
+ )
diff --git a/trpc_agent_sdk/code_executors/local/_local_program_session.py b/trpc_agent_sdk/code_executors/local/_local_program_session.py
new file mode 100644
index 0000000..fb1be8a
--- /dev/null
+++ b/trpc_agent_sdk/code_executors/local/_local_program_session.py
@@ -0,0 +1,299 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""WorkspaceInfo runtime for local code execution.
+
+This module provides the WorkspaceRuntime class which allows local code execution.
+It provides methods for staging directories and inputs into the workspace.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import time
+import uuid
+from typing import Optional
+from typing_extensions import override
+
+from .._program_session import BaseProgramSession
+from .._program_session import PROGRAM_STATUS_EXITED
+from .._program_session import PROGRAM_STATUS_RUNNING
+from .._program_session import ProgramLog
+from .._program_session import ProgramPoll
+from .._program_session import ProgramState
+from .._types import WorkspaceRunResult
+
+_DEFAULT_INTERACTIVE_MAX_LINES = 20_000
+if sys.platform != "win32":
+ import fcntl
+
+
+def _split_lines_with_partial(text: str) -> tuple[list[str], str]:
+ normalized = text.replace("\r\n", "\n")
+ parts = normalized.split("\n")
+ if len(parts) == 1:
+ return [], parts[0]
+ return parts[:-1], parts[-1]
+
+
+class LocalProgramSession(BaseProgramSession):
+ """Local interactive subprocess session."""
+
+ def __init__(
+ self,
+ process: asyncio.subprocess.Process,
+ *,
+ max_lines: int = _DEFAULT_INTERACTIVE_MAX_LINES,
+ master_fd: Optional[int] = None,
+ ) -> None:
+ self._id = uuid.uuid4().hex
+ self._process = process
+ self._max_lines = max_lines
+ self._master_fd = master_fd
+ self._lock = asyncio.Lock()
+ self._closed = False
+
+ self._started_at = time.time()
+ self._finished_at: Optional[float] = None
+ self._exit_code: Optional[int] = None
+ self._timed_out = False
+
+ self._line_base = 0
+ self._lines: list[str] = []
+ self._partial = ""
+ self._poll_cursor = 0
+
+ self._stdout = ""
+ self._stderr = ""
+ if self._master_fd is not None:
+ self._stdout_task = asyncio.create_task(self._read_pty(self._master_fd))
+ self._stderr_task = asyncio.create_task(asyncio.sleep(0))
+ else:
+ self._stdout_task = asyncio.create_task(self._read_stream(self._process.stdout, stream_name="stdout"))
+ self._stderr_task = asyncio.create_task(self._read_stream(self._process.stderr, stream_name="stderr"))
+ self._wait_task = asyncio.create_task(self._watch_process_exit())
+
+ @override
+ def id(self) -> str:
+ return self._id
+
+ async def _read_stream(self, reader: Optional[asyncio.StreamReader], *, stream_name: str) -> None:
+ if reader is None:
+ return
+ while True:
+ chunk = await reader.read(4096)
+ if not chunk:
+ return
+ await self._append_output(chunk.decode("utf-8", errors="replace"), stream=stream_name)
+
+ async def _read_pty(self, master_fd: int) -> None:
+ loop = asyncio.get_running_loop()
+ flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)
+ fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+
+ read_event = asyncio.Event()
+
+ def _on_readable() -> None:
+ read_event.set()
+
+ loop.add_reader(master_fd, _on_readable)
+ try:
+ while True:
+ read_event.clear()
+ if self._process.returncode is not None:
+ while True:
+ try:
+ data = os.read(master_fd, 4096)
+ if not data:
+ break
+ await self._append_output(data.decode("utf-8", errors="replace"), stream="stdout")
+ except BlockingIOError:
+ break
+ except OSError:
+ break
+ return
+
+ try:
+ await asyncio.wait_for(read_event.wait(), timeout=0.05)
+ except asyncio.TimeoutError:
+ pass
+ try:
+ data = os.read(master_fd, 4096)
+ if data:
+ await self._append_output(data.decode("utf-8", errors="replace"), stream="stdout")
+ except BlockingIOError:
+ pass
+ except OSError:
+ return
+ finally:
+ loop.remove_reader(master_fd)
+
+ async def _append_output(self, chunk: str, *, stream: str) -> None:
+ normalized = chunk.replace("\r\n", "\n")
+ async with self._lock:
+ if stream == "stderr":
+ self._stderr += normalized
+ else:
+ self._stdout += normalized
+
+ merged = self._partial + normalized
+ lines, self._partial = _split_lines_with_partial(merged)
+ self._lines.extend(lines)
+ self._trim_lines_locked()
+
+ async def _watch_process_exit(self) -> None:
+ code = await self._process.wait()
+ await asyncio.gather(self._stdout_task, self._stderr_task, return_exceptions=True)
+ async with self._lock:
+ if self._finished_at is not None:
+ return
+ if self._partial:
+ self._lines.append(self._partial)
+ self._partial = ""
+ self._trim_lines_locked()
+ self._exit_code = code
+ self._finished_at = time.time()
+
+ def _trim_lines_locked(self) -> None:
+ if self._max_lines <= 0:
+ return
+ if len(self._lines) <= self._max_lines:
+ return
+ drop = len(self._lines) - self._max_lines
+ self._lines = self._lines[drop:]
+ self._line_base += drop
+ if self._poll_cursor < self._line_base:
+ self._poll_cursor = self._line_base
+
+ @override
+ async def poll(self, limit: Optional[int] = None) -> ProgramPoll:
+ async with self._lock:
+ start = self._poll_cursor
+ if start < self._line_base:
+ start = self._line_base
+ self._poll_cursor = start
+ end = self._line_base + len(self._lines)
+ if limit is not None and limit > 0:
+ end = min(end, start + limit)
+
+ out = ""
+ if end > start:
+ out = "\n".join(self._lines[start - self._line_base:end - self._line_base])
+ if end == self._line_base + len(self._lines) and self._partial:
+ out = f"{out}\n{self._partial}" if out else self._partial
+
+ self._poll_cursor = end
+ status = PROGRAM_STATUS_RUNNING if self._finished_at is None else PROGRAM_STATUS_EXITED
+ return ProgramPoll(
+ status=status,
+ output=out,
+ offset=start,
+ next_offset=end,
+ exit_code=self._exit_code,
+ )
+
+ @override
+ async def log(self, offset: Optional[int] = None, limit: Optional[int] = None) -> ProgramLog:
+ async with self._lock:
+ start = self._line_base if offset is None else offset
+ end = self._line_base + len(self._lines)
+
+ if start < self._line_base:
+ start = self._line_base
+ if start > end:
+ start = end
+ if limit is not None and limit > 0:
+ end = min(end, start + limit)
+
+ out = ""
+ if end > start:
+ out = "\n".join(self._lines[start - self._line_base:end - self._line_base])
+ if end == self._line_base + len(self._lines) and self._partial:
+ out = f"{out}\n{self._partial}" if out else self._partial
+ return ProgramLog(output=out, offset=start, next_offset=end)
+
+ @override
+ async def write(self, data: str, newline: bool) -> None:
+ if not data and not newline:
+ return
+ if self._process.returncode is not None:
+ raise ValueError("session is not running")
+ text = data
+ if newline:
+ text += "\n"
+ if self._master_fd is not None:
+ try:
+ os.write(self._master_fd, text.encode("utf-8"))
+ return
+ except OSError as ex:
+ raise ValueError("stdin is not available") from ex
+ stdin = self._process.stdin
+ if stdin is None:
+ raise ValueError("stdin is not available")
+ stdin.write(text.encode("utf-8"))
+ await stdin.drain()
+
+ @override
+ async def kill(self, grace_seconds: float) -> None:
+ if self._process.returncode is not None:
+ return
+ self._process.terminate()
+ try:
+ await asyncio.wait_for(self._process.wait(), timeout=max(0.0, grace_seconds))
+ return
+ except asyncio.TimeoutError:
+ pass
+ if self._process.returncode is None:
+ self._process.kill()
+ await self._process.wait()
+
+ @override
+ async def close(self) -> None:
+ async with self._lock:
+ if self._closed:
+ return
+ self._closed = True
+ if self._process.returncode is None:
+ await self.kill(0.5)
+ if self._process.stdin is not None:
+ try:
+ self._process.stdin.close()
+ except Exception: # pylint: disable=broad-except
+ pass
+ await asyncio.gather(self._stdout_task, self._stderr_task, self._wait_task, return_exceptions=True)
+ if self._master_fd is not None:
+ try:
+ os.close(self._master_fd)
+ except OSError:
+ pass
+
+ async def enforce_timeout(self, timeout_sec: float) -> None:
+ if timeout_sec <= 0:
+ return
+ await asyncio.sleep(timeout_sec)
+ if self._process.returncode is None:
+ self._timed_out = True
+ await self.kill(0.5)
+
+ @override
+ async def state(self) -> ProgramState:
+ if self._finished_at is None:
+ return ProgramState(status=PROGRAM_STATUS_RUNNING)
+ return ProgramState(status=PROGRAM_STATUS_EXITED, exit_code=self._exit_code)
+
+ @override
+ async def run_result(self) -> WorkspaceRunResult:
+ duration = 0.0
+ if self._finished_at is not None:
+ duration = self._finished_at - self._started_at
+ return WorkspaceRunResult(
+ stdout=self._stdout,
+ stderr=self._stderr,
+ exit_code=self._exit_code or 0,
+ duration=duration,
+ timed_out=self._timed_out,
+ )
diff --git a/trpc_agent_sdk/code_executors/local/_local_ws_runtime.py b/trpc_agent_sdk/code_executors/local/_local_ws_runtime.py
index 87151c6..1b245ee 100644
--- a/trpc_agent_sdk/code_executors/local/_local_ws_runtime.py
+++ b/trpc_agent_sdk/code_executors/local/_local_ws_runtime.py
@@ -11,11 +11,14 @@
from __future__ import annotations
+import asyncio
import os
import re
import shutil
+import sys
import tempfile
import time
+import uuid
from datetime import datetime
from pathlib import Path
from typing import List
@@ -32,6 +35,7 @@
from .._base_workspace_runtime import BaseWorkspaceFS
from .._base_workspace_runtime import BaseWorkspaceManager
from .._base_workspace_runtime import BaseWorkspaceRuntime
+from .._base_workspace_runtime import RunEnvProvider
from .._constants import DEFAULT_FILE_MODE
from .._constants import DEFAULT_MAX_FILES
from .._constants import DEFAULT_MAX_TOTAL_BYTES
@@ -46,6 +50,7 @@
from .._constants import ENV_WORK_DIR
from .._constants import MAX_READ_SIZE_BYTES
from .._constants import WORKSPACE_ENV_DIR_KEY
+from .._program_session import BaseProgramSession
from .._types import CodeFile
from .._types import ManifestFileRef
from .._types import ManifestOutput
@@ -69,6 +74,11 @@
from ..utils import path_join
from ..utils import save_metadata
+if sys.platform != "win32":
+ import pty
+
+from ._local_program_session import LocalProgramSession
+
class LocalWorkspaceManager(BaseWorkspaceManager):
"""Local workspace manager for executing commands in skill workspaces."""
@@ -380,7 +390,10 @@ async def stage_inputs(
if mode == "link":
make_symlink(ws.path, dst.as_posix(), host_path)
else:
- self._put_directory(ws, host_path, dst.parent.as_posix())
+ # Preserve caller-provided destination path exactly.
+ # For files, copy to the exact dst filename.
+ # For directories, copy tree into dst directory.
+ copy_path(host_path, path_join(ws.path, dst.as_posix()))
elif spec.src.startswith("workspace://"):
# Handle workspace inputs
rel = spec.src[len("workspace://"):]
@@ -574,6 +587,35 @@ def _read_limited_with_cap(
class LocalProgramRunner(BaseProgramRunner):
"""Local program runner for executing commands in skill workspaces."""
+ def __init__(
+ self,
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False,
+ ):
+ super().__init__(provider=provider, enable_provider_env=enable_provider_env)
+
+ def _build_program_env(self, ws: WorkspaceInfo, spec: WorkspaceRunProgramSpec) -> dict[str, str]:
+ env = os.environ.copy()
+ user_env = dict(spec.env or {})
+ wr_path = Path(ws.path)
+ ensure_layout(wr_path)
+ run_dir = wr_path / DIR_RUNS / f"run_{datetime.now().strftime('%Y%m%dT%H%M%S.%f')}"
+ run_dir.mkdir(parents=True, exist_ok=True)
+
+ base_env = {
+ WORKSPACE_ENV_DIR_KEY: ws.path,
+ ENV_SKILLS_DIR: str(Path(ws.path) / DIR_SKILLS),
+ ENV_WORK_DIR: str(Path(ws.path) / DIR_WORK),
+ ENV_OUTPUT_DIR: str(Path(ws.path) / DIR_OUT),
+ ENV_RUN_DIR: str(run_dir),
+ }
+ for key, value in base_env.items():
+ if key not in user_env:
+ env[key] = value
+ if user_env:
+ env.update(user_env)
+ return env
+
@override
async def run_program(self,
ws: WorkspaceInfo,
@@ -591,37 +633,13 @@ async def run_program(self,
Returns:
Execution result
"""
+ spec = self._apply_provider_env(spec, ctx)
# Resolve cwd under workspace
cwd = Path(path_join(ws.path, spec.cwd))
cwd.mkdir(parents=True, exist_ok=True)
timeout = spec.timeout or float(DEFAULT_TIMEOUT_SEC)
-
- # Build environment
- env = os.environ.copy()
-
- wr_path = Path(ws.path)
- # Ensure layout exists and compute run dir
- ensure_layout(wr_path)
- run_dir = wr_path / DIR_RUNS / f"run_{datetime.now().strftime('%Y%m%dT%H%M%S.%f')}"
- run_dir.mkdir(parents=True, exist_ok=True)
-
- # Inject well-known variables if not set
- base_env = {
- WORKSPACE_ENV_DIR_KEY: ws.path,
- ENV_SKILLS_DIR: str(Path(ws.path) / DIR_SKILLS),
- ENV_WORK_DIR: str(Path(ws.path) / DIR_WORK),
- ENV_OUTPUT_DIR: str(Path(ws.path) / DIR_OUT),
- ENV_RUN_DIR: str(run_dir),
- }
-
- for key, value in base_env.items():
- if key not in spec.env:
- env[key] = value
-
- # Add user-provided environment variables
- if spec.env:
- env.update(spec.env)
+ env = self._build_program_env(ws, spec)
# Prepare command
cmd_args = [spec.cmd] + (spec.args or [])
@@ -639,6 +657,62 @@ async def run_program(self,
duration=time.time() - start_time,
timed_out=result.is_timeout)
+ async def start_program(
+ self,
+ ctx: Optional[InvocationContext],
+ ws: WorkspaceInfo,
+ spec: WorkspaceRunProgramSpec,
+ ) -> BaseProgramSession:
+ """Start an interactive program session in workspace."""
+ if spec.tty and sys.platform == "win32":
+ raise ValueError("interactive tty is not supported on windows")
+
+ spec = self._apply_provider_env(spec, ctx)
+ cwd = Path(path_join(ws.path, spec.cwd))
+ cwd.mkdir(parents=True, exist_ok=True)
+ env = self._build_program_env(ws, spec)
+ timeout = spec.timeout or float(DEFAULT_TIMEOUT_SEC)
+
+ cmd_args = [spec.cmd] + (spec.args or [])
+ if spec.tty:
+ master_fd, slave_fd = pty.openpty()
+ try:
+ process = await asyncio.create_subprocess_exec(
+ *cmd_args,
+ cwd=str(cwd),
+ env=env,
+ stdin=slave_fd,
+ stdout=slave_fd,
+ stderr=slave_fd,
+ close_fds=True,
+ preexec_fn=os.setsid,
+ )
+ except Exception:
+ os.close(master_fd)
+ os.close(slave_fd)
+ raise
+ finally:
+ try:
+ os.close(slave_fd)
+ except OSError:
+ pass
+ session = LocalProgramSession(process, master_fd=master_fd)
+ else:
+ process = await asyncio.create_subprocess_exec(
+ *cmd_args,
+ cwd=str(cwd),
+ env=env,
+ stdin=asyncio.subprocess.PIPE,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ )
+ session = LocalProgramSession(process)
+ if timeout > 0:
+ asyncio.create_task(session.enforce_timeout(float(timeout)))
+ if spec.stdin:
+ await session.write(spec.stdin, newline=False)
+ return session
+
class LocalWorkspaceRuntime(BaseWorkspaceRuntime):
"""Local workspace for executing commands in skill workspaces."""
@@ -647,9 +721,11 @@ def __init__(self,
work_root: str = '',
read_only_staged_skill: bool = False,
auto_inputs: bool = True,
- inputs_host_base: str = ""):
+ inputs_host_base: str = "",
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False):
self._fs = LocalWorkspaceFS(read_only_staged_skill)
- self._runner = LocalProgramRunner()
+ self._runner = LocalProgramRunner(provider=provider, enable_provider_env=enable_provider_env)
self._manager = LocalWorkspaceManager(work_root, auto_inputs, inputs_host_base, self._fs)
@override
@@ -681,6 +757,9 @@ def describe(self, ctx: Optional[InvocationContext] = None) -> WorkspaceCapabili
def create_local_workspace_runtime(work_root: str = '',
read_only_staged_skill: bool = False,
auto_inputs: bool = True,
- inputs_host_base: str = "") -> LocalWorkspaceRuntime:
+ inputs_host_base: str = "",
+ provider: Optional[RunEnvProvider] = None,
+ enable_provider_env: bool = False) -> LocalWorkspaceRuntime:
"""Create a new local workspace runtime."""
- return LocalWorkspaceRuntime(work_root, read_only_staged_skill, auto_inputs, inputs_host_base)
+ return LocalWorkspaceRuntime(work_root, read_only_staged_skill, auto_inputs, inputs_host_base, provider,
+ enable_provider_env)
diff --git a/trpc_agent_sdk/code_executors/local/_unsafe_local_code_executor.py b/trpc_agent_sdk/code_executors/local/_unsafe_local_code_executor.py
index 9593ca6..3b3aa19 100644
--- a/trpc_agent_sdk/code_executors/local/_unsafe_local_code_executor.py
+++ b/trpc_agent_sdk/code_executors/local/_unsafe_local_code_executor.py
@@ -17,7 +17,6 @@
from typing_extensions import override
from pydantic import Field
-
from trpc_agent_sdk.context import InvocationContext
from trpc_agent_sdk.utils import async_execute_command
@@ -44,7 +43,7 @@ class UnsafeLocalCodeExecutor(BaseCodeExecutor):
work_dir: str = Field(default="", description="The working directory for the code execution.")
- timeout: float = Field(default=0, description="The timeout for the code execution.")
+ timeout: float = Field(default=0, description="The timeout seconds for the code execution.")
clean_temp_files: bool = Field(default=True,
description="Whether to clean temporary files after the code execution.")
diff --git a/trpc_agent_sdk/code_executors/utils/_code_execution.py b/trpc_agent_sdk/code_executors/utils/_code_execution.py
index bae808a..8635015 100644
--- a/trpc_agent_sdk/code_executors/utils/_code_execution.py
+++ b/trpc_agent_sdk/code_executors/utils/_code_execution.py
@@ -24,6 +24,20 @@
class CodeExecutionUtils:
"""Utility functions for code execution."""
+ @classmethod
+ def _is_ignored_code_block(cls, code: str, ignore_codes: list[str]) -> bool:
+ """Return True when code block first line is in ignore list."""
+ if not code:
+ return False
+ lines = code.splitlines()
+ if not lines:
+ return False
+ first_line = lines[0].strip()
+ if not first_line:
+ return False
+ ignore_set = {item.strip() for item in ignore_codes if item and item.strip()}
+ return first_line in ignore_set
+
@classmethod
def prepare_globals(cls, code: str, globals_: dict[str, Any]) -> None:
"""Prepare globals for code execution, injecting __name__ if needed."""
@@ -61,6 +75,7 @@ def extract_code_and_truncate_content(
cls,
content: Content,
code_block_delimiters: list[CodeBlockDelimiter],
+ ignore_codes: list[str] = None,
) -> list[CodeBlock]:
"""Extracts all code blocks from the content and reconstructs content.parts.
@@ -71,10 +86,12 @@ def extract_code_and_truncate_content(
content: The mutable content to extract the code from.
code_block_delimiters: The list of the enclosing delimiters to identify
the code blocks.
+ ignore_codes: The list of codes to ignore.
Returns:
The first code block if found; otherwise, None.
"""
+ ignore_codes = ignore_codes or []
code_blocks = []
if not content or not content.parts:
return code_blocks
@@ -84,12 +101,13 @@ def extract_code_and_truncate_content(
total_len = len(content.parts)
for idx, part in enumerate(content.parts):
if part.executable_code:
+ code_str = part.executable_code.code or ""
+ if cls._is_ignored_code_block(code_str, ignore_codes):
+ continue
if idx < total_len - 1 and not content.parts[idx + 1].code_execution_result:
- code_blocks.append(CodeBlock(code=part.executable_code.code,
- language=part.executable_code.language))
+ code_blocks.append(CodeBlock(code=code_str, language=part.executable_code.language))
if idx == total_len - 1:
- code_blocks.append(CodeBlock(code=part.executable_code.code,
- language=part.executable_code.language))
+ code_blocks.append(CodeBlock(code=code_str, language=part.executable_code.language))
# If there are code blocks, return them.
if code_blocks:
return code_blocks
@@ -140,6 +158,9 @@ def extract_code_and_truncate_content(
# Extract code content, removing leading/trailing whitespace and newlines
code_str = code_content.strip()
+ if cls._is_ignored_code_block(code_str, ignore_codes):
+ last_end = match.end()
+ continue
# Store first code block for return value
if first_code is None:
diff --git a/trpc_agent_sdk/server/langfuse/tracing/opentelemetry.py b/trpc_agent_sdk/server/langfuse/tracing/opentelemetry.py
index 166f20a..5dab42d 100644
--- a/trpc_agent_sdk/server/langfuse/tracing/opentelemetry.py
+++ b/trpc_agent_sdk/server/langfuse/tracing/opentelemetry.py
@@ -58,7 +58,6 @@ def _should_skip_span(self, span: ReadableSpan) -> bool:
Returns:
True if the span should be skipped, False otherwise.
"""
- global _langfuse_config # pylint: disable=invalid-name
# If enable_a2a_trace is True, don't filter out any spans
if _langfuse_config.enable_a2a_trace:
return False
@@ -99,7 +98,6 @@ def _should_skip_span(self, span: ReadableSpan) -> bool:
def _transform_span_for_langfuse(self, span: ReadableSpan) -> ReadableSpan:
"""Transform TRPC agent span attributes to Langfuse format."""
- global _langfuse_config # pylint: disable=invalid-name
trpc_span_name = get_trpc_agent_span_name()
if span.name == "invocation":
span_name = span.attributes.get(f"{trpc_span_name}.runner.name", "unknown")
@@ -262,6 +260,8 @@ def _map_generation_attributes(self, attributes: Dict[str, Any]) -> Dict[str, An
# Map usage details
gen_attrs["gen_ai.usage.input_tokens"] = attributes.get("gen_ai.usage.input_tokens", "0")
gen_attrs["gen_ai.usage.output_tokens"] = attributes.get("gen_ai.usage.output_tokens", "0")
+ if "gen_ai.request.model" in attributes:
+ gen_attrs["gen_ai.request.model"] = attributes["gen_ai.request.model"]
# Map generation metadata
gen_metadata = {}
@@ -603,7 +603,6 @@ def setup(config: Optional[LangfuseConfig] = None) -> TracerProvider:
Raises:
ValueError: If required configuration is missing.
"""
- global _langfuse_config # pylint: disable=invalid-name
if config is None:
config = LangfuseConfig()
@@ -619,6 +618,7 @@ def setup(config: Optional[LangfuseConfig] = None) -> TracerProvider:
if config.host is None:
config.host = os.getenv("LANGFUSE_HOST")
+ global _langfuse_config # pylint: disable=invalid-name
# Set the global config and use it in span processor(Only be setted once)
_langfuse_config = config
diff --git a/trpc_agent_sdk/sessions/_base_session_service.py b/trpc_agent_sdk/sessions/_base_session_service.py
index 0d984c1..dd41fb7 100644
--- a/trpc_agent_sdk/sessions/_base_session_service.py
+++ b/trpc_agent_sdk/sessions/_base_session_service.py
@@ -84,6 +84,9 @@ async def append_event(self, session: Session, event: Event) -> Event:
"""Appends an event to a session object."""
if event.partial:
return event
+ # Apply temp-scoped state to in-memory session before trimming event delta,
+ # so same-invocation consumers can still read temp values.
+ self._apply_temp_state(session, event)
event = self._trim_temp_delta_state(event)
self.__update_session_state(session, event)
session.add_event(event,
@@ -91,6 +94,18 @@ async def append_event(self, session: Session, event: Event) -> Event:
max_events=self._session_config.max_events)
return event
+ def _apply_temp_state(self, session: Session, event: Event) -> None:
+ """Apply temp-scoped state delta to in-memory session state only.
+
+ Temp state is intentionally ephemeral: it should be visible within
+ current invocation memory but not persisted into stored event deltas.
+ """
+ if not event.actions or not event.actions.state_delta:
+ return
+ for key, value in event.actions.state_delta.items():
+ if key.startswith(State.TEMP_PREFIX):
+ session.state[key] = value
+
def _trim_temp_delta_state(self, event: Event) -> Event:
"""Removes temporary state delta keys from the event."""
if not event.actions or not event.actions.state_delta:
diff --git a/trpc_agent_sdk/sessions/_history_record.py b/trpc_agent_sdk/sessions/_history_record.py
index 62086a6..1950e09 100644
--- a/trpc_agent_sdk/sessions/_history_record.py
+++ b/trpc_agent_sdk/sessions/_history_record.py
@@ -23,6 +23,7 @@ class HistoryRecord(BaseModel):
user_texts: list[str] = Field(default_factory=list, description="List of user text")
# The text of the user
assistant_texts: list[str] = Field(default_factory=list, description="List of assistant text")
+
# The text of the assistant
def add_record(self, user_text: str, assistant_text: str | None = ""):
diff --git a/trpc_agent_sdk/sessions/_session.py b/trpc_agent_sdk/sessions/_session.py
index 7598a47..28c0b91 100644
--- a/trpc_agent_sdk/sessions/_session.py
+++ b/trpc_agent_sdk/sessions/_session.py
@@ -11,7 +11,6 @@
from typing import List
from pydantic import Field
-
from trpc_agent_sdk.abc import SessionABC
from trpc_agent_sdk.events import Event
@@ -54,10 +53,7 @@ def apply_event_filtering(self, event_ttl_seconds: float = 0.0, max_events: int
2. Count filtering: Keep only the most recent max_events events
If both filters result in removing all events, the method attempts to
- preserve the first user message and all events after it from the original events.
-
- The filtering logic is inspired by the ApplyEventFiltering function
- from trpc-agent-go: https://github.com/trpc-group/trpc-agent-go
+ preserve the first user message and all events after it from the original events.
Args:
event_ttl_seconds: Time-to-live in seconds for events. If 0, no TTL filtering is applied.
diff --git a/trpc_agent_sdk/skills/__init__.py b/trpc_agent_sdk/skills/__init__.py
index b8afbb3..d457bd6 100644
--- a/trpc_agent_sdk/skills/__init__.py
+++ b/trpc_agent_sdk/skills/__init__.py
@@ -1,3 +1,7 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright @ 2026 Tencent.com
+
# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
#
# Copyright (C) 2026 Tencent. All rights reserved.
@@ -21,120 +25,156 @@
>>> tools = await toolset.get_tools()
"""
-from ._common import BaseSelectionResult
from ._common import SelectionMode
-from ._common import add_selection
-from ._common import clear_selection
+from ._common import docs_scan_prefix
+from ._common import docs_state_key
from ._common import generic_get_selection
-from ._common import generic_select_items
-from ._common import get_previous_selection
-from ._common import get_state_delta_value
-from ._common import replace_selection
-from ._common import set_state_delta_for_selection
+from ._common import loaded_order_state_key
+from ._common import loaded_scan_prefix
+from ._common import loaded_state_key
+from ._common import tool_scan_prefix
+from ._common import tool_state_key
+from ._common import use_session_skill_state
from ._constants import ENV_SKILLS_ROOT
+from ._constants import SKILL_ARTIFACTS_STATE_KEY
+from ._constants import SKILL_DOCS_BY_AGENT_STATE_KEY_PREFIX
from ._constants import SKILL_DOCS_STATE_KEY_PREFIX
from ._constants import SKILL_FILE
+from ._constants import SKILL_LOADED_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_ORDER_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_ORDER_STATE_KEY_PREFIX
from ._constants import SKILL_LOADED_STATE_KEY_PREFIX
+from ._constants import SKILL_LOAD_MODE_VALUES
from ._constants import SKILL_REGISTRY_KEY
from ._constants import SKILL_REPOSITORY_KEY
+from ._constants import SKILL_TOOLS_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_TOOLS_NAMES
from ._constants import SKILL_TOOLS_STATE_KEY_PREFIX
+from ._constants import SkillLoadModeNames
+from ._constants import SkillProfileNames
+from ._constants import SkillToolsNames
from ._dynamic_toolset import DynamicSkillToolSet
from ._registry import SkillRegistry
from ._repository import BaseSkillRepository
from ._repository import FsSkillRepository
+from ._repository import VisibilityFilter
from ._repository import create_default_skill_repository
+from ._skill_config import get_skill_config
+from ._skill_config import get_skill_load_mode
+from ._skill_config import set_skill_config
+from ._skill_profile import SkillProfileFlags
+from ._state_keys import docs_key
+from ._state_keys import docs_prefix
+from ._state_keys import docs_session_key
+from ._state_keys import docs_session_prefix
+from ._state_keys import loaded_key
+from ._state_keys import loaded_order_key
+from ._state_keys import loaded_prefix
+from ._state_keys import loaded_session_key
+from ._state_keys import loaded_session_order_key
+from ._state_keys import loaded_session_prefix
+from ._state_keys import tool_key
+from ._state_keys import tool_prefix
+from ._state_keys import tool_session_key
+from ._state_keys import tool_session_prefix
+from ._state_migration import SKILLS_LEGACY_MIGRATION_STATE_KEY
+from ._state_migration import maybe_migrate_legacy_skill_state
+from ._state_order import marshal_loaded_order
+from ._state_order import parse_loaded_order
+from ._state_order import touch_loaded_order
from ._toolset import SkillToolSet
from ._types import Skill
from ._types import SkillConfig
from ._types import SkillFrontMatter
-from ._types import SkillMetadata
from ._types import SkillRequires
from ._types import SkillResource
from ._types import SkillSummary
-from ._types import SkillWorkspaceInputRecord
-from ._types import SkillWorkspaceMetadata
-from ._types import SkillWorkspaceOutputRecord
-from ._types import format_datetime
-from ._types import parse_datetime
-from ._url_root import ArchiveExt
from ._url_root import ArchiveExtractor
-from ._url_root import ArchiveKind
-from ._url_root import CacheConfig
-from ._url_root import FilePerm
-from ._url_root import SizeLimit
from ._url_root import SkillRootResolver
-from ._url_root import TarPerm
-from ._utils import compute_dir_digest
-from ._utils import ensure_layout
from ._utils import get_state_delta
-from ._utils import load_metadata
-from ._utils import save_metadata
from ._utils import set_state_delta
-from ._utils import shell_quote
+from .tools import SkillLoadTool
from .tools import SkillRunTool
from .tools import skill_list
from .tools import skill_list_docs
from .tools import skill_list_tools
-from .tools import skill_load
from .tools import skill_select_docs
from .tools import skill_select_tools
__all__ = [
- "BaseSelectionResult",
"SelectionMode",
- "add_selection",
- "clear_selection",
+ "docs_scan_prefix",
+ "docs_state_key",
"generic_get_selection",
- "generic_select_items",
- "get_previous_selection",
- "get_state_delta_value",
- "replace_selection",
- "set_state_delta_for_selection",
+ "loaded_order_state_key",
+ "loaded_scan_prefix",
+ "loaded_state_key",
+ "tool_scan_prefix",
+ "tool_state_key",
+ "use_session_skill_state",
"ENV_SKILLS_ROOT",
+ "SKILL_ARTIFACTS_STATE_KEY",
+ "SKILL_DOCS_BY_AGENT_STATE_KEY_PREFIX",
"SKILL_DOCS_STATE_KEY_PREFIX",
"SKILL_FILE",
+ "SKILL_LOADED_BY_AGENT_STATE_KEY_PREFIX",
+ "SKILL_LOADED_ORDER_BY_AGENT_STATE_KEY_PREFIX",
+ "SKILL_LOADED_ORDER_STATE_KEY_PREFIX",
"SKILL_LOADED_STATE_KEY_PREFIX",
+ "SKILL_LOAD_MODE_VALUES",
"SKILL_REGISTRY_KEY",
"SKILL_REPOSITORY_KEY",
+ "SKILL_TOOLS_BY_AGENT_STATE_KEY_PREFIX",
+ "SKILL_TOOLS_NAMES",
"SKILL_TOOLS_STATE_KEY_PREFIX",
+ "SkillLoadModeNames",
+ "SkillProfileNames",
+ "SkillToolsNames",
"DynamicSkillToolSet",
"SkillRegistry",
"BaseSkillRepository",
"FsSkillRepository",
+ "VisibilityFilter",
"create_default_skill_repository",
+ "get_skill_config",
+ "get_skill_load_mode",
+ "set_skill_config",
+ "SkillProfileFlags",
+ "docs_key",
+ "docs_prefix",
+ "docs_session_key",
+ "docs_session_prefix",
+ "loaded_key",
+ "loaded_order_key",
+ "loaded_prefix",
+ "loaded_session_key",
+ "loaded_session_order_key",
+ "loaded_session_prefix",
+ "tool_key",
+ "tool_prefix",
+ "tool_session_key",
+ "tool_session_prefix",
+ "SKILLS_LEGACY_MIGRATION_STATE_KEY",
+ "maybe_migrate_legacy_skill_state",
+ "marshal_loaded_order",
+ "parse_loaded_order",
+ "touch_loaded_order",
"SkillToolSet",
"Skill",
"SkillConfig",
"SkillFrontMatter",
- "SkillMetadata",
"SkillRequires",
"SkillResource",
"SkillSummary",
- "SkillWorkspaceInputRecord",
- "SkillWorkspaceMetadata",
- "SkillWorkspaceOutputRecord",
- "format_datetime",
- "parse_datetime",
- "ArchiveExt",
"ArchiveExtractor",
- "ArchiveKind",
- "CacheConfig",
- "FilePerm",
- "SizeLimit",
"SkillRootResolver",
- "TarPerm",
- "compute_dir_digest",
- "ensure_layout",
"get_state_delta",
- "load_metadata",
- "save_metadata",
"set_state_delta",
- "shell_quote",
+ "SkillLoadTool",
"SkillRunTool",
"skill_list",
"skill_list_docs",
"skill_list_tools",
- "skill_load",
"skill_select_docs",
"skill_select_tools",
]
diff --git a/trpc_agent_sdk/skills/_common.py b/trpc_agent_sdk/skills/_common.py
index a50f5a7..0eefc2c 100644
--- a/trpc_agent_sdk/skills/_common.py
+++ b/trpc_agent_sdk/skills/_common.py
@@ -24,6 +24,26 @@
from trpc_agent_sdk.context import InvocationContext
from trpc_agent_sdk.log import logger
+from ._constants import SkillLoadModeNames
+from ._skill_config import get_skill_load_mode
+from ._state_keys import docs_key
+from ._state_keys import docs_prefix
+from ._state_keys import docs_session_key
+from ._state_keys import docs_session_prefix
+from ._state_keys import loaded_key
+from ._state_keys import loaded_order_key
+from ._state_keys import loaded_prefix
+from ._state_keys import loaded_session_key
+from ._state_keys import loaded_session_order_key
+from ._state_keys import loaded_session_prefix
+from ._state_keys import tool_key
+from ._state_keys import tool_prefix
+from ._state_keys import tool_session_key
+from ._state_keys import tool_session_prefix
+from ._state_order import marshal_loaded_order
+from ._state_order import parse_loaded_order
+from ._state_order import touch_loaded_order
+
# Generic type for selection results
T = TypeVar('T', bound=BaseModel) # pylint: disable=invalid-name
@@ -59,8 +79,45 @@ class BaseSelectionResult(BaseModel):
mode: str = Field(default="", description="The mode used for selecting")
-def _set_state_delta(invocation_context: InvocationContext, key: str, value: Any) -> None:
- """Set the state delta for a key.
+def get_agent_name(invocation_context: InvocationContext) -> str:
+ """Get normalized agent name from invocation context."""
+ name = getattr(invocation_context, "agent_name", "")
+ return name.strip() if isinstance(name, str) else ""
+
+
+def use_session_skill_state(invocation_context: InvocationContext) -> bool:
+ """Whether skill-related state should use persistent (non-temp) keys."""
+ return get_skill_load_mode(invocation_context) == SkillLoadModeNames.SESSION
+
+
+def normalize_selection_mode(mode: str) -> str:
+ """Normalize selection mode; defaults to replace."""
+ m = (mode or "").strip().lower()
+ if m in ("add", "replace", "clear"):
+ return m
+ return "replace"
+
+
+def get_previous_selection_by_key(invocation_context: InvocationContext, key: str) -> tuple[list[str], bool]:
+ """Get previous selection by exact state key.
+
+ Returns:
+ (selected_items, had_all)
+ """
+ value = get_state_delta_value(invocation_context, key)
+ if not value:
+ return [], False
+ if value == "*":
+ return [], True
+ try:
+ parsed = json.loads(value)
+ except (json.JSONDecodeError, TypeError):
+ return [], False
+ return parsed if isinstance(parsed, list) else [], False
+
+
+def set_state_delta(invocation_context: InvocationContext, key: str, value: Any) -> None:
+ """Set the state delta of a skill workspace.
Args:
invocation_context: Invocation context
@@ -70,6 +127,35 @@ def _set_state_delta(invocation_context: InvocationContext, key: str, value: Any
invocation_context.actions.state_delta[key] = value
+def set_selection_state_delta_by_key(
+ invocation_context: InvocationContext,
+ key: str,
+ selected_items: list[str],
+ include_all: bool,
+) -> None:
+ """Set selection state delta by exact state key."""
+ if include_all:
+ set_state_delta(invocation_context, key, "*")
+ else:
+ set_state_delta(invocation_context, key, json.dumps(selected_items or []))
+
+
+def append_loaded_order_state_delta(
+ invocation_context: InvocationContext,
+ agent_name: str,
+ skill_name: str,
+) -> None:
+ """Append loaded-order state delta for skill touch order."""
+ key = loaded_order_key(agent_name)
+ if use_session_skill_state(invocation_context):
+ key = loaded_session_order_key(key)
+ current = parse_loaded_order(get_state_delta_value(invocation_context, key))
+ next_order = touch_loaded_order(current, skill_name)
+ encoded = marshal_loaded_order(next_order)
+ if encoded:
+ set_state_delta(invocation_context, key, encoded)
+
+
def get_previous_selection(invocation_context: InvocationContext, state_key_prefix: str,
skill_name: str) -> Optional[list[str]]:
"""Get the previous selection for a skill from session state.
@@ -191,12 +277,12 @@ def set_state_delta_for_selection(invocation_context: InvocationContext, state_k
include_all = getattr(result, 'include_all', False)
if include_all:
- _set_state_delta(invocation_context, key, '*')
+ set_state_delta(invocation_context, key, '*')
return
selected_items = getattr(result, 'selected_items', [])
selected_json = json.dumps(selected_items)
- _set_state_delta(invocation_context, key, selected_json)
+ set_state_delta(invocation_context, key, selected_json)
def generic_select_items(tool_context: InvocationContext, skill_name: str, items: Optional[list[str]],
@@ -354,3 +440,52 @@ def get_all_tools(skill_name):
except json.JSONDecodeError:
logger.warning("Failed to parse selection for skill '%s' with key '%s': %s", skill_name, key, v_str)
return []
+
+
+def loaded_state_key(ctx: InvocationContext, skill_name: str) -> str:
+ """Return the loaded-state key for a skill."""
+ agent_name = ctx.agent_name.strip()
+ load_keys = loaded_key(agent_name, skill_name)
+ return loaded_session_key(load_keys) if use_session_skill_state(ctx) else load_keys
+
+
+def docs_state_key(ctx: InvocationContext, skill_name: str) -> str:
+ """Return the docs-state key for a skill."""
+ agent_name = ctx.agent_name.strip()
+ key = docs_key(agent_name, skill_name)
+ return docs_session_key(key) if use_session_skill_state(ctx) else key
+
+
+def tool_state_key(ctx: InvocationContext, skill_name: str) -> str:
+ """Return the tools-state key for a skill."""
+ agent_name = ctx.agent_name.strip()
+ key = tool_key(agent_name, skill_name)
+ return tool_session_key(key) if use_session_skill_state(ctx) else key
+
+
+def loaded_scan_prefix(ctx: InvocationContext) -> str:
+ """Return the loaded-state scan prefix for an agent."""
+ agent_name = ctx.agent_name.strip()
+ key = loaded_prefix(agent_name)
+ return loaded_session_prefix(key) if use_session_skill_state(ctx) else key
+
+
+def docs_scan_prefix(ctx: InvocationContext) -> str:
+ """Return the docs-state scan prefix for an agent."""
+ agent_name = ctx.agent_name.strip()
+ key = docs_prefix(agent_name)
+ return docs_session_prefix(key) if use_session_skill_state(ctx) else key
+
+
+def tool_scan_prefix(ctx: InvocationContext) -> str:
+ """Return the tools-state scan prefix for an agent."""
+ agent_name = ctx.agent_name.strip()
+ key = tool_prefix(agent_name)
+ return tool_session_prefix(key) if use_session_skill_state(ctx) else key
+
+
+def loaded_order_state_key(ctx: InvocationContext) -> str:
+ """Return the loaded-order state key for an agent."""
+ agent_name = ctx.agent_name.strip()
+ key = loaded_order_key(agent_name)
+ return loaded_session_order_key(key) if use_session_skill_state(ctx) else key
diff --git a/trpc_agent_sdk/skills/_constants.py b/trpc_agent_sdk/skills/_constants.py
index 292fba8..9a36626 100644
--- a/trpc_agent_sdk/skills/_constants.py
+++ b/trpc_agent_sdk/skills/_constants.py
@@ -8,6 +8,8 @@
This module defines constants for the skills system.
"""
+from enum import Enum
+
SKILL_FILE = "SKILL.md"
# Environment variable name for skills root directory
@@ -24,15 +26,80 @@
SKILL_LOADED_STATE_KEY_PREFIX = "temp:skill:loaded:"
"""State key for loaded skills."""
+# State key for loaded skills scoped by agent
+SKILL_LOADED_BY_AGENT_STATE_KEY_PREFIX = "temp:skill:loaded_by_agent:"
+"""State key prefix for loaded skills scoped by agent."""
+
# State key for docs of skills
SKILL_DOCS_STATE_KEY_PREFIX = "temp:skill:docs:"
"""State key for docs of skills."""
+# State key for docs of skills scoped by agent
+SKILL_DOCS_BY_AGENT_STATE_KEY_PREFIX = "temp:skill:docs_by_agent:"
+"""State key prefix for docs scoped by agent."""
+
+# State key for loaded skill order
+SKILL_LOADED_ORDER_STATE_KEY_PREFIX = "temp:skill:loaded_order:"
+"""State key prefix for loaded skill touch order."""
+
+# State key for loaded skill order scoped by agent
+SKILL_LOADED_ORDER_BY_AGENT_STATE_KEY_PREFIX = "temp:skill:loaded_order_by_agent:"
+"""State key prefix for loaded skill touch order scoped by agent."""
+
# State key for tools of skills
SKILL_TOOLS_STATE_KEY_PREFIX = "temp:skill:tools:"
"""State key for tools of skills."""
+# State key for tools of skills scoped by agent
+SKILL_TOOLS_BY_AGENT_STATE_KEY_PREFIX = "temp:skill:tools_by_agent:"
+"""State key prefix for tools scoped by agent."""
+
+# State key for per-tool-call artifact refs (replay support)
+SKILL_ARTIFACTS_STATE_KEY = "temp:skill:artifacts"
+"""State key for skill tool-call artifact references."""
+
# EnvSkillsCacheDir overrides where URL-based skills roots are cached.
# When empty, the user cache directory is used.
ENV_SKILLS_CACHE_DIR = "SKILLS_CACHE_DIR"
"""Environment variable name for skills cache directory."""
+
+
+class SkillProfileNames(str, Enum):
+ FULL = "full"
+ KNOWLEDGE_ONLY = "knowledge_only"
+
+ def __str__(self) -> str:
+ return self.value
+
+
+class SkillToolsNames(str, Enum):
+ LOAD = "skill_load"
+ SELECT_DOCS = "skill_select_docs"
+ LIST_DOCS = "skill_list_docs"
+ RUN = "skill_run"
+ SELECT_TOOLS = "skill_select_tools"
+ LIST_SKILLS = "skill_list_skills"
+ EXEC = "skill_exec"
+ WRITE_STDIN = "skill_write_stdin"
+ POLL_SESSION = "skill_poll_session"
+ KILL_SESSION = "skill_kill_session"
+
+ def __str__(self) -> str:
+ return self.value
+
+
+SKILL_TOOLS_NAMES = [tool.value for tool in SkillToolsNames.__members__.values()]
+
+
+class SkillLoadModeNames(str, Enum):
+ ONCE = "once"
+ TURN = "turn"
+ SESSION = "session"
+
+ def __str__(self) -> str:
+ return self.value
+
+
+SKILL_LOAD_MODE_VALUES = [mode.value for mode in SkillLoadModeNames.__members__.values()]
+
+SKILL_CONFIG_KEY = "__trpc_agent_skills_config"
diff --git a/trpc_agent_sdk/skills/_dynamic_toolset.py b/trpc_agent_sdk/skills/_dynamic_toolset.py
index ba648cf..7d11ca5 100644
--- a/trpc_agent_sdk/skills/_dynamic_toolset.py
+++ b/trpc_agent_sdk/skills/_dynamic_toolset.py
@@ -25,8 +25,9 @@
from trpc_agent_sdk.tools import get_tool
from trpc_agent_sdk.tools import get_tool_set
-from ._constants import SKILL_LOADED_STATE_KEY_PREFIX
-from ._constants import SKILL_TOOLS_STATE_KEY_PREFIX
+from ._common import loaded_scan_prefix
+from ._common import tool_scan_prefix
+from ._common import tool_state_key
from ._repository import BaseSkillRepository
from ._utils import get_state_delta
@@ -130,6 +131,7 @@ def __init__(self,
self._find_tool_by_name(tool)
else:
self._find_tool_by_type(tool)
+
logger.info("DynamicSkillToolSet initialized: %s tools, %s toolsets, only_active_skills=%s",
len(self._available_tools), len(self._available_toolsets), only_active_skills)
@@ -266,9 +268,8 @@ async def get_tools(self, ctx: InvocationContext) -> List[BaseTool]:
tool = await self._resolve_tool(tool_name, ctx)
if tool is None:
logger.warning(
- "Tool '%s' required by skill '%s' could not be resolved. Checked: available_tools (%s), "
- "available_toolsets (%s), global registry", tool_name, skill_name, len(self._available_tools),
- len(self._available_toolsets))
+ "Tool '%s' required by skill '%s' could not be resolved. Checked: available_tools (%s), available_toolsets (%s), global registry",
+ tool_name, skill_name, len(self._available_tools), len(self._available_toolsets))
continue
selected_tools.append(tool)
@@ -293,13 +294,14 @@ def _get_loaded_skills_from_state(self, ctx: InvocationContext) -> List[str]:
List of loaded skill names
"""
loaded_skills: List[str] = []
- # Combine session state and current state delta
state = dict(ctx.session_state.copy())
state.update(ctx.actions.state_delta)
-
+ prefix = loaded_scan_prefix(ctx)
for key, value in state.items():
- if key.startswith(SKILL_LOADED_STATE_KEY_PREFIX) and value:
- skill_name = key[len(SKILL_LOADED_STATE_KEY_PREFIX):]
+ if not value or not key.startswith(prefix):
+ continue
+ skill_name = key[len(prefix):].strip()
+ if skill_name:
loaded_skills.append(skill_name)
return loaded_skills
@@ -321,18 +323,20 @@ def _get_active_skills_from_delta(self, ctx: InvocationContext) -> List[str]:
"""
active_skills: set[str] = set()
- # Check state_delta for skill-related changes
+ loaded_state_prefix = loaded_scan_prefix(ctx)
+ tools_state_prefix = tool_scan_prefix(ctx)
+
for key, value in ctx.actions.state_delta.items():
- if key.startswith(SKILL_LOADED_STATE_KEY_PREFIX) and value:
- # Skill was just loaded
- skill_name = key[len(SKILL_LOADED_STATE_KEY_PREFIX):]
- active_skills.add(skill_name)
- logger.debug("Skill '%s' is active (just loaded)", skill_name)
- elif key.startswith(SKILL_TOOLS_STATE_KEY_PREFIX):
- # Skill's tools were just selected/modified
- skill_name = key[len(SKILL_TOOLS_STATE_KEY_PREFIX):]
- active_skills.add(skill_name)
- logger.debug("Skill '%s' is active (tools modified)", skill_name)
+ if key.startswith(loaded_state_prefix) and value:
+ skill_name = key[len(loaded_state_prefix):].strip()
+ if skill_name:
+ active_skills.add(skill_name)
+ logger.debug("Skill '%s' is active (just loaded)", skill_name)
+ if key.startswith(tools_state_prefix):
+ skill_name = key[len(tools_state_prefix):].strip()
+ if skill_name:
+ active_skills.add(skill_name)
+ logger.debug("Skill '%s' is active (tools modified)", skill_name)
return list(active_skills)
@@ -346,7 +350,7 @@ def _get_tools_selection(self, ctx: InvocationContext, skill_name: str) -> list[
Returns:
List of selected tool names
"""
- key = SKILL_TOOLS_STATE_KEY_PREFIX + skill_name
+ key = tool_state_key(ctx, skill_name)
v = get_state_delta(ctx, key)
if not v:
# Fallback to SKILL.md defaults when explicit selection state is absent.
diff --git a/trpc_agent_sdk/skills/_hot_reload.py b/trpc_agent_sdk/skills/_hot_reload.py
new file mode 100644
index 0000000..270c76c
--- /dev/null
+++ b/trpc_agent_sdk/skills/_hot_reload.py
@@ -0,0 +1,163 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Skill hot-reload helpers.
+
+This module encapsulates filesystem event handling and dirty-directory queues
+for skill repositories. Repository implementations can stay focused on indexing
+while delegating watcher integration here.
+"""
+
+from __future__ import annotations
+
+import importlib
+import threading
+from pathlib import Path
+from typing import Callable
+
+from trpc_agent_sdk.log import logger
+
+
+class SkillHotReloadTracker:
+ """Track changed skill directories and optional watchdog observer state."""
+
+ def __init__(self, skill_file_name: str):
+ self._skill_file_name = skill_file_name
+ self._watchdog_init_attempted = False
+ self._watchdog_observer: object | None = None
+ self._changed_dirs_by_root: dict[str, set[str]] = {}
+ self._changed_dirs_lock = threading.Lock()
+
+ def clear(self) -> None:
+ """Clear queued directory changes."""
+ with self._changed_dirs_lock:
+ self._changed_dirs_by_root = {}
+
+ def mark_changed_path(self, raw_path: str, is_directory: bool, skill_roots: list[str]) -> None:
+ """Mark a changed path as dirty for the next incremental reload."""
+ path = Path(raw_path)
+ if not is_directory and path.name.lower() != self._skill_file_name.lower():
+ return
+ target_dir = path if is_directory else path.parent
+ self.mark_changed_dir(target_dir, skill_roots)
+
+ def mark_changed_dir(self, path: Path, skill_roots: list[str]) -> None:
+ """Queue a changed directory; consumed by repository incremental scans."""
+ root_key = self.resolve_root_key(path, skill_roots)
+ if root_key is None:
+ return
+ with self._changed_dirs_lock:
+ self._changed_dirs_by_root.setdefault(root_key, set()).add(str(path.resolve(strict=False)))
+
+ def pop_changed_dirs(self, root_key: str) -> list[Path]:
+ """Pop and return queued changed directories for a root."""
+ with self._changed_dirs_lock:
+ raw_dirs = self._changed_dirs_by_root.pop(root_key, set())
+ return [Path(raw) for raw in sorted(raw_dirs)]
+
+ def collect_changed_dirs(
+ self,
+ root_key: str,
+ tracked_dirs: set[str],
+ dir_mtime_ns: dict[str, int],
+ mtime_reader: Callable[[Path], int],
+ ) -> list[Path]:
+ """Collect changed directories via event queue or mtime probing."""
+ changed_dirs = self.pop_changed_dirs(root_key)
+ if not changed_dirs:
+ for dir_key in sorted(tracked_dirs):
+ path = Path(dir_key)
+ if not path.exists():
+ continue
+ current_mtime = mtime_reader(path)
+ if dir_mtime_ns.get(dir_key) != current_mtime:
+ changed_dirs.append(path)
+ dir_mtime_ns[dir_key] = current_mtime
+ return self.normalize_scan_targets(changed_dirs)
+
+ @staticmethod
+ def resolve_root_key(path: Path, skill_roots: list[str]) -> str | None:
+ """Find matching root key for a path."""
+ resolved = path.resolve(strict=False)
+ seen_roots: set[str] = set()
+ for root in skill_roots:
+ if not root:
+ continue
+ root_path = Path(root).resolve()
+ root_key = str(root_path)
+ if root_key in seen_roots:
+ continue
+ seen_roots.add(root_key)
+ if resolved.is_relative_to(root_path):
+ return root_key
+ return None
+
+ @staticmethod
+ def normalize_scan_targets(changed_dirs: list[Path]) -> list[Path]:
+ """Drop nested paths when their parent is already queued."""
+ result: list[Path] = []
+ for candidate in sorted(changed_dirs, key=lambda p: len(p.parts)):
+ if any(candidate.is_relative_to(parent) for parent in result):
+ continue
+ result.append(candidate)
+ return result
+
+ def start_watcher_if_possible(self, skill_roots: list[str]) -> None:
+ """Start filesystem watcher for near real-time hot reload if available."""
+ if self._watchdog_init_attempted:
+ return
+ self._watchdog_init_attempted = True
+ try:
+ events_module = importlib.import_module("watchdog.events")
+ observers_module = importlib.import_module("watchdog.observers")
+ except ImportError:
+ logger.debug("watchdog is unavailable; skill hot reload falls back to mtime probing")
+ return
+ except Exception as ex: # pylint: disable=broad-except
+ logger.warning("Failed to initialize watchdog imports: %s", ex)
+ return
+
+ file_system_event_handler_cls = getattr(events_module, "FileSystemEventHandler", None)
+ observer_cls = getattr(observers_module, "Observer", None)
+ if file_system_event_handler_cls is None or observer_cls is None:
+ logger.warning("watchdog is installed but required symbols are missing")
+ return
+
+ tracker = self
+
+ class _SkillDirChangeHandler(file_system_event_handler_cls): # type: ignore[misc,valid-type]
+
+ def on_any_event(self, event) -> None: # type: ignore[no-untyped-def]
+ src_path = getattr(event, "src_path", None)
+ if src_path:
+ tracker.mark_changed_path(src_path, bool(event.is_directory), skill_roots)
+ dest_path = getattr(event, "dest_path", None)
+ if dest_path:
+ tracker.mark_changed_path(dest_path, bool(event.is_directory), skill_roots)
+
+ observer = observer_cls()
+ handler = _SkillDirChangeHandler()
+ seen_roots: set[str] = set()
+ for root in skill_roots:
+ if not root:
+ continue
+ root_path = Path(root).resolve()
+ root_key = str(root_path)
+ if root_key in seen_roots:
+ continue
+ seen_roots.add(root_key)
+ if not root_path.is_dir():
+ continue
+ try:
+ observer.schedule(handler, path=root_key, recursive=True)
+ except Exception as ex: # pylint: disable=broad-except
+ logger.warning("Failed to watch skill root %s: %s", root_key, ex)
+
+ if not observer.emitters:
+ logger.debug("No valid skill roots to watch; hot reload watcher not started")
+ return
+ observer.start()
+ self._watchdog_observer = observer
+ logger.debug("Skill hot reload watcher started with %d root(s)", len(observer.emitters))
diff --git a/trpc_agent_sdk/skills/_repository.py b/trpc_agent_sdk/skills/_repository.py
index 0877f4c..08189bf 100644
--- a/trpc_agent_sdk/skills/_repository.py
+++ b/trpc_agent_sdk/skills/_repository.py
@@ -18,9 +18,9 @@
import abc
import os
from pathlib import Path
+from typing import Callable
from typing import List
from typing import Optional
-from typing import Literal
from typing_extensions import override
import yaml
@@ -29,74 +29,16 @@
from trpc_agent_sdk.log import logger
from ._constants import SKILL_FILE
+from ._hot_reload import SkillHotReloadTracker
from ._types import Skill
from ._types import SkillResource
from ._types import SkillSummary
from ._url_root import SkillRootResolver
+from ._utils import is_doc_file
+from ._utils import is_script_file
BASE_DIR_PLACEHOLDER = "__BASE_DIR__"
-
-
-def _split_front_matter(content: str) -> tuple[dict[str, str], str]:
- """Split markdown into (front matter dict, body) with optional YAML front matter."""
- text = content.replace("\r\n", "\n")
- if not text.startswith("---\n"):
- return {}, text
- idx = text.find("\n---\n", 4)
- if idx < 0:
- return {}, text
- raw_yaml = text[4:idx]
- body = text[idx + 5:]
- try:
- parsed = yaml.safe_load(raw_yaml) or {}
- if not isinstance(parsed, dict):
- return {}, body
- except Exception:
- return {}, body
- out: dict[str, str] = {}
- for k, v in parsed.items():
- key = str(k).strip()
- if not key:
- continue
- if v is None:
- out[key] = ""
- else:
- out[key] = str(v)
- return out, body
-
-
-def _parse_tools_from_body(body: str) -> list[str]:
- """Parse tool names from the Tools section in body text."""
- tool_names: list[str] = []
- in_tools_section = False
- for line in body.split("\n"):
- stripped = line.strip()
- if stripped.lower().startswith("tools:"):
- in_tools_section = True
- continue
- if not in_tools_section:
- continue
- if stripped and not stripped.startswith("-") and not stripped.startswith("#"):
- if ":" in stripped or (stripped[0].isupper() and any(
- stripped.startswith(s) for s in ["Overview", "Examples", "Usage", "Description", "Installation"])):
- break
- if stripped.startswith("#"):
- continue
- if stripped.startswith("-"):
- tool_name = stripped[1:].strip()
- if tool_name and not tool_name.startswith("#"):
- tool_names.append(tool_name)
- return tool_names
-
-
-def _is_doc_file(name: str) -> bool:
- name_lower = name.lower()
- return name_lower.endswith(".md") or name_lower.endswith(".txt")
-
-
-def _read_skill_file(path: Path) -> tuple[dict[str, str], str]:
- content = path.read_text(encoding="utf-8")
- return _split_front_matter(content)
+VisibilityFilter = Callable[[SkillSummary], bool]
class BaseSkillRepository(abc.ABC):
@@ -107,13 +49,19 @@ class BaseSkillRepository(abc.ABC):
must satisfy. Parsing internals are left entirely to subclasses.
"""
- def __init__(self, workspace_runtime: BaseWorkspaceRuntime):
+ def __init__(self, workspace_runtime: BaseWorkspaceRuntime, visibility_filter: VisibilityFilter | None = None):
self._workspace_runtime = workspace_runtime
+ self._visibility_filter = visibility_filter
@property
def workspace_runtime(self) -> BaseWorkspaceRuntime:
return self._workspace_runtime
+ @property
+ def visibility_filter(self) -> VisibilityFilter | None:
+ """Return the filter function."""
+ return self._visibility_filter
+
def user_prompt(self) -> str:
return ""
@@ -132,18 +80,8 @@ def get(self, name: str) -> Skill:
raise NotImplementedError
@abc.abstractmethod
- def skill_list(self, mode: Literal["all", "enabled", "disabled"] = "all") -> list[str]:
- """Return the names of all indexed skills.
-
- Args:
- mode: The mode to list the skills.
- - all: List all skills.
- - enabled: List enabled skills.
- - disabled: List disabled skills.
-
- Returns:
- A list of skill names.
- """
+ def skill_list(self, mode: str = 'all') -> list[str]:
+ """Return the names of all indexed skills."""
raise NotImplementedError
@abc.abstractmethod
@@ -163,8 +101,24 @@ def refresh(self) -> None:
def skill_run_env(self, skill_name: str) -> dict[str, str]:
"""Return the environment variables for the given skill.
"""
+ if self._visibility_filter is not None:
+ if not self._skill_visible_by_name(skill_name, self.summaries()):
+ raise ValueError(f"skill '{skill_name}' not found")
return {}
+ def _filter_summaries(
+ self,
+ summaries: list[SkillSummary],
+ ) -> list[SkillSummary]:
+ if not summaries:
+ return []
+ if self._visibility_filter is None:
+ return [SkillSummary(name=s.name, description=s.description) for s in summaries]
+ return [s for s in summaries if self._visibility_filter(s)]
+
+ def _skill_visible_by_name(self, name: str, summaries: list[SkillSummary]) -> bool:
+ return any(summary.name == name for summary in summaries)
+
class FsSkillRepository(BaseSkillRepository):
"""
@@ -181,6 +135,7 @@ def __init__(
*roots: str,
workspace_runtime: Optional[BaseWorkspaceRuntime] = None,
resolver: Optional[SkillRootResolver] = None,
+ enable_hot_reload: bool = False,
):
"""
Create a FsSkillRepository scanning the given roots.
@@ -190,6 +145,7 @@ def __init__(
``file://`` URLs, or ``http(s)://`` archive URLs).
workspace_runtime: Optional workspace runtime to use.
resolver: Optional skill root resolver to use.
+ enable_hot_reload: Whether to enable skill hot reload checks.
"""
if workspace_runtime is None:
workspace_runtime = create_local_workspace_runtime()
@@ -197,6 +153,11 @@ def __init__(
self._resolver = resolver or SkillRootResolver()
self._skill_paths: dict[str, str] = {} # name -> base dir
self._all_descriptions: dict[str, str] = {} # name -> description
+ self._discovered_skill_files: set[str] = set()
+ self._tracked_dirs_by_root: dict[str, set[str]] = {}
+ self._dir_mtime_ns: dict[str, int] = {}
+ self._hot_reload_tracker = SkillHotReloadTracker(skill_file_name=SKILL_FILE, )
+ self._enable_hot_reload = enable_hot_reload
self._skill_roots: list[str] = []
flat_roots: list[str] = []
@@ -212,6 +173,11 @@ def __init__(
# Root resolution
# ------------------------------------------------------------------
+ @property
+ def hot_reload_enabled(self) -> bool:
+ """Whether hot reload checks are enabled."""
+ return self._enable_hot_reload
+
def _resolve_skill_roots(self, roots: list[str]) -> None:
"""
Resolve a skill root string to a local directory path.
@@ -238,44 +204,140 @@ def _index(self) -> None:
"""Scan all roots and index available skills."""
self._skill_paths = {}
self._all_descriptions = {}
+ self._discovered_skill_files = set()
+ self._tracked_dirs_by_root = {}
+ self._dir_mtime_ns = {}
+ self._hot_reload_tracker.clear()
seen: set[str] = set()
for root in self._skill_roots:
if not root:
continue
root_path = Path(root).resolve()
- if str(root_path) in seen:
+ root_key = str(root_path)
+ if root_key in seen:
continue
- seen.add(str(root_path))
+ seen.add(root_key)
try:
- for dirpath, _dirs, _files in os.walk(root_path):
- skill_file_path = Path(dirpath) / SKILL_FILE
- if not skill_file_path.is_file():
- continue
- try:
- self._index_one(dirpath, skill_file_path)
- except Exception as ex: # pylint: disable=broad-except
- logger.debug("Failed to index skill at %s: %s", skill_file_path, ex)
-
+ self._scan_root(root_path, root_key=root_key)
except Exception as ex: # pylint: disable=broad-except
logger.warning("Error scanning root %s: %s", root_path, ex)
+ if self._enable_hot_reload:
+ self._hot_reload_tracker.start_watcher_if_possible(self._skill_roots)
+
+ def _scan_root(self, root_path: Path, root_key: str, start_path: Optional[Path] = None) -> None:
+ """Scan a full root or one of its changed subtrees."""
+ target = start_path or root_path
+ for dirpath, _dirs, _files in os.walk(target):
+ self._track_dir(root_key, Path(dirpath))
+ skill_file_path = Path(dirpath) / SKILL_FILE
+ if not skill_file_path.is_file():
+ continue
+ try:
+ self._index_one(dirpath, skill_file_path)
+ except Exception as ex: # pylint: disable=broad-except
+ logger.debug("Failed to index skill at %s: %s dirpath: %s, _files: %s", skill_file_path, ex, _dirs,
+ _files)
+
+ def _track_dir(self, root_key: str, path: Path) -> None:
+ """Store directory metadata used by incremental hot reload."""
+ dir_key = str(path.resolve())
+ self._tracked_dirs_by_root.setdefault(root_key, set()).add(dir_key)
+ self._dir_mtime_ns[dir_key] = self._safe_mtime_ns(path)
- def _index_one(self, dirpath: str, skill_file_path: Path) -> None:
+ @staticmethod
+ def _safe_mtime_ns(path: Path) -> int:
+ try:
+ return path.stat().st_mtime_ns
+ except OSError:
+ return -1
+
+ def _mark_changed_dir_for_hot_reload(self, path: Path) -> None:
+ """Queue a changed directory; consumed by _scan_changed_dirs."""
+ if not self._enable_hot_reload:
+ return
+ self._hot_reload_tracker.mark_changed_dir(path, self._skill_roots)
+
+ def _index_one(self, dirpath: str, skill_file_path: Path) -> bool:
"""Index a single skill directory found at *dirpath*."""
- front_matter, _ = _read_skill_file(skill_file_path)
+ skill_file_key = str(skill_file_path.resolve())
+ if skill_file_key in self._discovered_skill_files:
+ return False
+ self._discovered_skill_files.add(skill_file_key)
+
+ front_matter, _ = self._read_skill_file(skill_file_path)
name = front_matter.get("name", "").strip()
if not name:
name = Path(dirpath).name.strip()
if not name:
- return
+ return False
# First occurrence wins.
if name in self._skill_paths:
- return
+ return False
self._all_descriptions[name] = front_matter.get("description", "").strip()
self._skill_paths[name] = dirpath
logger.debug("Found skill '%s' at %s", name, dirpath)
+ return True
+
+ def _scan_changed_dirs(self) -> None:
+ """Fast probe + incremental scan for newly added SKILL.md files."""
+ if not self._enable_hot_reload:
+ return
+ seen_roots: set[str] = set()
+ for root in self._skill_roots:
+ if not root:
+ continue
+ root_path = Path(root).resolve()
+ root_key = str(root_path)
+ if root_key in seen_roots:
+ continue
+ seen_roots.add(root_key)
+
+ if not root_path.is_dir():
+ continue
+
+ tracked_dirs = self._tracked_dirs_by_root.get(root_key, {root_key})
+ changed_dirs = self._hot_reload_tracker.collect_changed_dirs(
+ root_key=root_key,
+ tracked_dirs=tracked_dirs,
+ dir_mtime_ns=self._dir_mtime_ns,
+ mtime_reader=self._safe_mtime_ns,
+ )
+ if not changed_dirs:
+ continue
+
+ for target in changed_dirs:
+ self._scan_root(root_path=root_path, root_key=root_key, start_path=target)
+ self._prune_deleted_skills()
+
+ def _prune_deleted_skills(self) -> None:
+ """Remove indexed skills whose directory or SKILL.md no longer exists."""
+ removed_names: list[str] = []
+ for name, dirpath in list(self._skill_paths.items()):
+ skill_file_path = Path(dirpath) / SKILL_FILE
+ if skill_file_path.is_file():
+ continue
+ removed_names.append(name)
+
+ for name in removed_names:
+ dirpath = self._skill_paths.pop(name, "")
+ self._all_descriptions.pop(name, None)
+ if dirpath:
+ removed_file_key = str((Path(dirpath) / SKILL_FILE).resolve(strict=False))
+ self._discovered_skill_files.discard(removed_file_key)
+ logger.debug("Pruned deleted skill '%s' from repository index", name)
+
+ stale_files = {path for path in self._discovered_skill_files if not Path(path).is_file()}
+ if stale_files:
+ self._discovered_skill_files.difference_update(stale_files)
+
+ @classmethod
+ def _read_skill_file(cls, path: Path) -> tuple[dict[str, str], str]:
+ """Read the skill file and return the front matter and body."""
+ content = path.read_text(encoding="utf-8")
+ return cls.from_markdown(content)
# ------------------------------------------------------------------
# Public API
@@ -290,17 +352,24 @@ def path(self, name: str) -> str:
"""
key = name.strip()
if key not in self._skill_paths:
- raise ValueError(f"skill '{name}' not found")
+ logger.warning("skill '%s' not found, refreshing repository", name)
+ self.refresh()
+ if key not in self._skill_paths:
+ raise ValueError(f"skill '{name}' not found")
+ if self._visibility_filter is not None:
+ if not self._skill_visible_by_name(key, self.summaries()):
+ raise ValueError(f"skill '{key}' not found")
return self._skill_paths[key]
@override
def summaries(self) -> List[SkillSummary]:
"""Return summaries for all indexed skills, sorted by name."""
+ self._scan_changed_dirs()
out: list[SkillSummary] = []
for name in sorted(self._skill_paths):
skill_file_path = Path(self._skill_paths[name]) / SKILL_FILE
try:
- front_matter, _ = _read_skill_file(skill_file_path)
+ front_matter, _ = self._read_skill_file(skill_file_path)
summary = SkillSummary(
name=front_matter.get("name", "").strip(),
description=front_matter.get("description", "").strip(),
@@ -310,6 +379,8 @@ def summaries(self) -> List[SkillSummary]:
out.append(summary)
except Exception as ex: # pylint: disable=broad-except
logger.warning("Failed to parse summary for skill '%s': %s", name, ex)
+ if self._visibility_filter is not None:
+ out = self._filter_summaries(out)
return out
@override
@@ -323,13 +394,13 @@ def get(self, name: str) -> Skill:
ValueError: If the skill is not found.
"""
dir_path = Path(self.path(name))
- front_matter, body = _read_skill_file(dir_path / SKILL_FILE)
+ front_matter, body = self._read_skill_file(dir_path / SKILL_FILE)
skill = Skill()
skill.base_dir = str(dir_path)
skill.summary.name = front_matter.get("name", "").strip() or name
skill.summary.description = front_matter.get("description", "").strip()
skill.body = body
- skill.tools = _parse_tools_from_body(skill.body)
+ skill.tools = self._parse_tools_from_body(skill.body)
if skill.base_dir:
skill.body = skill.body.replace(BASE_DIR_PLACEHOLDER, skill.base_dir)
@@ -338,12 +409,20 @@ def get(self, name: str) -> Skill:
return skill
@override
- def skill_list(self, mode: Literal["all", "enabled", "disabled"] = "all") -> list[str]:
- """Return the names of all indexed skills, sorted."""
+ def skill_list(self, mode: str = 'all') -> list[str]:
+ """Return the names of all indexed skills, sorted.
+
+ Args:
+ mode: The mode to list skills.
+ Returns:
+ A list of skill names.
+ """
+ self._scan_changed_dirs()
return sorted(self._skill_paths)
@override
def refresh(self) -> None:
+ """Refresh the skill repository."""
self._index()
def _read_docs(self, dir_path: Path, base_dir: str) -> list[SkillResource]:
@@ -356,7 +435,7 @@ def _read_docs(self, dir_path: Path, base_dir: str) -> list[SkillResource]:
continue
if entry.name.lower() == SKILL_FILE.lower():
continue
- if not _is_doc_file(entry.name):
+ if not is_doc_file(entry.name) and not is_script_file(entry.name):
continue
try:
content = entry.read_text(encoding="utf-8")
@@ -380,7 +459,30 @@ def from_markdown(cls, content: str) -> tuple[dict[str, str], str]:
.. deprecated::
Prefer repository-native front matter splitting directly.
"""
- return _split_front_matter(content)
+ text = content.replace("\r\n", "\n")
+ if not text.startswith("---\n"):
+ return {}, text
+ idx = text.find("\n---\n", 4)
+ if idx < 0:
+ return {}, text
+ raw_yaml = text[4:idx]
+ body = text[idx + 5:]
+ try:
+ parsed = yaml.safe_load(raw_yaml) or {}
+ if not isinstance(parsed, dict):
+ return {}, body
+ except Exception:
+ return {}, body
+ out: dict[str, str] = {}
+ for k, v in parsed.items():
+ key = str(k).strip()
+ if not key:
+ continue
+ if v is None:
+ out[key] = ""
+ else:
+ out[key] = str(v)
+ return out, body
@staticmethod
def _parse_tools_from_body(body: str) -> list[str]:
@@ -389,18 +491,40 @@ def _parse_tools_from_body(body: str) -> list[str]:
.. deprecated::
Prefer repository-native tool parser directly.
"""
- return _parse_tools_from_body(body)
+ tool_names: list[str] = []
+ in_tools_section = False
+ for line in body.split("\n"):
+ stripped = line.strip()
+ if stripped.lower().startswith("tools:"):
+ in_tools_section = True
+ continue
+ if not in_tools_section:
+ continue
+ if stripped and not stripped.startswith("-") and not stripped.startswith("#"):
+ if ":" in stripped or (stripped[0].isupper() and any(
+ stripped.startswith(s)
+ for s in ["Overview", "Examples", "Usage", "Description", "Installation"])):
+ break
+ if stripped.startswith("#"):
+ continue
+ if stripped.startswith("-"):
+ tool_name = stripped[1:].strip()
+ if tool_name and not tool_name.startswith("#"):
+ tool_names.append(tool_name)
+ return tool_names
def create_default_skill_repository(
*roots: str,
workspace_runtime: Optional[BaseWorkspaceRuntime] = None,
+ enable_hot_reload: bool = True,
) -> FsSkillRepository:
"""Create a new filesystem skill repository.
Args:
roots: Root directories (or URLs) to scan for skills.
workspace_runtime: Optional workspace runtime.
+ enable_hot_reload: Whether to enable skill hot reload checks.
Returns:
A configured :class:`FsSkillRepository`.
"""
@@ -409,4 +533,5 @@ def create_default_skill_repository(
return FsSkillRepository(
*roots,
workspace_runtime=workspace_runtime,
+ enable_hot_reload=enable_hot_reload,
)
diff --git a/trpc_agent_sdk/skills/_skill_config.py b/trpc_agent_sdk/skills/_skill_config.py
new file mode 100644
index 0000000..00f15fe
--- /dev/null
+++ b/trpc_agent_sdk/skills/_skill_config.py
@@ -0,0 +1,60 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+
+from typing import Any
+
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.context import InvocationContext
+
+from ._constants import SKILL_CONFIG_KEY
+from ._constants import SKILL_LOAD_MODE_VALUES
+from ._constants import SkillLoadModeNames
+
+DEFAULT_SKILL_CONFIG = {
+ "skill_processor": {
+ "load_mode": "turn",
+ "tooling_guidance": "",
+ "tool_result_mode": False,
+ "tool_profile": "full",
+ "forbidden_tools": [],
+ "tool_flags": None,
+ "exec_tools_disabled": False,
+ "repo_resolver": None,
+ "max_loaded_skills": 0,
+ },
+ "workspace_exec_processor": {
+ "session_tools": False,
+ "has_skills_repo": False,
+ "repo_resolver": None,
+ "enabled_resolver": None,
+ "sessions_resolver": None,
+ },
+ "skills_tool_result_processor": {
+ "skip_fallback_on_session_summary": True,
+ "repo_resolver": None,
+ "tool_result_mode": False,
+ },
+}
+
+
+def get_skill_config(agent_context: AgentContext) -> dict[str, Any]:
+ return agent_context.get_metadata(SKILL_CONFIG_KEY, DEFAULT_SKILL_CONFIG)
+
+
+def set_skill_config(agent_context: AgentContext, config: dict[str, Any] = DEFAULT_SKILL_CONFIG) -> None:
+ agent_context.with_metadata(SKILL_CONFIG_KEY, config)
+
+
+def get_skill_load_mode(ctx: InvocationContext) -> str:
+ skill_config = get_skill_config(ctx.agent_context)
+ load_mode = skill_config["skill_processor"].get("load_mode", SkillLoadModeNames.TURN.value)
+ if load_mode not in SKILL_LOAD_MODE_VALUES:
+ load_mode = SkillLoadModeNames.TURN.value
+ return str(load_mode)
+
+
+def is_exist_skill_config(agent_context: AgentContext) -> bool:
+ return SKILL_CONFIG_KEY in agent_context.metadata
diff --git a/trpc_agent_sdk/skills/_skill_profile.py b/trpc_agent_sdk/skills/_skill_profile.py
new file mode 100644
index 0000000..e1f07da
--- /dev/null
+++ b/trpc_agent_sdk/skills/_skill_profile.py
@@ -0,0 +1,120 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Skill tool profile options and flags."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ._constants import SKILL_TOOLS_NAMES
+from ._constants import SkillProfileNames
+from ._constants import SkillToolsNames
+
+
+@dataclass
+class SkillProfileFlags:
+ """Built-in skill tool flags"""
+ load: bool = False
+ select_docs: bool = False
+ list_docs: bool = False
+ run: bool = False
+ select_tools: bool = False
+ list_skills: bool = False
+ exec: bool = False
+ write_stdin: bool = False
+ poll_session: bool = False
+ kill_session: bool = False
+
+ @classmethod
+ def normalize_profile(cls, profile: str) -> str:
+ p = (profile or "").strip().lower()
+ if p == str(SkillProfileNames.KNOWLEDGE_ONLY):
+ return str(SkillProfileNames.KNOWLEDGE_ONLY)
+ return str(SkillProfileNames.FULL)
+
+ @classmethod
+ def normalize_tool(cls, name: str) -> str:
+ return (name or "").strip().lower()
+
+ @classmethod
+ def preset_flags(cls, profile: str, forbidden_tools: Optional[list[str]] = None) -> "SkillProfileFlags":
+ normalized = cls.normalize_profile(profile)
+ if normalized == SkillProfileNames.KNOWLEDGE_ONLY:
+ return cls(load=True, select_docs=True, list_docs=True)
+
+ flags = cls(
+ load=True,
+ select_docs=True,
+ list_docs=True,
+ run=True,
+ exec=True,
+ write_stdin=True,
+ poll_session=True,
+ kill_session=True,
+ select_tools=True,
+ list_skills=True,
+ )
+ if forbidden_tools:
+ flags = flags.flags_from_forbidden_tools(forbidden_tools, flags)
+ return flags
+
+ @classmethod
+ def flags_from_forbidden_tools(cls, forbidden_tools: list[str], flags: "SkillProfileFlags") -> "SkillProfileFlags":
+ for raw in forbidden_tools:
+ name = cls.normalize_tool(raw)
+ if name in SKILL_TOOLS_NAMES:
+ flags_mem = name[name.index("_") + 1:]
+ setattr(flags, flags_mem, False)
+ flags.validate()
+ return flags
+
+ @classmethod
+ def resolve_flags(cls, profile: str, forbidden_tools: Optional[list[str]] = None) -> "SkillProfileFlags":
+ flags = cls.preset_flags(profile, forbidden_tools)
+ flags.validate()
+ return flags
+
+ def validate(self) -> None:
+ if self.exec and not self.run:
+ raise ValueError(f"{SkillToolsNames.EXEC} requires {SkillToolsNames.RUN}")
+ if self.write_stdin and not self.exec:
+ raise ValueError(f"{SkillToolsNames.WRITE_STDIN} requires {SkillToolsNames.EXEC}")
+ if self.poll_session and not self.exec:
+ raise ValueError(f"{SkillToolsNames.POLL_SESSION} requires {SkillToolsNames.EXEC}")
+ if self.kill_session and not self.exec:
+ raise ValueError(f"{SkillToolsNames.KILL_SESSION} requires {SkillToolsNames.EXEC}")
+
+ def is_any(self) -> bool:
+ return (self.load or self.select_docs or self.list_docs or self.run or self.exec or self.write_stdin
+ or self.poll_session or self.kill_session or self.select_tools or self.list_skills)
+
+ def has_knowledge_tools(self) -> bool:
+ return self.load or self.select_docs or self.list_docs
+
+ def has_doc_helpers(self) -> bool:
+ return self.select_docs or self.list_docs
+
+ def has_select_tools(self) -> bool:
+ return self.select_tools
+
+ def requires_execution_tools(self) -> bool:
+ return self.run or self.exec or self.write_stdin or self.poll_session or self.kill_session
+
+ def requires_exec_session_tools(self) -> bool:
+ return self.exec or self.write_stdin or self.poll_session or self.kill_session
+
+ def without_interactive_execution(self) -> "SkillProfileFlags":
+ return SkillProfileFlags(
+ load=self.load,
+ select_docs=self.select_docs,
+ list_docs=self.list_docs,
+ run=self.run,
+ exec=False,
+ write_stdin=False,
+ poll_session=False,
+ kill_session=False,
+ )
diff --git a/trpc_agent_sdk/skills/_state_keys.py b/trpc_agent_sdk/skills/_state_keys.py
new file mode 100644
index 0000000..586f530
--- /dev/null
+++ b/trpc_agent_sdk/skills/_state_keys.py
@@ -0,0 +1,151 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""State key builders for skills."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from ._constants import SKILL_DOCS_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_DOCS_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_ORDER_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_ORDER_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_STATE_KEY_PREFIX
+from ._constants import SKILL_TOOLS_BY_AGENT_STATE_KEY_PREFIX
+from ._constants import SKILL_TOOLS_STATE_KEY_PREFIX
+
+_STATE_KEY_SCOPE_DELIMITER = "/"
+_STATE_KEY_TEMP_PREFIX = "temp:"
+
+
+def _escape_scope_segment(value: str) -> str:
+ """Escape a scoped-key segment when it contains the delimiter."""
+ if _STATE_KEY_SCOPE_DELIMITER in value:
+ return quote(value, safe="")
+ return value
+
+
+def to_persistent_prefix(prefix: str) -> str:
+ """Convert temp-prefixed state prefix to persistent prefix."""
+ if prefix.startswith(_STATE_KEY_TEMP_PREFIX):
+ return prefix[len(_STATE_KEY_TEMP_PREFIX):]
+ return prefix
+
+
+def loaded_key(agent_name: str, skill_name: str) -> str:
+ """Return the loaded-state key for a skill.
+
+ When ``agent_name`` is empty, fallback to the legacy unscoped key.
+ """
+ agent_name = agent_name.strip()
+ skill_name = skill_name.strip()
+ if not agent_name:
+ return f"{SKILL_LOADED_STATE_KEY_PREFIX}{skill_name}"
+ return (f"{SKILL_LOADED_BY_AGENT_STATE_KEY_PREFIX}"
+ f"{_escape_scope_segment(agent_name)}"
+ f"{_STATE_KEY_SCOPE_DELIMITER}{skill_name}")
+
+
+def loaded_session_key(keys: str) -> str:
+ """Return persistent loaded-state key for session mode."""
+ return to_persistent_prefix(keys)
+
+
+def docs_key(agent_name: str, skill_name: str) -> str:
+ """Return the docs-state key for a skill.
+
+ When ``agent_name`` is empty, fallback to the legacy unscoped key.
+ """
+ agent_name = agent_name.strip()
+ skill_name = skill_name.strip()
+ if not agent_name:
+ return f"{SKILL_DOCS_STATE_KEY_PREFIX}{skill_name}"
+ return (f"{SKILL_DOCS_BY_AGENT_STATE_KEY_PREFIX}"
+ f"{_escape_scope_segment(agent_name)}"
+ f"{_STATE_KEY_SCOPE_DELIMITER}{skill_name}")
+
+
+def docs_session_key(keys: str) -> str:
+ """Return persistent docs-state key for session mode."""
+ return to_persistent_prefix(keys)
+
+
+def tool_key(agent_name: str, skill_name: str) -> str:
+ """Return the tools-state key for a skill.
+
+ When ``agent_name`` is empty, fallback to the legacy unscoped key.
+ """
+ agent_name = agent_name.strip()
+ skill_name = skill_name.strip()
+ if not agent_name:
+ return f"{SKILL_TOOLS_STATE_KEY_PREFIX}{skill_name}"
+ return (f"{SKILL_TOOLS_BY_AGENT_STATE_KEY_PREFIX}"
+ f"{_escape_scope_segment(agent_name)}"
+ f"{_STATE_KEY_SCOPE_DELIMITER}{skill_name}")
+
+
+def tool_session_key(keys: str) -> str:
+ """Return persistent tools-state key for session mode."""
+ return to_persistent_prefix(keys)
+
+
+def loaded_prefix(agent_name: str) -> str:
+ """Return the loaded-state scan prefix for an agent."""
+ agent_name = agent_name.strip()
+ if not agent_name:
+ return SKILL_LOADED_STATE_KEY_PREFIX
+ return (f"{SKILL_LOADED_BY_AGENT_STATE_KEY_PREFIX}"
+ f"{_escape_scope_segment(agent_name)}"
+ f"{_STATE_KEY_SCOPE_DELIMITER}")
+
+
+def loaded_session_prefix(keys: str) -> str:
+ """Return persistent loaded-state scan prefix for session mode."""
+ return to_persistent_prefix(keys)
+
+
+def docs_prefix(agent_name: str) -> str:
+ """Return the docs-state scan prefix for an agent."""
+ agent_name = agent_name.strip()
+ if not agent_name:
+ return SKILL_DOCS_STATE_KEY_PREFIX
+ return (f"{SKILL_DOCS_BY_AGENT_STATE_KEY_PREFIX}"
+ f"{_escape_scope_segment(agent_name)}"
+ f"{_STATE_KEY_SCOPE_DELIMITER}")
+
+
+def docs_session_prefix(keys: str) -> str:
+ """Return persistent docs-state scan prefix for session mode."""
+ return to_persistent_prefix(keys)
+
+
+def tool_prefix(agent_name: str) -> str:
+ """Return the tools-state scan prefix for an agent."""
+ agent_name = agent_name.strip()
+ if not agent_name:
+ return SKILL_TOOLS_STATE_KEY_PREFIX
+ return (f"{SKILL_TOOLS_BY_AGENT_STATE_KEY_PREFIX}"
+ f"{_escape_scope_segment(agent_name)}"
+ f"{_STATE_KEY_SCOPE_DELIMITER}")
+
+
+def tool_session_prefix(keys: str) -> str:
+ """Return persistent tools-state scan prefix for session mode."""
+ return to_persistent_prefix(keys)
+
+
+def loaded_order_key(agent_name: str) -> str:
+ """Return the loaded-order key for an agent."""
+ agent_name = agent_name.strip()
+ if not agent_name:
+ return SKILL_LOADED_ORDER_STATE_KEY_PREFIX
+ return f"{SKILL_LOADED_ORDER_BY_AGENT_STATE_KEY_PREFIX}{_escape_scope_segment(agent_name)}"
+
+
+def loaded_session_order_key(keys: str) -> str:
+ """Return persistent loaded-order key for session mode."""
+ return to_persistent_prefix(keys)
diff --git a/trpc_agent_sdk/skills/_state_migration.py b/trpc_agent_sdk/skills/_state_migration.py
new file mode 100644
index 0000000..90feb15
--- /dev/null
+++ b/trpc_agent_sdk/skills/_state_migration.py
@@ -0,0 +1,165 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Legacy skill state migration utilities.
+
+- migrate legacy unscoped skill state keys once per session
+- infer skill owners from historical tool responses
+- write new scoped keys and clear old legacy keys
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from typing import Callable
+
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.events import Event
+
+from ._constants import SKILL_DOCS_STATE_KEY_PREFIX
+from ._constants import SKILL_LOADED_STATE_KEY_PREFIX
+from ._constants import SkillToolsNames
+from ._state_keys import docs_key
+from ._state_keys import loaded_key
+
+SKILLS_LEGACY_MIGRATION_STATE_KEY = "processor:skills:legacy_migrated"
+
+ScopedKeysBuilder = Callable[[str, str], str]
+
+
+def _state_has_key(ctx: InvocationContext, key: str) -> bool:
+ if key in ctx.actions.state_delta:
+ return True
+ return key in ctx.session.state
+
+
+def _snapshot_state(ctx: InvocationContext) -> dict[str, Any]:
+ state = dict(ctx.session.state or {})
+ for k, v in ctx.actions.state_delta.items():
+ if v is None:
+ state.pop(k, None)
+ else:
+ state[k] = v
+ return state
+
+
+def _migrate_legacy_state_key(
+ ctx: InvocationContext,
+ state: dict[str, Any],
+ delta: dict[str, Any],
+ legacy_key: str,
+ legacy_val: Any,
+ skill_name: str,
+ owners: dict[str, str],
+ build_keys: ScopedKeysBuilder,
+) -> None:
+ name = (skill_name or "").strip()
+ if not name:
+ return
+ # Skip already scoped entries.
+ if ":" in name:
+ return
+
+ owner = (owners.get(name, "") or "").strip()
+ if not owner:
+ owner = (getattr(ctx.agent, "name", "") or "").strip()
+ if not owner:
+ return
+
+ temp_key = build_keys(owner, name)
+ temp_existing = state.get(temp_key, None)
+ if temp_existing:
+ delta[legacy_key] = None
+ return
+
+ delta[temp_key] = legacy_val
+ delta[legacy_key] = None
+
+
+def _legacy_skill_owners(events: list[Event]) -> dict[str, str]:
+ owners: dict[str, str] = {}
+ for ev in reversed(events or []):
+ _add_owners_from_event(ev, owners)
+ return owners
+
+
+def _add_owners_from_event(ev: Event, owners: dict[str, str]) -> None:
+ if not ev or not ev.content or not ev.content.parts:
+ return
+ author = (ev.author or "").strip()
+ if not author:
+ return
+ for part in reversed(ev.content.parts):
+ fr = part.function_response
+ if not fr:
+ continue
+ tool_name = (fr.name or "").strip()
+ if tool_name not in (SkillToolsNames.LOAD, SkillToolsNames.SELECT_DOCS):
+ continue
+ skill_name = _skill_name_from_tool_response(fr.response)
+ if not skill_name or skill_name in owners:
+ continue
+ owners[skill_name] = author
+
+
+def _skill_name_from_tool_response(response: Any) -> str:
+ """Extract skill name from tool response payload."""
+ if isinstance(response, dict):
+ for key in ("skill", "skill_name", "name"):
+ value = response.get(key)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ result = response.get("result")
+ if isinstance(result, str):
+ matched = re.search(r"skill\s+'([^']+)'\s+loaded", result)
+ if matched:
+ return matched.group(1).strip()
+ elif isinstance(response, str):
+ matched = re.search(r"skill\s+'([^']+)'\s+loaded", response)
+ if matched:
+ return matched.group(1).strip()
+ return ""
+
+
+def maybe_migrate_legacy_skill_state(ctx: InvocationContext) -> None:
+ """Migrate legacy skill state keys into scoped keys once.
+
+ This function is idempotent per session via
+ ``SKILLS_LEGACY_MIGRATION_STATE_KEY``.
+ """
+ if ctx is None or ctx.session is None:
+ return
+ if _state_has_key(ctx, SKILLS_LEGACY_MIGRATION_STATE_KEY):
+ return
+ ctx.actions.state_delta[SKILLS_LEGACY_MIGRATION_STATE_KEY] = True
+
+ state = _snapshot_state(ctx)
+ if not state:
+ return
+ has_loaded = any(k.startswith(SKILL_LOADED_STATE_KEY_PREFIX) for k in state.keys())
+ has_docs = any(k.startswith(SKILL_DOCS_STATE_KEY_PREFIX) for k in state.keys())
+ if not has_loaded and not has_docs:
+ return
+
+ owners: dict[str, str] | None = None
+ delta: dict[str, Any] = {}
+
+ for key, value in state.items():
+ if value is None or value == "":
+ continue
+ if key.startswith(SKILL_LOADED_STATE_KEY_PREFIX):
+ if owners is None:
+ owners = _legacy_skill_owners(getattr(ctx.session, "events", []))
+ name = key[len(SKILL_LOADED_STATE_KEY_PREFIX):].strip()
+ _migrate_legacy_state_key(ctx, state, delta, key, value, name, owners, loaded_key)
+ elif key.startswith(SKILL_DOCS_STATE_KEY_PREFIX):
+ if owners is None:
+ owners = _legacy_skill_owners(getattr(ctx.session, "events", []))
+ name = key[len(SKILL_DOCS_STATE_KEY_PREFIX):].strip()
+ _migrate_legacy_state_key(ctx, state, delta, key, value, name, owners, docs_key)
+
+ if delta:
+ ctx.actions.state_delta.update(delta)
diff --git a/trpc_agent_sdk/skills/_state_order.py b/trpc_agent_sdk/skills/_state_order.py
new file mode 100644
index 0000000..8cae773
--- /dev/null
+++ b/trpc_agent_sdk/skills/_state_order.py
@@ -0,0 +1,82 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Loaded-skill order helpers.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def parse_loaded_order(raw: Any) -> list[str]:
+ """Parse a stored loaded-order payload.
+
+ Returns a normalized list of unique non-empty skill names.
+ """
+ if raw is None:
+ return []
+ if isinstance(raw, bytes):
+ if not raw:
+ return []
+ try:
+ raw = raw.decode("utf-8")
+ except UnicodeDecodeError:
+ return []
+ if isinstance(raw, str):
+ if not raw:
+ return []
+ try:
+ raw = json.loads(raw)
+ except json.JSONDecodeError:
+ return []
+ if not isinstance(raw, list):
+ return []
+ return _normalize_loaded_order(raw)
+
+
+def marshal_loaded_order(names: list[str]) -> str:
+ """Serialize a normalized loaded-order payload."""
+ normalized = _normalize_loaded_order(names)
+ if not normalized:
+ return ""
+ return json.dumps(normalized, ensure_ascii=False)
+
+
+def touch_loaded_order(names: list[str], *touched: str) -> list[str]:
+ """Move touched skills to the tail of the loaded order."""
+ order = _normalize_loaded_order(names)
+ for name in touched:
+ candidate = (name or "").strip()
+ if not candidate:
+ continue
+ order = _remove_loaded_order_name(order, candidate)
+ order.append(candidate)
+ return order
+
+
+def _normalize_loaded_order(names: list[Any]) -> list[str]:
+ if not names:
+ return []
+ out: list[str] = []
+ seen: set[str] = set()
+ for name in names:
+ if not isinstance(name, str):
+ continue
+ candidate = name.strip()
+ if not candidate or candidate in seen:
+ continue
+ out.append(candidate)
+ seen.add(candidate)
+ return out
+
+
+def _remove_loaded_order_name(order: list[str], target: str) -> list[str]:
+ for i, name in enumerate(order):
+ if name != target:
+ continue
+ return order[:i] + order[i + 1:]
+ return order
diff --git a/trpc_agent_sdk/skills/_toolset.py b/trpc_agent_sdk/skills/_toolset.py
index 024a1db..f276322 100644
--- a/trpc_agent_sdk/skills/_toolset.py
+++ b/trpc_agent_sdk/skills/_toolset.py
@@ -12,33 +12,44 @@
from __future__ import annotations
from typing import Any
-from typing import Callable
from typing import List
from typing import Optional
from typing import Union
from typing_extensions import override
-from trpc_agent_sdk.abc import ToolABC
-from trpc_agent_sdk.abc import ToolPredicate
from trpc_agent_sdk.abc import ToolSetABC
+from trpc_agent_sdk.abc import ToolPredicate
+from trpc_agent_sdk.abc import ToolABC
from trpc_agent_sdk.context import InvocationContext
-from trpc_agent_sdk.log import logger
+from trpc_agent_sdk.context import get_invocation_ctx
from trpc_agent_sdk.tools import FunctionTool
+from trpc_agent_sdk.log import logger
from ._constants import SKILL_REGISTRY_KEY
from ._constants import SKILL_REPOSITORY_KEY
+from ._repository import FsSkillRepository
+from ._repository import BaseSkillRepository
from ._registry import SKILL_REGISTRY
from ._registry import SkillToolFunction
-from ._repository import BaseSkillRepository
-from ._repository import FsSkillRepository
-from .tools import SkillExecTool
-from .tools import SkillRunTool
-from .tools import skill_list
+from ._skill_config import DEFAULT_SKILL_CONFIG
+from ._skill_config import set_skill_config
+from ._skill_config import is_exist_skill_config
from .tools import skill_list_docs
from .tools import skill_list_tools
-from .tools import skill_load
+from .tools import SkillLoadTool
from .tools import skill_select_docs
from .tools import skill_select_tools
+from .tools import skill_list
+from .tools import SkillExecTool
+from .tools import SkillRunTool
+from .tools import SaveArtifactTool
+from .tools import WorkspaceExecTool
+from .tools import WorkspaceWriteStdinTool
+from .tools import WorkspaceKillSessionTool
+from .tools import CreateWorkspaceNameCallback
+from .tools import default_create_ws_name_callback
+from .tools import CopySkillStager
+from .stager import Stager
class SkillToolSet(ToolSetABC):
@@ -58,31 +69,63 @@ class SkillToolSet(ToolSetABC):
def __init__(self,
paths: Optional[List[str]] = None,
repository: BaseSkillRepository = None,
+ enable_hot_reload: bool = False,
tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
is_include_all_tools: bool = True,
+ create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = None,
+ runtime_tools: Optional[List[ToolABC]] = None,
+ skill_stager: Optional[Stager] = None,
+ skill_config: Optional[dict[str, Any]] = None,
**run_tool_kwargs: dict[str, Any]):
"""Initialize the skill toolset.
Args:
paths: Optional list of skill paths. If None, will create a new one.
repository: Skill repository. If None, will be retrieved from context metadata.
+ enable_hot_reload: Whether to enable skill hot reload checks for
+ auto-created repositories.
tool_filter: Optional tool filter. If None, will include all tools.
is_include_all_tools: Optional flag to include all tools. If True, will include all tools.
+ user_tools: Optional list of user tools. If None, will not include any user tools.
run_tool_kwargs: Optional keyword arguments for skill run tool. If None, will use default values.
"""
super().__init__(tool_filter=tool_filter, is_include_all_tools=is_include_all_tools)
self.name = "skill_toolset"
- self._repository = repository or FsSkillRepository(*(paths or []))
- self._run_tool = SkillRunTool(repository=self._repository, **run_tool_kwargs)
- self._exec_tool = SkillExecTool(run_tool=self._run_tool)
- self._tools: List[Callable] = [
- skill_load,
+
+ self._repository = repository or FsSkillRepository(
+ *(paths or []),
+ enable_hot_reload=enable_hot_reload,
+ )
+ self._skill_config = skill_config or DEFAULT_SKILL_CONFIG
+ self._create_ws_name_cb = create_ws_name_cb or default_create_ws_name_callback
+ self._skill_stager = skill_stager or CopySkillStager()
+ self._load_tool = SkillLoadTool(repository=self._repository,
+ skill_stager=self._skill_stager,
+ create_ws_name_cb=self._create_ws_name_cb)
+ self._run_tool = SkillRunTool(repository=self._repository,
+ create_ws_name_cb=self._create_ws_name_cb,
+ skill_stager=self._skill_stager,
+ **run_tool_kwargs)
+ self._exec_tool = SkillExecTool(run_tool=self._run_tool, create_ws_name_cb=self._create_ws_name_cb)
+ self._function_tools: List[SkillToolFunction] = [
skill_list,
skill_list_docs,
skill_list_tools,
skill_select_docs,
skill_select_tools,
]
+ if runtime_tools:
+ self._runtime_tools = runtime_tools
+ else:
+ workspace_exec_tool = WorkspaceExecTool(workspace_runtime=self._repository.workspace_runtime,
+ create_ws_name_cb=self._create_ws_name_cb)
+ self._runtime_tools: List[ToolABC] = [
+ SaveArtifactTool(workspace_runtime=self._repository.workspace_runtime,
+ create_ws_name_cb=self._create_ws_name_cb),
+ workspace_exec_tool,
+ WorkspaceWriteStdinTool(workspace_exec_tool),
+ WorkspaceKillSessionTool(workspace_exec_tool),
+ ]
@property
def repository(self) -> BaseSkillRepository:
@@ -99,14 +142,21 @@ async def get_tools(self, invocation_context: Optional[InvocationContext] = None
Returns:
List of tools from all registered skills
"""
- tools: List[FunctionTool] = []
+ tools: List[ToolABC] = []
skill_functions: List[SkillToolFunction] = SKILL_REGISTRY.get_all()
- skill_functions.extend(self._tools)
- agent_context = invocation_context.agent_context
- agent_context.with_metadata(SKILL_REGISTRY_KEY, SKILL_REGISTRY)
- agent_context.with_metadata(SKILL_REPOSITORY_KEY, self._repository)
+ skill_functions.extend(self._function_tools)
+ if not invocation_context:
+ invocation_context = get_invocation_ctx()
+ if invocation_context:
+ agent_context = invocation_context.agent_context
+ agent_context.with_metadata(SKILL_REGISTRY_KEY, SKILL_REGISTRY)
+ agent_context.with_metadata(SKILL_REPOSITORY_KEY, self._repository)
+ if not is_exist_skill_config(agent_context):
+ set_skill_config(agent_context, self._skill_config)
+ tools.append(self._load_tool)
tools.append(self._run_tool)
tools.append(self._exec_tool)
+ tools.extend(self._runtime_tools)
for skill_function in skill_functions:
try:
tools.append(FunctionTool(func=skill_function))
diff --git a/trpc_agent_sdk/skills/_utils.py b/trpc_agent_sdk/skills/_utils.py
index c9434d7..61bccc0 100644
--- a/trpc_agent_sdk/skills/_utils.py
+++ b/trpc_agent_sdk/skills/_utils.py
@@ -194,3 +194,60 @@ def get_state_delta(invocation_context: InvocationContext, key: str) -> Optional
state = dict(invocation_context.session_state.copy())
state.update(invocation_context.actions.state_delta)
return state.get(key, None)
+
+
+FILE_EXTENSIONS_DOC = (".md", ".txt")
+
+
+def is_doc_file(name: str) -> bool:
+ """Check if a file is a document file.
+
+ Args:
+ name: The name of the file
+
+ Returns:
+ True if the file is a document file, False otherwise
+ """
+ name_lower = name.lower()
+ return name_lower.endswith(FILE_EXTENSIONS_DOC)
+
+
+_SCRIPT_FILE_EXTENSIONS = (
+ # Shell
+ ".sh",
+ ".bash",
+ ".zsh",
+ ".fish",
+ # Python / Node
+ ".py",
+ ".pyw",
+ ".js",
+ ".mjs",
+ ".cjs",
+ ".ts",
+ # Other interpreted / script languages
+ ".rb",
+ ".pl",
+ ".php",
+ ".lua",
+ ".r",
+ ".ps1",
+ ".awk",
+ ".tcl",
+ ".groovy",
+ ".kts",
+ ".jl",
+)
+
+
+def is_script_file(name: str) -> bool:
+ """Check if a file is a script file.
+
+ Args:
+ name: The name of the file
+
+ Returns:
+ True if the file is a script file, False otherwise
+ """
+ name_lower = name.lower()
+ return name_lower.endswith(_SCRIPT_FILE_EXTENSIONS)
diff --git a/trpc_agent_sdk/skills/stager/_base_stager.py b/trpc_agent_sdk/skills/stager/_base_stager.py
index 8bfffe3..3119193 100644
--- a/trpc_agent_sdk/skills/stager/_base_stager.py
+++ b/trpc_agent_sdk/skills/stager/_base_stager.py
@@ -27,6 +27,7 @@
from trpc_agent_sdk.code_executors import WorkspaceRunProgramSpec
from trpc_agent_sdk.code_executors import WorkspaceStageOptions
from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.log import logger
from .._types import SkillMetadata
from .._types import SkillWorkspaceMetadata
@@ -46,12 +47,14 @@
class Stager:
"""Materializes skill package contents into a workspace.
-
- Mirrors Go's ``internal/skillstage.Stager``. Create an instance with
- ``Stager()`` (or the module-level helper :func:`new`) and call
- :meth:`stage_skill` from async tool code.
+ Stager is responsible for staging the skill package contents into a workspace.
"""
+ def __init__(self) -> None:
+ # Deduplicate noisy link warnings within one process lifetime.
+ # Key format: "||".
+ self._link_error_warned_keys: set[str] = set()
+
# ------------------------------------------------------------------
# Public API
# ------------------------------------------------------------------
@@ -76,7 +79,7 @@ async def stage_skill(self, request: SkillStageRequest) -> SkillStageResult:
ctx = request.ctx
ws = request.workspace
root = request.repository.path(request.skill_name)
- runtime = request.engine or request.repository.workspace_runtime
+ runtime = request.repository.workspace_runtime
name = request.skill_name
digest = compute_dir_digest(root)
md = await self.load_workspace_metadata(ctx, runtime, ws)
@@ -277,7 +280,17 @@ async def _link_workspace_dirs(
cmd = (f"set -e; cd {shell_quote(skill_root)}"
f"; rm -rf out work {_SKILL_DIR_INPUTS} {shell_quote(_SKILL_DIR_VENV)}"
- f"; mkdir -p {shell_quote(to_inputs)} {shell_quote(_SKILL_DIR_VENV)}"
+ f"; if [ -L {shell_quote(to_work)} ]; then"
+ f" rm -rf {shell_quote(to_work)}; fi"
+ f"; if [ -e {shell_quote(to_work)} ] && [ ! -d {shell_quote(to_work)} ]; then"
+ f" rm -rf {shell_quote(to_work)}; fi"
+ f"; if [ ! -d {shell_quote(to_work)} ]; then mkdir -p {shell_quote(to_work)}; fi"
+ f"; if [ -L {shell_quote(to_inputs)} ]; then"
+ f" rm -rf {shell_quote(to_inputs)}; fi"
+ f"; if [ -e {shell_quote(to_inputs)} ] && [ ! -d {shell_quote(to_inputs)} ]; then"
+ f" rm -rf {shell_quote(to_inputs)}; fi"
+ f"; if [ ! -d {shell_quote(to_inputs)} ]; then mkdir -p {shell_quote(to_inputs)}; fi"
+ f"; mkdir -p {shell_quote(_SKILL_DIR_VENV)}"
f"; ln -sfn {shell_quote(to_out)} out"
f"; ln -sfn {shell_quote(to_work)} work"
f"; ln -sfn {shell_quote(to_inputs)} {_SKILL_DIR_INPUTS}")
@@ -294,8 +307,18 @@ async def _link_workspace_dirs(
ctx,
)
if ret.exit_code != 0:
- from trpc_agent_sdk.log import logger # noqa: PLC0415
- logger.info("Stager._link_workspace_dirs failed for %r: %s", name, ret.stderr)
+ inv_id = ctx.invocation_id
+ err = (ret.stderr or "").strip()
+ dedupe_key = f"{inv_id}|{name}|{err}"
+ if dedupe_key in self._link_error_warned_keys:
+ logger.debug("Stager._link_workspace_dirs retry failed for %r: %s", name, ret.stderr)
+ return
+
+ self._link_error_warned_keys.add(dedupe_key)
+ # Keep the set bounded for long-lived processes.
+ if len(self._link_error_warned_keys) > 2000:
+ self._link_error_warned_keys.clear()
+ logger.warning("Stager._link_workspace_dirs failed for %r: %s", name, ret.stderr)
async def _read_only_except_symlinks(
self,
@@ -327,7 +350,6 @@ async def _read_only_except_symlinks(
ctx,
)
if ret.exit_code != 0:
- from trpc_agent_sdk.log import logger # noqa: PLC0415
logger.info("Stager._read_only_except_symlinks failed for %r: %s", dest, ret.stderr)
@classmethod
diff --git a/trpc_agent_sdk/skills/stager/_types.py b/trpc_agent_sdk/skills/stager/_types.py
index fec0411..0d599cc 100644
--- a/trpc_agent_sdk/skills/stager/_types.py
+++ b/trpc_agent_sdk/skills/stager/_types.py
@@ -6,7 +6,6 @@
"""Skill staging types."""
from dataclasses import dataclass
-from typing import Optional
from trpc_agent_sdk.code_executors import BaseWorkspaceRuntime
from trpc_agent_sdk.code_executors import WorkspaceInfo
@@ -17,10 +16,7 @@
@dataclass
class SkillStageRequest:
- """Describes the skill staging context for one run.
-
- Mirrors Go's ``SkillStageRequest`` in ``tool/skill/stager.go``.
- """
+ """Describes the skill staging context for one run."""
skill_name: str
"""Name of the skill to stage."""
@@ -34,11 +30,6 @@ class SkillStageRequest:
ctx: InvocationContext
"""Invocation context (used for workspace FS/runner access)."""
- engine: Optional[BaseWorkspaceRuntime] = None
- """Explicit workspace runtime (Go: ``Engine``).
- When ``None`` the runtime is obtained from ``repository.workspace_runtime``.
- """
-
timeout: float = 300.0
"""Timeout in seconds for internal staging helpers."""
diff --git a/trpc_agent_sdk/skills/tools/__init__.py b/trpc_agent_sdk/skills/tools/__init__.py
index 9ecf8a5..a6fc68d 100644
--- a/trpc_agent_sdk/skills/tools/__init__.py
+++ b/trpc_agent_sdk/skills/tools/__init__.py
@@ -1,64 +1,40 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+# -*- coding: utf-8 -*-
#
-# Copyright (C) 2026 Tencent. All rights reserved.
-#
-# tRPC-Agent-Python is licensed under Apache-2.0.
+# Copyright @ 2025 Tencent.com
"""Skill tools package."""
+from ._common import CreateWorkspaceNameCallback
+from ._common import default_create_ws_name_callback
from ._copy_stager import CopySkillStager
-from ._copy_stager import normalize_workspace_skill_dir
-from ._skill_exec import ExecInput
-from ._skill_exec import ExecOutput
-from ._skill_exec import KillSessionInput
-from ._skill_exec import KillSessionTool
-from ._skill_exec import PollSessionInput
-from ._skill_exec import PollSessionTool
-from ._skill_exec import SessionInteraction
-from ._skill_exec import SessionKillOutput
+from ._save_artifact import SaveArtifactTool
from ._skill_exec import SkillExecTool
-from ._skill_exec import WriteStdinInput
-from ._skill_exec import WriteStdinTool
-from ._skill_exec import create_exec_tools
from ._skill_list import skill_list
from ._skill_list_docs import skill_list_docs
from ._skill_list_tool import skill_list_tools
-from ._skill_load import skill_load
-from ._skill_run import ArtifactInfo
-from ._skill_run import SkillRunFile
-from ._skill_run import SkillRunInput
-from ._skill_run import SkillRunOutput
+from ._skill_load import SkillLoadTool
from ._skill_run import SkillRunTool
-from ._skill_select_docs import SkillSelectDocsResult
from ._skill_select_docs import skill_select_docs
-from ._skill_select_tools import SkillSelectToolsResult
from ._skill_select_tools import skill_select_tools
+from ._workspace_exec import WorkspaceExecTool
+from ._workspace_exec import WorkspaceKillSessionTool
+from ._workspace_exec import WorkspaceWriteStdinTool
+from ._workspace_exec import create_workspace_exec_tools
__all__ = [
+ "CreateWorkspaceNameCallback",
+ "default_create_ws_name_callback",
"CopySkillStager",
- "normalize_workspace_skill_dir",
- "ExecInput",
- "ExecOutput",
- "KillSessionInput",
- "KillSessionTool",
- "PollSessionInput",
- "PollSessionTool",
- "SessionInteraction",
- "SessionKillOutput",
+ "SaveArtifactTool",
"SkillExecTool",
- "WriteStdinInput",
- "WriteStdinTool",
- "create_exec_tools",
"skill_list",
"skill_list_docs",
"skill_list_tools",
- "skill_load",
- "ArtifactInfo",
- "SkillRunFile",
- "SkillRunInput",
- "SkillRunOutput",
+ "SkillLoadTool",
"SkillRunTool",
- "SkillSelectDocsResult",
"skill_select_docs",
- "SkillSelectToolsResult",
"skill_select_tools",
+ "WorkspaceExecTool",
+ "WorkspaceKillSessionTool",
+ "WorkspaceWriteStdinTool",
+ "create_workspace_exec_tools",
]
diff --git a/trpc_agent_sdk/skills/tools/_common.py b/trpc_agent_sdk/skills/tools/_common.py
new file mode 100644
index 0000000..2cd6bf3
--- /dev/null
+++ b/trpc_agent_sdk/skills/tools/_common.py
@@ -0,0 +1,159 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Shared helpers for skill/workspace tools."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from typing import Any
+from typing import Awaitable
+from typing import Callable
+from typing import TypeVar
+
+from trpc_agent_sdk.context import InvocationContext
+
+T = TypeVar("T")
+
+CreateWorkspaceNameCallback = Callable[[InvocationContext], str]
+"""Callback to create a workspace name."""
+
+
+def default_create_ws_name_callback(ctx: InvocationContext) -> str:
+ """Default callback to create a workspace name."""
+ return ctx.session.id
+
+
+def require_non_empty(value: str, *, field_name: str) -> str:
+ """Validate a required string field and return trimmed value."""
+ normalized = (value or "").strip()
+ if not normalized:
+ raise ValueError(f"{field_name} is required")
+ return normalized
+
+
+async def put_session(
+ sessions: dict[str, T],
+ lock: asyncio.Lock,
+ sid: str,
+ session: T,
+ gc: Callable[[], Awaitable[None]],
+) -> None:
+ """Insert session after running gc in lock."""
+ async with lock:
+ await gc()
+ sessions[sid] = session
+
+
+async def get_session(
+ sessions: dict[str, T],
+ lock: asyncio.Lock,
+ sid: str,
+ gc: Callable[[], Awaitable[None]],
+) -> T:
+ """Lookup session after running gc in lock."""
+ async with lock:
+ await gc()
+ session = sessions.get(sid)
+ if session is None:
+ raise ValueError(f"unknown session_id: {sid}")
+ return session
+
+
+async def remove_session(
+ sessions: dict[str, T],
+ lock: asyncio.Lock,
+ sid: str,
+ gc: Callable[[], Awaitable[None]],
+) -> T:
+ """Remove session after running gc in lock."""
+ async with lock:
+ await gc()
+ session = sessions.pop(sid, None)
+ if session is None:
+ raise ValueError(f"unknown session_id: {sid}")
+ return session
+
+
+async def _await_if_needed(value: object) -> None:
+ if inspect.isawaitable(value):
+ await value
+
+
+async def cleanup_expired_sessions(
+ sessions: dict[str, T],
+ *,
+ ttl: float,
+ refresh_exit_state: Callable[[T, float], object],
+ close_session: Callable[[T], object],
+) -> None:
+ """Refresh exit state and evict expired sessions in-place."""
+ if ttl <= 0:
+ return
+ now = time.time()
+ expired: list[str] = []
+ for sid, session in sessions.items():
+ await _await_if_needed(refresh_exit_state(session, now))
+ exited_at = getattr(session, "exited_at", None)
+ if exited_at is not None and (now - exited_at) >= ttl:
+ expired.append(sid)
+
+ for sid in expired:
+ session = sessions.pop(sid, None)
+ if session is None:
+ continue
+ try:
+ await _await_if_needed(close_session(session))
+ except Exception: # pylint: disable=broad-except
+ # Best-effort cleanup: mirror Go behavior and keep evicting others.
+ pass
+
+
+def inline_json_schema_refs(schema: dict[str, Any]) -> dict[str, Any]:
+ """Inline $ref references in JSON Schema by replacing them with actual definitions."""
+ defs = schema.get('$defs', {})
+ if not defs:
+ return schema
+
+ def resolve_ref(obj: Any) -> Any:
+ if isinstance(obj, dict):
+ if '$ref' in obj:
+ ref_path = obj['$ref']
+ if ref_path.startswith('#/$defs/'):
+ ref_name = ref_path.replace('#/$defs/', '')
+ if ref_name in defs:
+ resolved = resolve_ref(defs[ref_name])
+ merged = {**resolved, **{k: v for k, v in obj.items() if k != '$ref'}}
+ return merged
+ return obj
+ else:
+ return {k: resolve_ref(v) for k, v in obj.items()}
+ elif isinstance(obj, list):
+ return [resolve_ref(item) for item in obj]
+ else:
+ return obj
+
+ result = {k: v for k, v in schema.items() if k != '$defs'}
+ result = resolve_ref(result)
+ return result
+
+
+SKILL_STAGED_WORKSPACE_DIR_KEY = "__trpc_agent_skills_staged_workspace_dir"
+"""Key for staged workspace directory."""
+
+
+def get_staged_workspace_dir(ctx: InvocationContext, skill_name: str) -> str:
+ """Get the staged workspace directory."""
+ dir_map = ctx.agent_context.get_metadata(SKILL_STAGED_WORKSPACE_DIR_KEY, {})
+ return dir_map.get(skill_name, "")
+
+
+def set_staged_workspace_dir(ctx: InvocationContext, skill_name: str, dir: str) -> None:
+ """Set the staged workspace directory."""
+ dir_map = ctx.agent_context.get_metadata(SKILL_STAGED_WORKSPACE_DIR_KEY, {})
+ dir_map[skill_name] = dir
+ ctx.agent_context.with_metadata(SKILL_STAGED_WORKSPACE_DIR_KEY, dir_map)
diff --git a/trpc_agent_sdk/skills/tools/_copy_stager.py b/trpc_agent_sdk/skills/tools/_copy_stager.py
index 534f616..0ca5288 100644
--- a/trpc_agent_sdk/skills/tools/_copy_stager.py
+++ b/trpc_agent_sdk/skills/tools/_copy_stager.py
@@ -22,17 +22,8 @@
from ..stager import SkillStageResult
from ..stager import Stager
-# ---------------------------------------------------------------------------
-# Error messages (mirrors Go const block in tool/skill/stager.go)
-# ---------------------------------------------------------------------------
-
-_ERR_STAGER_NOT_CONFIGURED = "skill stager is not configured"
_ERR_REPO_NOT_CONFIGURED = "skill repository is not configured"
-# ---------------------------------------------------------------------------
-# Allowed workspace roots (mirrors Go isAllowedWorkspacePath)
-# ---------------------------------------------------------------------------
-
_ALLOWED_WS_ROOTS = (
DIR_SKILLS, # "skills"
DIR_WORK, # "work"
@@ -40,17 +31,12 @@
DIR_RUNS, # "runs"
)
-# ---------------------------------------------------------------------------
-# Path normalization helpers
-# (mirrors normalizeWorkspaceSkillDir / normalizeSkillStageResult)
-# ---------------------------------------------------------------------------
-
def normalize_workspace_skill_dir(raw: str) -> str:
"""Normalize and validate a workspace-relative skill directory.
Mirrors Go's ``normalizeWorkspaceSkillDir``. Strips leading slashes,
- normalizes path separators, and ensures the result stays within a
+ normalises path separators, and ensures the result stays within a
known workspace root.
Raises:
@@ -74,7 +60,7 @@ def normalize_workspace_skill_dir(raw: str) -> str:
def _normalize_skill_stage_result(result: SkillStageResult) -> SkillStageResult:
- """Return *result* with :attr:`workspace_skill_dir` normalized.
+ """Return *result* with :attr:`workspace_skill_dir` normalised.
Mirrors Go's ``normalizeSkillStageResult``.
@@ -84,39 +70,15 @@ def _normalize_skill_stage_result(result: SkillStageResult) -> SkillStageResult:
return SkillStageResult(workspace_skill_dir=normalize_workspace_skill_dir(result.workspace_skill_dir))
-# ---------------------------------------------------------------------------
-# Default copy-based stager (mirrors Go copySkillStager)
-# ---------------------------------------------------------------------------
-
-
class CopySkillStager(Stager):
"""Default stager: copies the skill directory into ``skills/``.
- Mirrors Go's ``copySkillStager`` struct. Holds an optional
- back-reference to the owning ``SkillRunTool`` (``run_tool``), matching
- the Go pattern of ``copySkillStager{tool: tool}``.
-
The actual filesystem work — digest check, ``stage_directory``, symlink
- creation, read-only chmod — is delegated to
- :class:`~trpc_agent_sdk.skills.stager.Stager`, which mirrors
- :class:`~trpc_agent_sdk.skills.stager.Stager`.
-
- Construct via :func:`new_copy_skill_stager` or
- :class:`~trpc_agent_sdk.skills.tools.CopySkillStager`.
+ creation, read-only chmod — is delegated to :class:`~trpc_agent.skills.stager.Stager`.
"""
async def stage_skill(self, request: SkillStageRequest) -> SkillStageResult:
- """Stage the skill and return the normalized workspace skill dir.
-
- Mirrors Go's ``copySkillStager.StageSkill``:
-
- 1. Validate repository is present.
- 2. Resolve the on-disk skill root via the repository.
- 3. Resolve the runtime (``request.engine`` takes priority, falls back
- to ``repository.workspace_runtime``).
- 4. Delegate copy / link / chmod to :class:`~trpc_agent_sdk.skills.stager.Stager`.
- 5. Return a normalized :class:`SkillStageResult`.
- """
+ """Stage the skill and return the normalised workspace skill dir."""
if request.repository is None:
raise ValueError(_ERR_REPO_NOT_CONFIGURED)
diff --git a/trpc_agent_sdk/skills/tools/_save_artifact.py b/trpc_agent_sdk/skills/tools/_save_artifact.py
new file mode 100644
index 0000000..17cb70c
--- /dev/null
+++ b/trpc_agent_sdk/skills/tools/_save_artifact.py
@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright @ 2025 Tencent.com
+"""Workspace artifact save tool.
+
+This tool persists an existing file from the current workspace as an artifact.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import posixpath
+from typing import Any
+from typing import Optional
+
+from trpc_agent_sdk.code_executors import BaseWorkspaceRuntime
+from trpc_agent_sdk.code_executors import DIR_OUT
+from trpc_agent_sdk.code_executors import DIR_RUNS
+from trpc_agent_sdk.code_executors import DIR_WORK
+from trpc_agent_sdk.code_executors import WORKSPACE_ENV_DIR_KEY
+from trpc_agent_sdk.code_executors.utils import normalize_globs
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.filter import BaseFilter
+from trpc_agent_sdk.tools import BaseTool
+from trpc_agent_sdk.types import FunctionDeclaration
+from trpc_agent_sdk.types import Part
+from trpc_agent_sdk.types import Schema
+from trpc_agent_sdk.types import Type
+
+from .._constants import SKILL_ARTIFACTS_STATE_KEY
+from ._common import CreateWorkspaceNameCallback
+from ._common import default_create_ws_name_callback
+
+_DEFAULT_MAX_BYTES = 64 * 1024 * 1024
+_ALLOWED_ROOTS = (DIR_WORK, DIR_OUT, DIR_RUNS)
+_SAVE_REASON_NO_SERVICE = "artifact service is not configured"
+_SAVE_REASON_NO_SESSION = "session is missing from invocation context"
+_SAVE_REASON_NO_SESSION_IDS = "session app/user/session IDs are missing"
+
+
+def _has_glob_meta(s: str) -> bool:
+ return any(ch in s for ch in ("*", "?", "["))
+
+
+def _normalize_workspace_prefix(path: str) -> str:
+ """Normalize workspace env-style prefixes in path."""
+ s = path.strip().replace("\\", "/")
+ if s.startswith("workspace://"):
+ s = s[len("workspace://"):]
+ replacements = (
+ ("${WORKSPACE_DIR}/", ""),
+ ("$WORKSPACE_DIR/", ""),
+ ("${WORK_DIR}/", f"{DIR_WORK}/"),
+ ("$WORK_DIR/", f"{DIR_WORK}/"),
+ ("${OUTPUT_DIR}/", f"{DIR_OUT}/"),
+ ("$OUTPUT_DIR/", f"{DIR_OUT}/"),
+ ("${RUN_DIR}/", f"{DIR_RUNS}/"),
+ ("$RUN_DIR/", f"{DIR_RUNS}/"),
+ )
+ for src, dst in replacements:
+ if s.startswith(src):
+ return dst + s[len(src):]
+ if s in ("$WORKSPACE_DIR", "${WORKSPACE_DIR}"):
+ return ""
+ if s in ("$WORK_DIR", "${WORK_DIR}"):
+ return DIR_WORK
+ if s in ("$OUTPUT_DIR", "${OUTPUT_DIR}"):
+ return DIR_OUT
+ if s in ("$RUN_DIR", "${RUN_DIR}"):
+ return DIR_RUNS
+ return s
+
+
+def _is_workspace_env_path(path: str) -> bool:
+ s = path.strip()
+ if not s:
+ return False
+ return s.startswith("$") or s.startswith("${")
+
+
+def _is_allowed_publish_path(rel: str) -> bool:
+ return any(rel == root or rel.startswith(f"{root}/") for root in _ALLOWED_ROOTS)
+
+
+def _artifact_save_skip_reason(ctx: InvocationContext) -> str:
+ if ctx.artifact_service is None:
+ return _SAVE_REASON_NO_SERVICE
+ if ctx.session is None:
+ return _SAVE_REASON_NO_SESSION
+ if not (ctx.app_name and ctx.user_id and ctx.session_id):
+ return _SAVE_REASON_NO_SESSION_IDS
+ return ""
+
+
+def _apply_artifact_state_delta(ctx: InvocationContext, saved_as: str, version: int, ref: str) -> None:
+ tool_call_id = (ctx.function_call_id or "").strip()
+ if not tool_call_id or not saved_as or version < 0:
+ return
+ artifact_ref = ref.strip() or f"artifact://{saved_as}@{version}"
+ ctx.actions.state_delta[SKILL_ARTIFACTS_STATE_KEY] = {
+ "tool_call_id": tool_call_id,
+ "artifacts": [{
+ "name": saved_as,
+ "version": version,
+ "ref": artifact_ref,
+ }],
+ }
+
+
+def _resolve_workspace_root_from_config(ctx: InvocationContext) -> str:
+ """Resolve workspace root from run_config/env; fallback to cwd."""
+ if ctx.run_config and isinstance(ctx.run_config.custom_data, dict):
+ for k in ("workspace_dir", "workspace_root", "workspace_path"):
+ v = ctx.run_config.custom_data.get(k)
+ if isinstance(v, str) and v.strip():
+ return os.path.abspath(v.strip())
+ env_root = os.environ.get(WORKSPACE_ENV_DIR_KEY, "").strip()
+ if env_root:
+ return os.path.abspath(env_root)
+ return os.path.abspath(os.getcwd())
+
+
+def _normalize_artifact_path(raw: str, workspace_root: str) -> tuple[str, str]:
+ """Return (workspace-relative path, absolute file path)."""
+ s = _normalize_workspace_prefix(raw)
+ if not s:
+ raise ValueError("path is required")
+ if _has_glob_meta(s):
+ raise ValueError("path must not contain glob patterns")
+ if _is_workspace_env_path(s):
+ out = normalize_globs([s.replace("${RUN_DIR}", DIR_RUNS).replace("$RUN_DIR", DIR_RUNS)])
+ if not out:
+ raise ValueError("invalid path")
+ s = out[0]
+
+ cleaned = posixpath.normpath(s)
+ if posixpath.isabs(cleaned):
+ rel = cleaned.lstrip("/")
+ rel = posixpath.normpath(rel)
+ if rel in ("", ".", ".."):
+ raise ValueError("path must point to a file inside the workspace")
+ else:
+ rel = cleaned
+ if rel in (".", "..") or rel.startswith("../"):
+ raise ValueError("path must stay within the workspace")
+
+ if not _is_allowed_publish_path(rel):
+ raise ValueError("path must stay under work/, out/, or runs/")
+
+ abs_path = os.path.abspath(os.path.join(workspace_root, rel))
+ rel_check = os.path.relpath(abs_path, workspace_root).replace("\\", "/")
+ if rel_check in (".", "..") or rel_check.startswith("../"):
+ raise ValueError("path must stay within the workspace")
+
+ rel = posixpath.normpath(rel)
+ return rel, abs_path
+
+
+class SaveArtifactTool(BaseTool):
+ """Persist an existing workspace file as an artifact."""
+
+ def __init__(
+ self,
+ max_file_bytes: int = _DEFAULT_MAX_BYTES,
+ workspace_runtime: Optional[BaseWorkspaceRuntime] = None,
+ create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = None,
+ filters_name: Optional[list[str]] = None,
+ filters: Optional[list[BaseFilter]] = None,
+ ):
+ super().__init__(
+ name="workspace_save_artifact",
+ description=("Save an existing file from the current workspace as an artifact. "
+ "Path must be under work/, out/, or runs/."),
+ filters_name=filters_name,
+ filters=filters,
+ )
+ self._max_file_bytes = max_file_bytes
+ self._workspace_runtime = workspace_runtime
+ self._create_ws_name_cb = create_ws_name_cb or default_create_ws_name_callback
+
+ async def _resolve_workspace_root(self, ctx: InvocationContext) -> str:
+ """Resolve workspace root, preferring the shared workspace_exec workspace."""
+ runtime = self._workspace_runtime
+ if runtime is not None:
+ workspace_id = self._create_ws_name_cb(ctx)
+ ws = await runtime.manager(ctx).create_workspace(workspace_id, ctx)
+ if ws.path:
+ return os.path.abspath(ws.path)
+ return _resolve_workspace_root_from_config(ctx)
+
+ def _get_declaration(self) -> Optional[FunctionDeclaration]:
+ return FunctionDeclaration(
+ name="workspace_save_artifact",
+ description=("Save an existing file from the current workspace as an artifact. "
+ "Use this to get a stable artifact:// reference for files under "
+ "work/, out/, or runs/."),
+ parameters=Schema(
+ type=Type.OBJECT,
+ required=["path"],
+ properties={
+ "path":
+ Schema(
+ type=Type.STRING,
+ description=("Workspace-relative file path to save. "
+ "Supports prefixes like $WORK_DIR/, $OUTPUT_DIR/, "
+ "$RUN_DIR/, and workspace://."),
+ ),
+ },
+ ),
+ response=Schema(
+ type=Type.OBJECT,
+ required=["path", "saved_as", "version", "ref", "size_bytes"],
+ properties={
+ "path": Schema(type=Type.STRING, description="Workspace-relative source path."),
+ "saved_as": Schema(type=Type.STRING, description="Artifact name used when saving."),
+ "version": Schema(type=Type.INTEGER, description="Artifact version."),
+ "ref": Schema(type=Type.STRING, description="artifact:// reference for saved artifact."),
+ "mime_type": Schema(type=Type.STRING, description="Detected MIME type."),
+ "size_bytes": Schema(type=Type.INTEGER, description="File size in bytes."),
+ },
+ ),
+ )
+
+ async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> Any:
+ raw_path = str(args.get("path", "")).strip()
+ if not raw_path:
+ return {"error": "INVALID_PARAMETER: path is required"}
+ reason = _artifact_save_skip_reason(tool_context)
+ if reason:
+ return {"error": f"ARTIFACT_SAVE_UNAVAILABLE: {reason}"}
+
+ try:
+ workspace_root = await self._resolve_workspace_root(tool_context)
+ rel, abs_path = _normalize_artifact_path(raw_path, workspace_root)
+ except ValueError as ex:
+ return {"error": f"INVALID_PARAMETER: {str(ex)}"}
+
+ if not os.path.exists(abs_path):
+ return {"error": f"FILE_NOT_FOUND: workspace artifact file not found: {rel}"}
+ if not os.path.isfile(abs_path):
+ return {"error": f"INVALID_PATH: path is not a file: {rel}"}
+
+ size_bytes = os.path.getsize(abs_path)
+ if size_bytes > self._max_file_bytes:
+ return {"error": f"FILE_TOO_LARGE: file exceeds {self._max_file_bytes} bytes limit"}
+
+ with open(abs_path, "rb") as f:
+ data = f.read()
+
+ mime_type = mimetypes.guess_type(abs_path)[0] or "application/octet-stream"
+ version = await tool_context.save_artifact(rel, Part.from_bytes(data=data, mime_type=mime_type))
+ ref = f"artifact://{rel}@{version}"
+ _apply_artifact_state_delta(tool_context, rel, version, ref)
+ return {
+ "path": rel,
+ "saved_as": rel,
+ "version": version,
+ "ref": ref,
+ "mime_type": mime_type,
+ "size_bytes": size_bytes,
+ }
diff --git a/trpc_agent_sdk/skills/tools/_skill_exec.py b/trpc_agent_sdk/skills/tools/_skill_exec.py
index 7e4cfe6..6a0e511 100644
--- a/trpc_agent_sdk/skills/tools/_skill_exec.py
+++ b/trpc_agent_sdk/skills/tools/_skill_exec.py
@@ -5,15 +5,13 @@
# tRPC-Agent-Python is licensed under Apache-2.0.
"""Interactive skill execution tools.
-Provides four tools that mirror the Go :mod:`~trpc_agent_sdk.skills.tools.SkillExecTool` implementation:
-
-* :class:`~trpc_agent_sdk.skills.tools.SkillExecTool` — start an interactive session
-* :class:`~trpc_agent_sdk.skills.tools.WriteStdinTool` — write stdin to a running session
-* :class:`~trpc_agent_sdk.skills.tools.PollSessionTool` — poll a session for new output
-* :class:`~trpc_agent_sdk.skills.tools.KillSessionTool` — terminate and remove a session
+* ``skill_exec`` — start an interactive session (SkillExecTool)
+* ``skill_write_stdin`` — write stdin to a running session (WriteStdinTool)
+* ``skill_poll_session`` — poll a session for new output (PollSessionTool)
+* ``skill_kill_session`` — terminate and remove a session (KillSessionTool)
Sessions run real sub-processes inside the staged skill workspace. When
-:attr:`~trpc_agent_sdk.skills.tools.ExecInput.tty` is ``True`` a POSIX pseudo-terminal is allocated so TTY-aware programs work
+``tty=True`` a POSIX pseudo-terminal is allocated so TTY-aware programs work
correctly (e.g. interactive shells, ncurses UIs).
Usage example::
@@ -22,7 +20,7 @@
result = await skill_exec_tool.run(ctx, {
"skill": "my_skill",
"command": "python interactive.py",
- "yield_ms": 500,
+ "yield_time_ms": 500,
})
sid = result["session_id"]
@@ -46,6 +44,7 @@
import uuid
from dataclasses import dataclass
from dataclasses import field
+from datetime import datetime
from pathlib import Path
from typing import Any
from typing import Dict
@@ -55,13 +54,29 @@
from pydantic import BaseModel
from pydantic import Field
+from trpc_agent_sdk.code_executors import BaseProgramRunner
+from trpc_agent_sdk.code_executors import BaseProgramSession
+from trpc_agent_sdk.code_executors import DEFAULT_EXEC_YIELD_MS
+from trpc_agent_sdk.code_executors import DEFAULT_IO_YIELD_MS
+from trpc_agent_sdk.code_executors import DEFAULT_SESSION_KILL_SEC
+from trpc_agent_sdk.code_executors import DEFAULT_SESSION_TTL_SEC
from trpc_agent_sdk.code_executors import DIR_OUT
+from trpc_agent_sdk.code_executors import DIR_RUNS
from trpc_agent_sdk.code_executors import DIR_SKILLS
from trpc_agent_sdk.code_executors import DIR_WORK
+from trpc_agent_sdk.code_executors import ENV_OUTPUT_DIR
+from trpc_agent_sdk.code_executors import ENV_SKILLS_DIR
from trpc_agent_sdk.code_executors import ENV_SKILL_NAME
+from trpc_agent_sdk.code_executors import ENV_WORK_DIR
+from trpc_agent_sdk.code_executors import PROGRAM_STATUS_EXITED
+from trpc_agent_sdk.code_executors import WORKSPACE_ENV_DIR_KEY
from trpc_agent_sdk.code_executors import WorkspaceInfo
from trpc_agent_sdk.code_executors import WorkspaceInputSpec
from trpc_agent_sdk.code_executors import WorkspaceOutputSpec
+from trpc_agent_sdk.code_executors import WorkspaceRunProgramSpec
+from trpc_agent_sdk.code_executors import poll_line_limit
+from trpc_agent_sdk.code_executors import wait_for_program_output
+from trpc_agent_sdk.code_executors import yield_duration_ms
from trpc_agent_sdk.context import InvocationContext
from trpc_agent_sdk.filter import BaseFilter
from trpc_agent_sdk.log import logger
@@ -69,24 +84,20 @@
from trpc_agent_sdk.types import FunctionDeclaration
from trpc_agent_sdk.types import Schema
+from .._constants import SKILL_ARTIFACTS_STATE_KEY
+from ._common import CreateWorkspaceNameCallback
+from ._common import cleanup_expired_sessions
+from ._common import default_create_ws_name_callback
+from ._common import inline_json_schema_refs
+from ._common import require_non_empty
from ._copy_stager import SkillStageRequest
from ._skill_run import SkillRunInput
from ._skill_run import SkillRunOutput
from ._skill_run import SkillRunTool
from ._skill_run import _filter_failed_empty_outputs
-from ._skill_run import _inline_json_schema_refs
from ._skill_run import _select_primary_output
from ._skill_run import _truncate_output
-# ---------------------------------------------------------------------------
-# Defaults (mirrors Go program's session defaults)
-# ---------------------------------------------------------------------------
-
-DEFAULT_EXEC_YIELD_MS: int = 300 # wait time on skill_exec
-DEFAULT_IO_YIELD_MS: int = 100 # wait time on write/poll
-DEFAULT_POLL_LINES: int = 50 # max lines returned per call
-DEFAULT_SESSION_TTL: float = 300.0 # seconds after exit before GC
-
# Status strings
_STATUS_RUNNING = "running"
_STATUS_EXITED = "exited"
@@ -109,7 +120,7 @@ class ExecInput(BaseModel):
env: dict[str, str] = Field(default_factory=dict, description="Extra environment variables")
stdin: str = Field(default="", description="Optional initial stdin written before yielding")
tty: bool = Field(default=False, description="Allocate a pseudo-TTY")
- yield_ms: int = Field(default=0, description="Milliseconds to wait for initial output before returning")
+ yield_time_ms: int = Field(default=0, description="Milliseconds to wait for initial output before returning")
poll_lines: int = Field(default=0, description="Maximum output lines to return per call")
output_files: list[str] = Field(default_factory=list, description="Glob patterns to collect on exit")
timeout: int = Field(default=0, description="Timeout in seconds (0 = no timeout)")
@@ -126,7 +137,7 @@ class WriteStdinInput(BaseModel):
session_id: str = Field(..., description="Session id returned by skill_exec")
chars: str = Field(default="", description="Text to write to stdin")
submit: bool = Field(default=False, description="Append a newline after chars")
- yield_ms: int = Field(default=0, description="Milliseconds to wait for new output")
+ yield_time_ms: int = Field(default=0, description="Milliseconds to wait for new output")
poll_lines: int = Field(default=0, description="Maximum output lines to return")
@@ -134,7 +145,7 @@ class PollSessionInput(BaseModel):
"""Input for skill_poll_session."""
session_id: str = Field(..., description="Session id returned by skill_exec")
- yield_ms: int = Field(default=0, description="Milliseconds to wait for new output")
+ yield_time_ms: int = Field(default=0, description="Milliseconds to wait for new output")
poll_lines: int = Field(default=0, description="Maximum output lines to return")
@@ -173,6 +184,31 @@ class SessionKillOutput(BaseModel):
status: str = Field(default="", description="Final status after kill")
+def _apply_artifacts_state_delta(ctx: InvocationContext, output: ExecOutput) -> None:
+ """Store replayable artifact refs in state delta (Go execArtifactsStateDelta parity)."""
+ tool_call_id = (ctx.function_call_id or "").strip()
+ if not tool_call_id or output.result is None or not output.result.artifact_files:
+ return
+
+ artifacts: list[dict[str, Any]] = []
+ for item in output.result.artifact_files:
+ name = (item.name or "").strip()
+ version = int(item.version)
+ if not name or version < 0:
+ continue
+ artifacts.append({
+ "name": name,
+ "version": version,
+ "ref": f"artifact://{name}@{version}",
+ })
+ if not artifacts:
+ return
+ ctx.actions.state_delta[SKILL_ARTIFACTS_STATE_KEY] = {
+ "tool_call_id": tool_call_id,
+ "artifacts": artifacts,
+ }
+
+
# ---------------------------------------------------------------------------
# Internal session state
# ---------------------------------------------------------------------------
@@ -182,169 +218,31 @@ class SessionKillOutput(BaseModel):
class _ExecSession:
"""Holds state for one running interactive skill session."""
- proc: asyncio.subprocess.Process
+ proc: BaseProgramSession
ws: WorkspaceInfo
in_data: ExecInput
- # Output buffer (all output since start as raw bytes → decoded text)
- _output_buf: list[str] = field(default_factory=list)
- _output_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
- _output_event: asyncio.Event = field(default_factory=asyncio.Event)
-
- # Current byte offset for incremental reads
- _read_offset: int = 0
-
- # Background reader task
- reader_task: Optional[asyncio.Task] = None
-
- # PTY master fd (None for non-TTY)
- master_fd: Optional[int] = None
-
# Final state
exit_code: Optional[int] = None
exited_at: Optional[float] = None
final_result: Optional[SkillRunOutput] = None
finalized: bool = False
- async def append_output(self, chunk: str) -> None:
- async with self._output_lock:
- self._output_buf.append(chunk)
- self._output_event.set()
-
- async def total_output(self) -> str:
- async with self._output_lock:
- return "".join(self._output_buf)
-
- async def yield_output(self, yield_ms: int, poll_lines: int) -> tuple[str, str, int, int]:
- """Wait *yield_ms* ms for new output then return a chunk.
+ async def yield_output(self, yield_time_ms: int, poll_lines: int) -> tuple[str, str, int, int]:
+ """Wait *yield_time_ms* ms for new output then return a chunk.
Returns ``(status, output_chunk, offset, next_offset)``.
"""
- yield_sec = (yield_ms or DEFAULT_EXEC_YIELD_MS) / 1000.0
- deadline = asyncio.get_event_loop().time() + yield_sec
-
- while True:
- remaining = deadline - asyncio.get_event_loop().time()
- if remaining <= 0:
- break
- self._output_event.clear()
- # Break early if process has already exited and we have all output
- if self.proc.returncode is not None:
- break
- try:
- await asyncio.wait_for(asyncio.shield(self._output_event.wait()), timeout=remaining)
- except asyncio.TimeoutError:
- break
-
- # Determine status
- rc = self.proc.returncode
- if rc is not None:
- self.exit_code = rc
- if self.exited_at is None:
- self.exited_at = time.time()
- status = _STATUS_RUNNING if rc is None else _STATUS_EXITED
-
- # Slice the output since last read
- async with self._output_lock:
- full = "".join(self._output_buf)
-
- chunk = full[self._read_offset:]
-
- # Apply poll_lines limit
- limit = poll_lines or DEFAULT_POLL_LINES
- if limit > 0 and chunk:
- lines = chunk.split("\n")
- if len(lines) > limit:
- chunk = "\n".join(lines[:limit])
- if not chunk.endswith("\n"):
- chunk += "\n"
-
- offset = self._read_offset
- self._read_offset += len(chunk)
- next_offset = self._read_offset
-
- return status, chunk, offset, next_offset
-
-
-# ---------------------------------------------------------------------------
-# Background output readers
-# ---------------------------------------------------------------------------
-
-
-async def _read_pipe(session: _ExecSession, stream: asyncio.StreamReader) -> None:
- """Continuously read from *stream* and append to session output."""
- try:
- while True:
- data = await stream.read(4096)
- if not data:
- break
- await session.append_output(data.decode("utf-8", errors="replace"))
- except Exception: # pylint: disable=broad-except
- pass
- finally:
- # Ensure exit is captured
- try:
- await session.proc.wait()
- except Exception: # pylint: disable=broad-except
- pass
- session._output_event.set() # unblock any waiting yield
-
-
-async def _read_pty(session: _ExecSession, master_fd: int) -> None:
- """Continuously read from a PTY master fd and append to session output."""
- loop = asyncio.get_event_loop()
- try:
- # Set master_fd non-blocking
- flags = fcntl.fcntl(master_fd, fcntl.F_GETFL)
- fcntl.fcntl(master_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK)
-
- # Use loop.add_reader for non-blocking reads
- read_event = asyncio.Event()
-
- def _on_readable() -> None:
- read_event.set()
-
- loop.add_reader(master_fd, _on_readable)
- try:
- while True:
- read_event.clear()
- # Check if process has exited
- rc = session.proc.returncode
- if rc is not None:
- # Drain remaining data
- while True:
- try:
- data = os.read(master_fd, 4096)
- if data:
- await session.append_output(data.decode("utf-8", errors="replace"))
- else:
- break
- except OSError:
- break
- break
- # Wait for readable or timeout
- try:
- await asyncio.wait_for(read_event.wait(), timeout=0.05)
- except asyncio.TimeoutError:
- pass
- try:
- data = os.read(master_fd, 4096)
- if data:
- await session.append_output(data.decode("utf-8", errors="replace"))
- except BlockingIOError:
- pass
- except OSError:
- break
- finally:
- loop.remove_reader(master_fd)
- except Exception: # pylint: disable=broad-except
- pass
- finally:
- try:
- await session.proc.wait()
- except Exception: # pylint: disable=broad-except
- pass
- session._output_event.set()
+ poll = await wait_for_program_output(
+ self.proc,
+ yield_duration_ms(yield_time_ms, DEFAULT_EXEC_YIELD_MS),
+ poll_line_limit(poll_lines),
+ )
+ if poll.exit_code is not None:
+ self.exit_code = poll.exit_code
+ if poll.status == _STATUS_EXITED and self.exited_at is None:
+ self.exited_at = time.time()
+ return poll.status, poll.output, poll.offset, poll.next_offset
# ---------------------------------------------------------------------------
@@ -395,10 +293,6 @@ def _detect_interaction(status: str, output: str) -> Optional[SessionInteraction
def _build_exec_env(ws: WorkspaceInfo, extra: dict[str, str]) -> dict[str, str]:
"""Build the merged environment for a subprocess in *ws*."""
- from trpc_agent_sdk.code_executors._constants import ( # lazy import to avoid circular
- WORKSPACE_ENV_DIR_KEY, ENV_SKILLS_DIR, ENV_WORK_DIR, ENV_OUTPUT_DIR, DIR_RUNS,
- )
- from datetime import datetime
env = os.environ.copy()
run_dir = str(Path(ws.path) / DIR_RUNS / f"run_{datetime.now().strftime('%Y%m%dT%H%M%S_%f')}")
@@ -416,15 +310,6 @@ def _build_exec_env(ws: WorkspaceInfo, extra: dict[str, str]) -> dict[str, str]:
return env
-def _resolve_abs_cwd(ws_path: str, rel_cwd: str) -> str:
- """Return the absolute cwd by joining *ws_path* and *rel_cwd*."""
- if rel_cwd and os.path.isabs(rel_cwd):
- return rel_cwd
- resolved = os.path.normpath(os.path.join(ws_path, rel_cwd or "."))
- os.makedirs(resolved, exist_ok=True)
- return resolved
-
-
# ---------------------------------------------------------------------------
# SkillExecTool (skill_exec)
# ---------------------------------------------------------------------------
@@ -442,7 +327,8 @@ def __init__(
self,
run_tool: SkillRunTool,
filters: Optional[List[BaseFilter]] = None,
- session_ttl: float = DEFAULT_SESSION_TTL,
+ session_ttl: float = DEFAULT_SESSION_TTL_SEC,
+ create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = None,
):
super().__init__(name="skill_exec",
description=("Start an interactive command inside a skill workspace. "
@@ -452,8 +338,8 @@ def __init__(
filters=filters)
self._run_tool = run_tool
self._ttl = session_ttl
+ self._create_ws_name_cb = create_ws_name_cb or default_create_ws_name_callback
self._sessions: dict[str, _ExecSession] = {}
- self._sessions_lock = asyncio.Lock()
# ------------------------------------------------------------------
# Declaration
@@ -461,8 +347,8 @@ def __init__(
@override
def _get_declaration(self) -> FunctionDeclaration:
- params_schema = _inline_json_schema_refs(ExecInput.model_json_schema())
- response_schema = _inline_json_schema_refs(ExecOutput.model_json_schema())
+ params_schema = inline_json_schema_refs(ExecInput.model_json_schema())
+ response_schema = inline_json_schema_refs(ExecOutput.model_json_schema())
return FunctionDeclaration(
name="skill_exec",
description=("Start an interactive command inside a skill workspace. "
@@ -476,37 +362,39 @@ def _get_declaration(self) -> FunctionDeclaration:
# Session management
# ------------------------------------------------------------------
- async def _put_session(self, sid: str, sess: _ExecSession) -> None:
- async with self._sessions_lock:
- await self._gc_expired_locked()
- self._sessions[sid] = sess
+ async def _put_session(self, sid: str, exec_session: _ExecSession) -> None:
+ await self._gc_expired_sessions()
+ self._sessions[sid] = exec_session
- async def get_session(self, sid: str) -> _ExecSession:
- async with self._sessions_lock:
- await self._gc_expired_locked()
- sess = self._sessions.get(sid)
- if sess is None:
+ async def _get_session(self, sid: str) -> _ExecSession:
+ await self._gc_expired_sessions()
+ session = self._sessions.get(sid)
+ if session is None:
raise ValueError(f"unknown session_id: {sid}")
- return sess
+ return session
- async def remove_session(self, sid: str) -> _ExecSession:
- async with self._sessions_lock:
- await self._gc_expired_locked()
- sess = self._sessions.pop(sid, None)
- if sess is None:
+ async def _remove_session(self, sid: str) -> _ExecSession:
+ await self._gc_expired_sessions()
+ session = self._sessions.pop(sid, None)
+ if session is None:
raise ValueError(f"unknown session_id: {sid}")
- return sess
-
- async def _gc_expired_locked(self) -> None:
- if self._ttl <= 0:
- return
- now = time.time()
- expired = [
- sid for sid, s in self._sessions.items() if s.exited_at is not None and (now - s.exited_at) >= self._ttl
- ]
- for sid in expired:
- s = self._sessions.pop(sid)
- _close_session(s)
+ return session
+
+ async def _gc_expired_sessions(self) -> None:
+
+ async def _refresh_exit_state(session: _ExecSession, now: float) -> None:
+ if session.exited_at is not None:
+ return
+ session_state = await session.proc.state()
+ if session_state.status == PROGRAM_STATUS_EXITED:
+ session.exited_at = now
+
+ await cleanup_expired_sessions(
+ self._sessions,
+ ttl=self._ttl,
+ refresh_exit_state=_refresh_exit_state,
+ close_session=_close_session,
+ )
# ------------------------------------------------------------------
# Main execution
@@ -523,26 +411,30 @@ async def _run_async_impl(
inputs = ExecInput.model_validate(args)
except Exception as ex: # pylint: disable=broad-except
raise ValueError(f"Invalid skill_exec arguments: {ex}") from ex
+ normalized_skill = inputs.skill.strip()
+ normalized_command = inputs.command.strip()
+ if not normalized_skill or not normalized_command:
+ raise ValueError("skill and command are required")
+ inputs = inputs.model_copy(update={"skill": normalized_skill, "command": normalized_command})
+
+ if self._run_tool.require_skill_loaded and not self._run_tool._is_skill_loaded(tool_context, normalized_skill):
+ raise ValueError(f"skill_exec requires skill_load first for {normalized_skill!r}")
repository = self._run_tool._get_repository(tool_context)
# Workspace creation
- session_id_ws = inputs.skill
- if tool_context.session and tool_context.session.id:
- session_id_ws = tool_context.session.id
-
workspace_runtime = repository.workspace_runtime
manager = workspace_runtime.manager(tool_context)
- ws = await manager.create_workspace(session_id_ws, tool_context)
+ workspace_id = self._create_ws_name_cb(tool_context)
+ ws = await manager.create_workspace(workspace_id, tool_context)
# Stage skill via the same pluggable stager used by SkillRunTool
stage_result = await self._run_tool.skill_stager.stage_skill(
SkillStageRequest(
- skill_name=inputs.skill,
+ skill_name=normalized_skill,
repository=repository,
workspace=ws,
ctx=tool_context,
- engine=workspace_runtime,
timeout=self._run_tool._timeout,
))
workspace_skill_dir = stage_result.workspace_skill_dir
@@ -553,29 +445,35 @@ async def _run_async_impl(
# Resolve cwd and env
rel_cwd = self._run_tool._resolve_cwd(inputs.cwd, workspace_skill_dir)
- abs_cwd = _resolve_abs_cwd(ws.path, rel_cwd)
extra_env: dict[str, str] = dict(inputs.env)
if ENV_SKILL_NAME not in extra_env:
- extra_env[ENV_SKILL_NAME] = inputs.skill
+ extra_env[ENV_SKILL_NAME] = normalized_skill
merged_env = _build_exec_env(ws, extra_env)
- # Start subprocess
+ # Start interactive program session via runtime runner.
+ runner = workspace_runtime.runner(tool_context)
+ start_program = getattr(runner, "start_program", None)
+ if start_program is None:
+ raise ValueError("skill_exec is not supported by the current executor")
sid = str(uuid.uuid4())
- sess = await _start_session(inputs, ws, abs_cwd, merged_env)
- await self._put_session(sid, sess)
-
- # Write initial stdin if provided
- if inputs.stdin:
- await _write_stdin(sess, inputs.stdin, submit=False)
+ exec_session = await _start_session(
+ runner=runner,
+ tool_context=tool_context,
+ inputs=inputs,
+ ws=ws,
+ rel_cwd=rel_cwd,
+ env=merged_env,
+ )
+ await self._put_session(sid, exec_session)
- yield_ms = inputs.yield_ms or DEFAULT_EXEC_YIELD_MS
- status, chunk, offset, next_offset = await sess.yield_output(yield_ms, inputs.poll_lines)
+ yield_time_ms = inputs.yield_time_ms or DEFAULT_EXEC_YIELD_MS
+ status, chunk, offset, next_offset = await exec_session.yield_output(yield_time_ms, inputs.poll_lines)
# Attempt to collect final result if already exited
final_result = None
- if status == _STATUS_EXITED and not sess.finalized:
- final_result = await _collect_final_result(tool_context, sess, self._run_tool)
+ if status == _STATUS_EXITED and not exec_session.finalized:
+ final_result = await _collect_final_result(tool_context, exec_session, self._run_tool)
out = ExecOutput(
status=status,
@@ -583,10 +481,11 @@ async def _run_async_impl(
output=chunk,
offset=offset,
next_offset=next_offset,
- exit_code=sess.exit_code,
+ exit_code=exec_session.exit_code,
interaction=_detect_interaction(status, chunk),
result=final_result,
)
+ _apply_artifacts_state_delta(tool_context, out)
return out.model_dump(exclude_none=True)
@@ -613,8 +512,8 @@ def __init__(self, exec_tool: SkillExecTool, filters: Optional[List[BaseFilter]]
@override
def _get_declaration(self) -> FunctionDeclaration:
- params_schema = _inline_json_schema_refs(WriteStdinInput.model_json_schema())
- response_schema = _inline_json_schema_refs(ExecOutput.model_json_schema())
+ params_schema = inline_json_schema_refs(WriteStdinInput.model_json_schema())
+ response_schema = inline_json_schema_refs(ExecOutput.model_json_schema())
return FunctionDeclaration(
name="skill_write_stdin",
description=("Write to a running skill_exec session. Set submit=true to "
@@ -635,29 +534,32 @@ async def _run_async_impl(
inputs = WriteStdinInput.model_validate(args)
except Exception as ex: # pylint: disable=broad-except
raise ValueError(f"Invalid skill_write_stdin arguments: {ex}") from ex
+ normalized_session_id = require_non_empty(inputs.session_id, field_name="session_id")
+ inputs = inputs.model_copy(update={"session_id": normalized_session_id})
- sess = await self._exec.get_session(inputs.session_id)
+ exec_session = await self._exec._get_session(inputs.session_id)
if inputs.chars or inputs.submit:
- await _write_stdin(sess, inputs.chars, submit=inputs.submit)
+ await _write_stdin(exec_session, inputs.chars, submit=inputs.submit)
- yield_ms = inputs.yield_ms or DEFAULT_IO_YIELD_MS
- status, chunk, offset, next_offset = await sess.yield_output(yield_ms, inputs.poll_lines)
+ yield_time_ms = inputs.yield_time_ms or DEFAULT_IO_YIELD_MS
+ status, chunk, offset, next_offset = await exec_session.yield_output(yield_time_ms, inputs.poll_lines)
final_result = None
- if status == _STATUS_EXITED and not sess.finalized:
- final_result = await _collect_final_result(tool_context, sess, self._exec._run_tool)
+ if status == _STATUS_EXITED and not exec_session.finalized:
+ final_result = await _collect_final_result(tool_context, exec_session, self._exec._run_tool)
out = ExecOutput(
status=status,
- session_id=inputs.session_id,
+ session_id=normalized_session_id,
output=chunk,
offset=offset,
next_offset=next_offset,
- exit_code=sess.exit_code,
+ exit_code=exec_session.exit_code,
interaction=_detect_interaction(status, chunk),
result=final_result,
)
+ _apply_artifacts_state_delta(tool_context, out)
return out.model_dump(exclude_none=True)
@@ -678,8 +580,8 @@ def __init__(self, exec_tool: SkillExecTool, filters: Optional[List[BaseFilter]]
@override
def _get_declaration(self) -> FunctionDeclaration:
- params_schema = _inline_json_schema_refs(PollSessionInput.model_json_schema())
- response_schema = _inline_json_schema_refs(ExecOutput.model_json_schema())
+ params_schema = inline_json_schema_refs(PollSessionInput.model_json_schema())
+ response_schema = inline_json_schema_refs(ExecOutput.model_json_schema())
return FunctionDeclaration(
name="skill_poll_session",
description=("Poll a running or recently exited skill_exec session for "
@@ -699,26 +601,29 @@ async def _run_async_impl(
inputs = PollSessionInput.model_validate(args)
except Exception as ex: # pylint: disable=broad-except
raise ValueError(f"Invalid skill_poll_session arguments: {ex}") from ex
+ normalized_session_id = require_non_empty(inputs.session_id, field_name="session_id")
+ inputs = inputs.model_copy(update={"session_id": normalized_session_id})
- sess = await self._exec.get_session(inputs.session_id)
+ exec_session = await self._exec._get_session(inputs.session_id)
- yield_ms = inputs.yield_ms or DEFAULT_IO_YIELD_MS
- status, chunk, offset, next_offset = await sess.yield_output(yield_ms, inputs.poll_lines)
+ yield_time_ms = inputs.yield_time_ms or DEFAULT_IO_YIELD_MS
+ status, chunk, offset, next_offset = await exec_session.yield_output(yield_time_ms, inputs.poll_lines)
final_result = None
- if status == _STATUS_EXITED and not sess.finalized:
- final_result = await _collect_final_result(tool_context, sess, self._exec._run_tool)
+ if status == _STATUS_EXITED and not exec_session.finalized:
+ final_result = await _collect_final_result(tool_context, exec_session, self._exec._run_tool)
out = ExecOutput(
status=status,
- session_id=inputs.session_id,
+ session_id=normalized_session_id,
output=chunk,
offset=offset,
next_offset=next_offset,
- exit_code=sess.exit_code,
+ exit_code=exec_session.exit_code,
interaction=_detect_interaction(status, chunk),
result=final_result,
)
+ _apply_artifacts_state_delta(tool_context, out)
return out.model_dump(exclude_none=True)
@@ -738,8 +643,8 @@ def __init__(self, exec_tool: SkillExecTool, filters: Optional[List[BaseFilter]]
@override
def _get_declaration(self) -> FunctionDeclaration:
- params_schema = _inline_json_schema_refs(KillSessionInput.model_json_schema())
- response_schema = _inline_json_schema_refs(SessionKillOutput.model_json_schema())
+ params_schema = inline_json_schema_refs(KillSessionInput.model_json_schema())
+ response_schema = inline_json_schema_refs(SessionKillOutput.model_json_schema())
return FunctionDeclaration(
name="skill_kill_session",
description="Terminate and remove a skill_exec session.",
@@ -758,25 +663,26 @@ async def _run_async_impl(
inputs = KillSessionInput.model_validate(args)
except Exception as ex: # pylint: disable=broad-except
raise ValueError(f"Invalid skill_kill_session arguments: {ex}") from ex
+ normalized_session_id = require_non_empty(inputs.session_id, field_name="session_id")
+ inputs = inputs.model_copy(update={"session_id": normalized_session_id})
+ exec_session = await self._exec._get_session(normalized_session_id)
- sess = await self._exec.remove_session(inputs.session_id)
-
- rc = sess.proc.returncode
final_status = _STATUS_EXITED
- if rc is None:
+ poll = await exec_session.proc.poll(None)
+ if poll.status == _STATUS_RUNNING:
try:
- sess.proc.kill()
- await asyncio.wait_for(sess.proc.wait(), timeout=5.0)
+ await exec_session.proc.kill(DEFAULT_SESSION_KILL_SEC)
except Exception: # pylint: disable=broad-except
pass
final_status = "killed"
- _close_session(sess)
+ await self._exec._remove_session(normalized_session_id)
+ await _close_session(exec_session)
out = SessionKillOutput(
ok=True,
- session_id=inputs.session_id,
+ session_id=normalized_session_id,
status=final_status,
)
return out.model_dump()
@@ -790,7 +696,7 @@ async def _run_async_impl(
def create_exec_tools(
run_tool: SkillRunTool,
filters: Optional[List[BaseFilter]] = None,
- session_ttl: float = DEFAULT_SESSION_TTL,
+ session_ttl: float = DEFAULT_SESSION_TTL_SEC,
) -> tuple[SkillExecTool, WriteStdinTool, PollSessionTool, KillSessionTool]:
"""Create the full set of interactive exec tools sharing one session store.
@@ -823,85 +729,46 @@ def create_exec_tools(
async def _start_session(
+ *,
+ runner: BaseProgramRunner,
+ tool_context: InvocationContext,
inputs: ExecInput,
ws: WorkspaceInfo,
- abs_cwd: str,
+ rel_cwd: str,
env: dict[str, str],
) -> _ExecSession:
- """Spawn a subprocess and return an initialized :class:`_ExecSession`."""
- command = inputs.command
- master_fd: Optional[int] = None
-
- if inputs.tty:
- # Allocate a pseudo-TTY.
- master_fd, slave_fd = pty.openpty()
- try:
- proc = await asyncio.create_subprocess_exec(
- "bash",
- "-c",
- command,
- stdin=slave_fd,
- stdout=slave_fd,
- stderr=slave_fd,
- cwd=abs_cwd,
- env=env,
- close_fds=True,
- preexec_fn=os.setsid,
- )
- finally:
- os.close(slave_fd) # parent doesn't need the slave end
-
- sess = _ExecSession(proc=proc, ws=ws, in_data=inputs, master_fd=master_fd)
- sess.reader_task = asyncio.create_task(_read_pty(sess, master_fd))
- else:
- proc = await asyncio.create_subprocess_exec(
- "bash",
- "-c",
- command,
- stdin=asyncio.subprocess.PIPE,
- stdout=asyncio.subprocess.PIPE,
- stderr=asyncio.subprocess.STDOUT,
- cwd=abs_cwd,
- env=env,
- )
- sess = _ExecSession(proc=proc, ws=ws, in_data=inputs)
- if proc.stdout:
- sess.reader_task = asyncio.create_task(_read_pipe(sess, proc.stdout))
-
- return sess
+ """Start a ProgramSession via runtime runner."""
+ spec = WorkspaceRunProgramSpec(
+ cmd="bash",
+ args=["-c", inputs.command],
+ env=env,
+ cwd=rel_cwd,
+ stdin=inputs.stdin,
+ timeout=float(inputs.timeout or 0),
+ tty=inputs.tty,
+ )
+ proc = await runner.start_program(tool_context, ws, spec)
+ return _ExecSession(proc=proc, ws=ws, in_data=inputs)
-async def _write_stdin(sess: _ExecSession, chars: str, submit: bool) -> None:
+async def _write_stdin(exec_session: _ExecSession, chars: str, submit: bool) -> None:
"""Write *chars* (and optionally a newline) to the session's stdin."""
- if sess.master_fd is not None:
- # PTY path: write to master fd
- data = (chars + ("\n" if submit else "")).encode("utf-8")
- if data:
- try:
- os.write(sess.master_fd, data)
- except OSError as ex:
- logger.debug("skill_exec: write to pty failed: %s", ex)
- elif sess.proc.stdin:
- # Pipe path: use asyncio StreamWriter
- data = (chars + ("\n" if submit else "")).encode("utf-8")
- if data:
- try:
- sess.proc.stdin.write(data)
- await sess.proc.stdin.drain()
- except Exception as ex: # pylint: disable=broad-except
- logger.debug("skill_exec: write to stdin failed: %s", ex)
+ try:
+ await exec_session.proc.write(chars, submit)
+ except Exception as ex: # pylint: disable=broad-except
+ logger.debug("skill_exec: write to stdin failed: %s", ex)
async def _collect_final_result(
ctx: InvocationContext,
- sess: _ExecSession,
+ exec_session: _ExecSession,
run_tool: SkillRunTool,
) -> Optional[SkillRunOutput]:
"""Collect output files and build the final :class:`SkillRunOutput`."""
- if sess.finalized:
- return sess.final_result
+ if exec_session.finalized:
+ return exec_session.final_result
- in_data = sess.in_data
+ in_data = exec_session.in_data
fake_run_input = SkillRunInput(
skill=in_data.skill,
command=in_data.command,
@@ -916,13 +783,19 @@ async def _collect_final_result(
outputs=in_data.outputs,
)
try:
- files, manifest = await run_tool._prepare_outputs(ctx, sess.ws, fake_run_input)
+ files, manifest = await run_tool._prepare_outputs(ctx, exec_session.ws, fake_run_input)
except Exception as ex: # pylint: disable=broad-except
logger.warning("skill_exec: collect outputs failed: %s", ex)
files, manifest = [], None
- total_out = await sess.total_output()
- exit_code = sess.exit_code or 0
+ try:
+ run_result = await exec_session.proc.run_result()
+ total_out = (run_result.stdout or "") + (run_result.stderr or "")
+ exit_code = run_result.exit_code
+ except Exception: # pylint: disable=broad-except
+ run_log = await exec_session.proc.log(None, None)
+ total_out = run_log.output or ""
+ exit_code = exec_session.exit_code or 0
# Reuse the same output-quality helpers as skill_run
warnings: list[str] = []
@@ -944,30 +817,21 @@ async def _collect_final_result(
)
try:
- await run_tool._attach_artifacts_if_requested(ctx, sess.ws, fake_run_input, result, files)
+ await run_tool._attach_artifacts_if_requested(ctx, exec_session.ws, fake_run_input, result, files)
except Exception as ex: # pylint: disable=broad-except
logger.warning("skill_exec: attach artifacts failed: %s", ex)
if manifest:
run_tool._merge_manifest_artifact_refs(manifest, result)
- sess.final_result = result
- sess.finalized = True
+ exec_session.final_result = result
+ exec_session.finalized = True
return result
-def _close_session(sess: _ExecSession) -> None:
- """Cancel background tasks and close any open fds."""
- if sess.reader_task and not sess.reader_task.done():
- sess.reader_task.cancel()
- if sess.master_fd is not None:
- try:
- os.close(sess.master_fd)
- except OSError:
- pass
- sess.master_fd = None
- if sess.proc.stdin and not sess.proc.stdin.is_closing():
- try:
- sess.proc.stdin.close()
- except Exception: # pylint: disable=broad-except
- pass
+async def _close_session(exec_session: _ExecSession) -> None:
+ """Release program session resources."""
+ try:
+ await exec_session.proc.close()
+ except Exception: # pylint: disable=broad-except
+ pass
diff --git a/trpc_agent_sdk/skills/tools/_skill_list.py b/trpc_agent_sdk/skills/tools/_skill_list.py
index 83d0903..1bfa72e 100644
--- a/trpc_agent_sdk/skills/tools/_skill_list.py
+++ b/trpc_agent_sdk/skills/tools/_skill_list.py
@@ -8,8 +8,8 @@
from __future__ import annotations
-from typing import Optional
from typing import Literal
+from typing import Optional
from trpc_agent_sdk.context import InvocationContext
@@ -17,16 +17,16 @@
from .._repository import BaseSkillRepository
-def skill_list(tool_context: InvocationContext, mode: Literal["all", "enabled", "disabled"] = "all") -> list[str]:
+def skill_list(tool_context: InvocationContext, mode: Literal['all', 'available'] = 'all') -> list[str]:
"""List all discovered skills.
Args:
tool_context: The tool context.
-
+ mode: The mode to list skills.
Returns:
A list of skill names.
"""
repository: Optional[BaseSkillRepository] = tool_context.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
if repository is None:
raise ValueError("repository not found")
- return repository.skill_list()
+ return repository.skill_list(mode)
diff --git a/trpc_agent_sdk/skills/tools/_skill_list_docs.py b/trpc_agent_sdk/skills/tools/_skill_list_docs.py
index f1e82e9..02f4abb 100644
--- a/trpc_agent_sdk/skills/tools/_skill_list_docs.py
+++ b/trpc_agent_sdk/skills/tools/_skill_list_docs.py
@@ -8,32 +8,33 @@
from __future__ import annotations
-from typing import Any
from typing import Optional
from trpc_agent_sdk.context import InvocationContext
-from trpc_agent_sdk.log import logger
from .._constants import SKILL_REPOSITORY_KEY
from .._repository import BaseSkillRepository
-def skill_list_docs(tool_context: InvocationContext, skill_name: str) -> dict[str, Any]:
+def skill_list_docs(tool_context: InvocationContext, skill_name: str) -> list[str]:
"""List doc filenames for a skill.
+
Args:
- skill_name: The name of the skill to load.
+ skill_name: The name of the skill.
Returns:
- Object containing docs list and whether SKILL.md body is loaded.
+ Array of doc filenames.
"""
+ normalized_skill = (skill_name or "").strip()
+ if not normalized_skill:
+ raise ValueError("skill is required")
+
repository: Optional[BaseSkillRepository] = tool_context.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
if repository is None:
- raise ValueError("repository not found")
- skill = repository.get(skill_name)
- if skill is None:
- logger.error("Skill %s not found", repr(skill_name))
- return {"docs": [], "body_loaded": False}
- return {
- "docs": [resource.path for resource in skill.resources],
- "body_loaded": bool(skill.body),
- }
+ return []
+
+ try:
+ skill = repository.get(normalized_skill)
+ except ValueError as ex:
+ raise ValueError(f"unknown skill: {normalized_skill}") from ex
+ return [resource.path for resource in (skill.resources or [])]
diff --git a/trpc_agent_sdk/skills/tools/_skill_list_tool.py b/trpc_agent_sdk/skills/tools/_skill_list_tool.py
index 4ecfbb2..942d127 100644
--- a/trpc_agent_sdk/skills/tools/_skill_list_tool.py
+++ b/trpc_agent_sdk/skills/tools/_skill_list_tool.py
@@ -1,4 +1,4 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+# -*- coding: utf-8 -*-
#
# Copyright (C) 2026 Tencent. All rights reserved.
#
@@ -9,7 +9,6 @@
from __future__ import annotations
-import re
from typing import Any
from typing import Optional
@@ -20,63 +19,13 @@
from .._repository import BaseSkillRepository
-def _extract_shell_examples_from_skill_body(body: str, limit: int = 5) -> list[str]:
- """Extract likely runnable command examples from SKILL.md body."""
- if not body:
- return []
- out: list[str] = []
- seen: set[str] = set()
- lines = body.splitlines()
-
- def maybe_add(cmd: str) -> None:
- cmd = re.sub(r"\s+", " ", (cmd or "").strip())
- if not cmd or cmd in seen:
- return
- if not re.match(r"^[A-Za-z0-9_./$\"'`-]", cmd):
- return
- seen.add(cmd)
- out.append(cmd)
-
- i = 0
- while i < len(lines) and len(out) < limit:
- cur = lines[i].strip()
- if cur.lower() != "command:":
- i += 1
- continue
- i += 1
- block: list[str] = []
- while i < len(lines):
- raw = lines[i]
- s = raw.strip()
- if not s:
- if block:
- break
- i += 1
- continue
- if s.lower() in ("command:", "output files", "overview", "examples", "tools:"):
- break
- if re.match(r"^\d+\)", s):
- break
- if raw.startswith(" ") or raw.startswith("\t"):
- block.append(s)
- i += 1
- continue
- if block:
- break
- i += 1
- if block:
- merged = " ".join(part.rstrip("\\").strip() for part in block)
- maybe_add(merged)
- return out
-
-
def skill_list_tools(tool_context: InvocationContext, skill_name: str) -> dict[str, Any]:
- """List executable guidance for a skill.
+ """List callable tools declared for a skill.
Args:
skill_name: The name of the skill to load.
Returns:
- Object containing declared tools and command examples from SKILL.md.
+ Object containing available tools.
"""
repository: Optional[BaseSkillRepository] = tool_context.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
if repository is None:
@@ -84,8 +33,5 @@ def skill_list_tools(tool_context: InvocationContext, skill_name: str) -> dict[s
skill = repository.get(skill_name)
if skill is None:
logger.error("Skill %s not found", repr(skill_name))
- return {"tools": [], "command_examples": []}
- return {
- "tools": list(skill.tools or []),
- "command_examples": _extract_shell_examples_from_skill_body(skill.body, limit=5),
- }
+ return {"available_tools": []}
+ return {"available_tools": list(skill.tools or [])}
diff --git a/trpc_agent_sdk/skills/tools/_skill_load.py b/trpc_agent_sdk/skills/tools/_skill_load.py
index ec2c62c..3579d31 100644
--- a/trpc_agent_sdk/skills/tools/_skill_load.py
+++ b/trpc_agent_sdk/skills/tools/_skill_load.py
@@ -1,4 +1,4 @@
-# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+# -*- coding: utf-8 -*-
#
# Copyright (C) 2026 Tencent. All rights reserved.
#
@@ -12,65 +12,138 @@
import json
from typing import Any
+from typing import List
from typing import Optional
+from typing_extensions import override
from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.filter import BaseFilter
+from trpc_agent_sdk.tools import BaseTool
+from trpc_agent_sdk.types import FunctionDeclaration
+from trpc_agent_sdk.types import Schema
+from trpc_agent_sdk.types import Type
-from .._constants import SKILL_DOCS_STATE_KEY_PREFIX
-from .._constants import SKILL_LOADED_STATE_KEY_PREFIX
-from .._constants import SKILL_REPOSITORY_KEY
-from .._constants import SKILL_TOOLS_STATE_KEY_PREFIX
+from .._common import append_loaded_order_state_delta
+from .._common import docs_state_key
+from .._common import loaded_state_key
+from .._common import set_state_delta
+from .._common import tool_state_key
from .._repository import BaseSkillRepository
+from .._types import Skill
+from ..stager import SkillStageRequest
+from ..stager import Stager
+from ._common import CreateWorkspaceNameCallback
+from ._common import default_create_ws_name_callback
+from ._common import set_staged_workspace_dir
+from ._copy_stager import CopySkillStager
-def _set_state_delta(invocation_context: InvocationContext, key: str, value: Any) -> None:
- """Set the state delta of a skill loaded."""
- invocation_context.actions.state_delta[key] = value
+class SkillLoadTool(BaseTool):
+ """Tool for loading a skill."""
+ def __init__(
+ self,
+ repository: BaseSkillRepository,
+ skill_stager: Optional[Stager] = None,
+ create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = None,
+ filters: Optional[List[BaseFilter]] = None,
+ ):
+ super().__init__(name="skill_load", description="Load a skill.", filters=filters)
+ self._repository = repository
+ self._skill_stager: Stager = skill_stager or CopySkillStager()
+ self._create_ws_name_cb: Optional[
+ CreateWorkspaceNameCallback] = create_ws_name_cb or default_create_ws_name_callback
-def _set_state_delta_for_skill_load(invocation_context: InvocationContext,
- skill_name: str,
- docs: list[str],
- include_all_docs: bool = False) -> None:
- """Set the state delta of a skill loaded."""
- key = f"{SKILL_LOADED_STATE_KEY_PREFIX}{skill_name}"
- _set_state_delta(invocation_context, key, True)
- key = f"{SKILL_DOCS_STATE_KEY_PREFIX}{skill_name}"
- if include_all_docs:
- _set_state_delta(invocation_context, key, '*')
- else:
- _set_state_delta(invocation_context, key, json.dumps(docs or []))
+ @override
+ def _get_declaration(self) -> Optional[FunctionDeclaration]:
+ return FunctionDeclaration(
+ name="skill_load",
+ description=("Load a skill body and optional docs. Safe to call multiple times to add or replace docs. "
+ "Do not call this to list skills; names and descriptions are already in context. "
+ "Use when a task needs a skill's SKILL.md body and selected docs in context."),
+ parameters=Schema(
+ type=Type.OBJECT,
+ required=["skill_name"],
+ properties={
+ "skill_name":
+ Schema(type=Type.STRING, description="The name of the skill to load."),
+ "docs":
+ Schema(type=Type.ARRAY,
+ default=None,
+ items=Schema(type=Type.STRING),
+ description="The docs of the skill to load."),
+ "include_all_docs":
+ Schema(type=Type.BOOLEAN, default=False, description="Whether to include all docs of the skill."),
+ },
+ ),
+ response=Schema(type=Type.STRING,
+ description="Result of skill_load. message is a string indicating the skill was loaded."),
+ )
+ @override
+ async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> str:
+ if not (args["skill_name"] or "").strip():
+ raise ValueError("skill_name is required")
+ skill_name = args["skill_name"]
+ docs = args.get("docs", [])
+ include_all_docs = args.get("include_all_docs", False)
+ normalized_skill = skill_name.strip()
+ skill = self._repository.get(normalized_skill)
+ await self._ensure_staged(ctx=tool_context, skill_name=skill_name)
+ clean_docs = [doc.strip() for doc in (docs or []) if isinstance(doc, str) and doc.strip()]
+ self.__set_state_delta_for_skill_load(tool_context, skill_name, clean_docs, include_all_docs)
+ if skill.tools:
+ self.__set_state_delta_for_skill_tools(tool_context, skill)
+ return f"skill {skill_name!r} loaded"
-def _set_state_delta_for_skill_tools(invocation_context: InvocationContext, skill_name: str, tools: list[str]) -> None:
- """Set the state delta of a skill tools."""
- key = f"{SKILL_TOOLS_STATE_KEY_PREFIX}{skill_name}"
- _set_state_delta(invocation_context, key, json.dumps(tools or []))
+ async def _ensure_staged(self, *, ctx: InvocationContext, skill_name: str) -> None:
+ runtime = self._repository.workspace_runtime
+ manager = runtime.manager(ctx)
+ ws_id = self._create_ws_name_cb(ctx)
+ ws = await manager.create_workspace(ws_id, ctx)
+ result = await self._skill_stager.stage_skill(
+ SkillStageRequest(skill_name=skill_name, repository=self._repository, workspace=ws, ctx=ctx))
+ set_staged_workspace_dir(ctx, skill_name, result.workspace_skill_dir)
+ def __set_state_delta_for_skill_load(self,
+ invocation_context: InvocationContext,
+ skill_name: str,
+ docs: list[str],
+ include_all_docs: bool = False) -> None:
+ """Set state delta for skill_load, aligned with Go StateDeltaForInvocation."""
+ agent_name = invocation_context.agent_name.strip()
+ delta, normalized_skill = self.__build_state_delta_for_skill_load(
+ invocation_context=invocation_context,
+ skill_name=skill_name,
+ docs=docs,
+ include_all_docs=include_all_docs,
+ )
+ invocation_context.actions.state_delta.update(delta)
+ append_loaded_order_state_delta(invocation_context, agent_name, normalized_skill)
-def skill_load(tool_context: InvocationContext,
- skill_name: str,
- docs: Optional[list[str]] = None,
- include_all_docs: bool = False) -> str:
- """Load a skill body and optional docs. Safe to call multiple times to add or replace docs.
- Do not call this to list skills; names and descriptions are already in context.
- Use when a task needs a skill's SKILL.md body and selected docs in context.
- Args:
- skill_name: The name of the skill to load.
- docs: The docs of the skill to load.
- include_all_docs: Whether to include all docs of the skill.
+ def __build_state_delta_for_skill_load(
+ self,
+ invocation_context: InvocationContext,
+ skill_name: str,
+ docs: list[str],
+ include_all_docs: bool = False,
+ ) -> tuple[dict[str, Any], str]:
+ """Build skill_load state delta."""
+ normalized_skill = skill_name.strip()
+ if not normalized_skill:
+ return {}, ""
+ delta: dict[str, Any] = {}
+ delta[loaded_state_key(invocation_context, normalized_skill)] = True
+ if include_all_docs:
+ delta[docs_state_key(invocation_context, normalized_skill)] = '*'
+ else:
+ delta[docs_state_key(invocation_context, normalized_skill)] = json.dumps(docs or [])
+ return delta, normalized_skill
- Returns:
- A message indicating the skill was loaded.
- """
-
- repository: Optional[BaseSkillRepository] = tool_context.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
- if repository is None:
- raise ValueError("repository not found")
- skill = repository.get(skill_name)
- if skill is None:
- return f"skill {skill_name!r} not found"
- _set_state_delta_for_skill_load(tool_context, skill_name, docs or [], include_all_docs)
- if skill.tools:
- _set_state_delta_for_skill_tools(tool_context, skill_name, skill.tools)
- return f"skill {skill_name!r} loaded"
+ def __set_state_delta_for_skill_tools(self, invocation_context: InvocationContext, skill: Skill) -> None:
+ """Set the state delta of a skill tools."""
+ normalized_skill = skill.summary.name.strip()
+ if not normalized_skill:
+ return
+ key = tool_state_key(invocation_context, normalized_skill)
+ set_state_delta(invocation_context, key, json.dumps(skill.tools))
diff --git a/trpc_agent_sdk/skills/tools/_skill_run.py b/trpc_agent_sdk/skills/tools/_skill_run.py
index 23ac4fa..01dcdc8 100644
--- a/trpc_agent_sdk/skills/tools/_skill_run.py
+++ b/trpc_agent_sdk/skills/tools/_skill_run.py
@@ -3,19 +3,12 @@
# Copyright (C) 2026 Tencent. All rights reserved.
#
# tRPC-Agent-Python is licensed under Apache-2.0.
-"""Skill run tool for executing commands in skill workspaces.
-
-This module provides the SkillRunTool class which allows LLM to execute commands
-inside a skill workspace. It stages the entire skill directory and runs commands,
-aligned with the Go implementation at:
-https://github.com/trpc-group/trpc-agent-go/blob/main/tool/skill/run.go
-"""
+"""Skill run tool for executing commands in skill workspaces."""
from __future__ import annotations
import os
-import re
-import shlex
+import posixpath
from pathlib import Path
from typing import Any
from typing import Dict
@@ -45,12 +38,19 @@
from trpc_agent_sdk.types import Part
from trpc_agent_sdk.types import Schema
-from .._constants import SKILL_LOADED_STATE_KEY_PREFIX
+from .._common import get_state_delta_value
+from .._common import loaded_state_key
+from .._constants import SKILL_ARTIFACTS_STATE_KEY
from .._constants import SKILL_REPOSITORY_KEY
from .._repository import BaseSkillRepository
from .._utils import shell_quote
from ..stager import SkillStageRequest
from ..stager import Stager
+from ..stager import default_workspace_skill_dir
+from ._common import CreateWorkspaceNameCallback
+from ._common import default_create_ws_name_callback
+from ._common import get_staged_workspace_dir
+from ._common import inline_json_schema_refs
from ._copy_stager import CopySkillStager
# ---------------------------------------------------------------------------
@@ -68,7 +68,7 @@
_ENV_EDITOR = "EDITOR"
_ENV_VISUAL = "VISUAL"
-_EDITOR_HELPER_DIR = ".trpc_agent_sdk"
+_EDITOR_HELPER_DIR = ".trpc_agent"
_EDITOR_CONTENT_FILE = "editor_input.txt"
_EDITOR_SCRIPT_FILE = "editor_write.sh"
@@ -115,35 +115,6 @@
# ---------------------------------------------------------------------------
-def _inline_json_schema_refs(schema: dict[str, Any]) -> dict[str, Any]:
- """Inline $ref references in JSON Schema by replacing them with actual definitions."""
- defs = schema.get('$defs', {})
- if not defs:
- return schema
-
- def resolve_ref(obj: Any) -> Any:
- if isinstance(obj, dict):
- if '$ref' in obj:
- ref_path = obj['$ref']
- if ref_path.startswith('#/$defs/'):
- ref_name = ref_path.replace('#/$defs/', '')
- if ref_name in defs:
- resolved = resolve_ref(defs[ref_name])
- merged = {**resolved, **{k: v for k, v in obj.items() if k != '$ref'}}
- return merged
- return obj
- else:
- return {k: resolve_ref(v) for k, v in obj.items()}
- elif isinstance(obj, list):
- return [resolve_ref(item) for item in obj]
- else:
- return obj
-
- result = {k: v for k, v in schema.items() if k != '$defs'}
- result = resolve_ref(result)
- return result
-
-
def _is_text_mime(mime: str) -> bool:
"""Return True when *mime* is a text-like content type."""
if not mime:
@@ -176,6 +147,51 @@ def _workspace_ref(name: str) -> str:
return f"workspace://{name}" if name else ""
+def _normalize_input_dst(dst: str) -> str:
+ """Normalize declarative input destination like Go normalizeInputTo."""
+ s = (dst or "").strip().replace("\\", "/")
+ if not s:
+ return ""
+ cleaned = posixpath.normpath(s)
+ if cleaned in (".", "inputs"):
+ return ""
+ prefix = "inputs/"
+ if cleaned.startswith(prefix):
+ rest = cleaned[len(prefix):]
+ return posixpath.join(DIR_WORK, "inputs", rest)
+ return cleaned
+
+
+def _normalize_run_input(input_data: "SkillRunInput") -> "SkillRunInput":
+ """Normalize run input fields like Go normalizeRunInput."""
+ if not input_data.inputs:
+ return input_data
+ normalized_inputs: list[WorkspaceInputSpec] = []
+ for spec in input_data.inputs:
+ normalized_inputs.append(spec.model_copy(update={"dst": _normalize_input_dst(spec.dst)}))
+ return input_data.model_copy(update={"inputs": normalized_inputs})
+
+
+def _apply_run_artifacts_state_delta(ctx: InvocationContext, output: "SkillRunOutput") -> None:
+ """Write run artifact refs to state delta (Go RunTool.StateDelta parity)."""
+ tool_call_id = (ctx.function_call_id or "").strip()
+ if not tool_call_id or not output.artifact_files:
+ return
+ artifacts: list[dict[str, Any]] = []
+ for item in output.artifact_files:
+ name = (item.name or "").strip()
+ version = int(item.version)
+ if not name or version < 0:
+ continue
+ artifacts.append({"name": name, "version": version, "ref": f"artifact://{name}@{version}"})
+ if not artifacts:
+ return
+ ctx.actions.state_delta[SKILL_ARTIFACTS_STATE_KEY] = {
+ "tool_call_id": tool_call_id,
+ "artifacts": artifacts,
+ }
+
+
def _filter_failed_empty_outputs(
exit_code: int,
timed_out: bool,
@@ -215,7 +231,7 @@ def _split_command_line(cmd: str) -> list[str]:
raise ValueError("skill_run: command is empty")
for ch in _DISALLOWED_SHELL_META:
if ch in cmd:
- raise ValueError(f"skill_run: shell metacharacter {ch!r} is not allowed when "
+ raise ValueError(f"skill_run: shell meta character {ch!r} is not allowed when "
"command restrictions are enabled. Provide a single executable "
"with args only (no redirects/pipes/chaining).")
args: list[str] = []
@@ -345,16 +361,6 @@ class SkillRunOutput(BaseModel):
default_factory=list,
description="Non-fatal warnings about truncation, persistence, or empty outputs",
)
- suggested_commands: Optional[list[str]] = Field(
- default=None,
- description=("Suggested runnable commands extracted from SKILL.md when the provided "
- "command is not found."),
- )
- suggested_tools: Optional[list[str]] = Field(
- default=None,
- description=("Suggested tool names from SKILL.md Tools section when command-not-found "
- "indicates the request should use tool calls instead of shell execution."),
- )
# ---------------------------------------------------------------------------
@@ -375,11 +381,11 @@ def __init__(
filters: Optional[List[BaseFilter]] = None,
*,
require_skill_loaded: bool = False,
- block_inline_python_rewrite: bool = False,
force_save_artifacts: bool = False,
allowed_cmds: Optional[List[str]] = None,
denied_cmds: Optional[List[str]] = None,
skill_stager: Optional[Stager] = None,
+ create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = None,
**kwargs,
):
"""Initialize SkillRunTool.
@@ -389,9 +395,6 @@ def __init__(
filters: Optional tool filters.
require_skill_loaded: When True, skill_run raises unless skill_load was called first
for this skill in the current session.
- block_inline_python_rewrite: When True, reject ad-hoc ``python -c`` commands
- if SKILL.md already provides script-based python
- command examples (for example ``python3 scripts/foo.py``).
force_save_artifacts: When True, always attempt to persist collected output files
via the artifact service (if available).
allowed_cmds: When set, only these command names (first token) are allowed.
@@ -414,7 +417,6 @@ def __init__(
)
self._repository = repository
self._require_skill_loaded = require_skill_loaded
- self._block_inline_python_rewrite = block_inline_python_rewrite
self._force_save_artifacts = force_save_artifacts
self._allowed_cmds: frozenset[str] = frozenset(c.strip() for c in (allowed_cmds or []) if c.strip())
self._denied_cmds: frozenset[str] = frozenset(c.strip() for c in (denied_cmds or []) if c.strip())
@@ -429,10 +431,17 @@ def __init__(
self._kwargs = kwargs
self._run_tool_kwargs: dict = kwargs.pop("run_tool_kwargs", {})
self._timeout = self._run_tool_kwargs.pop("timeout", 300.0)
+ self._create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = \
+ create_ws_name_cb or default_create_ws_name_callback
# Staging strategy: default is copy-based stager (mirrors Go newCopySkillStager)
self._skill_stager: Stager = skill_stager or CopySkillStager()
+ @property
+ def require_skill_loaded(self) -> bool:
+ """Get the require_skill_loaded flag."""
+ return self._require_skill_loaded
+
@property
def skill_stager(self) -> Stager:
"""Get the skill stager."""
@@ -444,8 +453,8 @@ def skill_stager(self) -> Stager:
@override
def _get_declaration(self) -> FunctionDeclaration:
- params_schema = _inline_json_schema_refs(SkillRunInput.model_json_schema())
- response_schema = _inline_json_schema_refs(SkillRunOutput.model_json_schema())
+ params_schema = inline_json_schema_refs(SkillRunInput.model_json_schema())
+ response_schema = inline_json_schema_refs(SkillRunOutput.model_json_schema())
desc = ("Run a command inside a skill workspace. "
"Use it only for commands required by the skill docs (not for generic shell tasks). "
"User-uploaded file inputs are staged under $WORK_DIR/inputs (also visible as inputs/). "
@@ -482,11 +491,10 @@ def _get_repository(self, context: InvocationContext) -> BaseSkillRepository:
def _is_skill_loaded(self, ctx: InvocationContext, skill_name: str) -> bool:
"""Return True when the skill was loaded in the current session."""
try:
- key = f"{SKILL_LOADED_STATE_KEY_PREFIX}{skill_name.strip()}"
- val = ctx.session_state.get(key)
- return bool(val)
+ key = loaded_state_key(ctx, skill_name.strip())
+ return bool(get_state_delta_value(ctx, key))
except Exception: # pylint: disable=broad-except
- return True # default to allowed when state is not accessible
+ return False
# ------------------------------------------------------------------
# Editor helper
@@ -639,6 +647,10 @@ async def _run_async_impl(
inputs = SkillRunInput.model_validate(args)
except Exception as ex: # pylint: disable=broad-except
raise ValueError(f"Invalid skill_run arguments: {ex}") from ex
+ if not (inputs.skill or "").strip() or not (inputs.command or "").strip():
+ raise ValueError("skill and command are required")
+ inputs = inputs.model_copy(update={"skill": inputs.skill.strip(), "command": inputs.command.strip()})
+ inputs = _normalize_run_input(inputs)
# require_skill_loaded gate
if self._require_skill_loaded and not self._is_skill_loaded(tool_context, inputs.skill):
@@ -653,25 +665,27 @@ async def _run_async_impl(
repository = self._get_repository(tool_context)
- session_id = inputs.skill
- if tool_context.session and tool_context.session.id:
- session_id = tool_context.session.id
-
+ workspace_id = self._create_ws_name_cb(tool_context)
workspace_runtime = repository.workspace_runtime
manager = workspace_runtime.manager(tool_context)
- ws = await manager.create_workspace(session_id, tool_context)
-
- # Stage skill via the pluggable stager strategy
- stage_result = await self._skill_stager.stage_skill(
- SkillStageRequest(
- skill_name=inputs.skill,
- repository=repository,
- workspace=ws,
- ctx=tool_context,
- engine=workspace_runtime,
- timeout=self._timeout,
- ))
- workspace_skill_dir = stage_result.workspace_skill_dir
+ ws = await manager.create_workspace(workspace_id, tool_context)
+
+ # Static stage is handled by skill_load. Keep fallback staging here for
+ # backward compatibility when callers skip skill_load.
+ if self._is_skill_loaded(tool_context, inputs.skill):
+ workspace_skill_dir = get_staged_workspace_dir(tool_context, inputs.skill)
+ if not workspace_skill_dir:
+ workspace_skill_dir = default_workspace_skill_dir(inputs.skill)
+ else:
+ stage_result = await self._skill_stager.stage_skill(
+ SkillStageRequest(
+ skill_name=inputs.skill,
+ repository=repository,
+ workspace=ws,
+ ctx=tool_context,
+ timeout=self._timeout,
+ ))
+ workspace_skill_dir = stage_result.workspace_skill_dir
if inputs.inputs:
fs = workspace_runtime.fs(tool_context)
@@ -705,16 +719,6 @@ async def _run_async_impl(
# Select primary output
primary = _select_primary_output(files)
- suggested_commands = self._suggest_commands_for_missing_command(
- result,
- repository,
- inputs.skill,
- )
- suggested_tools = self._suggest_tools_for_missing_command(
- result,
- repository,
- inputs.skill,
- )
output = SkillRunOutput(
stdout=stdout,
@@ -725,20 +729,20 @@ async def _run_async_impl(
output_files=files,
primary_output=primary,
warnings=warnings,
- suggested_commands=suggested_commands,
- suggested_tools=suggested_tools,
)
await self._attach_artifacts_if_requested(tool_context, ws, inputs, output, files)
self._merge_manifest_artifact_refs(manifest, output)
# omit_inline_content
- if inputs.omit_inline_content and output.artifact_files:
+ if inputs.omit_inline_content:
for f in output.output_files:
f.content = ""
if output.primary_output:
output.primary_output.content = ""
+ _apply_run_artifacts_state_delta(tool_context, output)
+
return output.model_dump(exclude_none=True)
# ------------------------------------------------------------------
@@ -761,13 +765,15 @@ async def _run_program(
# Inject skill-specific env from repository (e.g. api_key → primary_env)
repository = self._get_repository(ctx)
try:
- skill_env: dict[str, str] = repository.skill_run_env(input_data.skill)
+ skill_env: dict[str, str] = repository.skill_run_env(ctx, input_data.skill)
for k, v in skill_env.items():
k = k.strip()
if not k or not v.strip():
continue
if k in env: # don't override explicit tool-call env
continue
+ if os.environ.get(k, "").strip(): # don't override host env
+ continue
if k.upper() in _BLOCKED_SKILL_ENV_KEYS:
continue
env[k] = v
@@ -778,9 +784,6 @@ async def _run_program(
await self._prepare_editor_env(ctx, ws, env, input_data.editor_text)
# Build command (with venv activation or command restrictions)
- blocked = self._precheck_inline_python_rewrite(repository, input_data)
- if blocked is not None:
- return blocked
cmd, cmd_args = self._build_command(input_data.command, ws.path, cwd)
workspace_runtime = repository.workspace_runtime
@@ -798,300 +801,10 @@ async def _run_program(
ctx,
)
if ret.exit_code != 0:
- ret = self._with_missing_command_hint(ret, input_data)
- ret = self._with_skill_doc_command_hint(ret, repository, input_data)
- ret = self._with_missing_entrypoint_hint(ret, input_data, ws, cwd)
- logger.info("Failed to run program: %s", ret.stderr)
+ raw_stderr = ret.stderr or ""
+ logger.info("Failed to run program: exit_code=%s, stderr=%s", ret.exit_code, raw_stderr.strip())
return ret
- def _precheck_inline_python_rewrite(
- self,
- repository: BaseSkillRepository,
- input_data: SkillRunInput,
- ) -> Optional[WorkspaceRunResult]:
- """Optionally block ad-hoc python -c when SKILL.md has script examples."""
- if not self._block_inline_python_rewrite:
- return None
- cmd = (input_data.command or "").strip()
- if not re.match(r"^python(?:\d+(?:\.\d+)?)?\s+-c\b", cmd):
- return None
- try:
- sk = repository.get(input_data.skill)
- except Exception: # pylint: disable=broad-except
- return None
- if sk is None:
- return None
- examples = self._extract_shell_examples_from_skill_body(sk.body, limit=8)
- script_examples = [
- e for e in examples if re.match(r"^python(?:\d+(?:\.\d+)?)?\s+scripts/[^\s]+(?:\s|$)", e.strip())
- ]
- if not script_examples:
- return None
- stderr = ("skill_run rejected this ad-hoc inline python command.\n"
- "This skill already provides script-based Python command examples in SKILL.md.\n"
- "Use one of these commands exactly instead of `python -c` rewrites:\n" +
- "\n".join(f"- {c}" for c in script_examples) + "\n")
- return WorkspaceRunResult(
- stdout="",
- stderr=stderr,
- exit_code=2,
- duration=0,
- timed_out=False,
- )
-
- @staticmethod
- def _with_missing_command_hint(ret: WorkspaceRunResult, input_data: SkillRunInput) -> WorkspaceRunResult:
- """Add a targeted hint when the shell command does not exist."""
- stderr_lower = (ret.stderr or "").lower()
- is_missing_cmd = ret.exit_code == 127 and ("command not found" in stderr_lower or
- "not recognized as an internal or external command" in stderr_lower)
- if not is_missing_cmd:
- return ret
- hint = ("\n\nSkill command hint:\n"
- f"- The command `{input_data.command}` was not found in this skill workspace.\n"
- "- Do not invent command names.\n"
- "- Read the loaded `SKILL.md` and execute one of its exact shell examples.\n"
- "- If needed, call `skill_load` first so the full skill body is injected "
- "before calling `skill_run`.\n")
- return ret.model_copy(update={"stderr": f"{ret.stderr}{hint}"})
-
- @staticmethod
- def _extract_shell_examples_from_skill_body(body: str, limit: int = 5) -> list[str]:
- """Extract likely runnable shell command lines from SKILL.md body."""
- if not body:
- return []
- out: list[str] = []
- seen: set[str] = set()
- lines = body.splitlines()
-
- def maybe_add(cmd: str) -> None:
- cmd = re.sub(r"\s+", " ", (cmd or "").strip())
- if not cmd:
- return
- if cmd in seen:
- return
- # Keep only command-like lines.
- if not re.match(r"^[A-Za-z0-9_./$\"'`-]", cmd):
- return
- # Skip function-style examples like tool_name(arg="..."), which are
- # LLM tool calls rather than shell commands.
- if re.match(r"^[A-Za-z_][A-Za-z0-9_]*\s*\(.*\)\s*$", cmd):
- return
- seen.add(cmd)
- out.append(cmd)
-
- # 1) Parse markdown fenced code blocks.
- in_fence = False
- for raw in lines:
- line = raw.strip()
- if line.startswith("```"):
- in_fence = not in_fence
- continue
- if not in_fence:
- continue
- if not line or line.startswith("#"):
- continue
- if line in ("PY", "EOF") or line.startswith(("-", "*")):
- continue
- maybe_add(line)
- if len(out) >= limit:
- return out
-
- # 2) Parse "Command:" sections with indented multi-line commands.
- i = 0
- while i < len(lines) and len(out) < limit:
- cur = lines[i].strip()
- if cur.lower() != "command:":
- i += 1
- continue
- i += 1
- block: list[str] = []
- while i < len(lines):
- raw = lines[i]
- s = raw.strip()
- if not s:
- if block:
- break
- i += 1
- continue
- # Next section marker
- if s.lower() in ("command:", "output files", "overview", "examples", "tools:"):
- break
- if re.match(r"^\d+\)", s):
- break
- # Command content is commonly indented in SKILL.md examples.
- if raw.startswith(" ") or raw.startswith("\t"):
- block.append(s)
- i += 1
- continue
- if block:
- break
- i += 1
- if block:
- merged = " ".join(part.rstrip("\\").strip() for part in block)
- maybe_add(merged)
- return out[:limit]
-
- def _with_skill_doc_command_hint(
- self,
- ret: WorkspaceRunResult,
- repository: BaseSkillRepository,
- input_data: SkillRunInput,
- ) -> WorkspaceRunResult:
- """Append SKILL.md command examples when command is not found."""
- stderr = ret.stderr or ""
- stderr_lower = stderr.lower()
- is_missing_cmd = ret.exit_code == 127 and ("command not found" in stderr_lower or
- "not recognized as an internal or external command" in stderr_lower)
- if not is_missing_cmd:
- return ret
- try:
- sk = repository.get(input_data.skill)
- except Exception: # pylint: disable=broad-except
- return ret
- examples = self._extract_shell_examples_from_skill_body(sk.body, limit=5)
- tools = list(getattr(sk, "tools", []) or [])
- if not examples and not tools:
- return ret
- hint_parts: list[str] = []
- if examples:
- hint_parts.append("\n\nSKILL.md command examples:\n" + "\n".join(f"- {cmd}" for cmd in examples) + "\n")
- if tools:
- hint_parts.append("\nSKILL.md tools suggest this is a tool-call workflow:\n" +
- "\n".join(f"- {name}" for name in tools) + "\n" +
- "- Do not run these tool names via `skill_run` shell commands.\n" +
- "- Call those tools directly (e.g. function/tool call) after `skill_load`.\n")
- hint = "".join(hint_parts)
- return ret.model_copy(update={"stderr": f"{stderr}{hint}"})
-
- @staticmethod
- def _is_missing_command_result(ret: WorkspaceRunResult) -> bool:
- """Return True when stderr indicates command-not-found failure."""
- stderr_lower = (ret.stderr or "").lower()
- return ret.exit_code == 127 and ("command not found" in stderr_lower
- or "not recognized as an internal or external command" in stderr_lower)
-
- def _suggest_commands_for_missing_command(
- self,
- ret: WorkspaceRunResult,
- repository: BaseSkillRepository,
- skill_name: str,
- ) -> Optional[list[str]]:
- """Return SKILL.md command suggestions for missing-command failures."""
- if not self._is_missing_command_result(ret):
- return None
- try:
- sk = repository.get(skill_name)
- except Exception: # pylint: disable=broad-except
- return None
- suggestions = self._extract_shell_examples_from_skill_body(sk.body, limit=5)
- return suggestions or None
-
- def _suggest_tools_for_missing_command(
- self,
- ret: WorkspaceRunResult,
- repository: BaseSkillRepository,
- skill_name: str,
- ) -> Optional[list[str]]:
- """Return SKILL.md tool names when command-not-found implies tool calls."""
- if not self._is_missing_command_result(ret):
- return None
- try:
- sk = repository.get(skill_name)
- except Exception: # pylint: disable=broad-except
- return None
- tools = list(getattr(sk, "tools", []) or [])
- return tools or None
-
- @staticmethod
- def _extract_command_path_candidates(command: str) -> list[str]:
- """Extract likely relative path tokens from a shell command."""
- try:
- tokens = shlex.split(command, posix=True)
- except ValueError:
- tokens = command.split()
- out: list[str] = []
- seen: set[str] = set()
- for tok in tokens:
- s = (tok or "").strip()
- if not s or s.startswith("-"):
- continue
- # Keep relative path-like tokens only.
- is_path_like = "/" in s or s.endswith((".py", ".sh", ".pl", ".rb", ".js", ".ts"))
- if not is_path_like or os.path.isabs(s):
- continue
- if s in seen:
- continue
- seen.add(s)
- out.append(s)
- return out
-
- @staticmethod
- def _list_entrypoint_suggestions(run_dir: Path, limit: int = 20) -> list[str]:
- """List likely runnable files from common locations under the current cwd."""
- suggestions: list[str] = []
- seen: set[str] = set()
- roots = [
- run_dir,
- run_dir / "scripts",
- run_dir / "bin",
- run_dir / "tools",
- ]
- for root in roots:
- try:
- if not root.is_dir():
- continue
- for p in sorted(root.rglob("*")):
- if len(suggestions) >= limit:
- return suggestions
- if not p.is_file():
- continue
- rel = p.relative_to(run_dir).as_posix()
- # Prefer obviously runnable entries.
- is_runnable = os.access(p.as_posix(), os.X_OK) or rel.endswith(
- (".py", ".sh", ".pl", ".rb", ".js", ".ts"))
- if not is_runnable or rel in seen:
- continue
- seen.add(rel)
- suggestions.append(rel)
- except Exception: # pylint: disable=broad-except
- continue
- return suggestions
-
- @staticmethod
- def _with_missing_entrypoint_hint(
- ret: WorkspaceRunResult,
- input_data: SkillRunInput,
- ws: WorkspaceInfo,
- cwd: str,
- ) -> WorkspaceRunResult:
- """Add a generic hint when command references missing relative entrypoints."""
- stderr = ret.stderr or ""
- stderr_lower = stderr.lower()
- if ret.exit_code == 0:
- return ret
- if "no such file or directory" not in stderr_lower and "can't open file" not in stderr_lower:
- return ret
- missing_candidates = SkillRunTool._extract_command_path_candidates(input_data.command)
- if not missing_candidates:
- return ret
-
- run_dir = Path(ws.path) / cwd
- # Show only candidates that are truly missing under cwd.
- missing = [p for p in missing_candidates if not (run_dir / p).exists()]
- if not missing:
- return ret
- available = SkillRunTool._list_entrypoint_suggestions(run_dir, limit=20)
- if not available:
- return ret
-
- hint = ("\n\nSkill entrypoint hint:\n"
- f"- Missing relative path(s) in command: {', '.join(f'`{m}`' for m in missing)}\n"
- f"- Runnable file candidates from current skill cwd: {', '.join(available)}\n"
- "- Do not invent file names or paths.\n"
- "- Read the loaded `SKILL.md` and run one of those commands exactly.\n")
- return ret.model_copy(update={"stderr": f"{stderr}{hint}"})
-
def _resolve_cwd(self, cwd: str, skill_dir: str) -> str:
"""Resolve the working directory relative to the workspace root.
diff --git a/trpc_agent_sdk/skills/tools/_skill_select_docs.py b/trpc_agent_sdk/skills/tools/_skill_select_docs.py
index ad5c756..1e07dc4 100644
--- a/trpc_agent_sdk/skills/tools/_skill_select_docs.py
+++ b/trpc_agent_sdk/skills/tools/_skill_select_docs.py
@@ -15,8 +15,14 @@
from trpc_agent_sdk.context import InvocationContext
from .._common import BaseSelectionResult
-from .._common import generic_select_items
-from .._constants import SKILL_DOCS_STATE_KEY_PREFIX
+from .._common import append_loaded_order_state_delta
+from .._common import docs_state_key
+from .._common import get_agent_name
+from .._common import get_previous_selection_by_key
+from .._common import normalize_selection_mode
+from .._common import set_selection_state_delta_by_key
+from .._constants import SKILL_REPOSITORY_KEY
+from .._repository import BaseSkillRepository
class SkillSelectDocsResult(BaseSelectionResult):
@@ -53,11 +59,58 @@ def skill_select_docs(tool_context: InvocationContext,
Returns:
A message indicating the docs were selected.
"""
- result = generic_select_items(tool_context=tool_context,
- skill_name=skill_name,
- items=docs,
- include_all=include_all_docs,
- mode=mode,
- state_key_prefix=SKILL_DOCS_STATE_KEY_PREFIX,
- result_class=SkillSelectDocsResult)
+ normalized_skill = (skill_name or "").strip()
+ if not normalized_skill:
+ raise ValueError("skill is required")
+ normalized_mode = normalize_selection_mode(mode)
+ agent_name = get_agent_name(tool_context)
+
+ repository: Optional[BaseSkillRepository] = tool_context.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
+ if repository is not None:
+ try:
+ _ = repository.get(normalized_skill)
+ except ValueError as ex:
+ raise ValueError(f"unknown skill: {normalized_skill}") from ex
+
+ docs_selection_key = docs_state_key(tool_context, normalized_skill)
+ previous_items, had_all = get_previous_selection_by_key(tool_context, docs_selection_key)
+ if had_all and normalized_mode != "clear":
+ result = SkillSelectDocsResult(
+ skill=normalized_skill,
+ selected_items=[],
+ include_all=True,
+ mode=normalized_mode,
+ )
+ elif normalized_mode == "clear":
+ result = SkillSelectDocsResult(
+ skill=normalized_skill,
+ selected_items=[],
+ include_all=False,
+ mode="clear",
+ )
+ elif normalized_mode == "add":
+ selected = set(previous_items)
+ for item in docs or []:
+ selected.add(item)
+ result = SkillSelectDocsResult(
+ skill=normalized_skill,
+ selected_items=[] if include_all_docs else list(selected),
+ include_all=include_all_docs,
+ mode="add",
+ )
+ else:
+ result = SkillSelectDocsResult(
+ skill=normalized_skill,
+ selected_items=[] if include_all_docs else list(docs or []),
+ include_all=include_all_docs,
+ mode="replace",
+ )
+
+ set_selection_state_delta_by_key(
+ tool_context,
+ docs_selection_key,
+ result.selected_docs,
+ result.include_all_docs,
+ )
+ append_loaded_order_state_delta(tool_context, agent_name, normalized_skill)
return result
diff --git a/trpc_agent_sdk/skills/tools/_skill_select_tools.py b/trpc_agent_sdk/skills/tools/_skill_select_tools.py
index 0c44b0f..f2e9745 100644
--- a/trpc_agent_sdk/skills/tools/_skill_select_tools.py
+++ b/trpc_agent_sdk/skills/tools/_skill_select_tools.py
@@ -15,8 +15,14 @@
from trpc_agent_sdk.context import InvocationContext
from .._common import BaseSelectionResult
-from .._common import generic_select_items
-from .._constants import SKILL_TOOLS_STATE_KEY_PREFIX
+from .._common import append_loaded_order_state_delta
+from .._common import get_agent_name
+from .._common import get_previous_selection_by_key
+from .._common import normalize_selection_mode
+from .._common import set_selection_state_delta_by_key
+from .._common import tool_state_key
+from .._constants import SKILL_REPOSITORY_KEY
+from .._repository import BaseSkillRepository
class SkillSelectToolsResult(BaseSelectionResult):
@@ -73,11 +79,58 @@ def skill_select_tools(tool_context: InvocationContext,
tools=["get_current_weather"],
mode="replace")
"""
- result = generic_select_items(tool_context=tool_context,
- skill_name=skill_name,
- items=tools,
- include_all=include_all_tools,
- mode=mode,
- state_key_prefix=SKILL_TOOLS_STATE_KEY_PREFIX,
- result_class=SkillSelectToolsResult)
+ normalized_skill = (skill_name or "").strip()
+ if not normalized_skill:
+ raise ValueError("skill is required")
+ normalized_mode = normalize_selection_mode(mode)
+ agent_name = get_agent_name(tool_context)
+
+ repository: Optional[BaseSkillRepository] = tool_context.agent_context.get_metadata(SKILL_REPOSITORY_KEY)
+ if repository is not None:
+ try:
+ _ = repository.get(normalized_skill)
+ except ValueError as ex:
+ raise ValueError(f"unknown skill: {normalized_skill}") from ex
+
+ tools_selection_key = tool_state_key(tool_context, normalized_skill)
+ previous_items, had_all = get_previous_selection_by_key(tool_context, tools_selection_key)
+ if had_all and normalized_mode != "clear":
+ result = SkillSelectToolsResult(
+ skill=normalized_skill,
+ selected_items=[],
+ include_all=True,
+ mode=normalized_mode,
+ )
+ elif normalized_mode == "clear":
+ result = SkillSelectToolsResult(
+ skill=normalized_skill,
+ selected_items=[],
+ include_all=False,
+ mode="clear",
+ )
+ elif normalized_mode == "add":
+ selected = set(previous_items)
+ for item in tools or []:
+ selected.add(item)
+ result = SkillSelectToolsResult(
+ skill=normalized_skill,
+ selected_items=[] if include_all_tools else list(selected),
+ include_all=include_all_tools,
+ mode="add",
+ )
+ else:
+ result = SkillSelectToolsResult(
+ skill=normalized_skill,
+ selected_items=[] if include_all_tools else list(tools or []),
+ include_all=include_all_tools,
+ mode="replace",
+ )
+
+ set_selection_state_delta_by_key(
+ tool_context,
+ tools_selection_key,
+ result.selected_tools,
+ result.include_all_tools,
+ )
+ append_loaded_order_state_delta(tool_context, agent_name, normalized_skill)
return result
diff --git a/trpc_agent_sdk/skills/tools/_workspace_exec.py b/trpc_agent_sdk/skills/tools/_workspace_exec.py
new file mode 100644
index 0000000..395457f
--- /dev/null
+++ b/trpc_agent_sdk/skills/tools/_workspace_exec.py
@@ -0,0 +1,518 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Shared executor workspace tools."""
+
+from __future__ import annotations
+
+import posixpath
+import time
+from dataclasses import dataclass
+from typing import Any
+from typing import Optional
+from typing_extensions import override
+
+from pydantic import BaseModel
+from pydantic import Field
+from trpc_agent_sdk.code_executors import BaseCodeExecutor
+from trpc_agent_sdk.code_executors import BaseProgramSession
+from trpc_agent_sdk.code_executors import BaseWorkspaceRuntime
+from trpc_agent_sdk.code_executors import DEFAULT_EXEC_YIELD_MS
+from trpc_agent_sdk.code_executors import DEFAULT_SESSION_KILL_SEC
+from trpc_agent_sdk.code_executors import DEFAULT_SESSION_TTL_SEC
+from trpc_agent_sdk.code_executors import DIR_OUT
+from trpc_agent_sdk.code_executors import DIR_RUNS
+from trpc_agent_sdk.code_executors import DIR_SKILLS
+from trpc_agent_sdk.code_executors import DIR_WORK
+from trpc_agent_sdk.code_executors import PROGRAM_STATUS_EXITED
+from trpc_agent_sdk.code_executors import PROGRAM_STATUS_RUNNING
+from trpc_agent_sdk.code_executors import ProgramPoll
+from trpc_agent_sdk.code_executors import WorkspaceRunProgramSpec
+from trpc_agent_sdk.code_executors import poll_line_limit
+from trpc_agent_sdk.code_executors import wait_for_program_output
+from trpc_agent_sdk.code_executors import yield_duration_ms
+from trpc_agent_sdk.code_executors.utils import normalize_globs
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.filter import BaseFilter
+from trpc_agent_sdk.tools import BaseTool
+from trpc_agent_sdk.types import FunctionDeclaration
+from trpc_agent_sdk.types import Schema
+from trpc_agent_sdk.types import Type
+
+from ._common import CreateWorkspaceNameCallback
+from ._common import cleanup_expired_sessions
+from ._common import default_create_ws_name_callback
+from ._common import require_non_empty
+
+_DEFAULT_WORKSPACE_EXEC_TIMEOUT_SEC = 5 * 60
+_DEFAULT_WORKSPACE_WRITE_YIELD_MS = 200
+
+
+def _combine_output(stdout: str, stderr: str) -> str:
+ if not stdout:
+ return stderr
+ if not stderr:
+ return stdout
+ return stdout + stderr
+
+
+def _has_glob_meta(s: str) -> bool:
+ return any(ch in s for ch in ("*", "?", "["))
+
+
+def _has_env_prefix(s: str, name: str) -> bool:
+ if s.startswith(f"${name}"):
+ tail = s[len(name) + 1:]
+ return tail == "" or tail.startswith("/") or tail.startswith("\\")
+ brace = f"${{{name}}}"
+ if s.startswith(brace):
+ tail = s[len(brace):]
+ return tail == "" or tail.startswith("/") or tail.startswith("\\")
+ return False
+
+
+def _is_workspace_env_path(s: str) -> bool:
+ return (_has_env_prefix(s, "WORKSPACE_DIR") or _has_env_prefix(s, "SKILLS_DIR") or _has_env_prefix(s, "WORK_DIR")
+ or _has_env_prefix(s, "OUTPUT_DIR") or _has_env_prefix(s, "RUN_DIR"))
+
+
+def _is_allowed_workspace_path(rel: str) -> bool:
+ return any(rel == root or rel.startswith(f"{root}/") for root in (DIR_SKILLS, DIR_WORK, DIR_OUT, DIR_RUNS))
+
+
+def _normalize_cwd(raw: str) -> str:
+ s = (raw or "").strip().replace("\\", "/")
+ if not s:
+ return "."
+ if _has_glob_meta(s):
+ raise ValueError("cwd must not contain glob patterns")
+ if _is_workspace_env_path(s):
+ out = normalize_globs([s])
+ if not out:
+ raise ValueError("invalid cwd")
+ s = out[0]
+ if s.startswith("/"):
+ rel = posixpath.normpath(s).lstrip("/")
+ if rel in ("", "."):
+ return "."
+ if not _is_allowed_workspace_path(rel):
+ raise ValueError(f"cwd must stay under workspace roots: {raw!r}")
+ return rel
+ rel = posixpath.normpath(s)
+ if rel == ".":
+ return "."
+ if rel == ".." or rel.startswith("../"):
+ raise ValueError("cwd must stay within the workspace")
+ if not _is_allowed_workspace_path(rel):
+ raise ValueError(
+ f"cwd must stay under supported workspace roots such as skills/, work/, out/, or runs/: {raw!r}")
+ return rel
+
+
+def _exec_timeout_seconds(raw: int) -> float:
+ if raw <= 0:
+ return float(_DEFAULT_WORKSPACE_EXEC_TIMEOUT_SEC)
+ return float(raw)
+
+
+def _exec_yield_seconds(background: bool, raw_ms: Optional[int]) -> float:
+ if background:
+ if raw_ms is not None and raw_ms > 0:
+ return raw_ms / 1000.0
+ return 0.0
+ return yield_duration_ms(raw_ms or 0, DEFAULT_EXEC_YIELD_MS)
+
+
+def _write_yield_seconds(raw_ms: Optional[int]) -> float:
+ if raw_ms is None:
+ return _DEFAULT_WORKSPACE_WRITE_YIELD_MS / 1000.0
+ if raw_ms < 0:
+ return 0.0
+ return raw_ms / 1000.0
+
+
+class _ExecInput(BaseModel):
+ command: str = Field(default="")
+ cwd: str = Field(default="")
+ env: dict[str, str] = Field(default_factory=dict)
+ stdin: str = Field(default="")
+ yield_time_ms: int = Field(default=0)
+ background: bool = Field(default=False)
+ timeout_sec: int = Field(default=0)
+ tty: bool = Field(default=False)
+
+
+class _WriteInput(BaseModel):
+ session_id: str = Field(default="")
+ chars: str = Field(default="")
+ yield_time_ms: Optional[int] = Field(default=None)
+ append_newline: bool = Field(default=False)
+
+
+class _KillInput(BaseModel):
+ session_id: str = Field(default="")
+
+
+@dataclass
+class _ExecSession:
+ proc: BaseProgramSession
+ exited_at: Optional[float] = None
+ finalized: bool = False
+ finalized_at: Optional[float] = None
+
+
+class WorkspaceExecTool(BaseTool):
+ """Execute shell commands in shared executor workspace."""
+
+ def __init__(
+ self,
+ workspace_runtime: BaseWorkspaceRuntime,
+ create_ws_name_cb: Optional[CreateWorkspaceNameCallback] = None,
+ session_ttl: float = DEFAULT_SESSION_TTL_SEC,
+ filters_name: Optional[list[str]] = None,
+ filters: Optional[list[BaseFilter]] = None,
+ ):
+ super().__init__(
+ name="workspace_exec",
+ description=("Execute a shell command inside the current executor workspace. "
+ "This is the default shell runner for executor-side work not bound to a specific skill."),
+ filters_name=filters_name,
+ filters=filters,
+ )
+ self._workspace_runtime = workspace_runtime
+ self._create_ws_name_cb = create_ws_name_cb or default_create_ws_name_callback
+ self._ttl = session_ttl
+ self._sessions: dict[str, _ExecSession] = {}
+
+ def _runtime(self) -> BaseWorkspaceRuntime:
+ runtime = self._workspace_runtime
+ if runtime is None:
+ raise ValueError("workspace_exec requires an executor with live workspace support")
+ return runtime
+
+ async def _workspace(self, ctx: InvocationContext):
+ runtime = self._runtime()
+ manager = runtime.manager(ctx)
+ workspace_id = self._create_ws_name_cb(ctx)
+ ws = await manager.create_workspace(workspace_id, ctx)
+ return runtime, ws
+
+ def _supports_interactive(self, ctx: InvocationContext) -> bool:
+ runner = self._runtime().runner(ctx)
+ start_program = getattr(runner, "start_program", None)
+ return start_program is not None
+
+ async def _put_session(self, sid: str, session: _ExecSession) -> None:
+ await self._cleanup_expired_locked()
+ self._sessions[sid] = session
+
+ async def _get_session(self, sid: str) -> _ExecSession:
+ await self._cleanup_expired_locked()
+ session = self._sessions.get(sid)
+ if session is None:
+ raise ValueError(f"unknown session_id: {sid}")
+ return session
+
+ async def _remove_session(self, sid: str) -> _ExecSession:
+ await self._cleanup_expired_locked()
+ session = self._sessions.pop(sid, None)
+ if session is None:
+ raise ValueError(f"unknown session_id: {sid}")
+ return session
+
+ async def _finalize_and_remove_session(self, sid: str) -> None:
+ session = await self._get_session(sid)
+ now = time.time()
+ session.finalized = True
+ session.finalized_at = now
+ session.exited_at = now
+ await session.proc.close()
+ await self._remove_session(sid)
+
+ async def _cleanup_expired_locked(self) -> None:
+
+ async def _refresh_exit_state(session: _ExecSession, now: float) -> None:
+ if session.exited_at is not None:
+ return
+ session_state = await session.proc.state()
+ if session_state.status == PROGRAM_STATUS_EXITED:
+ session.exited_at = now
+
+ await cleanup_expired_sessions(
+ self._sessions,
+ ttl=self._ttl,
+ refresh_exit_state=_refresh_exit_state,
+ close_session=lambda s: s.proc.close(),
+ )
+
+ @override
+ def _get_declaration(self) -> FunctionDeclaration:
+ return FunctionDeclaration(
+ name="workspace_exec",
+ description=("Execute a shell command in the shared executor workspace. "
+ "Use for workspace-level file operations and validation commands."),
+ parameters=Schema(
+ type=Type.OBJECT,
+ required=["command"],
+ properties={
+ "command": Schema(type=Type.STRING, description="Shell command to execute."),
+ "cwd": Schema(type=Type.STRING, description="Optional workspace-relative cwd."),
+ "env": Schema(type=Type.OBJECT, description="Optional environment overrides."),
+ "stdin": Schema(type=Type.STRING, description="Optional initial stdin text."),
+ "timeout_sec": Schema(type=Type.INTEGER, description="Maximum command runtime in seconds."),
+ "yield_time_ms": Schema(type=Type.INTEGER, description="How long to wait before returning."),
+ "background": Schema(type=Type.BOOLEAN, description="Start command in background session."),
+ "tty": Schema(type=Type.BOOLEAN, description="Allocate TTY for interactive commands."),
+ },
+ ),
+ response=_exec_output_schema(
+ "Result of workspace_exec. output is aggregated terminal text and may combine stdout/stderr."),
+ )
+
+ @override
+ async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> Any:
+ inputs = _ExecInput.model_validate(args)
+ command = (inputs.command or "").strip()
+ if not command:
+ raise ValueError("command is required")
+ cwd = _normalize_cwd(inputs.cwd)
+ timeout_raw = inputs.timeout_sec
+ tty = inputs.tty
+ yield_ms = inputs.yield_time_ms
+
+ runtime, ws = await self._workspace(tool_context)
+ spec = WorkspaceRunProgramSpec(
+ cmd="sh",
+ args=["-lc", command],
+ env=inputs.env,
+ cwd=cwd,
+ stdin=inputs.stdin,
+ timeout=_exec_timeout_seconds(timeout_raw),
+ )
+
+ if not self._supports_interactive(tool_context):
+ if inputs.background or tty:
+ raise ValueError("workspace_exec interactive sessions are not supported by the current executor")
+ return await _run_one_shot(runtime, ws, spec, tool_context)
+
+ if (not inputs.background) and (not tty) and yield_ms <= 0:
+ return await _run_one_shot(runtime, ws, spec, tool_context)
+
+ runner = runtime.runner(tool_context)
+ interactive_spec = WorkspaceRunProgramSpec(
+ cmd=spec.cmd,
+ args=spec.args,
+ env=spec.env,
+ cwd=spec.cwd,
+ stdin=spec.stdin,
+ timeout=spec.timeout,
+ limits=spec.limits,
+ tty=tty,
+ )
+ proc = await runner.start_program(tool_context, ws, interactive_spec) # type: ignore[attr-defined]
+ sid = proc.id()
+ await self._put_session(sid, _ExecSession(proc=proc))
+
+ if inputs.background and yield_ms <= 0:
+ poll = await proc.poll(poll_line_limit(0))
+ else:
+ poll = await wait_for_program_output(
+ proc,
+ _exec_yield_seconds(inputs.background, yield_ms if yield_ms > 0 else None),
+ poll_line_limit(0),
+ )
+
+ out = _poll_output(sid, poll)
+ if poll.status == PROGRAM_STATUS_EXITED:
+ try:
+ await self._finalize_and_remove_session(sid)
+ except Exception: # pylint: disable=broad-except
+ out["session_id"] = sid
+ return out
+
+
+class WorkspaceWriteStdinTool(BaseTool):
+ """Write stdin to a running workspace_exec session or poll it."""
+
+ def __init__(
+ self,
+ exec_tool: WorkspaceExecTool,
+ *,
+ filters_name: Optional[list[str]] = None,
+ filters: Optional[list[BaseFilter]] = None,
+ ):
+ super().__init__(
+ name="workspace_write_stdin",
+ description="Write to a running workspace_exec session. Empty chars acts like poll.",
+ filters_name=filters_name,
+ filters=filters,
+ )
+ self._exec = exec_tool
+
+ @override
+ def _get_declaration(self) -> FunctionDeclaration:
+ return FunctionDeclaration(
+ name="workspace_write_stdin",
+ description="Write to a running workspace_exec session. Empty chars acts like poll.",
+ parameters=Schema(
+ type=Type.OBJECT,
+ required=["session_id"],
+ properties={
+ "session_id": Schema(type=Type.STRING, description="Session id returned by workspace_exec."),
+ "chars": Schema(type=Type.STRING, description="Characters to write."),
+ "yield_time_ms": Schema(type=Type.INTEGER, description="Optional wait before polling output."),
+ "append_newline": Schema(type=Type.BOOLEAN, description="Append newline after chars."),
+ },
+ ),
+ response=_exec_output_schema("Result of stdin write or follow-up poll."),
+ )
+
+ @override
+ async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> Any:
+ inputs = _WriteInput.model_validate(args)
+ session_id = require_non_empty(inputs.session_id, field_name="session_id")
+ session = await self._exec._get_session(session_id)
+
+ append_newline = inputs.append_newline
+ if inputs.chars or append_newline:
+ await session.proc.write(inputs.chars or "", append_newline)
+
+ yield_ms = inputs.yield_time_ms or 0
+ user_set_yield = inputs.yield_time_ms is not None
+ poll = await wait_for_program_output(
+ session.proc,
+ _write_yield_seconds(yield_ms if user_set_yield else None),
+ poll_line_limit(0),
+ )
+ out = _poll_output(session_id, poll)
+ if poll.status == PROGRAM_STATUS_EXITED:
+ try:
+ await self._exec._finalize_and_remove_session(session_id)
+ except Exception: # pylint: disable=broad-except
+ out["session_id"] = session_id
+ return out
+
+
+class WorkspaceKillSessionTool(BaseTool):
+ """Terminate a running workspace_exec session."""
+
+ def __init__(
+ self,
+ exec_tool: WorkspaceExecTool,
+ *,
+ filters_name: Optional[list[str]] = None,
+ filters: Optional[list[BaseFilter]] = None,
+ ):
+ super().__init__(
+ name="workspace_kill_session",
+ description="Terminate a running workspace_exec session.",
+ filters_name=filters_name,
+ filters=filters,
+ )
+ self._exec = exec_tool
+
+ @override
+ def _get_declaration(self) -> FunctionDeclaration:
+ return FunctionDeclaration(
+ name="workspace_kill_session",
+ description="Terminate a running workspace_exec session.",
+ parameters=Schema(
+ type=Type.OBJECT,
+ required=["session_id"],
+ properties={
+ "session_id": Schema(type=Type.STRING, description="Session id returned by workspace_exec."),
+ },
+ ),
+ response=Schema(
+ type=Type.OBJECT,
+ required=["ok", "session_id", "status"],
+ properties={
+ "ok": Schema(type=Type.BOOLEAN, description="True when session was removed."),
+ "session_id": Schema(type=Type.STRING, description="Session id."),
+ "status": Schema(type=Type.STRING, description="Final status."),
+ },
+ ),
+ )
+
+ @override
+ async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> Any:
+ if "session_id" not in args:
+ raise ValueError("session_id is required")
+ session_id = args["session_id"]
+ session = await self._exec._get_session(session_id)
+ status = PROGRAM_STATUS_EXITED
+ poll = await session.proc.poll(None)
+ if poll.status == PROGRAM_STATUS_RUNNING:
+ await session.proc.kill(DEFAULT_SESSION_KILL_SEC)
+ status = "killed"
+ await self._exec._finalize_and_remove_session(session_id)
+ return {"ok": True, "session_id": session_id, "status": status}
+
+
+def _exec_output_schema(description: str) -> Schema:
+ return Schema(
+ type=Type.OBJECT,
+ description=description,
+ required=["status", "offset", "next_offset"],
+ properties={
+ "status": Schema(type=Type.STRING, description="running or exited"),
+ "output": Schema(type=Type.STRING, description="Aggregated terminal text observed for this call."),
+ "exit_code": Schema(type=Type.INTEGER, description="Exit code when session has exited."),
+ "session_id": Schema(type=Type.STRING, description="Interactive session id when still running."),
+ "offset": Schema(type=Type.INTEGER, description="Start offset of returned output."),
+ "next_offset": Schema(type=Type.INTEGER, description="Next output offset."),
+ },
+ )
+
+
+def _poll_output(session_id: str, poll: ProgramPoll) -> dict[str, Any]:
+ out: dict[str, Any] = {
+ "status": poll.status,
+ "output": poll.output,
+ "offset": poll.offset,
+ "next_offset": poll.next_offset,
+ }
+ if poll.exit_code is not None:
+ out["exit_code"] = poll.exit_code
+ if poll.status == PROGRAM_STATUS_RUNNING:
+ out["session_id"] = session_id
+ return out
+
+
+async def _run_one_shot(
+ runtime: BaseWorkspaceRuntime,
+ workspace: Any,
+ spec: WorkspaceRunProgramSpec,
+ ctx: InvocationContext,
+) -> dict[str, Any]:
+ rr = await runtime.runner(ctx).run_program(workspace, spec, ctx)
+ return {
+ "status": PROGRAM_STATUS_EXITED,
+ "output": _combine_output(rr.stdout, rr.stderr),
+ "exit_code": rr.exit_code,
+ "offset": 0,
+ "next_offset": 0,
+ }
+
+
+def create_workspace_exec_tools(
+ code_executor: BaseCodeExecutor,
+ *,
+ workspace_runtime: Optional[BaseWorkspaceRuntime] = None,
+ session_ttl: float = DEFAULT_SESSION_TTL_SEC,
+ filters_name: Optional[list[str]] = None,
+ filters: Optional[list[BaseFilter]] = None,
+) -> tuple[WorkspaceExecTool, WorkspaceWriteStdinTool, WorkspaceKillSessionTool]:
+ """Create workspace_exec tool trio."""
+ exec_tool = WorkspaceExecTool(
+ code_executor=code_executor,
+ workspace_runtime=workspace_runtime,
+ session_ttl=session_ttl,
+ filters_name=filters_name,
+ filters=filters,
+ )
+ write_tool = WorkspaceWriteStdinTool(exec_tool, filters_name=filters_name, filters=filters)
+ kill_tool = WorkspaceKillSessionTool(exec_tool, filters_name=filters_name, filters=filters)
+ return exec_tool, write_tool, kill_tool
diff --git a/trpc_agent_sdk/storage/_sql_common.py b/trpc_agent_sdk/storage/_sql_common.py
index d9d4c04..8f5ef17 100644
--- a/trpc_agent_sdk/storage/_sql_common.py
+++ b/trpc_agent_sdk/storage/_sql_common.py
@@ -172,6 +172,8 @@ class DynamicPickleType(TypeDecorator):
def load_dialect_impl(self, dialect: Dialect) -> TypeDecorator:
if dialect.name == "spanner+spanner":
return dialect.type_descriptor(SpannerPickleType) # type: ignore
+ if dialect.name == "mysql":
+ return dialect.type_descriptor(mysql.LONGBLOB) # type: ignore
return self.impl
def process_bind_param(self, value: Any, dialect: Dialect) -> Any: