@inneranimalmedia/agentsam-sdk 2.0.0 → 2.1.0

package/README.md

@@ -67,6 +67,7 @@ Python-backed snapshots capture repository composition and Git churn.
 | File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
 | Dependency health and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
 | Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
+| Recon bounded-worker packets | `agentsam recon pack\|validate` | [Recon](docs/RECON.md) |
 | Local containers | `agentsam dockerize`; `/dockerize` | [Dockerize](docs/DOCKERIZE.md) |
 | Background indexing service | Docker `knowledge_service`; `/knowledge-service-client` | [Knowledge service](docs/knowledge-service.md) |
 | Local status, DB, terminal UI | `agentsam status`, `db`, `tui`, `start-local` | [Terminal UI](docs/CLI_SHELL.md) |

package/docs/DEPLOY_RECEIPTS.md

@@ -0,0 +1,83 @@
+# Deployment receipts and checkpoints
+
+Agent Sam's Merkle tree answers a source identity question: **what exact file tree exists right now?**
+
+The deploy-receipt lifecycle adds a second question: **what changed since the last state we trusted?**
+
+The runtime checkpoint belongs under `.agentsam/deploy-merkle/` by default and is deliberately excluded from the captured source tree. It is cache/checkpoint state, not application source. Committing it would make deployment bookkeeping mutate Git and feed back into the next hash.
+
+## CLI
+
+```sh
+agentsam deploy-receipt capture . --project my-app --json
+# run any deployment provider here
+agentsam deploy-receipt success . --deployment-id dep_123 --worker-version worker_v1 --json
+```
+
+If deployment fails:
+
+```sh
+agentsam deploy-receipt failure . --deployment-id dep_123 --json
+```
+
+A successful finalize promotes `latest.snapshot.json` and `latest.receipt.json`. A failed finalize writes failure history but does **not** advance the trusted baseline.
+
+An external durable snapshot (R2, S3, GCS, artifact store, etc.) can be restored before capture and supplied explicitly:
+
+```sh
+agentsam deploy-receipt capture . \
+  --baseline /tmp/last-success.snapshot.json \
+  --baseline-source r2 \
+  --project my-app \
+  --json
+```
+
+Provider storage stays an adapter. The Merkle tree, diff, receipt contract, local checkpoint state, Git metadata, dirty-tree observation, and success/failure promotion semantics live in the SDK.
+
+## Programmatic API
+
+```js
+import {
+  captureDeployReceipt,
+  finalizeDeployReceipt,
+} from '@inneranimalmedia/agentsam-sdk/deploy-receipt';
+
+const capture = await captureDeployReceipt({
+  root: process.cwd(),
+  project: 'my-app',
+  baselineSnapshot: restoredSnapshotPath,
+  baselineSource: 'r2',
+});
+
+try {
+  const deployment = await deploy();
+  const completed = await finalizeDeployReceipt({
+    root: process.cwd(),
+    status: 'success',
+    deploymentId: deployment.id,
+    workerVersionId: deployment.versionId,
+  });
+  await persistSnapshotAndReceipt(completed);
+} catch (error) {
+  await finalizeDeployReceipt({
+    root: process.cwd(),
+    status: 'failed',
+  });
+  throw error;
+}
+```
+
+The same primitive is exported as `captureCheckpoint()` / `promoteCheckpoint()` for long-running agent work. That enables a loop to checkpoint a trusted tree, execute a batch, inspect the exact Merkle delta, run verification, and only promote the new checkpoint when the batch is accepted.
+
+## Receipt shape
+
+A capture includes compact metadata such as:
+
+- Git SHA, branch, repository remote, and dirty-tree state
+- current Merkle root and previous trusted root
+- added / modified / removed counts
+- exact changed paths (capped for receipt size)
+- file / directory / byte statistics
+- baseline provenance
+
+Full file trees remain Merkle snapshots. Deployment ledgers should store the compact receipt metadata rather than the complete manifest.

package/docs/RECON.md

