@inneranimalmedia/agentsam-sdk 2.0.0 → 2.2.0

package/protocol/knowledge/source.schema.json

@@ -4,49 +4,15 @@
   "type": "object",
   "additionalProperties": false,
   "title": "Source",
-  "required": [
-    "source_id",
-    "source_type",
-    "workspace_id",
-    "uri"
-  ],
+  "required": ["source_id", "source_type", "uri"],
   "properties": {
-    "source_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "source_type": {
-      "type": "string",
-      "minLength": 1
-    },
-    "workspace_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "uri": {
-      "type": "string",
-      "minLength": 1
-    },
-    "repository_full_name": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "ref": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "commit_sha": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "metadata": {
-      "type": "object"
-    }
+    "source_id": { "type": "string", "minLength": 1 },
+    "source_type": { "type": "string", "minLength": 1 },
+    "workspace_id": { "type": "string", "minLength": 1, "deprecated": true, "description": "Legacy compatibility metadata only." },
+    "uri": { "type": "string", "minLength": 1 },
+    "repository_full_name": { "type": ["string", "null"] },
+    "ref": { "type": ["string", "null"] },
+    "commit_sha": { "type": ["string", "null"] },
+    "metadata": { "type": "object" }
   }
 }

package/protocol/presets/catalog.json

@@ -0,0 +1,48 @@
+{
+  "schema_version": 1,
+  "presets": {
+    "fullstack": {
+      "id": "fullstack",
+      "version": 1,
+      "lane": "fullstack",
+      "description": "Local-first application with AgentSam runtime, repository primitives, knowledge, and delivery hooks.",
+      "features": ["agent", "knowledge"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "security.scan", "deploy.receipt"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    },
+    "cms": {
+      "id": "cms",
+      "version": 1,
+      "lane": "cms",
+      "description": "Content-oriented application starting from local CMS primitives with explicit auth/deploy opt-ins.",
+      "features": ["cms", "knowledge"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "site.scrape", "deploy.receipt"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    },
+    "prototype": {
+      "id": "prototype",
+      "version": 1,
+      "lane": "fullstack",
+      "description": "Small local prototype with the minimum deterministic AgentSam runtime.",
+      "features": ["agent"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "security.scan"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    },
+    "data": {
+      "id": "data",
+      "version": 1,
+      "lane": "data",
+      "description": "Data-oriented local application with repository knowledge and explicit production storage graduation.",
+      "features": ["knowledge"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "security.scan"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    }
+  },
+  "addons": {
+    "agent": { "id": "agent", "capabilities": ["scaffold.create"], "description": "AgentSam local runtime selection." },
+    "auth": { "id": "auth", "capabilities": ["identity.init"], "description": "Identity package selection; use `agentsam identity init` when a standalone auth app scaffold is required." },
+    "cms": { "id": "cms", "capabilities": ["site.scrape"], "description": "CMS/content feature selection." },
+    "knowledge": { "id": "knowledge", "capabilities": ["knowledge.index", "knowledge.search"], "description": "Portable repository indexing and retrieval." },
+    "deploy-cloudflare": { "id": "deploy-cloudflare", "capabilities": ["deploy.receipt"], "description": "Select Cloudflare as the intended deploy target; provisioning remains explicit at deploy time." }
+  }
+}

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/knowledge/models.py

@@ -1,40 +1,46 @@
-"""Provider-neutral contracts for indexing and retrieval."""
+"""Provider-neutral contracts for indexing and retrieval.
+
+Portable knowledge is repository-scoped. ``workspace_id`` remains optional compatibility
+metadata only; it is never required to identify repository knowledge.
+"""
 
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Mapping, Sequence
+from typing import Any, Mapping
 
 JsonMap = Mapping[str, Any]
 
+
 @dataclass(frozen=True, slots=True)
 class Source:
     source_id: str
     source_type: str
-    workspace_id: str
     uri: str
     repository_full_name: str | None = None
     ref: str | None = None
     commit_sha: str | None = None
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class Document:
     document_id: str
     source_id: str
-    workspace_id: str
     content_hash: str
     media_type: str
     title: str | None = None
     path: str | None = None
     text: str | None = None
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class Chunk:
     chunk_id: str
     document_id: str
-    workspace_id: str
     content: str
     ordinal: int
     content_hash: str
@@ -45,25 +51,27 @@ class Chunk:
     path: str | None = None
     symbol: str | None = None
     heading_path: tuple[str, ...] = ()
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class RepositoryDescriptor:
     repository_id: str
     full_name: str
-    workspace_id: str
     default_branch: str
     product_ids: tuple[str, ...] = ()
     indexed_refs: tuple[str, ...] = ()
     enabled_lanes: tuple[str, ...] = ("code", "docs")
     include: tuple[str, ...] = ()
     exclude: tuple[str, ...] = ()
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class RetrievalQuery:
     text: str
-    workspace_id: str
     repositories: tuple[str, ...] = ()
     product_ids: tuple[str, ...] = ()
     refs: tuple[str, ...] = ()
@@ -74,6 +82,8 @@ class RetrievalQuery:
     require_current_ref: bool = True
     include_archived: bool = False
     explain: bool = True
+    workspace_id: str | None = None
+
 
 @dataclass(frozen=True, slots=True)
 class RetrievalHit:
@@ -92,6 +102,7 @@ class RetrievalHit:
     stale: bool = False
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class ContextPack:
     query_id: str
@@ -101,6 +112,7 @@ class ContextPack:
     confidence: str = "unknown"
     diagnostics: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class IngestReceipt:
     run_id: str

package/python/agentsam_sdk/repository/__main__.py

@@ -1,3 +1,3 @@
-from agentsam_sdk.repository.inventory import main
+from agentsam_sdk.repository.intelligence.cli import main_cli
 
-raise SystemExit(main())
+raise SystemExit(main_cli())

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())

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