agent: add container sandbox runtime for code review

This change adds an optional Container sandbox runtime for the code review Agent example. The runtime reuses the existing ContainerClient to execute allowlisted sandbox scripts with diff input through stdin, network access disabled, timeout enforcement, output truncation, and structured sandbox run records.

The fake sandbox remains the default deterministic runtime for local tests and CI, while the container runtime provides an isolated execution path for diff summary and static rule scripts.

Updates #92

RELEASE NOTES: NONE

Author: ghost613bb

examples/code_review_agent/README.md

@@ -10,7 +10,7 @@ The default mode intentionally does **not** require API keys, Docker, Cube/E2B,
 - Unified diff parsing for files, hunks, changed lines, and line anchors.
 - Deterministic rules for secrets, security risks, async issues, resource leaks, database lifecycle issues, and missing tests.
 - Pre-sandbox governance decisions for allowlisted scripts, forbidden paths, risky commands, network access, and output budgets.
-- Fake sandbox runs with failure/timeout/output-limit records.
+- Fake sandbox runs with failure/timeout/output-limit records, plus optional Docker Container runtime for allowlisted scripts.
 - Structured findings, warnings, filter decisions, sandbox summaries, audit events, and metrics.
 - Optional SQLite persistence for review task, sandbox run, filter decision, finding, warning, audit, and report records.
 
@@ -22,7 +22,7 @@ user / CI request
   -> parse files, hunks, changed lines, and anchors
   -> build sandbox requests
   -> apply pre-sandbox Filter governance
-  -> execute allowed requests in fake sandbox
+  -> execute allowed requests in fake sandbox or Docker container
   -> run deterministic fake-model rules
   -> post-filter findings: redact, anchor, dedupe, route low confidence
   -> build review_report.json and review_report.md
@@ -122,6 +122,17 @@ python examples/code_review_agent/run_review.py \
   --json
 ```
 
+Review with Docker Container sandbox execution for allowlisted scripts:
+
+```bash
+python examples/code_review_agent/run_review.py \
+  --diff-file examples/code_review_agent/fixtures/hardcoded_secret.diff \
+  --fake-model \
+  --sandbox-runtime container \
+  --container-image python:3-slim \
+  --json
+```
+
 Query a persisted task:
 
 ```bash
@@ -175,16 +186,16 @@ Rows store redacted summaries and report payloads. Raw secret-bearing diffs are
 ## Security boundaries
 
 - Fake sandbox is the default and never executes host commands.
-- Non-fake runtimes are not required for tests and should be treated as future adapters.
-- Local execution is a development fallback only, not the production default.
+- Container runtime is optional and uses the project's existing Docker `ContainerClient` to execute only allowlisted scripts with network disabled.
+- Cube/E2B can be integrated through the repository's existing `CubeWorkspaceRuntime`, but it is not required for the default deterministic path.
 - Pre-sandbox governance denies risky commands, forbidden paths, network access, and over-budget requests.
 - Denied or `needs_human_review` sandbox requests are recorded but not executed.
 - Reports and database rows redact API keys, tokens, passwords, private keys, cookies, authorization headers, and credential URLs.
 - Sandbox failures, timeouts, and truncated output are recorded as non-fatal audit data.
 
 ## Design note
 
