agentsam-sdk 0.1.0__py3-none-any.whl

agentsam_sdk/__init__.py

@@ -0,0 +1,13 @@
+"""agentsam_sdk — stdlib-only toolkit for inneranimalmedia D1/repo audits.
+
+Every tool follows the runtime.contract pattern: ToolInput in, ToolResult out,
+plus a receipt written to output_dir for audit trail. No hardcoded
+identity/repo/workspace/tenant values anywhere in this package — see
+runtime.contract.HARD_LAW_NOTE.
+"""
+
+__version__ = "0.1.0"
+
+# Public local SAM client. Remote ACP, MCP and app-specific authorities remain
+# separately scoped; their mere existence does not grant this client access.
+from .client import AgentSamClient, AsyncAgentSamClient, Choose, Check, Score, SamClientError

agentsam_sdk/cli.py

@@ -0,0 +1,263 @@
+"""agentsam CLI -- stdlib argparse only (no click/typer dep, per project
+convention: Python tooling here is stdlib-only).
+
+  agentsam data d1-bloat --quick --format markdown --output-dir /tmp/d1-bloat
+  agentsam data agentsam-walk --prefix agentsam_ --output-dir /tmp/walk
+  agentsam repository inventory --repo-root .. --output-dir /tmp/scan --format json
+  agentsam repository inventory --repo-root .. --format json | jq '.data.totals'
+  agentsam repository scan-bloat --root src --min-kb 10 --top 30 --format json
+  agentsam repository inspect --repo-root . --json --dupes | jq '.duplicates'
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult
+
+
+def _print_result(result: ToolResult, fmt: str) -> None:
+    if fmt == "json":
+        print(json.dumps(result.to_dict(), indent=2, default=str))
+    else:
+        status = "OK" if result.ok else "FAIL"
+        print(f"[{status}] {result.tool} ({result.mode}) — {result.summary}", file=sys.stderr)
+        if result.error:
+            print(f"  error: {result.error}", file=sys.stderr)
+        for a in result.artifacts:
+            print(f"  wrote: {a}", file=sys.stderr)
+        # When markdown artifacts were written, surface path; else dump summary data keys
+        if fmt == "markdown" and result.ok and result.data.get("categories"):
+            # stdout stays quiet when artifacts exist; callers use the .md file
+            if not result.artifacts:
+                from agentsam_sdk.repository.inventory import _markdown
+
+                sys.stdout.write(_markdown(result.data))
+        if fmt == "markdown" and result.ok and result.data.get("files") is not None:
+            from agentsam_sdk.repository.scan_bloat import human_table
+
+            sys.stdout.write(
+                human_table(
+                    result.data.get("files") or [],
+                    scanned=int(result.data.get("file_count") or 0),
+                    total_kb=float(result.data.get("total_kb") or 0),
+                    total_tokens=int(result.data.get("total_est_tokens") or 0),
+                )
+            )
+
+
+def _cmd_data_d1_bloat(args: argparse.Namespace) -> int:
+    from agentsam_sdk.data import d1_bloat
+
+    mode = "full" if args.full else "quick"
+    ti = ToolInput(
+        mode=mode,
+        params={
+            "db": args.db, "config": args.config, "repo_root": args.repo_root,
+            "prefix": args.prefix, "workers": args.workers, "top": args.top,
+        },
+        output_dir=args.output_dir,
+    )
+    result = d1_bloat.run(ti)
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_data_agentsam_walk(args: argparse.Namespace) -> int:
+    from agentsam_sdk.data import agentsam_walk
+
+    ti = ToolInput(
+        mode="default",
+        params={"db": args.db, "config": args.config, "repo_root": args.repo_root, "prefix": args.prefix},
+        output_dir=args.output_dir,
+    )
+    result = agentsam_walk.run(ti)
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_repository_inventory(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import inventory
+
+    ti = ToolInput(
+        mode="read-only",
+        params={
+            "repo_root": args.repo_root,
+            "top": args.top,
+            "min_bytes": args.min_bytes,
+            "by_ext": args.by_ext,
+            "include_node_modules": args.include_node_modules,
+            "include_venvs": args.include_venvs,
+            "include_git": args.include_git,
+            "include_dist": args.include_dist,
+            "follow_symlinks": args.follow_symlinks,
+        },
+        output_dir=args.output_dir,
+    )
+    result = inventory.run(ti)
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_repository_scan_bloat(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import scan_bloat
+
+    ti = ToolInput(
+        mode="read-only",
+        params={
+            "root": args.root,
+            "top": args.top,
+            "min_kb": args.min_kb,
+            "ext": args.ext,
+            "exclude": args.exclude,
+        },
+        output_dir=args.output_dir,
+    )
+    result = scan_bloat.run(ti)
+    # Agent capture: --json-envelope prints data payload only (legacy tools/scan_bloat.py)
+    if args.json_envelope:
+        print(json.dumps(result.data if result.ok else {"ok": False, "error": result.error}, indent=2))
+        return 0 if result.ok else 1
+    _print_result(result, args.format)
+    return 0 if result.ok else 1
+
+
+def _cmd_repository_inspect(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import inspect as repo_inspect
+
+    argv: list[str] = []
+    if args.repo_root:
+        argv.extend(["--repo-root", args.repo_root])
+    want_text = bool(args.text) or args.format in ("text", "markdown")
+    want_json = bool(args.json) or args.format == "json" or not want_text
+    if want_json and not want_text:
+        argv.append("--json")
+    if want_text and not want_json:
+        argv.append("--text")
+    if want_text and want_json:
+        # Explicit both → JSON wins (machine default) unless only --text
+        argv.append("--json")
+    if args.dupes:
+        argv.append("--dupes")
+    if args.all:
+        argv.append("--all")
+    if args.since:
+        argv.extend(["--since", args.since])
+    if args.recent is not None:
+        argv.extend(["--recent", str(args.recent)])
+    if args.largest is not None:
+        argv.extend(["--largest", str(args.largest)])
+    if args.out:
+        argv.extend(["--out", args.out])
+    return repo_inspect.main_cli(argv)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="agentsam", description="agentsam_sdk CLI")
+    sub = ap.add_subparsers(dest="group", required=True)
+
+
+    data = sub.add_parser("data", help="D1 data audits")
+    data_sub = data.add_subparsers(dest="cmd", required=True)
+
+    bloat = data_sub.add_parser(
+        "d1-bloat",
+        help="database-scoped D1 audit (--quick=counts, --full=text sizes)",
+    )
+    bloat.add_argument("--db", help="D1 database name (else AGENTSAM_D1_DB_NAME)")
+    bloat.add_argument("--config", help="wrangler config path (else AGENTSAM_WRANGLER_CONFIG)")
+    bloat.add_argument("--repo-root", help="repo root wrangler runs from")
+    bloat.add_argument("--quick", action="store_true", default=True,
+                       help="All tables: COUNT(*) only (default)")
+    bloat.add_argument("--full", action="store_true",
+                       help="All tables: row counts + text/JSON LENGTH estimates")
+    bloat.add_argument("--prefix", help="Only tables whose name starts with this prefix")
+    bloat.add_argument("--workers", type=int, default=6)
+    bloat.add_argument("--top", type=int, default=40)
+    bloat.add_argument("--output-dir")
+    bloat.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    bloat.set_defaults(func=_cmd_data_d1_bloat)
+
+    walk = data_sub.add_parser("agentsam-walk", help="walk agentsam_* tables")
+    walk.add_argument("--db")
+    walk.add_argument("--config")
+    walk.add_argument("--repo-root")
+    walk.add_argument("--prefix", default="agentsam_")
+    walk.add_argument("--output-dir")
+    walk.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    walk.set_defaults(func=_cmd_data_agentsam_walk)
+
+    repo = sub.add_parser("repository", help="repository-level audits")
+    repo_sub = repo.add_subparsers(dest="cmd", required=True)
+    inv = repo_sub.add_parser(
+        "inventory",
+        help="file counts + sizes by logical category (jq-friendly JSON)",
+    )
+    inv.add_argument("--repo-root", default=".")
+    inv.add_argument("--output-dir")
+    inv.add_argument("--format", choices=["json", "markdown"], default="json")
+    inv.add_argument("--top", type=int, default=20, help="N largest files (0 to omit)")
+    inv.add_argument("--min-bytes", type=int, default=0)
+    inv.add_argument(
+        "--by-ext",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Include by_extension_detail with byte rollups (default: on)",
+    )
+    inv.add_argument("--include-node-modules", action="store_true")
+    inv.add_argument("--include-venvs", action="store_true")
+    inv.add_argument("--include-git", action="store_true")
+    inv.add_argument("--include-dist", action="store_true")
+    inv.add_argument("--follow-symlinks", action="store_true")
+    inv.set_defaults(func=_cmd_repository_inventory)
+
+    sb = repo_sub.add_parser(
+        "scan-bloat",
+        help="largest runtime source files (KB/lines/est. tokens)",
+    )
+    sb.add_argument("--root", default=".", help="directory to scan (default: cwd)")
+    sb.add_argument("--top", type=int, default=30)
+    sb.add_argument("--min-kb", type=float, default=0)
+    sb.add_argument(
+        "--ext",
+        default=".js,.ts,.jsx,.tsx,.mjs,.cjs",
+        help="comma-separated extensions",
+    )
+    sb.add_argument("--exclude", default="", help="extra dir names to exclude")
+    sb.add_argument("--output-dir")
+    sb.add_argument("--format", choices=["json", "markdown"], default="markdown")
+    sb.add_argument(
+        "--json-envelope",
+        action="store_true",
+        help="print ToolResult.data JSON only (agent/terminal capture)",
+    )
+    sb.set_defaults(func=_cmd_repository_scan_bloat)
+
+    insp = repo_sub.add_parser(
+        "inspect",
+        help="file walk: sizes + dates (+ optional --dupes SHA-256 groups)",
+    )
+    insp.add_argument("--repo-root", default=None)
+    insp.add_argument("--format", choices=["json", "markdown", "text"], default="json")
+    insp.add_argument("--json", action="store_true")
+    insp.add_argument("--text", action="store_true")
+    insp.add_argument("--dupes", action="store_true")
+    insp.add_argument("--all", action="store_true")
+    insp.add_argument("--since", default=None)
+    insp.add_argument("--recent", type=int, default=50)
+    insp.add_argument("--largest", type=int, default=30)
+    insp.add_argument("--out", default=None)
+    insp.set_defaults(func=_cmd_repository_inspect)
+
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentsam_sdk/client.py

@@ -0,0 +1,220 @@
+"""A real, bounded SAM local client: delegates to existing Node machinery.
+
+The current Python 0.1 package is a repository/data toolkit, not a remotely
+hosted universal SDK. This bridge exposes read-only deterministic capabilities
+and refuses any write, D1, CMS or arbitrary terminal operation. A native ACP
+client and remote per-installation identity are separately tracked work.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import time
+from urllib import request as urllib_request, error as urllib_error
+from typing import Any, Mapping
+
+class SamClientError(RuntimeError):
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code)
+
+@dataclass(frozen=True)
+class Choose:
+    options: tuple[str, ...]
+    instructions: str = ""
+    def __init__(self, options: list[str] | tuple[str,...], instructions: str = ""):
+        object.__setattr__(self, "options", tuple(options))
+        object.__setattr__(self, "instructions", instructions)
+    def question(self) -> dict:
+        return {"type":"choose","options":list(self.options),"instructions":self.instructions,"evaluator_hint":"deterministic"}
+
+@dataclass(frozen=True)
+class Check:
+    instructions: str = ""
+    def question(self) -> dict:
+        return {"type":"check","instructions":self.instructions,"evaluator_hint":"deterministic"}
+
+@dataclass(frozen=True)
+class Score:
+    levels: tuple[str, ...]
+    instructions: str = ""
+    def __init__(self, levels: list[str] | tuple[str,...], instructions: str = ""):
+        object.__setattr__(self, "levels", tuple(levels))
+        object.__setattr__(self, "instructions", instructions)
+    def question(self) -> dict:
+        return {"type":"score","levels":list(self.levels),"instructions":self.instructions,"evaluator_hint":"heuristic"}
+
+_BRIDGE_REL = Path("src/sam/bridge/stdio.mjs")
+_NPM_PACKAGE = Path("node_modules/@inneranimalmedia/agentsam-sdk")
+
+
+def _discover_bridge(cwd: str | Path | None) -> Path | None:
+    """Find the Node bridge without configuration.
+
+    Order: this tree's own npm/monorepo layout, then the working directory and
+    its parents (a checkout, or an installed ``@inneranimalmedia/agentsam-sdk``).
+    """
+    roots = [Path(__file__).resolve().parents[2]]
+    if cwd is not None:
+        start = Path(cwd).expanduser().resolve()
+        roots.extend([start, *start.parents])
+    for root in roots:
+        for candidate in (root / _BRIDGE_REL, root / _NPM_PACKAGE / _BRIDGE_REL):
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def _bridge_path(explicit: str | None, cwd: str | Path | None = None) -> Path:
+    candidate = explicit or os.environ.get("AGENTSAM_SDK_JS_BRIDGE")
+    path = Path(candidate).expanduser().resolve() if candidate else _discover_bridge(cwd)
+    if path is None or not path.is_file():
+        raise SamClientError("sam_bridge_not_installed")
+    return path
+
+def _binary(explicit: str | None) -> str:
+    node = explicit or os.environ.get("AGENTSAM_NODE") or shutil.which("node")
+    if not node:
+        raise SamClientError("sam_node_not_available")
+    return node
+
+def _normalize_questions(questions: Mapping[str, Any] | list) -> dict | list:
+    if isinstance(questions, Mapping):
+        return {key:(val.question() if isinstance(val,(Choose,Check,Score)) else val)
+            for key,val in questions.items()}
+    return questions
+
+def _decode(raw: bytes) -> Any:
+    try:
+        reply = json.loads(raw)
+    except (ValueError, TypeError) as exc:
+        raise SamClientError("sam_bridge_invalid_response") from exc
+    if not isinstance(reply,dict) or not reply.get("ok"):
+        raise SamClientError(str((reply.get("error") or {}).get("code","sam_bridge_failed")))
+    return reply["result"]
+
+class _ControlPlane:
+    """Existing ACP HTTP endpoints, not a second agent-run database."""
+    def __init__(self, url: str, token: str):
+        if not url.startswith("https://") and not url.startswith("http://127.0.0.1:"):
+            raise SamClientError("sam_acp_https_required")
+        self.url=url.rstrip("/")
+        self.token=token
+    def request(self, route: str, payload: dict | None = None) -> dict:
+        body=json.dumps(payload).encode() if payload is not None else None
+        headers={"Accept":"application/json"}
+        if body is not None: headers["Content-Type"]="application/json"
+        if self.token: headers["Authorization"]="Bearer "+self.token
+        req=urllib_request.Request(self.url+route,data=body,headers=headers,
+            method="POST" if body is not None else "GET")
+        try:
+            with urllib_request.urlopen(req,timeout=20) as response:
+                value=json.loads(response.read())
+        except urllib_error.HTTPError as exc:
+            raise SamClientError("sam_acp_http_"+str(exc.code)) from exc
+        except (urllib_error.URLError, TimeoutError) as exc:
+            raise SamClientError("sam_acp_unavailable") from exc
+        return value
+    def start(self, goal: str, **kwargs):
+        return self.request("/v1/runs", {"objective":goal,
+            "source_client":"agentsam-sdk-python", "surface":kwargs.get("surface","sdk"),
+            "metadata":{"requested_operations":kwargs.get("operations",[]),
+                "requested_deliverables":kwargs.get("deliverables"),
+                "context":kwargs.get("context",{})}})
+    def get(self, id: str):
+        from urllib.parse import quote
+        return self.request("/v1/runs/"+quote(id,safe=""))
+    def events(self, id: str, after: int = -1, limit: int = 200):
+        from urllib.parse import quote
+        return self.request("/v1/runs/"+quote(id,safe="")+"/events?after="+str(int(after))+"&limit="+str(int(limit)))
+
+class RunHandle:
+    def __init__(self, cp: _ControlPlane, row: dict):
+        self.id=row.get("id") or row.get("run_id")
+        if not self.id:raise SamClientError("sam_acp_run_missing_id")
+        self.status=row.get("status","unknown")
+        self._control=cp
+    def get(self):return self._control.get(self.id)
+    def events(self, *, after: int = -1, limit: int = 200):
+        return self._control.events(self.id,after,limit)
+    def wait(self, *, attempts: int = 60, interval: float = 1.0):
+        for index in range(attempts):
+            state=self.get()
+            if state.get("status") in ("completed","failed","cancelled","timed_out"):
+                return {"id":self.id,"status":state["status"],"run":state,"deliverables":[],
+                        "note":"ACP authority must supply real evidence and artifact references."}
+            if index+1<attempts:time.sleep(interval)
+        raise SamClientError("sam_run_wait_timeout")
+
+class AsyncRunHandle:
+    def __init__(self, sync: RunHandle):
+        self.id=sync.id
+        self.status=sync.status
+        self._sync=sync
+    async def get(self):return await asyncio.to_thread(self._sync.get)
+    async def events(self, **kwargs):return await asyncio.to_thread(self._sync.events,**kwargs)
+    async def wait(self, **kwargs):return await asyncio.to_thread(self._sync.wait,**kwargs)
+
+class AgentSamClient:
+    """Synchronous local machine client; no implicit remote credentials."""
+    def __init__(self, *, cwd: str | Path = ".", node: str | None = None, bridge: str | None = None, control_plane_url: str | None = None, control_plane_token: str | None = None):
+        self.cwd = str(Path(cwd).resolve())
+        self.node = _binary(node)
+        self.bridge = str(_bridge_path(bridge, self.cwd))
+        self.control_plane = _ControlPlane(control_plane_url,control_plane_token or "") if control_plane_url else None
+    def _request(self, method: str, **kwargs) -> Any:
+        result = subprocess.run([self.node,self.bridge], input=json.dumps({"method":method,**kwargs}),
+            text=True, capture_output=True, cwd=self.cwd, timeout=120, check=False)
+        return _decode(result.stdout.encode())
+    def discover(self, **query): return self._request("discover",query=query)
+    def describe(self, operation_id: str): return self._request("describe",id=operation_id)
+    def status(self, operation_id: str): return self._request("status",id=operation_id)
+    def invoke(self, operation_id: str, input: dict | None = None):
+        return self._request("invoke",id=operation_id,input=input or {})
+    def decide(self, *, state: dict, questions: Mapping[str, Any] | list, **kwargs):
+        return self._request("decide",input={"state":state,"questions":_normalize_questions(questions),**kwargs})
+    def run(self, **kwargs):
+        if not self.control_plane: raise SamClientError("sam_python_acp_run_adapter_not_configured")
+        goal=kwargs.get("goal","")
+        if not isinstance(goal,str) or not goal.strip(): raise SamClientError("sam_run_goal_required")
+        result=self.control_plane.start(goal, **{k:v for k,v in kwargs.items() if k!="goal"})
+        row=result.get("run",result)
+        if not isinstance(row,dict) or not (row.get("id") or row.get("run_id")):raise SamClientError("sam_acp_run_missing_id")
+        return RunHandle(self.control_plane,row)
+    def events(self, run_id: str, **kwargs):
+        if not self.control_plane:raise SamClientError("sam_python_acp_run_adapter_not_configured")
+        return self.control_plane.events(run_id,**kwargs)
+    def __enter__(self):return self
+    def __exit__(self, *_):return False
+
+class AsyncAgentSamClient(AgentSamClient):
+    """Async subprocess transport to the same authorized local SAM entrypoint."""
+    async def _request_async(self, method: str, **kwargs):
+        proc = await asyncio.create_subprocess_exec(self.node,self.bridge,stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,stderr=asyncio.subprocess.PIPE,cwd=self.cwd)
+        try:
+            out,_ = await asyncio.wait_for(proc.communicate(json.dumps({"method":method,**kwargs}).encode()),120)
+        except asyncio.TimeoutError as exc:
+            proc.kill()
+            await proc.wait()
+            raise SamClientError("sam_bridge_timeout") from exc
+        return _decode(out)
+    async def discover(self, **query):return await self._request_async("discover",query=query)
+    async def describe(self, operation_id: str):return await self._request_async("describe",id=operation_id)
+    async def status(self, operation_id: str):return await self._request_async("status",id=operation_id)
+    async def invoke(self, operation_id: str, input: dict | None = None):
+        return await self._request_async("invoke",id=operation_id,input=input or {})
+    async def decide(self, *, state: dict, questions: Mapping[str, Any] | list, **kwargs):
+        return await self._request_async("decide",input={"state":state,"questions":_normalize_questions(questions),**kwargs})
+    async def run(self, **kwargs):
+        handle=await asyncio.to_thread(super().run,**kwargs)
+        return AsyncRunHandle(handle)
+    async def events(self, run_id: str, **kwargs):
+        return await asyncio.to_thread(super().events,run_id,**kwargs)
+    async def __aenter__(self):return self
+    async def __aexit__(self,*_):return False

