@inneranimalmedia/agentsam-sdk 2.0.0 → 2.1.0

package/python/tests/test_recon.py

@@ -0,0 +1,257 @@
+"""Unit tests for repository.recon -- packet building and report validation.
+
+No git dependency required (base_sha falls back to "unknown" outside a repo);
+no model calls; no network.
+"""
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from agentsam_sdk.repository.recon import (
+    PacketError,
+    ReportError,
+    build_task_packet,
+    from_ast_grep,
+    from_matches,
+    from_ripgrep,
+    validate_report,
+)
+
+
+class TestBuildTaskPacket(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        (self.root / "backend").mkdir()
+        (self.root / "backend" / "workflows.js").write_text(
+            "\n".join(f"line {i}" for i in range(1, 201)), encoding="utf-8"
+        )
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_builds_bounded_packet_with_content(self):
+        packet = build_task_packet(
+            self.root,
+            question="Does this file depend on workspace_id?",
+            slices=[{"path": "backend/workflows.js", "start_line": 1, "end_line": 5}],
+        )
+        self.assertEqual(packet["schema_version"], 1)
+        self.assertEqual(len(packet["slices"]), 1)
+        self.assertEqual(packet["slices"][0]["content"], "line 1\nline 2\nline 3\nline 4\nline 5")
+        self.assertEqual(packet["ceilings"]["max_follow_up_reads"], 2)
+        self.assertTrue(packet["task_id"].startswith("recon-"))
+
+    def test_rejects_missing_question(self):
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="  ", slices=[{"path": "backend/workflows.js"}])
+
+    def test_rejects_more_than_five_slices(self):
+        slices = [{"path": "backend/workflows.js"} for _ in range(6)]
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="q", slices=slices)
+
+    def test_rejects_slice_outside_repo_root(self):
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="q", slices=[{"path": "../../etc/passwd"}])
+
+    def test_rejects_missing_file(self):
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="q", slices=[{"path": "backend/nope.js"}])
+
+
+class TestFromMatches(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        (self.root / "backend").mkdir()
+        for name in ("a.js", "b.js", "c.js", "d.js", "e.js", "f.js"):
+            (self.root / "backend" / name).write_text(
+                "\n".join(f"line {i}" for i in range(1, 51)), encoding="utf-8"
+            )
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_chunks_more_than_five_files_into_multiple_packets(self):
+        # 6 files -> ceiling is 5 per packet -> 2 packets
+        matches = [
+            {"path": f"backend/{name}", "line": 10, "kind": "member"}
+            for name in ("a.js", "b.js", "c.js", "d.js", "e.js", "f.js")
+        ]
+        packets = from_matches(self.root, question="q", matches=matches, task_id_prefix="wf")
+        self.assertEqual(len(packets), 2)
+        self.assertEqual(packets[0]["task_id"], "wf-1of2")
+        self.assertEqual(packets[1]["task_id"], "wf-2of2")
+        total_slices = sum(len(p["slices"]) for p in packets)
+        self.assertEqual(total_slices, 6)
+        for p in packets:
+            self.assertLessEqual(len(p["slices"]), 5)
+
+    def test_groups_multiple_hits_in_one_file_into_one_windowed_slice(self):
+        matches = [
+            {"path": "backend/a.js", "line": 5, "kind": "sql_string"},
+            {"path": "backend/a.js", "line": 20, "kind": "sql_string"},
+        ]
+        packets = from_matches(self.root, question="q", matches=matches, context_lines=2)
+        slice_ = packets[0]["slices"][0]
+        self.assertEqual(slice_["start_line"], 3)
+        self.assertEqual(slice_["end_line"], 22)
+        self.assertEqual(slice_["hit_count"], 2)
+        self.assertEqual(slice_["kind"], "sql_string")
+
+    def test_rejects_empty_matches(self):
+        with self.assertRaises(PacketError):
+            from_matches(self.root, question="q", matches=[])
+
+
+class TestFromRipgrep(unittest.TestCase):
+    def test_parses_ndjson_match_lines_only(self):
+        # Real `rg --json` shape: begin/match/end/summary records per file.
+        ndjson = "\n".join([
+            json.dumps({"type": "begin", "data": {"path": {"text": "backend/http/workflows/scope.js"}}}),
+            json.dumps({
+                "type": "match",
+                "data": {
+                    "path": {"text": "backend/http/workflows/scope.js"},
+                    "line_number": 66,
+                    "lines": {"text": "  body.workspace_id\n"},
+                },
+            }),
+            json.dumps({"type": "end", "data": {"path": {"text": "backend/http/workflows/scope.js"}}}),
+            json.dumps({"type": "summary", "data": {}}),
+        ])
+        hits = from_ripgrep(ndjson)
+        self.assertEqual(hits, [{"path": "backend/http/workflows/scope.js", "line": 66}])
+
+    def test_accepts_a_list_of_lines_too(self):
+        lines = [json.dumps({"type": "match", "data": {"path": {"text": "a.js"}, "line_number": 1}})]
+        self.assertEqual(from_ripgrep(lines), [{"path": "a.js", "line": 1}])
+
+    def test_empty_input_yields_no_hits(self):
+        self.assertEqual(from_ripgrep(""), [])
+
+    def test_rejects_malformed_json_line(self):
+        with self.assertRaises(PacketError):
+            from_ripgrep("not json")
+
+
+class TestFromAstGrep(unittest.TestCase):
+    def test_parses_compact_json_array_with_caller_supplied_kind(self):
+        # Real `sg -p '...' --json=compact` shape.
+        raw = json.dumps([
+            {
+                "text": "body.workspace_id",
+                "range": {"start": {"line": 66, "column": 76}, "end": {"line": 66, "column": 93}},
+                "file": "backend/http/workflows/scope.js",
+            },
+            {
+                "text": "ctx.workspaceId",
+                "range": {"start": {"line": 12, "column": 4}, "end": {"line": 12, "column": 19}},
+                "file": "backend/workflows/handlers/tool.js",
+            },
+        ])
+        hits = from_ast_grep(raw, kind="member")
+        self.assertEqual(hits, [
+            {"path": "backend/http/workflows/scope.js", "line": 66, "kind": "member"},
+            {"path": "backend/workflows/handlers/tool.js", "line": 12, "kind": "member"},
+        ])
+
+    def test_kind_is_optional(self):
+        raw = json.dumps([{"range": {"start": {"line": 1}}, "file": "a.js"}])
+        self.assertEqual(from_ast_grep(raw), [{"path": "a.js", "line": 1}])
+
+    def test_empty_array_yields_no_hits(self):
+        self.assertEqual(from_ast_grep("[]"), [])
+
+    def test_rejects_invalid_json(self):
+        with self.assertRaises(PacketError):
+            from_ast_grep("not json")
+
+    def test_adapters_compose_into_from_matches(self):
+        # The actual workflow: run several classified sg queries + one rg sweep,
+        # concatenate, then chunk into packets -- same shape as the iMac smoke test.
+        member_hits = from_ast_grep(
+            json.dumps([{"range": {"start": {"line": 5}}, "file": "backend/a.js"}]), kind="member"
+        )
+        sql_hits = from_ast_grep(
+            json.dumps([{"range": {"start": {"line": 20}}, "file": "backend/b.js"}]), kind="sql_string"
+        )
+        rg_hits = from_ripgrep(json.dumps({
+            "type": "match", "data": {"path": {"text": "backend/c.js"}, "line_number": 8},
+        }))
+        combined = member_hits + sql_hits + rg_hits
+        self.assertEqual(len(combined), 3)
+        self.assertEqual({h["path"] for h in combined}, {"backend/a.js", "backend/b.js", "backend/c.js"})
+        self.assertEqual(combined[2].get("kind"), None)  # rg hit carries no kind
+
+
+class TestValidateReport(unittest.TestCase):
+    def setUp(self):
+        self.packet = {
+            "task_id": "recon-abc123",
+            "slices": [{"path": "backend/workflows.js"}],
+        }
+
+    def test_accepts_answered_report_citing_known_file(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "answered",
+            "findings": [
+                {
+                    "severity": "high",
+                    "file": "backend/workflows.js",
+                    "finding": "still queries workspace_id",
+                }
+            ],
+        }
+        self.assertEqual(validate_report(report, self.packet), report)
+
+    def test_accepts_needs_context_with_reason(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "needs_context",
+            "reason": "definition of ensureWorkflowRun() not supplied",
+        }
+        self.assertEqual(validate_report(report, self.packet)["status"], "needs_context")
+
+    def test_rejects_needs_context_without_reason(self):
+        report = {"schema_version": 1, "task_id": "recon-abc123", "status": "needs_context"}
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+    def test_rejects_finding_that_cites_a_file_outside_the_packet(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "answered",
+            "findings": [
+                {"severity": "high", "file": "backend/other.js", "finding": "made up"}
+            ],
+        }
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+    def test_rejects_task_id_mismatch(self):
+        report = {"schema_version": 1, "task_id": "recon-different", "status": "needs_context", "reason": "x"}
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+    def test_rejects_invalid_severity(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "answered",
+            "findings": [
+                {"severity": "critical", "file": "backend/workflows.js", "finding": "x"}
+            ],
+        }
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/cli.js

@@ -21,7 +21,9 @@ import { runTui } from './commands/tui.js';
 import { runDockerize } from './commands/dockerize.js';
 import { runMini } from './commands/mini.js';
 import { runMerkle } from './commands/merkle.js';
+import { runDeployReceipt } from './commands/deploy-receipt.js';
 import { runSecurity } from './commands/security.js';
+import { runRecon } from './commands/recon.js';
 import { SLASH_COMMANDS, SHELL_PHASES } from './lib/slash-commands.js';
 import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
@@ -48,6 +50,8 @@ function printHelp() {
     agentsam repo snapshot     Git composition/churn; --save retains observations
     agentsam mini <name>       Create and preview a small local gadget (--help for options)
     agentsam merkle            File integrity, snapshots, comparisons, and TUI (--help)
+    agentsam deploy-receipt    Merkle deploy/checkpoint capture + promote/failure receipts (--help)
+    agentsam recon             Bounded-worker task packets + finding-report validation (--help)
     agentsam security          Dependency scan, log triage, and verified repair (--help)
     agentsam status [--json]   Live local Git + DB + API + PTY status
     agentsam db init|status    Manage the project-local SQLite database
@@ -121,13 +125,13 @@ async function runLocalInit(config) {
   );
 
   console.log(`
-  ┌─────────────────────────────────────┐
+  ┌──────────────────────────────────────┐
   │  Agent Sam — local-first scaffold   │
-  ├─────────────────────────────────────┤
+  ├──────────────────────────────────────┤
   │  Name:     ${meta.projectName.padEnd(25)}│
   │  Lane:     ${meta.laneKey.padEnd(25)}│
   │  Run:      ${meta.runTarget.padEnd(25)}│
-  └─────────────────────────────────────┘
+  └──────────────────────────────────────┘
   `);
 
   const dir = writeScaffoldFiles(meta.projectName, meta.files);
@@ -165,10 +169,10 @@ async function initInteractive(partial = {}) {
   const prompt = createPrompt();
 
   console.log(`
-  ╔═══════════════════════════════════╗
+  ╔════════════════════════════════╗
   ║   Agent Sam SDK — Init            ║
   ║   Local-first · Node only         ║
-  ╚═══════════════════════════════════╝
+  ╚════════════════════════════════╝
   `);
 
   const projectName =
@@ -241,9 +245,9 @@ async function runShellInfo(argv = []) {
 
   const next = SHELL_PHASES.find((p) => p.status === 'next' || p.status === 'current');
   console.log(`
-  ╔═══════════════════════════════════╗
+  ╔═══════════════════════════════╗
   ║        Agent Sam Terminal         ║
-  ╚═══════════════════════════════════╝
+  ╚════════════════════════════════╝
 
   Local PTY   agentsam start-local     ws://127.0.0.1:3099
   ANSI TUI    agentsam tui             zero-dependency Node UI
@@ -329,6 +333,10 @@ if (command === '--version' || command === '-v') {
   await runSecurity(rest);
 } else if (command === 'merkle') {
   await runMerkle(rest);
+} else if (command === 'deploy-receipt') {
+  await runDeployReceipt(rest);
+} else if (command === 'recon') {
+  await runRecon(rest);
 } else if (command === 'mini') {
   try {
     await runMini(rest);

package/src/commands/deploy-receipt.js

@@ -0,0 +1,129 @@
+import { captureDeployReceipt, finalizeDeployReceipt, showLatestDeployReceipt } from '../lib/deploy-receipt/index.js';
+
+export function printDeployReceiptHelp() {
+  console.log(`
+  agentsam deploy-receipt — reusable Merkle deployment/checkpoint lifecycle
+
+  capture [path]              Capture the current tree and compare to the last promoted baseline
+  success [path]              Finalize a successful run and promote its snapshot to latest
+  failure [path]              Finalize a failed run without advancing the baseline
+  show [path]                 Print the latest promoted receipt
+
+  --project <id>              Logical project identifier (defaults to directory name)
+  --state-dir <path>          Runtime state directory (default: .agentsam/deploy-merkle)
+  --baseline <snapshot>       Explicit baseline snapshot for capture (e.g. restored from R2)
+  --baseline-source <label>   Baseline provenance label (e.g. r2, local-cache)
+  --include <default-rule>    Include one AgentSam default-ignored category
+  --exclude <path-or-name>    Additional literal exclusion (repeatable)
+  --max-changed-files <n>     Receipt path cap (default 100)
+  --deployment-id <id>        Deployment/ledger identity for success/failure
+  --worker-version <id>       Provider version identity for success/failure
+  --metadata-json <json>      Extra compact receipt metadata object
+  --json                      Machine-readable output
+
+  Runtime state is intentionally not source. The state directory is excluded from the
+  captured Merkle tree, successful finalize advances latest.*, and failure never does.
+
+  Examples:
+    agentsam deploy-receipt capture . --project my-worker --json
+    wrangler deploy
+    agentsam deploy-receipt success . --deployment-id dep_123 --json
+    agentsam deploy-receipt failure . --deployment-id dep_124 --json
+`);
+}
+
+function parseJsonObject(value, flag) {
+  let parsed;
+  try { parsed = JSON.parse(value); } catch { throw new Error(`${flag} must be valid JSON.`); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error(`${flag} must be a JSON object.`);
+  return parsed;
+}
+
+function parse(argv) {
+  const [command, ...args] = argv;
+  const normalized = command === 'fail' ? 'failure' : command === 'promote' ? 'success' : command;
+  if (!['capture', 'success', 'failure', 'show'].includes(normalized)) throw new Error(`Unknown deploy-receipt command: ${command || ''}`);
+  const opts = { command: normalized, root: '.', include: [], exclude: [], json: false, metadata: {} };
+  let positional = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') { positional = true; continue; }
+    if (positional || !arg.startsWith('-')) {
+      if (opts.root !== '.') throw new Error('Only one root path may be supplied.');
+      opts.root = arg;
+      continue;
+    }
+    if (arg === '--json') { opts.json = true; continue; }
+    if (['--project', '--state-dir', '--baseline', '--baseline-source', '--deployment-id', '--worker-version', '--metadata-json', '--max-changed-files', '--include', '--exclude'].includes(arg)) {
+      const value = args[++i];
+      if (value == null || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (arg === '--include') opts.include.push(value);
+      else if (arg === '--exclude') opts.exclude.push(value);
+      else if (arg === '--metadata-json') opts.metadata = parseJsonObject(value, arg);
+      else if (arg === '--max-changed-files') {
+        const count = Number(value);
+        if (!Number.isSafeInteger(count) || count < 1 || count > 10000) throw new Error('--max-changed-files must be an integer from 1 to 10000.');
+        opts.maxChangedFiles = count;
+      } else opts[arg.slice(2).replaceAll('-', '_')] = value;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  if (opts.command !== 'capture' && (opts.baseline || opts.baseline_source || opts.include.length || opts.exclude.length || opts.maxChangedFiles)) {
+    throw new Error('Baseline/include/exclude/change-cap options apply only to capture.');
+  }
+  if (!['success', 'failure'].includes(opts.command) && (opts.deployment_id || opts.worker_version)) {
+    throw new Error('--deployment-id and --worker-version apply only to success/failure.');
+  }
+  return opts;
+}
+
+function human(result, command) {
+  if (!result) return 'No promoted deploy receipt.\n';
+  const receipt = result.receipt || result;
+  if (command === 'capture') {
+    const delta = receipt.diff_stats ? `${receipt.diff_stats.added} added, ${receipt.diff_stats.modified} modified, ${receipt.diff_stats.removed} removed` : 'no baseline';
+    return `Captured ${receipt.root_hash} (${delta}; baseline=${receipt.baseline_source}).\n`;
+  }
+  return `${receipt.status}: ${receipt.root_hash}${receipt.deployment_id ? ` deployment=${receipt.deployment_id}` : ''}\n`;
+}
+
+export async function runDeployReceipt(argv = []) {
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) { printDeployReceiptHelp(); return; }
+  try {
+    const opts = parse(argv);
+    let result;
+    if (opts.command === 'capture') {
+      result = await captureDeployReceipt({
+        root: opts.root,
+        project: opts.project,
+        stateDir: opts.state_dir,
+        baselineSnapshot: opts.baseline,
+        baselineSource: opts.baseline_source,
+        include: opts.include,
+        exclude: opts.exclude,
+        maxChangedFiles: opts.maxChangedFiles,
+        metadata: opts.metadata,
+      });
+    } else if (opts.command === 'show') {
+      result = await showLatestDeployReceipt({ root: opts.root, stateDir: opts.state_dir });
+    } else {
+      result = await finalizeDeployReceipt({
+        root: opts.root,
+        stateDir: opts.state_dir,
+        status: opts.command === 'success' ? 'success' : 'failed',
+        deploymentId: opts.deployment_id,
+        workerVersionId: opts.worker_version,
+        metadata: opts.metadata,
+      });
+    }
+    const output = result?.receipt || result;
+    if (opts.json) process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    else process.stdout.write(human(result, opts.command));
+    return result;
+  } catch (error) {
+    process.exitCode = 2;
+    const json = argv.includes('--json');
+    process.stderr.write(json ? JSON.stringify({ error: error.message }) + '\n' : `Deploy receipt: ${error.message}\n`);
+  }
+}

package/src/commands/recon.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PYTHON_ROOT = fileURLToPath(new URL('../../python', import.meta.url));
+
+export function printReconHelp() {
+  console.log(`
+  agentsam recon — bounded-worker task packets and finding-report validation
+
+  pack --repo-root <path> --question "..." --slice <path[:start-end]> [--slice ...]
+                               Build a bounded ReconTaskPacket (<=5 slices, hard ceilings)
+  validate --packet <file> --report <file>
+                               Validate a ReconFindingReport against its packet
+
+  pack options:
+    --repo-root <path>         Default: .
+    --question <text>          Required. Exactly one bounded question.
+    --slice <path[:start-end]> Repeatable, up to 5. e.g. --slice src/foo.js:10-40
+    --task-id <id>             Default: generated
+    --out <file>                Write the packet JSON to a file instead of stdout
+
+  validate options:
+    --packet <file>             Required. Path to a packet JSON file.
+    --report <file>              Required. Path to a worker's report JSON file.
+
+  Neither command calls a model or writes into the target repository. This is a thin
+  passthrough to the bundled Python module (agentsam_sdk.repository.recon) — same
+  engine as \`python -m agentsam_sdk.repository.recon\`. See docs/RECON.md.
+
+  Examples:
+    agentsam recon pack --repo-root . --question "Does this still read workspace_id?" \\
+      --slice backend/workflows/repository.js:1-180 --out /tmp/packet.json
+    agentsam recon validate --packet /tmp/packet.json --report /tmp/report.json
+
+  For a raw rg/ast-grep hit list instead of hand-picked slices, use
+  agentsam_sdk.repository.recon.{from_ripgrep,from_ast_grep,from_matches}() from
+  Python directly — those have no Node CLI surface yet since hit shapes vary by tool.
+`);
+}
+
+function run(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: { ...process.env, PYTHONPATH: [PYTHON_ROOT, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter) },
+    });
+    child.once('error', (err) => {
+      console.error(`\n  ✗ Could not run Python (${err.message}). Python 3.10+ must be on PATH for \`agentsam recon\`.\n`);
+      resolve(1);
+    });
+    child.once('exit', (code, signal) => {
+      if (signal) { console.error(`\n  ✗ recon ${signal}\n`); resolve(1); }
+      else resolve(code ?? 1);
+    });
+  });
+}
+
+export async function runRecon(argv = []) {
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) { printReconHelp(); return; }
+  const [command] = argv;
+  if (!['pack', 'validate'].includes(command)) {
+    console.error(`\n  ✗ Unknown recon command: ${command}. Use \`agentsam recon --help\`.\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const python = process.platform === 'win32' ? 'python' : 'python3';
+  const code = await run(python, ['-B', '-m', 'agentsam_sdk.repository.recon', ...argv]);
+  if (code !== 0) process.exitCode = code;
+}

package/src/index.js

@@ -6,6 +6,14 @@ export { AgentSam } from './AgentSam.js';
 export { routeIntent } from './lib/router.js';
 export { getToolCatalog } from './lib/tools.js';
 export { scaffoldProject } from './lib/scaffold.js';
+export {
+  DEFAULT_DEPLOY_EXCLUDES,
+  captureDeployReceipt,
+  finalizeDeployReceipt,
+  showLatestDeployReceipt,
+  captureCheckpoint,
+  promoteCheckpoint,
+} from './lib/deploy-receipt/index.js';
 export {
   normalizeGitRemote,
   resolveGitContext,