@@ -0,0 +1,165 @@
+# Recon: bounded-worker harness (aka "MiniCodeScout")
+
+A cheap or local model (Ollama/Qwen-class, a mini-tier hosted model, whatever's
+cheapest that week) can be useful as a **reconnaissance subagent** — but only once
+the evidence handed to it is already disambiguated. Live investigation on the
+`feat/workflow-runtime-v2` worktree found the actual failure mode wasn't missing
+ceilings, it was mixed-signal evidence: a flat `rg 'workspace_id'` sweep conflates
+a JS member access (`authUser?.workspace_id`), an object key (`workspace_id: ctx.workspaceId`),
+and a SQL template literal (`` `AND workspace_id = ?` ``) into one undifferentiated
+hit list. That's why a Qwen-class mini guessed — not because it lacked a schema.
+
+**Current status:** the mini-worker step is benched for this sprint (decision:
+`workflows-v2:ollama-benched`; follow-up tracked as backlog P3). Deterministic
+search alone (`rg` and `ast-grep`, both installed on the primary dev machine) is
+already answering the questions that matter, faster and for free. This kit ships
+as reusable infra ahead of need — it isn't on the critical path for Workflows v2,
+and nothing here should be read as "go delegate to Ollama now." `ast-grep` stays
+recon-only: no `sgconfig.yml`, no `--fix`/`--update-all`/`--interactive` on target
+files until well after v2 lands — those are what turn it from search into a write
+action.
+
+## Where recon actually starts
+
+Recon is the last two stages of a longer pipeline, not the whole thing:
+
+```text
+lexical search (rg)         "where is this text?"          — do this first, always
+        |
+structural search (ast-grep)
+        |                   "where is this shape, and which kind?"
+        v
+   raw hits: {path, line, kind?}
+        |
+        v
+agentsam_sdk.repository.recon.from_matches(...)
+        |                   groups by file, windows context lines,
+        |                   chunks into packets of <=5 files each
+        v
+   ReconTaskPacket(s)   (protocol/recon/task-packet.schema.json)
+        |
+        v
+     mini worker          (only if/when actually delegated -- never given rg)
+        |
+        v
+   ReconFindingReport   (protocol/recon/finding-report.schema.json)
+        |
+        v
+agentsam_sdk.repository.recon.validate_report(...)
+        |
+        v
+     capable agent         (verifies, edits, git, tests, PR)
+```
+
+Hand-picked slices still work too — `build_task_packet()` takes an explicit slice
+list directly when you already know exactly which 5 files matter and don't have a
+raw hit list to chunk.
+
+## Rules the worker operates under
+
+- **One question, not a subsystem audit.** "Does this file still read
+  `workspace_id`?" — not "audit the workflow runtime."
+- **≤5 file slices per packet, supplied — never discovered.** The worker doesn't
+  run its own `rg`/`ast-grep`/`find`/`ls`; the controller already ran search and
+  chunked the results before the worker ever sees anything. "Do not give Qwen rg."
+- **≤2 follow-up reads**, each still inside the packet's ceilings.
+- **Read-only diagnostics only**, and only ones the controller pre-approved
+  (`allowed_diagnostics` in the packet) — `git status`/`diff`/`log`/`show`, a
+  syntax check, a single named test. Never `git add|commit|reset|push`, never a
+  migration, never a full build or deploy, never `ast-grep --fix`/`sg --update-all`
+  on the target files.
+- **No branch ownership.** The worker's only output is a `ReconFindingReport`. It
+  never calls `write_file` against the repository.
+- **Never guess.** If the supplied slices don't answer the question, the worker
+  returns `status: "needs_context"` with `reason` and `missing` — not a
+  fabricated finding. `validate_report` rejects any `answered` report that cites
+  a file outside the packet's slices, so a worker can't paper over a gap with
+  invented evidence either.
+- **A slice's `kind` (when present) is a controller-verified structural label,
+  not a hint the worker should second-guess.** `sql_string` and `member` are not
+  the same finding even when the literal text matches.
+
+## Where each half lives
+
+| Half | Module | Notes |
+| --- | --- | --- |
+| rg adapter | `agentsam_sdk.repository.recon.from_ripgrep` | Parses `rg --json` NDJSON into hits. No `kind` — lexical only. Runs no search itself. |
+| ast-grep adapter | `agentsam_sdk.repository.recon.from_ast_grep` | Parses `sg`/`ast-grep --json=compact` array output into hits, tagged with a caller-supplied `kind` (one invocation = one shape). Runs no search itself. |
+| Chunker | `agentsam_sdk.repository.recon.from_matches` | Takes hits from either adapter (or hand-built), groups by file, windows context lines, chunks anything over 5 files into multiple packets. |
+| Controller (hand-picked packets) | `agentsam_sdk.repository.recon.build_task_packet` | For when you already know the exact ≤5 files/lines — no hit list to chunk. |
+| Validator (gate reports) | `agentsam_sdk.repository.recon.validate_report` | Structural check + the "never guess" rule + citation check (findings can't reference files the worker was never given). Raises `ReportError`; callers must discard, not patch, a rejected report. |
+| Contracts | `protocol/recon/task-packet.schema.json`, `protocol/recon/finding-report.schema.json` | Provider-neutral; usable from the CLI, the MCP surface, or a Worker. |
+| CLI | `agentsam recon pack \| validate` (Node, thin passthrough) or `python -m agentsam_sdk.repository.recon pack \| validate` | Hand-picked slices only. Same `ToolInput`/`ToolResult` contract as every other `agentsam_sdk` tool on the Python side — read-only by default, gets a receipt. |
+
+This kit intentionally stops at the report. Model orchestration — which model
+answers a packet, retries, cost routing, whether delegation happens at all — is
+host policy, same as the rest of the SDK's "host integration and ownership"
+boundary in the root README. A future `bounded-mutation` contract (a worker
+allowed to perform one specific, proven-safe transform, e.g. "rename import path
+A → B") is a separate, narrower protocol, not an extension of recon's read-only
+contract. `ast-grep` structural classification (splitting hits by node kind) is a
+separate layer with its own hard rule — recon only, never `sgconfig.yml`/`--fix`
+on target files — and `from_ast_grep()`/`from_matches()` carry its `kind` labels
+through into packets without needing a schema change.
+
+## Example
+
+`from_ripgrep()` and `from_ast_grep()` parse the two tools' real output shapes directly
+-- no hand-rolled JSON parsing needed. `from_ast_grep()` takes a `kind` label because one
+`sg`/`ast-grep` invocation is one pattern or rule, i.e. one structural shape; `from_ripgrep()`
+never sets `kind` since lexical hits carry no structural classification on their own.
+
+```python
+import subprocess
+from agentsam_sdk.repository import recon
+
+def run(*args):
+    return subprocess.run(args, capture_output=True, text=True).stdout
+
+matches = []
+matches += recon.from_ast_grep(
+    run("sg", "-p", "$X.workspace_id", "-l", "js", "--json=compact",
+        "backend/workflows", "backend/http/workflows"),
+    kind="member",
+)
+matches += recon.from_ast_grep(
+    run("sg", "-p", "$X.workspaceId", "-l", "js", "--json=compact",
+        "backend/workflows", "backend/http/workflows"),
+    kind="member_camel",
+)
+matches += recon.from_ast_grep(
+    run("sg", "scan", "--inline-rules",
+        "id: sql-ws\nlanguage: JavaScript\nrule:\n  kind: template_string\n  regex: workspace_id",
+        "backend/workflows", "backend/http/workflows", "--json=compact"),
+    kind="sql_string",
+)
+
+packets = recon.from_matches(
+    ".",
+    question="Does this file still depend on removed workspace-scoped columns?",
+    matches=matches,
+    task_id_prefix="workflow-v2-runtime-audit",
+)
+# classified hits across N files -> packets of <=5 files each, ready to hand to a
+# capable model for direct classification, or to a delegated worker later. Files
+# with more than one kind in their hit set come back with slice.kind omitted --
+# genuinely mixed evidence is a real signal, not something to flatten.
+```
+
+Also usable from the shell directly for hand-picked slices, no Python needed:
+
+```sh
+agentsam recon pack --repo-root . --question "..." \
+  --slice backend/workflows/repository.js:1-180 --out /tmp/packet.json
+agentsam recon validate --packet /tmp/packet.json --report /tmp/report.json
+```
+
+`agentsam recon` is a thin passthrough to the same Python module (`python -m
+agentsam_sdk.repository.recon`), for hand-picked slices only -- `from_matches`,
+`from_ripgrep`, and `from_ast_grep` are Python-only since raw hit shapes vary by tool
+and don't have a stable CLI surface yet.
+
+See [`REPOSITORY_INTELLIGENCE.md`](REPOSITORY_INTELLIGENCE.md) for the git-level
+evidence layer (hotspots/churn) that can help decide *which* files to search in
+the first place, and [`protocol/README.md`](../protocol/README.md) (rule 6) for
+the read-only, no-hardcoded-identity law this module follows.

package/docs/RELEASES.md

@@ -1,11 +1,11 @@
 # `@inneranimalmedia/agentsam-sdk` release receipts
 
-**2.0.0 is prepared, not yet published.** See [stable release instructions](sdk-2.0-release.md).
-Add its publication receipt only after npm confirms success; this preparation does not
-publish the private identity workspace or create a `v2.0.0` release tag.
+**2.0.0 is published on npm and is the `latest` dist-tag.** The private identity workspace
+continues to ship through the root SDK exports and is not published separately.
 
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
+| 2.0.0 | 2026-09-03T02:21:44.857Z | `ed629869e701809d2bf4c61bd56d05d8d8d1e183` | Stable SDK 2.0.0; npm `latest`; identity bundled through root exports; release verification and dependency scan passed before publish. |
 | 2.0.0-alpha.identity.5 | _(pending npm)_ | `df064114eb7f8888f163e4a07dfddf19035b7169` | Password reset service, `registerFinalizeInboundOAuth`, IAM live proof. |
 | 2.0.0-alpha.identity.4 | 2026-08-22 | `df064114eb7f8888f163e4a07dfddf19035b7169` | IAM auth portal sync: signup→`/api/auth/signup`, `company-branding.js`, preview stubs. SDK git `d7498ca`. |
 | 2.0.0-alpha.identity.3 | 2026-08-22 | `559bc37267f76790136004f5fa94a2bb3cd6a721` | `company` table + `GET/PATCH /api/company` branding SSOT. |

package/docs/sdk-2.0-release.md

@@ -1,6 +1,6 @@
 # AgentSam SDK 2.0.0 release
 
-Status: prepared for manual npm publication; no publish is performed by branch cleanup.
+Status: published to npm as `@inneranimalmedia/agentsam-sdk@2.0.0`; npm `latest` points to 2.0.0.
 
 ## Product boundaries
 
@@ -32,8 +32,8 @@ automatic retention, multi-user authorization and production routing remain host
 
 ## Changes from 1.9 and the identity alphas
 
-- The npm `latest` tag was 1.9.0 at preparation; the alpha tag was
-  2.0.0-alpha.identity.12. Version 2.0.0 was not present in the registry.
+- npm `latest` advanced from 1.9.0 to 2.0.0. The alpha tag remains
+  2.0.0-alpha.identity.12 for the final identity prerelease line.
 - Node 22.5+ is required. Python 3.10+ is required for Python repository intelligence;
   Docker is required only when actually building/running containers.
 - In an existing repository, `agentsam init` configures repository knowledge. Use
@@ -43,36 +43,34 @@ automatic retention, multi-user authorization and production routing remain host
 - Knowledge and Docker features from PRs #20 and #21 are integrated in main.
 - Publication runs the installed-tarball consumer proof, Python tests, and dependency scan
   in addition to the existing SDK, identity, bootstrap and package checks.
-- The legacy alpha workflow refuses stable versions. Stable npm publication stays manual.
+- The legacy alpha workflow refuses stable versions. Stable npm publication remains manual.
 
-## Publish from the clean main checkout
+## Publication receipt
 
-```sh
-cd /Users/samprimeaux/agentsam-sdk
-git status --short
-git pull --ff-only
-npm ci
-bash scripts/npm-publish-preflight.sh
-npm publish --tag latest --access public
+Version 2.0.0 was published on 2026-09-03 at `2026-09-03T02:21:44.857Z` from SDK git SHA
+`ed629869e701809d2bf4c61bd56d05d8d8d1e183`. npm recorded this integrity value:
+
+```text
+sha512-lXnBp8GR1iduKWxxHSRHSd9Q1fjTUZvX1UecwtS8xdDxMdZRd2BSHtDygm0OMNYchrtUP1nR6g0t3MqZTkE5HA==
 ```
 
-The `prepublishOnly` hook runs `npm run verify:release` before upload. This runs the SDK and
-identity suites, package/bootstrap checks, installed-tarball fixtures, Python tests and a
-complete dependency scan. The tests do not call embedding providers or production databases.
-If npm requests login or a one-time code, complete that in your terminal. Do not publish
-with `--workspaces`: identity and shell-kit workspaces remain private.
+The `prepublishOnly` hook ran `npm run verify:release` before upload. That verification ran
+the SDK and identity suites, package/bootstrap checks, installed-tarball fixtures, Python
+tests and the complete dependency scan. The private identity and shell-kit workspaces were
+not published separately.
 
-After a successful publish, verify the registry and record the receipt:
+Verify the live registry state with:
 
 ```sh
-npm view @inneranimalmedia/agentsam-sdk@2.0.0 version dist.integrity
+npm view @inneranimalmedia/agentsam-sdk@2.0.0 version gitHead dist.integrity
 npm view @inneranimalmedia/agentsam-sdk dist-tags --json
 npm install -g @inneranimalmedia/agentsam-sdk@2.0.0
 agentsam --version
 ```
 
-Record the actual publication date and SDK commit in `docs/RELEASES.md`; only then create
-the `v2.0.0` release tag. A published npm name/version cannot be overwritten.
+The publication receipt is recorded in `docs/RELEASES.md`. Git tag `v2.0.0` identifies the
+exact npm `gitHead`. A published npm name/version cannot be overwritten; subsequent package
+changes require a new version.
 
 ## Branch consolidation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Portable AgentSam SDK and CLI kits for local scaffolding, repository intelligence, incremental indexing, identity adapters, and verified dependency maintenance.",
   "type": "module",
   "main": "./src/index.js",
@@ -12,6 +12,7 @@
     "./dockerize": "./src/lib/dockerize.js",
     "./mini": "./src/lib/mini/index.js",
     "./merkle": "./src/lib/merkle/index.js",
+    "./deploy-receipt": "./src/lib/deploy-receipt/index.js",
     "./knowledge": "./src/knowledge/index.js",
     "./knowledge-service-client": "./src/knowledge/service/client.js",
     "./identity": "./packages/identity/src/index.js",

package/packages/identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-identity",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": true,
   "type": "module",
   "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace — publish via root SDK)",

package/protocol/recon/README.md

@@ -0,0 +1,19 @@
+# AgentSam Recon Protocol (aka "MiniCodeScout")
+
+Provider-neutral contracts for delegating bounded read-only investigation to a cheap or
+local model (Ollama/Qwen-class, mini-tier hosted models, etc.) without giving it branch,
+Git, or write authority. See [docs/RECON.md](../../docs/RECON.md) for the design rationale
+and current status — the delegation step itself is currently benched in favor of plain
+deterministic search; these contracts are the reusable substrate for when it isn't.
+
+`task-packet.schema.json` is the only input a recon worker receives. It is built by a
+deterministic controller (`repository.intelligence`, `rg`, AST lookups) — never by the
+worker itself, and never contains a workspace/tenant ID as the task handle.
+
+`finding-report.schema.json` is the only output a recon worker may return. A worker that
+cannot answer from its supplied slices must return `status: "needs_context"`, not a guess.
+
+These schemas intentionally do not define a code-mutation contract. Recon workers observe;
+they do not write, `git commit`, migrate, or merge. A future `bounded-mutation` protocol
+(scoped to specific, proven-safe transforms) is a separate contract, not an extension of
+this one — see ownership rule 6 in `protocol/README.md`.

package/protocol/recon/finding-report.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/recon/finding-report.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "title": "ReconFindingReport",
+  "description": "The only artifact a bounded recon worker may produce. It never edits files, never touches Git, and never owns a branch.",
+  "required": ["schema_version", "task_id", "status"],
+  "oneOf": [
+    { "required": ["status"], "properties": { "status": { "const": "needs_context" } } },
+    { "required": ["status"], "properties": { "status": { "const": "answered" } } }
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "task_id": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["answered", "needs_context"] },
+    "summary": { "type": "string" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "file", "finding"],
+        "properties": {
+          "severity": { "enum": ["low", "medium", "high"] },
+          "file": { "type": "string" },
+          "lines": { "type": "string" },
+          "finding": { "type": "string" },
+          "evidence": { "type": "string" },
+          "recommended_action": { "type": "string" }
+        }
+      }
+    },
+    "affected_files": { "type": "array", "items": { "type": "string" } },
+    "unknowns": { "type": "array", "items": { "type": "string" } },
+    "missing": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Required when status is needs_context: what evidence was missing."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Required when status is needs_context: why the supplied slices were insufficient."
+    }
+  }
+}

package/protocol/recon/task-packet.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/recon/task-packet.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "title": "ReconTaskPacket",
+  "description": "A bounded assignment handed to a cheap/local recon worker. Produced by a deterministic controller (rg/AST/repository.intelligence), never by the worker itself.",
+  "required": [
+    "schema_version",
+    "task_id",
+    "repo_root",
+    "base_sha",
+    "question",
+    "slices",
+    "ceilings"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "task_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Caller-supplied identifier. Never a workspace/tenant ID — this is a task handle only."
+    },
+    "repo_root": { "type": "string", "minLength": 1 },
+    "base_sha": { "type": "string", "minLength": 1 },
+    "question": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Exactly one bounded question. Not 'audit the subsystem'."
+    },
+    "slices": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 5,
+      "description": "Exact file/line slices the worker may read. The worker must not open anything outside this list.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "start_line": { "type": "integer", "minimum": 1 },
+          "end_line": { "type": "integer", "minimum": 1 },
+          "content": { "type": "string" },
+          "reason": { "type": "string" },
+          "kind": {
+            "type": "string",
+            "description": "Optional structural label from a disambiguating tool (e.g. ast-grep): member, object_key, sql_string, call, comment, unknown. Absent when the slice came from lexical search alone."
+          },
+          "hit_count": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Optional: how many raw search hits this slice's line range covers, when built via from_matches()."
+          }
+        }
+      }
+    },
+    "allowed_diagnostics": {
+      "type": "array",
+      "description": "Pre-approved read-only commands the worker may run verbatim. Empty/omitted means none.",
+      "items": { "type": "string" },
+      "default": []
+    },
+    "ceilings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["max_follow_up_reads", "max_output_tokens", "timeout_seconds"],
+      "properties": {
+        "max_follow_up_reads": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "max_output_tokens": { "type": "integer", "minimum": 1 },
+        "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 600 }
+      }
+    },
+    "response_schema_ref": {
+      "type": "string",
+      "const": "./finding-report.schema.json"
+    }
+  }
+}

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

@@ -0,0 +1,28 @@
+"""Bounded recon-worker harness: task-packet construction and finding-report validation.
+
+This module does not call any model. It is the deterministic controller half of the
+recon protocol described in docs/RECON.md — building small, exact, already-scoped work
+packets, and validating whatever a worker (local or hosted) sends back against hard
+ceilings before it reaches a capable coding agent.
+"""
+from .packet import (
+    build_task_packet,
+    from_matches,
+    from_ast_grep,
+    from_ripgrep,
+    PacketError,
+    TOOL_NAME_PACK,
+)
+from .validate import validate_report, ReportError, TOOL_NAME_VALIDATE
+
+__all__ = [
+    "build_task_packet",
+    "from_matches",
+    "from_ast_grep",
+    "from_ripgrep",
+    "PacketError",
+    "TOOL_NAME_PACK",
+    "validate_report",
+    "ReportError",
+    "TOOL_NAME_VALIDATE",
+]

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

@@ -0,0 +1,3 @@
+from .cli import main_cli
+
+raise SystemExit(main_cli())