@inneranimalmedia/agentsam-sdk 2.0.0 → 2.1.0

package/python/agentsam_sdk/repository/recon/cli.py

@@ -0,0 +1,178 @@
+"""CLI and ToolInput adapter for the recon bounded-worker harness.
+
+Two read-only operations, matching the controller/validator halves of the pipeline
+described in docs/RECON.md:
+
+    python -m agentsam_sdk.repository.recon pack --repo-root . \\
+        --question "..." --slice backend/workflows/repository/workflows.js:1-180 \\
+        --out packet.json
+
+    python -m agentsam_sdk.repository.recon validate --packet packet.json \\
+        --report report.json
+
+Neither operation calls a model. `pack` is the deterministic controller step;
+`validate` is the deterministic gate a worker's report must pass before a capable
+agent ever sees it.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult, start_timer, write_receipt
+
+from .packet import TOOL_NAME_PACK, build_task_packet
+from .validate import TOOL_NAME_VALIDATE, ReportError, validate_report
+
+
+def _parse_slice_arg(raw: str) -> dict[str, str | int]:
+    # path[:start-end]
+    if ":" in raw:
+        path, rng = raw.rsplit(":", 1)
+        if "-" in rng:
+            start, end = rng.split("-", 1)
+            return {"path": path, "start_line": int(start), "end_line": int(end)}
+    return {"path": raw}
+
+
+def run_pack(tool_input: ToolInput) -> ToolResult:
+    started = start_timer()
+    try:
+        tool_input.assert_read_only()
+        params = tool_input.params
+        packet = build_task_packet(
+            params.get("repo_root") or ".",
+            question=params["question"],
+            slices=params.get("slices") or [],
+            task_id=params.get("task_id"),
+            allowed_diagnostics=params.get("allowed_diagnostics") or (),
+            max_follow_up_reads=int(params.get("max_follow_up_reads", 2)),
+            max_output_tokens=int(params.get("max_output_tokens", 800)),
+            timeout_seconds=int(params.get("timeout_seconds", 90)),
+        )
+        artifacts: list[str] = []
+        output_dir = tool_input.output_path()
+        if output_dir:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            out = output_dir / f"recon-packet-{packet['task_id']}.json"
+            out.write_text(json.dumps(packet, indent=2), encoding="utf-8")
+            artifacts.append(str(out))
+        result = ToolResult(
+            ok=True,
+            tool=TOOL_NAME_PACK,
+            mode=tool_input.mode or "read-only",
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary=f"Built bounded task packet {packet['task_id']} ({len(packet['slices'])} slice(s)).",
+            data=packet,
+            artifacts=artifacts,
+        )
+    except Exception as exc:  # noqa: BLE001 - normalized into ToolResult
+        result = ToolResult(
+            ok=False,
+            tool=TOOL_NAME_PACK,
+            mode=tool_input.mode or "read-only",
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary="recon pack failed",
+            error=str(exc)[:500],
+        )
+    write_receipt(result, tool_input.output_path())
+    return result
+
+
+def run_validate(tool_input: ToolInput) -> ToolResult:
+    started = start_timer()
+    try:
+        tool_input.assert_read_only()
+        params = tool_input.params
+        packet = params["packet"]
+        report = params["report"]
+        try:
+            validated = validate_report(report, packet)
+            ok = True
+            summary = f"Report for {report.get('task_id')} is valid ({report.get('status')})."
+            error = None
+        except ReportError as exc:
+            validated = {}
+            ok = False
+            summary = "Report rejected; do not forward to the capable agent."
+            error = str(exc)
+        result = ToolResult(
+            ok=ok,
+            tool=TOOL_NAME_VALIDATE,
+            mode=tool_input.mode or "read-only",
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary=summary,
+            data={"validated_report": validated} if ok else {},
+            error=error,
+        )
+    except Exception as exc:  # noqa: BLE001 - normalized into ToolResult
+        result = ToolResult(
+            ok=False,
+            tool=TOOL_NAME_VALIDATE,
+            mode=tool_input.mode or "read-only",
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary="recon validate failed",
+            error=str(exc)[:500],
+        )
+    write_receipt(result, tool_input.output_path())
+    return result
+
+
+def main_cli(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m agentsam_sdk.repository.recon",
+        description="Build bounded recon task packets and validate worker findings.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    pack_p = sub.add_parser("pack", help="Build a bounded ReconTaskPacket.")
+    pack_p.add_argument("--repo-root", default=".")
+    pack_p.add_argument("--question", required=True)
+    pack_p.add_argument(
+        "--slice", dest="slices", action="append", default=[],
+        help="path[:start-end], repeatable, up to 5.",
+    )
+    pack_p.add_argument("--task-id")
+    pack_p.add_argument("--out")
+
+    validate_p = sub.add_parser("validate", help="Validate a ReconFindingReport against its packet.")
+    validate_p.add_argument("--packet", required=True, help="Path to a packet JSON file.")
+    validate_p.add_argument("--report", required=True, help="Path to a report JSON file.")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "pack":
+        packet = build_task_packet(
+            args.repo_root,
+            question=args.question,
+            slices=[_parse_slice_arg(s) for s in args.slices],
+            task_id=args.task_id,
+        )
+        rendered = json.dumps(packet, indent=2)
+        if args.out:
+            Path(args.out).expanduser().write_text(rendered, encoding="utf-8")
+        else:
+            print(rendered)
+        return 0
+
+    if args.command == "validate":
+        packet = json.loads(Path(args.packet).expanduser().read_text(encoding="utf-8"))
+        report = json.loads(Path(args.report).expanduser().read_text(encoding="utf-8"))
+        try:
+            validate_report(report, packet)
+        except ReportError as exc:
+            print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
+            return 1
+        print(json.dumps({"ok": True}, indent=2))
+        return 0
+
+    return 2

package/python/agentsam_sdk/repository/recon/packet.py

@@ -0,0 +1,294 @@
+"""Build a bounded ReconTaskPacket from an explicit repo root and an explicit file list.
+
+Design law (mirrors protocol/README.md rule 6 and docs/REPOSITORY_INTELLIGENCE.md):
+  - Read-only. This module never writes into the target repository.
+  - Accepts an explicit repo_root; never assumes one repository's layout.
+  - Never hardcodes a tenant/workspace/provider ID as the task handle.
+  - The caller (a capable agent, or repository.intelligence output) selects the files.
+    This module does not go searching for "relevant" files on its own — that discovery
+    step belongs upstream, where budget and reasoning are cheap.
+
+Stdlib only.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Iterable
+
+SCHEMA_VERSION = 1
+TOOL_NAME_PACK = "repository.recon.pack"
+MAX_SLICES = 5
+MAX_FOLLOW_UP_READS = 2
+DEFAULT_TIMEOUT_SECONDS = 90
+DEFAULT_MAX_OUTPUT_TOKENS = 800
+
+
+class PacketError(ValueError):
+    """Raised when a task packet cannot be built as specified."""
+
+
+def _head_sha(repo_root: Path) -> str:
+    try:
+        out = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"], cwd=repo_root, stderr=subprocess.DEVNULL
+        )
+        return out.decode("utf-8", errors="surrogateescape").strip()
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+        return "unknown"
+
+
+def _read_slice(repo_root: Path, rel_path: str, start_line: int | None, end_line: int | None) -> str:
+    target = (repo_root / rel_path).resolve()
+    try:
+        target.relative_to(repo_root.resolve())
+    except ValueError as exc:
+        raise PacketError(f"slice_escapes_repo_root:{rel_path}") from exc
+    if not target.is_file():
+        raise PacketError(f"slice_not_found:{rel_path}")
+    try:
+        text = target.read_text(encoding="utf-8", errors="strict")
+    except (UnicodeDecodeError, OSError) as exc:
+        raise PacketError(f"slice_unreadable:{rel_path}") from exc
+    if start_line is None and end_line is None:
+        return text
+    lines = text.splitlines()
+    start = max(1, start_line or 1)
+    end = min(len(lines), end_line or len(lines))
+    if start > end:
+        raise PacketError(f"slice_range_invalid:{rel_path}:{start}-{end}")
+    return "\n".join(lines[start - 1 : end])
+
+
+def build_task_packet(
+    repo_root: str | Path,
+    *,
+    question: str,
+    slices: Iterable[dict[str, Any]],
+    task_id: str | None = None,
+    allowed_diagnostics: Iterable[str] = (),
+    max_follow_up_reads: int = MAX_FOLLOW_UP_READS,
+    max_output_tokens: int = DEFAULT_MAX_OUTPUT_TOKENS,
+    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+    embed_content: bool = True,
+) -> dict[str, Any]:
+    """Build one bounded ReconTaskPacket.
+
+    `slices` is a list of {"path", "start_line"?, "end_line"?, "reason"?} — exact,
+    caller-chosen material. This function never expands that list; it only reads and
+    validates it, and enforces the hard ceilings from protocol/recon/task-packet.schema.json.
+    """
+    root = Path(repo_root).expanduser().resolve()
+    if not root.is_dir():
+        raise PacketError(f"repo_root_not_found:{root}")
+    if not question or not question.strip():
+        raise PacketError("question_required")
+
+    slice_list = list(slices)
+    if not slice_list:
+        raise PacketError("at_least_one_slice_required")
+    if len(slice_list) > MAX_SLICES:
+        raise PacketError(f"too_many_slices:{len(slice_list)}>{MAX_SLICES}")
+    if not (0 <= max_follow_up_reads <= MAX_FOLLOW_UP_READS):
+        raise PacketError(f"max_follow_up_reads_out_of_range:{max_follow_up_reads}")
+
+    resolved_slices: list[dict[str, Any]] = []
+    for item in slice_list:
+        path = item.get("path")
+        if not path:
+            raise PacketError("slice_missing_path")
+        start_line = item.get("start_line")
+        end_line = item.get("end_line")
+        entry: dict[str, Any] = {"path": path}
+        if start_line is not None:
+            entry["start_line"] = int(start_line)
+        if end_line is not None:
+            entry["end_line"] = int(end_line)
+        if item.get("reason"):
+            entry["reason"] = str(item["reason"])
+        if item.get("kind"):
+            entry["kind"] = str(item["kind"])
+        if item.get("hit_count"):
+            entry["hit_count"] = int(item["hit_count"])
+        if embed_content:
+            entry["content"] = _read_slice(root, path, entry.get("start_line"), entry.get("end_line"))
+        resolved_slices.append(entry)
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "task_id": task_id or f"recon-{uuid.uuid4().hex[:12]}",
+        "repo_root": str(root),
+        "base_sha": _head_sha(root),
+        "generated_at_unix": int(time.time()),
+        "question": question.strip(),
+        "slices": resolved_slices,
+        "allowed_diagnostics": list(allowed_diagnostics),
+        "ceilings": {
+            "max_follow_up_reads": max_follow_up_reads,
+            "max_output_tokens": max_output_tokens,
+            "timeout_seconds": timeout_seconds,
+        },
+        "response_schema_ref": "./finding-report.schema.json",
+    }
+
+
+def from_matches(
+    repo_root: str | Path,
+    *,
+    question: str,
+    matches: Iterable[dict[str, Any]],
+    task_id_prefix: str = "recon",
+    max_files_per_packet: int = MAX_SLICES,
+    context_lines: int = 3,
+    **packet_kwargs: Any,
+) -> list[dict[str, Any]]:
+    """Turn raw, tool-agnostic search hits into one or more bounded packets.
+
+    This is the adapter for "I already ran rg/ast-grep and have a hit list, now I
+    need packets" -- it does not run any search itself. `matches` is any iterable of
+    {"path": str, "line": int, "kind": str?} -- output from from_ripgrep()/from_ast_grep()
+    (or any hand-built equivalent) works directly.
+
+    Hits are grouped by file into one slice per file (a [min-context, max+context]
+    line window covering every hit in that file), then chunked into packets of at
+    most `max_files_per_packet` files each -- so a 16-file, 41-hit sweep becomes
+    several small packets instead of one that violates the slice ceiling or silently
+    drops files.
+
+    The worker still never searches. This function is what the controller runs
+    *instead of* handing the worker rg.
+    """
+    if max_files_per_packet > MAX_SLICES:
+        raise PacketError(f"max_files_per_packet_exceeds_ceiling:{max_files_per_packet}>{MAX_SLICES}")
+
+    by_path: dict[str, dict[str, Any]] = {}
+    for hit in matches:
+        path = hit.get("path")
+        if not path:
+            raise PacketError("match_missing_path")
+        line = hit.get("line")
+        entry = by_path.setdefault(path, {"lines": [], "kinds": set()})
+        if line is not None:
+            entry["lines"].append(int(line))
+        if hit.get("kind"):
+            entry["kinds"].add(str(hit["kind"]))
+
+    if not by_path:
+        raise PacketError("no_matches_supplied")
+
+    files = sorted(by_path)
+    packets: list[dict[str, Any]] = []
+    chunks = [files[i : i + max_files_per_packet] for i in range(0, len(files), max_files_per_packet)]
+    for idx, chunk in enumerate(chunks, start=1):
+        slices = []
+        for path in chunk:
+            entry = by_path[path]
+            lines = entry["lines"]
+            if lines:
+                start = max(1, min(lines) - context_lines)
+                end = max(lines) + context_lines
+            else:
+                start = end = None
+            kinds = sorted(entry["kinds"])
+            reason = f"{len(lines) or 'unknown-count of'} hit(s)"
+            if kinds:
+                reason += f" ({', '.join(kinds)})"
+            slice_entry: dict[str, Any] = {"path": path, "reason": reason}
+            if start is not None:
+                slice_entry["start_line"] = start
+                slice_entry["end_line"] = end
+            if lines:
+                slice_entry["hit_count"] = len(lines)
+            if len(kinds) == 1:
+                slice_entry["kind"] = kinds[0]
+            slices.append(slice_entry)
+        suffix = f"-{idx}of{len(chunks)}" if len(chunks) > 1 else ""
+        packets.append(
+            build_task_packet(
+                repo_root,
+                question=question,
+                slices=slices,
+                task_id=f"{task_id_prefix}{suffix}",
+                **packet_kwargs,
+            )
+        )
+    return packets
+
+
+def from_ripgrep(rg_json: str | Iterable[str]) -> list[dict[str, Any]]:
+    """Parse `rg --json` NDJSON output into `from_matches()`-shaped hits.
+
+    Runs no search itself -- pass the captured stdout of an `rg --json ...` call
+    (a single string, or an iterable of its lines). Only `type: "match"` records are
+    kept. rg is lexical only, so hits carry no `kind` -- pair with `from_ast_grep()`
+    output in the same `matches` list when structural classification is available.
+
+    Example::
+
+        raw = subprocess.run(
+            ["rg", "--json", "-e", "workspace_id", "backend/workflows"],
+            capture_output=True, text=True,
+        ).stdout
+        matches = recon.from_ripgrep(raw)
+    """
+    lines = rg_json.splitlines() if isinstance(rg_json, str) else rg_json
+    hits: list[dict[str, Any]] = []
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise PacketError(f"rg_json_line_invalid:{line[:80]}") from exc
+        if obj.get("type") != "match":
+            continue
+        data = obj.get("data", {})
+        path = (data.get("path") or {}).get("text")
+        line_number = data.get("line_number")
+        if not path or line_number is None:
+            continue
+        hits.append({"path": path, "line": int(line_number)})
+    return hits
+
+
+def from_ast_grep(sg_json_compact: str, *, kind: str | None = None) -> list[dict[str, Any]]:
+    """Parse `sg`/`ast-grep ... --json=compact` array output into `from_matches()`-shaped hits.
+
+    Runs no search itself. One ast-grep invocation is one pattern or one inline rule --
+    i.e. one structural shape -- so `kind` is a caller-supplied label applied to every
+    hit from that call (e.g. "member", "member_camel", "sql_string"), not something
+    this function infers. Redirect the deprecation banner ast-grep prints on stderr
+    away from stdout (it does not appear in --json=compact stdout, but callers piping
+    `2>&1` will see it mixed in).
+
+    Example::
+
+        raw = subprocess.run(
+            ["sg", "-p", "$X.workspace_id", "-l", "js", "--json=compact",
+             "backend/workflows"],
+            capture_output=True, text=True,
+        ).stdout
+        matches = recon.from_ast_grep(raw, kind="member")
+    """
+    text = sg_json_compact.strip()
+    if not text:
+        return []
+    try:
+        records = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise PacketError(f"sg_json_invalid:{text[:80]}") from exc
+    hits: list[dict[str, Any]] = []
+    for record in records:
+        path = record.get("file")
+        line_number = ((record.get("range") or {}).get("start") or {}).get("line")
+        if not path or line_number is None:
+            continue
+        hit: dict[str, Any] = {"path": path, "line": int(line_number)}
+        if kind:
+            hit["kind"] = kind
+        hits.append(hit)
+    return hits

