feat(examples): add code review agent prototype

Author: k0mondor

examples/skills_code_review_agent/README.md

@@ -26,7 +26,8 @@ execution, SQLite persistence, and dual-format reports.
 ## Directory Map
 
 - `agent/`: orchestration, config, and runtime helpers
-- `skills/code-review/`: formal skill package and deterministic scripts
+- repository `skills/code-review/`: canonical formal skill package and deterministic scripts
+- example-local `examples/skills_code_review_agent/skills/code-review/`: teaching copy kept in sync for the example
 - `src/`: parser, rules, filter policy, storage, report, telemetry, redaction
 - `tests/`: fixtures and automated tests
 - `DEVELOPMENT_PLAN.md`: phased implementation plan
@@ -124,16 +125,22 @@ Key method:
 
 ## Formal Skill Package
 
-The reusable skill lives under:
+The canonical reusable skill lives under:
 
-- [SKILL.md](file:///c:/Users/32349/trpc-agent-python-fork/examples/skills_code_review_agent/skills/code-review/SKILL.md)
-- [USAGE.md](file:///c:/Users/32349/trpc-agent-python-fork/examples/skills_code_review_agent/skills/code-review/USAGE.md)
-- [RULES.md](file:///c:/Users/32349/trpc-agent-python-fork/examples/skills_code_review_agent/skills/code-review/RULES.md)
-- [SCRIPT_CONTRACTS.md](file:///c:/Users/32349/trpc-agent-python-fork/examples/skills_code_review_agent/skills/code-review/SCRIPT_CONTRACTS.md)
+- [SKILL.md](file:///c:/Users/32349/trpc-agent-python-fork/skills/code-review/SKILL.md)
+- [USAGE.md](file:///c:/Users/32349/trpc-agent-python-fork/skills/code-review/USAGE.md)
+- [RULES.md](file:///c:/Users/32349/trpc-agent-python-fork/skills/code-review/RULES.md)
+- [SCRIPT_CONTRACTS.md](file:///c:/Users/32349/trpc-agent-python-fork/skills/code-review/SCRIPT_CONTRACTS.md)
 
-The agent currently formalizes the skill package, its scripts, and its
-`SkillToolSet` entrypoints. The main pipeline still owns orchestration,
-governance, persistence, and final reporting.
+The example now resolves the repository-level `skills/code-review/` directory
+first for repository indexing, skill-script planning, and container skill mounts.
+The example-local copy remains as a fallback so the sample stays readable and
+self-contained.
+
+The agent formalizes the skill package, its scripts, and its `SkillToolSet`
+entrypoints. The main pipeline still owns orchestration, governance,
+persistence, and final reporting so Filter, Storage, and Telemetry stay fully
+auditable inside the example.
 
 ## Test Coverage
 

examples/skills_code_review_agent/agent/tools.py

@@ -10,6 +10,7 @@
 from typing import Any
 
 from trpc_agent_sdk.code_executors import BaseWorkspaceRuntime
+from trpc_agent_sdk.code_executors import DEFAULT_SKILLS_CONTAINER
 from trpc_agent_sdk.code_executors import create_container_workspace_runtime
 from trpc_agent_sdk.code_executors import create_local_workspace_runtime
 from trpc_agent_sdk.skills import BaseSkillRepository
@@ -20,6 +21,7 @@
 from ..src.filter_policy import SkillScriptInvocation
 from ..src.review_types import SandboxRunRecord, SandboxRunStatus
 
+SKILL_NAME = "code-review"
 SCRIPT_TIMEOUT_SECONDS = 20
 OUTPUT_LIMIT_CHARS = 4000
 
@@ -36,9 +38,9 @@ def create_skill_tool_set(
         "omit_inline_content": False,
     }
     workspace_runtime = _create_workspace_runtime(workspace_runtime_type=workspace_runtime_type)
-    skill_paths = _get_skill_paths()
+    skill_paths = _get_skill_roots()
     repository = create_default_skill_repository(
-        skill_paths,
+        *skill_paths,
         workspace_runtime=workspace_runtime,
         use_cached_repository=use_cached_repository,
     )
@@ -52,7 +54,7 @@ def build_skill_script_plan(
 ) -> list[SkillScriptInvocation]:
     """Build the list of planned skill-script executions for the review."""
 
-    scripts_dir = project_root / "examples" / "skills_code_review_agent" / "skills" / "code-review" / "scripts"
+    scripts_dir = resolve_code_review_skill_dir(project_root=project_root) / "scripts"
     return [
         SkillScriptInvocation(
             name="parse_diff",
@@ -126,8 +128,14 @@ def execute_skill_script(
             encoding="utf-8",
             timeout=timeout_seconds,
         )
-        stdout, stdout_truncated = _truncate_output(completed.stdout, output_limit_chars)
-        stderr, stderr_truncated = _truncate_output(completed.stderr, output_limit_chars)
+        stdout, stdout_truncated = _truncate_output(
+            _normalize_process_output(completed.stdout),
+            output_limit_chars,
+        )
+        stderr, stderr_truncated = _truncate_output(
+            _normalize_process_output(completed.stderr),
+            output_limit_chars,
+        )
         status = (
             SandboxRunStatus.SUCCEEDED
             if completed.returncode == 0
@@ -147,8 +155,14 @@ def execute_skill_script(
             blocked_by_filter=False,
         )
     except subprocess.TimeoutExpired as exc:
-        stdout, stdout_truncated = _truncate_output(exc.stdout or "", output_limit_chars)
-        stderr, stderr_truncated = _truncate_output(exc.stderr or "", output_limit_chars)
+        stdout, stdout_truncated = _truncate_output(
+            _normalize_process_output(exc.stdout),
+            output_limit_chars,
+        )
+        stderr, stderr_truncated = _truncate_output(
+            _normalize_process_output(exc.stderr),
+            output_limit_chars,
+        )
         return SandboxRunRecord(
             name=invocation.name,
             command=invocation.command,
@@ -195,13 +209,63 @@ def _truncate_output(text: str, limit: int) -> tuple[str, bool]:
     return text[:limit], True
 
 
-def _get_skill_paths() -> str:
-    """Get the skill root path for this example."""
+def _normalize_process_output(text: object) -> str:
+    """Normalize subprocess output for type-safe truncation and storage."""
+
+    if text is None:
+        return ""
+    if isinstance(text, bytes):
+        return text.decode("utf-8", errors="replace")
+    if isinstance(text, str):
+        return text
+    return str(text)
+
+
+def resolve_code_review_skill_dir(*, project_root: Path | None = None) -> Path:
+    """Resolve the canonical code-review skill directory.
+
+    The repository-level ``skills/code-review`` path is preferred so the example
+    matches the issue's requested artifact layout. The example-local copy remains
+    as a fallback to keep the sample self-contained.
+    """
+
+    for root in _get_skill_roots(project_root=project_root):
+        candidate = Path(root).resolve() / SKILL_NAME
+        if (candidate / "SKILL.md").is_file():
+            return candidate
+    raise FileNotFoundError(
+        "Unable to locate the `code-review` skill under repository or example skill roots."
+    )
+
+
+def _get_skill_roots(*, project_root: Path | None = None) -> tuple[str, ...]:
+    """Get ordered skill roots for repository scanning."""
+
 
     skills_root = os.getenv(ENV_SKILLS_ROOT)
     if skills_root:
-        return skills_root
-    return str(Path(__file__).resolve().parent.parent / "skills")
+        return (skills_root,)
+
+    repo_root = _resolve_project_root(project_root)
+    candidates = [
+        repo_root / "skills",
+        repo_root / "examples" / "skills_code_review_agent" / "skills",
+    ]
+
+    roots: list[str] = []
+    for candidate in candidates:
+        resolved = str(candidate.resolve())
+        if candidate.is_dir() and resolved not in roots:
+            roots.append(resolved)
+    return tuple(roots)
+
+
+def _resolve_project_root(project_root: Path | None = None) -> Path:
+    """Resolve the repository root for the example."""
+
+    if project_root is not None:
+        return project_root.expanduser().resolve()
+    return Path(__file__).resolve().parents[3]
 
 
 def _create_workspace_runtime(
@@ -212,9 +276,8 @@ def _create_workspace_runtime(
     """Create a workspace runtime for skill execution demos."""
 
     if workspace_runtime_type == "container":
-        skill_paths = _get_skill_paths()
-        container_path = "/opt/trpc-agent/skills"
-        host_config = {"Binds": [f"{skill_paths}:{container_path}:ro"]}
+        skill_root = _get_skill_roots()[0]
+        host_config = {"Binds": [f"{skill_root}:{DEFAULT_SKILLS_CONTAINER}:ro"]}
         kwargs["host_config"] = host_config
         kwargs["auto_inputs"] = True
         return create_container_workspace_runtime(**kwargs)

examples/skills_code_review_agent/src/deduper.py

@@ -29,7 +29,7 @@ def dedupe_and_classify_findings(findings: list[ReviewFinding]) -> list[ReviewFi
             finding.category.value,
             finding.file,
             finding.line,
-            _normalize_evidence(finding.evidence),
+            finding.title.strip().lower(),
         )
         existing = deduped.get(key)
         if existing is None or _should_replace(existing, finding):