feat: add sandbox filter and telemetry summaries

Author: Small-fish-QAQ

examples/skills_code_review_agent/README.md

@@ -4,9 +4,12 @@ This example implements the early phases of issue #92 as a deterministic,
 local-only code review loop. It reads a unified diff, scans added lines with a
 small static rule set, redacts likely secrets, and writes JSON and Markdown
 reports. When `--db-path` is provided, it also persists the review task,
-findings, and report metadata into SQLite.
+findings, report metadata, sandbox run metadata, and filter decisions into
+SQLite.
 
 It intentionally does not call an LLM, remote sandbox, or SDK core extension.
+The sandbox runner in this example is a fake dry-run runner: it records what
+would have happened, but never executes untrusted code.
 
 ## Run
 
@@ -37,11 +40,13 @@ python examples/skills_code_review_agent/run_agent.py --diff-file examples/skill
 ```
 
 When `--db-path` is set, the command prints the database path and generated
-task id. The database contains three tables:
+task id. The database contains these tables:
 
 - `review_tasks`
 - `findings`
 - `reports`
+- `sandbox_runs`
+- `filter_decisions`
 
 ## Verify SQLite Records
 
@@ -64,8 +69,9 @@ python -m pytest examples/skills_code_review_agent/tests
 ```
 
 The tests run only local parsing, rules, redaction, report generation, and
-dedupe checks. They do not call an LLM, Docker, Cube, remote network, or any
-external service.
+dedupe checks, fake sandbox status, filter decisions, telemetry summaries, and
+SQLite persistence. They do not call an LLM, Docker, Cube, remote network, or
+any external service.
 
 ## Fixtures
 
@@ -90,12 +96,27 @@ external service.
 - Redacts likely API keys, tokens, secrets, and passwords before writing reports.
 - Produces `review_report.json` and `review_report.md`.
 - Optionally persists review tasks, findings, and report metadata to SQLite.
+- Records minimal filter decisions: `allow`, `deny`, or `needs_human_review`.
+- Records a fake dry-run sandbox result without executing untrusted code.
+- Adds telemetry summary fields to JSON and Markdown reports.
 - Includes local pytest coverage for the deterministic rule fixtures.
 
+## Sandbox Notes
+
+The current `dry-run` sandbox runner is deliberately fake and safe for local
+development. It simulates a static-check pass and records status/timing fields.
+It does not run shell commands, install dependencies, invoke Docker, or reach a
+remote sandbox service.
+
+A true local runner should only be used as a development fallback because it
+does not isolate untrusted code. Later phases can replace this example runner
+with the project-level `ContainerWorkspaceRuntime` or `CubeWorkspaceRuntime`
+without changing the report and storage shape introduced here.
+
 ## Not Implemented Yet
 
 - Real LLM review.
 - Real remote sandbox or container execution.
 - SDK core integration.
-- Filter governance and telemetry.
+- Production-grade filter governance and telemetry export.
 - Multi-agent orchestration.

examples/skills_code_review_agent/agent/filtering.py