-The prototype keeps the Agent implementation deterministic so contributors can validate the full review lifecycle without external services. The Skill package defines the policy layer: scope, review categories, finding schema, and sandbox safety expectations. The Python pipeline then implements that policy in a dry-run form. Inputs are normalized from either a diff file or local git diff, then parsed into files, hunks, and changed-line anchors. Before any executable check, sandbox requests pass through a governance filter that allowlists known scripts and rejects risky commands, forbidden paths, network access, or excessive output. The fake sandbox records the same shape of result that a Container or Cube/E2B runtime would provide, including failures and timeouts, but never executes arbitrary host commands. Deterministic rules produce structured findings for secrets, security risks, async issues, resource leaks, database lifecycle problems, and missing tests. Post-filters redact sensitive values, dedupe by file/line/category, and route low-confidence or unanchored issues to human-review warnings. SQLite persistence stores task state, sandbox runs, filter decisions, findings, warnings, metrics, audit events, and the final report using only redacted data. Reports expose findings, severity/category statistics, human-review items, Filter decisions, sandbox summaries, monitoring fields, and actionable recommendations.
+The prototype keeps the Agent implementation deterministic so contributors can validate the full review lifecycle without external services. The Skill package defines the policy layer: scope, review categories, finding schema, and sandbox safety expectations. The Python pipeline then implements that policy in a dry-run form. Inputs are normalized from either a diff file or local git diff, then parsed into files, hunks, and changed-line anchors. Before any executable check, sandbox requests pass through a governance filter that allowlists known scripts and rejects risky commands, forbidden paths, network access, or excessive output. The fake sandbox records the same shape of result that an isolated runtime would provide, while the optional Container runtime uses the repository's existing Docker `ContainerClient` to execute allowlisted scripts with stdin, timeout, output caps, and network disabled. Deterministic rules produce structured findings for secrets, security risks, async issues, resource leaks, database lifecycle problems, and missing tests. Post-filters redact sensitive values, dedupe by file/line/category, and route low-confidence or unanchored issues to human-review warnings. SQLite persistence stores task state, sandbox runs, filter decisions, findings, warnings, metrics, audit events, and the final report using only redacted data. Reports expose findings, severity/category statistics, human-review items, Filter decisions, sandbox summaries, monitoring fields, and actionable recommendations.
 
 ## Verification
 

examples/code_review_agent/agent/pipeline.py

@@ -20,7 +20,7 @@
 from .inputs import build_review_input
 from .report import build_report
 from .rules import review_with_rules
-from .sandbox import FakeSandboxRunner
+from .sandbox import create_sandbox_runner
 from .schemas import AuditEvent
 from .schemas import ParsedDiff
 from .schemas import ReviewInput
@@ -39,6 +39,7 @@ class ReviewRunConfig:
     db_path: Path | None = None
     task_id: str | None = None
     include_missing_tests: bool = True
+    container_image: str = "python:3-slim"
 
 
 def run_dry_review(diff_text: str, *, fake_model: bool = True) -> ReviewReport:
@@ -88,7 +89,8 @@ def run_review(
 
         requests = build_default_sandbox_requests(review_input.changed_files)
         allowed_requests, pre_decisions = evaluate_sandbox_requests(requests, policy)
-        sandbox_runs = FakeSandboxRunner(policy).run_requests(allowed_requests, parsed)
+        sandbox_runner = create_sandbox_runner(policy, container_image=config.container_image)
+        sandbox_runs = sandbox_runner.run_requests(allowed_requests, parsed, diff_text)
         for run in sandbox_runs:
             if run.error_type:
                 audit_events.append(

examples/code_review_agent/agent/sandbox.py

@@ -7,23 +7,35 @@
 
 from __future__ import annotations
 
+import asyncio
+import contextlib
+import logging
+import sys
 import time
 from collections.abc import Sequence
+from pathlib import Path
 
 from .filters import redact_text
 from .governance import SandboxRequest
 from .schemas import ParsedDiff
 from .schemas import SandboxPolicy
 from .schemas import SandboxRun
 
+_SCRIPT_FILES = {
+    "diff_summary": "diff_summary.py",
+    "static_rules": "static_rules.py",
+}
+
 
 class FakeSandboxRunner:
     """Deterministic sandbox runner that never executes host commands."""
 
     def __init__(self, policy: SandboxPolicy) -> None:
         self._policy = policy
 
-    def run_requests(self, requests: Sequence[SandboxRequest], parsed_diff: ParsedDiff) -> list[SandboxRun]:
+    def run_requests(
+        self, requests: Sequence[SandboxRequest], parsed_diff: ParsedDiff, diff_text: str = ""
+    ) -> list[SandboxRun]:
         """Run all allowed requests deterministically."""
         return [self.run_request(request, parsed_diff) for request in requests]
 
@@ -72,6 +84,149 @@ def run_request(self, request: SandboxRequest, parsed_diff: ParsedDiff) -> Sandb
         )
 
 
+class ContainerSandboxRunner:
+    """Sandbox runner backed by the project's existing Docker ContainerClient."""
+
+    def __init__(self, policy: SandboxPolicy, *, scripts_dir: Path | None = None, image: str = "python:3-slim") -> None:
+        self._policy = policy
+        self._scripts_dir = scripts_dir or Path(__file__).resolve().parents[1] / "skills" / "code-review" / "scripts"
+        self._image = image
+
+    def run_requests(
+        self, requests: Sequence[SandboxRequest], parsed_diff: ParsedDiff, diff_text: str = ""
+    ) -> list[SandboxRun]:
+        """Run allowed requests in Docker containers."""
+        return [self.run_request(request, diff_text) for request in requests]
+
+    def run_request(self, request: SandboxRequest, diff_text: str) -> SandboxRun:
+        """Run one allowlisted script in a Docker container."""
+        started = time.monotonic()
+        script_file = _SCRIPT_FILES.get(request.script_name)
+        if script_file is None:
+            return _build_run(
+                request,
+                runtime="container",
+                started=started,
+                exit_code=1,
+                stderr=f"no container script is mapped for {request.script_name}",
+                error_type="SandboxScriptUnavailable",
+                policy=self._policy,
+            )
+
+        try:
+            return asyncio.run(self._run_request_async(request, script_file, diff_text, started))
+        except Exception as exc:  # pylint: disable=broad-except
+            return _build_run(
+                request,
+                runtime="container",
+                started=started,
+                exit_code=-1,
+                stderr=str(exc),
+                error_type=exc.__class__.__name__,
+                policy=self._policy,
+            )
+
+    async def _run_request_async(
+        self, request: SandboxRequest, script_file: str, diff_text: str, started: float
+    ) -> SandboxRun:
+        CommandArgs, ContainerClient, ContainerConfig = _load_container_runtime()
+        _redirect_trpc_agent_logs_to_stderr()
+        with contextlib.redirect_stdout(sys.stderr):
+            client = ContainerClient(
+                ContainerConfig(
+                    image=self._image,
+                    host_config={
+                        "Binds": [f"{self._scripts_dir}:/workspace/scripts:ro"],
+                        "network_mode": "none",
+                        "working_dir": "/workspace",
+                    },
+                )
+            )
+        try:
+            with contextlib.redirect_stdout(sys.stderr):
+                result = await client.exec_run(
+                    ["python3", f"/workspace/scripts/{script_file}"],
+                    CommandArgs(timeout=self._policy.timeout_seconds, stdin=diff_text, environment={}),
+                )
+        finally:
+            cleanup = getattr(client, "_cleanup_container", None)
+            if callable(cleanup):
+                cleanup()
+
+        error_type = None
+        if result.is_timeout:
+            error_type = "SandboxTimeout"
+        elif result.exit_code:
+            error_type = "SandboxCommandFailed"
+        return _build_run(
+            request,
+            runtime="container",
+            started=started,
+            exit_code=result.exit_code,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            timed_out=result.is_timeout,
+            error_type=error_type,
+            policy=self._policy,
+        )
+
+
+
+def _redirect_trpc_agent_logs_to_stderr() -> None:
+    logging.getLogger("trpc_agent_sdk").disabled = True
+
+
+def _load_container_runtime():
+    try:
+        from trpc_agent_sdk.code_executors.container import CommandArgs
+        from trpc_agent_sdk.code_executors.container import ContainerClient
+        from trpc_agent_sdk.code_executors.container import ContainerConfig
+    except ModuleNotFoundError:
+        repo_root = Path(__file__).resolve().parents[3]
+        sys.path.insert(0, str(repo_root))
+        from trpc_agent_sdk.code_executors.container import CommandArgs
+        from trpc_agent_sdk.code_executors.container import ContainerClient
+        from trpc_agent_sdk.code_executors.container import ContainerConfig
+    return CommandArgs, ContainerClient, ContainerConfig
+
+
+def create_sandbox_runner(policy: SandboxPolicy, *, container_image: str = "python:3-slim") -> FakeSandboxRunner | ContainerSandboxRunner:
+    """Create a sandbox runner for the configured runtime."""
+    if policy.runtime == "container":
+        return ContainerSandboxRunner(policy, image=container_image)
+    return FakeSandboxRunner(policy)
+
+
+def _build_run(
+    request: SandboxRequest,
+    *,
+    runtime: str,
+    started: float,
+    exit_code: int | None,
+    stdout: str = "",
+    stderr: str = "",
+    timed_out: bool = False,
+    error_type: str | None = None,
+    policy: SandboxPolicy,
+) -> SandboxRun:
+    stdout_excerpt, stdout_truncated = _cap_output(redact_text(stdout), policy.max_output_bytes)
+    stderr_excerpt, stderr_truncated = _cap_output(redact_text(stderr), policy.max_output_bytes)
+    duration_ms = max(0, int((time.monotonic() - started) * 1000))
+    return SandboxRun(
+        id=f"sandbox-{request.script_name}",
+        script_name=request.script_name,
+        runtime=runtime,
+        decision="allow",
+        exit_code=exit_code,
+        timed_out=timed_out,
+        duration_ms=duration_ms,
+        stdout_excerpt=stdout_excerpt,
+        stderr_excerpt=stderr_excerpt,
+        output_truncated=stdout_truncated or stderr_truncated,
+        error_type=error_type,
+    )
+
+
 def _cap_output(text: str, max_bytes: int) -> tuple[str, bool]:
     raw = text.encode("utf-8")
     if len(raw) <= max_bytes:

examples/code_review_agent/run_review.py

@@ -29,7 +29,8 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--repo-path", type=Path, help="Path to a local git repository whose diff should be reviewed.")
     parser.add_argument("--base-ref", help="Optional base ref for repo-path mode, e.g. origin/main.")
     parser.add_argument("--fake-model", action="store_true", default=True, help="Use deterministic fake-model mode.")
-    parser.add_argument("--sandbox-runtime", default="fake", choices=("fake", "container", "local-dev"), help="Sandbox runtime.")
+    parser.add_argument("--sandbox-runtime", default="fake", choices=("fake", "container"), help="Sandbox runtime.")
+    parser.add_argument("--container-image", default="python:3-slim", help="Docker image for --sandbox-runtime container.")
     parser.add_argument("--sandbox-timeout-seconds", type=int, default=10, help="Sandbox timeout budget.")
     parser.add_argument("--max-output-bytes", type=int, default=4096, help="Maximum sandbox output bytes to retain.")
     parser.add_argument("--db-path", type=Path, help="SQLite database path for persisted review results.")
@@ -64,10 +65,6 @@ def main(argv: list[str] | None = None) -> int:
         print("provide exactly one of --diff-file or --repo-path", file=sys.stderr)
         return 2
 
-    if args.sandbox_runtime != "fake":
-        print("only --sandbox-runtime fake is implemented in this deterministic example", file=sys.stderr)
-        return 2
-
     try:
         bundle = load_review_input(diff_file=args.diff_file, repo_path=args.repo_path, base_ref=args.base_ref)
     except (FileNotFoundError, RuntimeError, ValueError) as exc:
@@ -84,7 +81,12 @@ def main(argv: list[str] | None = None) -> int:
         bundle.diff_text,
         parsed_diff=bundle.parsed_diff,
         review_input=bundle.review_input,
-        config=ReviewRunConfig(fake_model=args.fake_model, sandbox_policy=policy, db_path=args.db_path),
+        config=ReviewRunConfig(
+            fake_model=args.fake_model,
+            sandbox_policy=policy,
+            db_path=args.db_path,
+            container_image=args.container_image,
+        ),
     )
 
     printed = False

examples/code_review_agent/skills/code-review/references/sandbox_policy.md

@@ -4,11 +4,11 @@ The code-review Agent must treat diff content, generated scripts, and command ou
 
 ## Default runtime
 
-The deterministic example uses `fake` sandbox runtime by default. It records sandbox-shaped results without executing arbitrary host commands.
+The deterministic example uses `fake` sandbox runtime by default. It records sandbox-shaped results without executing arbitrary host commands. It also supports optional `container` runtime through the project's Docker `ContainerClient` for allowlisted scripts.
 
 ## Production runtime
 
-Production implementations should use Container or Cube/E2B workspace runtimes. Local execution is only a development fallback and must require explicit opt-in.
+Production implementations should use Container or Cube/E2B workspace runtimes. This example implements the Container path for allowlisted scripts and documents Cube/E2B as a compatible extension point. Local execution is only a development fallback and must require explicit opt-in.
 
 ## Pre-execution governance