agentsam_sdk/data/agentsam_walk.py

@@ -0,0 +1,158 @@
+"""agentsam_sdk.data.agentsam_walk -- condensed port of
+scripts/walk_agentsam_tables.py (+ schema-focus of scripts/d1_schema_audit.py).
+
+Walks every `agentsam_%` sqlite_master object: schema, indexes, foreign
+keys, row count, freshness (via *_at / *_at_epoch columns if present), and
+groups tables into capability buckets by name-substring heuristics.
+
+Note: this is a condensed re-implementation, not a byte-for-byte port of the
+801-line original -- see docs/gaps.md for what's folded in vs deferred
+(duplicate-detection heuristics, per-feature markdown chunking into db/*.md
+files a la d1_schema_audit.py are deferred to a follow-up pass).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from agentsam_sdk.data.d1_adapter import D1Adapter, D1AdapterError
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult, write_receipt, start_timer
+
+TOOL_NAME = "data.agentsam_walk"
+
+CAPABILITY_RULES: dict[str, list[str]] = {
+    "agent_run_spine": ["run", "runs", "execution", "executions", "session", "sessions", "step", "steps", "message", "messages"],
+    "model_routing": ["model", "catalog", "routing", "route", "routes", "arm", "arms", "requirement", "provider", "prompt"],
+    "tools_commands_mcp": ["tool", "tools", "mcp", "command", "commands", "skill", "skills", "invocation", "chain", "script", "scripts"],
+    "workflow_dag": ["workflow", "workflows", "node", "nodes", "edge", "edges", "approval", "approvals", "task", "tasks"],
+    "memory_rag": ["memory", "embedding", "vector", "chunk", "chunks", "document", "documents", "rag"],
+    "observability": ["log", "logs", "trace", "traces", "metric", "metrics", "health", "analytics", "otlp", "error", "errors"],
+    "cms_content": ["cms_", "page", "pages", "content", "nav", "template"],
+    "security_policy": ["policy", "policies", "guardrail", "trusted", "origin", "auth", "credential"],
+}
+
+
+@dataclass
+class TableWalk:
+    name: str
+    columns: list[dict] = field(default_factory=list)
+    indexes: list[dict] = field(default_factory=list)
+    foreign_keys: list[dict] = field(default_factory=list)
+    row_count: int = 0
+    has_freshness_col: bool = False
+    capability: str = "uncategorized"
+    error: Optional[str] = None
+    flags: list[str] = field(default_factory=list)
+
+
+def _capability_for(table: str) -> str:
+    """Score by total matched-keyword *length*, not match count -- a single
+    specific hit ("workflow") should outrank two generic ones ("run", "runs").
+    """
+    lname = table.lower()
+    best, best_score = "uncategorized", 0
+    for cap, keywords in CAPABILITY_RULES.items():
+        score = sum(len(kw) for kw in keywords if kw in lname)
+        if score > best_score:
+            best, best_score = cap, score
+    return best
+
+
+def _walk_table(adapter: D1Adapter, table: str) -> TableWalk:
+    tw = TableWalk(name=table, capability=_capability_for(table))
+    try:
+        cols = adapter.table_columns(table)
+        tw.columns = [{"name": n, "type": t} for n, t in cols]
+        tw.indexes = adapter.table_indexes(table)
+        tw.foreign_keys = adapter.foreign_keys(table)
+        tw.row_count = adapter.row_count(table)
+        tw.has_freshness_col = any(
+            n.lower() in ("updated_at", "created_at", "updated_at_epoch", "created_at_epoch")
+            for n, _ in cols
+        )
+        if tw.row_count == 0:
+            tw.flags.append("empty")
+        if not tw.has_freshness_col:
+            tw.flags.append("no_freshness_column")
+        if not tw.indexes and tw.row_count > 1000:
+            tw.flags.append("no_index_high_row_count")
+    except D1AdapterError as e:
+        tw.error = str(e)[:200]
+    except Exception as e:  # noqa: BLE001
+        tw.error = str(e)[:200]
+    return tw
+
+
+def _render_markdown(walks: list[TableWalk], prefix: str) -> str:
+    lines = [
+        f"# agentsam walk -- `{prefix}%` objects",
+        "",
+        f"- **Generated:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}",
+        f"- **Tables walked:** {len(walks)}",
+        "",
+        "## By capability",
+        "",
+    ]
+    by_cap: dict[str, list[TableWalk]] = {}
+    for w in walks:
+        by_cap.setdefault(w.capability, []).append(w)
+    for cap in sorted(by_cap):
+        lines.append(f"### {cap} ({len(by_cap[cap])})")
+        lines.append("")
+        lines.append("| Table | Rows | Indexes | FKs | Flags |")
+        lines.append("|-------|------|---------|-----|-------|")
+        for w in sorted(by_cap[cap], key=lambda x: x.row_count, reverse=True):
+            flags = ", ".join(w.flags) or "-"
+            err = f" ⚠ {w.error}" if w.error else ""
+            lines.append(f"| `{w.name}` | {w.row_count:,} | {len(w.indexes)} | {len(w.foreign_keys)} | {flags}{err} |")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def run(tool_input: ToolInput) -> ToolResult:
+    started = start_timer()
+    tool_input.assert_read_only()
+    p = tool_input.params
+    prefix = p.get("prefix", "agentsam_")
+    output_dir = tool_input.output_path()
+
+    try:
+        adapter = D1Adapter.from_env(
+            db_name=p.get("db"), wrangler_config=p.get("config"), repo_root=p.get("repo_root")
+        )
+        tables = adapter.list_tables(like=f"{prefix}%")
+        walks = [_walk_table(adapter, t) for t in tables]
+        md = _render_markdown(walks, prefix)
+        json_payload = {
+            "prefix": prefix,
+            "database": adapter.db_name,
+            "table_count": len(walks),
+            "tables": [asdict(w) for w in walks],
+        }
+
+        artifacts: list[str] = []
+        if output_dir:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            (output_dir / "agentsam-walk.md").write_text(md, encoding="utf-8")
+            (output_dir / "agentsam-walk.json").write_text(
+                __import__("json").dumps(json_payload, indent=2), encoding="utf-8"
+            )
+            artifacts = [str(output_dir / "agentsam-walk.md"), str(output_dir / "agentsam-walk.json")]
+
+        result = ToolResult(
+            ok=True, tool=TOOL_NAME, mode=tool_input.mode, request_id=tool_input.request_id,
+            started_at=started, finished_at=start_timer(),
+            summary=f"Walked {len(walks)} `{prefix}%` tables.",
+            data=json_payload, artifacts=artifacts,
+        )
+    except D1AdapterError as e:
+        result = ToolResult(
+            ok=False, tool=TOOL_NAME, mode=tool_input.mode, request_id=tool_input.request_id,
+            started_at=started, finished_at=start_timer(),
+            summary="D1 adapter error", error=str(e),
+        )
+
+    write_receipt(result, output_dir)
+    return result