@@ -0,0 +1,56 @@
+"""Minimal filter decision abstraction for the code review example."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict
+from dataclasses import dataclass
+
+from .diff_parser import ParsedDiff
+
+
+_HIGH_RISK_COMMAND_RE = re.compile(
+    r"\b("
+    r"rm\s+-rf\s+/|"
+    r"curl\b[^|;&]*\|\s*(?:sh|bash)|"
+    r"wget\b[^|;&]*\|\s*(?:sh|bash)|"
+    r"chmod\s+777|"
+    r"Invoke-WebRequest\b[^|;&]*\|\s*iex|"
+    r"iwr\b[^|;&]*\|\s*iex"
+    r")",
+    re.IGNORECASE,
+)
+_MAX_DIFF_BYTES = 200_000
+_MAX_CHANGED_LINES = 2_000
+
+
+@dataclass(frozen=True)
+class FilterDecision:
+    """A minimal filter decision for review governance."""
+
+    decision: str
+    reason: str
+
+    def to_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+def evaluate_filter_decision(diff_text: str, parsed_diff: ParsedDiff) -> FilterDecision:
+    """Evaluate whether the review can proceed automatically."""
+
+    if len(diff_text.encode("utf-8")) > _MAX_DIFF_BYTES:
+        return FilterDecision(
+            decision="needs_human_review",
+            reason=f"diff is larger than {_MAX_DIFF_BYTES} bytes",
+        )
+    if len(parsed_diff.changed_lines) > _MAX_CHANGED_LINES:
+        return FilterDecision(
+            decision="needs_human_review",
+            reason=f"diff changes more than {_MAX_CHANGED_LINES} lines",
+        )
+    if _HIGH_RISK_COMMAND_RE.search(diff_text):
+        return FilterDecision(
+            decision="needs_human_review",
+            reason="diff contains a high-risk command pattern",
+        )
+    return FilterDecision(decision="allow", reason="diff is within dry-run review limits")

examples/skills_code_review_agent/agent/report.py

@@ -35,10 +35,38 @@ def _counts(items: list[str]) -> dict[str, int]:
     return dict(sorted(Counter(items).items()))
 
 
-def build_report(*, diff_file: str, files: list[str], findings: list[Finding], dry_run: bool) -> dict[str, Any]:
+def build_report(
+    *,
+    diff_file: str,
+    files: list[str],
+    findings: list[Finding],
+    dry_run: bool,
+    filter_summary: dict[str, Any] | None = None,
+    sandbox_summary: dict[str, Any] | None = None,
+    telemetry_summary: dict[str, Any] | None = None,
+) -> dict[str, Any]:
     finding_dicts = [_redact_value(finding.to_dict()) for finding in findings]
     severity_counts = _counts([str(item["severity"]) for item in finding_dicts])
     category_counts = _counts([str(item["category"]) for item in finding_dicts])
+    filter_summary = filter_summary or {"decision": "allow", "reason": "not evaluated"}
+    sandbox_summary = sandbox_summary or {
+        "runner_name": "none",
+        "timeout_seconds": 0,
+        "status": "not_run",
+        "started_at": "",
+        "finished_at": "",
+        "stdout_summary": "",
+        "stderr_summary": "",
+    }
+    telemetry_summary = telemetry_summary or {
+        "files_scanned": files,
+        "total_findings": len(finding_dicts),
+        "severity_counts": severity_counts,
+        "category_counts": category_counts,
+        "sandbox_status": sandbox_summary["status"],
+        "filter_decision": filter_summary["decision"],
+        "duration_ms": 0,
+    }
 
     report = {
         "summary": {
@@ -51,6 +79,9 @@ def build_report(*, diff_file: str, files: list[str], findings: list[Finding], d
             "severity_counts": severity_counts,
             "category_counts": category_counts,
         },
+        "filter": filter_summary,
+        "sandbox": sandbox_summary,
+        "telemetry": telemetry_summary,
         "findings": finding_dicts,
     }
     return _redact_value(report)
@@ -68,6 +99,9 @@ def _markdown_table_row(finding: dict[str, Any]) -> str:
 
 def render_markdown(report: dict[str, Any]) -> str:
     summary = report["summary"]
+    filter_summary = report.get("filter", {})
+    sandbox_summary = report.get("sandbox", {})
+    telemetry_summary = report.get("telemetry", {})
     lines = [
         "# Code Review Report",
         "",
@@ -76,6 +110,8 @@ def render_markdown(report: dict[str, Any]) -> str:
         f"- Diff file: `{summary['diff_file']}`",
         f"- Files scanned: {len(summary['files_scanned'])}",
         f"- Total findings: {summary['total_findings']}",
+        f"- Filter decision: {filter_summary.get('decision', 'unknown')}",
+        f"- Sandbox status: {sandbox_summary.get('status', 'unknown')}",
         "",
         "## Severity Counts",
         "",
@@ -86,6 +122,32 @@ def render_markdown(report: dict[str, Any]) -> str:
     else:
         lines.append("- none: 0")
 
+    lines.extend([
+        "",
+        "## Filter Summary",
+        "",
+        f"- Decision: {filter_summary.get('decision', 'unknown')}",
+        f"- Reason: {filter_summary.get('reason', '')}",
+        "",
+        "## Sandbox Summary",
+        "",
+        f"- Runner: {sandbox_summary.get('runner_name', 'unknown')}",
+        f"- Timeout seconds: {sandbox_summary.get('timeout_seconds', 0)}",
+        f"- Status: {sandbox_summary.get('status', 'unknown')}",
+        f"- Started: {sandbox_summary.get('started_at', '')}",
+        f"- Finished: {sandbox_summary.get('finished_at', '')}",
+        f"- Stdout summary: {sandbox_summary.get('stdout_summary', '')}",
+        f"- Stderr summary: {sandbox_summary.get('stderr_summary', '')}",
+        "",
+        "## Telemetry Summary",
+        "",
+        f"- Files scanned: {len(telemetry_summary.get('files_scanned', []))}",
+        f"- Total findings: {telemetry_summary.get('total_findings', 0)}",
+        f"- Sandbox status: {telemetry_summary.get('sandbox_status', 'unknown')}",
+        f"- Filter decision: {telemetry_summary.get('filter_decision', 'unknown')}",
+        f"- Duration ms: {telemetry_summary.get('duration_ms', 0)}",
+    ])
+
     lines.extend(["", "## Findings", ""])
     findings = report["findings"]
     if not findings:

examples/skills_code_review_agent/agent/sandbox.py

@@ -0,0 +1,73 @@
+"""Minimal dry-run sandbox runner abstraction.
+
+This module intentionally does not execute untrusted code. It only records a
+structured dry-run result so later phases can replace the runner with a real
+container or Cube workspace runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Sequence
+
+from .filtering import FilterDecision
+from .findings import Finding
+
+
+def _utc_now() -> str:
+    return datetime.utcnow().replace(microsecond=0).isoformat() + "Z"
+
+
+@dataclass(frozen=True)
+class SandboxRun:
+    """Structured summary of a sandbox runner invocation."""
+
+    runner_name: str
+    timeout_seconds: int
+    status: str
+    started_at: str
+    finished_at: str
+    stdout_summary: str
+    stderr_summary: str
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+class DryRunSandboxRunner:
+    """A fake sandbox runner that records a completed static-check simulation."""
+
+    def __init__(self, timeout_seconds: int = 30) -> None:
+        self.runner_name = "dry-run"
+        self.timeout_seconds = timeout_seconds
+
+    def run(
+        self,
+        *,
+        files: Sequence[str],
+        findings: Sequence[Finding],
+        filter_decision: FilterDecision,
+    ) -> SandboxRun:
+        started_at = _utc_now()
+        finished_at = _utc_now()
+        if filter_decision.decision == "deny":
+            return SandboxRun(
+                runner_name=self.runner_name,
+                timeout_seconds=self.timeout_seconds,
+                status="skipped",
+                started_at=started_at,
+                finished_at=finished_at,
+                stdout_summary="dry-run sandbox skipped because filter denied the review",
+                stderr_summary=filter_decision.reason,
+            )
+        return SandboxRun(
+            runner_name=self.runner_name,
+            timeout_seconds=self.timeout_seconds,
+            status="completed",
+            started_at=started_at,
+            finished_at=finished_at,
+            stdout_summary=f"simulated static checks for {len(files)} files and {len(findings)} findings",
+            stderr_summary="",
+        )