package/python/agentsam_sdk/repository/recon/validate.py

@@ -0,0 +1,76 @@
+"""Validate a worker's ReconFindingReport against its originating packet.
+
+This is the deterministic validator in the pipeline:
+    controller -> packet -> mini worker -> [this module] -> capable agent
+
+It does not trust the worker. It checks structure, checks that every referenced file
+was actually inside the packet's slices (a worker cannot invent evidence for a file it
+was never given), and enforces the "never guess" rule: a report that isn't clearly
+`answered` or `needs_context` is rejected rather than passed upstream.
+
+Stdlib only.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+TOOL_NAME_VALIDATE = "repository.recon.validate"
+REQUIRED_TOP_LEVEL = ("schema_version", "task_id", "status")
+VALID_STATUSES = ("answered", "needs_context")
+VALID_SEVERITIES = ("low", "medium", "high")
+
+
+class ReportError(ValueError):
+    """Raised when a finding report fails validation and must not be forwarded."""
+
+
+def _known_paths(packet: dict[str, Any]) -> set[str]:
+    return {s["path"] for s in packet.get("slices", [])}
+
+
+def validate_report(report: dict[str, Any], packet: dict[str, Any]) -> dict[str, Any]:
+    """Return the report unchanged if valid; raise ReportError otherwise.
+
+    Callers should treat a ReportError as "discard this worker output, do not hand it
+    to the capable agent" — never as something to silently patch and pass along.
+    """
+    if not isinstance(report, dict):
+        raise ReportError("report_not_an_object")
+
+    missing = [key for key in REQUIRED_TOP_LEVEL if key not in report]
+    if missing:
+        raise ReportError(f"missing_fields:{','.join(missing)}")
+
+    if report.get("schema_version") != 1:
+        raise ReportError(f"unsupported_schema_version:{report.get('schema_version')}")
+
+    if report.get("task_id") != packet.get("task_id"):
+        raise ReportError("task_id_mismatch")
+
+    status = report.get("status")
+    if status not in VALID_STATUSES:
+        raise ReportError(f"invalid_status:{status}")
+
+    if status == "needs_context":
+        if not report.get("reason"):
+            raise ReportError("needs_context_missing_reason")
+        return report
+
+    # status == "answered"
+    known = _known_paths(packet)
+    for finding in report.get("findings", []):
+        for key in ("severity", "file", "finding"):
+            if key not in finding:
+                raise ReportError(f"finding_missing_field:{key}")
+        if finding["severity"] not in VALID_SEVERITIES:
+            raise ReportError(f"invalid_severity:{finding['severity']}")
+        if finding["file"] not in known:
+            raise ReportError(
+                f"finding_cites_file_outside_packet:{finding['file']}"
+            )
+
+    for path in report.get("affected_files", []):
+        if path not in known:
+            raise ReportError(f"affected_file_outside_packet:{path}")
+
+    return report