examples/skills_code_review_agent/agent/storage.py

@@ -56,6 +56,32 @@ def init_db(db_path: Path) -> None:
             )
             """
         )
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS sandbox_runs (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                task_id TEXT NOT NULL,
+                runner_name TEXT NOT NULL,
+                timeout_seconds INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                started_at TEXT NOT NULL,
+                finished_at TEXT NOT NULL,
+                stdout_summary TEXT NOT NULL,
+                stderr_summary TEXT NOT NULL,
+                FOREIGN KEY (task_id) REFERENCES review_tasks(task_id) ON DELETE CASCADE
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS filter_decisions (
+                task_id TEXT PRIMARY KEY,
+                decision TEXT NOT NULL,
+                reason TEXT NOT NULL,
+                FOREIGN KEY (task_id) REFERENCES review_tasks(task_id) ON DELETE CASCADE
+            )
+            """
+        )
 
 
 def persist_review(
@@ -71,6 +97,8 @@ def persist_review(
     task_id = str(uuid.uuid4())
     summary = report["summary"]
     findings = report["findings"]
+    sandbox = report.get("sandbox", {})
+    filter_decision = report.get("filter", {})
 
     with sqlite3.connect(db_path) as conn:
         conn.execute("PRAGMA foreign_keys = ON")
@@ -141,5 +169,43 @@ def persist_review(
                 json.dumps(summary, ensure_ascii=False),
             ),
         )
+        conn.execute(
+            """
+            INSERT INTO sandbox_runs (
+                task_id,
+                runner_name,
+                timeout_seconds,
+                status,
+                started_at,
+                finished_at,
+                stdout_summary,
+                stderr_summary
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                task_id,
+                sandbox.get("runner_name", ""),
+                int(sandbox.get("timeout_seconds", 0)),
+                sandbox.get("status", ""),
+                sandbox.get("started_at", ""),
+                sandbox.get("finished_at", ""),
+                sandbox.get("stdout_summary", ""),
+                sandbox.get("stderr_summary", ""),
+            ),
+        )
+        conn.execute(
+            """
+            INSERT INTO filter_decisions (
+                task_id,
+                decision,
+                reason
+            ) VALUES (?, ?, ?)
+            """,
+            (
+                task_id,
+                filter_decision.get("decision", ""),
+                filter_decision.get("reason", ""),
+            ),
+        )
 
     return task_id