@inneranimalmedia/agentsam-sdk 1.7.0 → 1.9.0

package/DEVELOPMENT.md

@@ -1,4 +1,4 @@
-# Developing agentsam-sdk with Inner Animal Media
+# DEVELOPING AGENTSAM-SDK WITH INNER ANIMAL MEDIA
 
 ## Local smoke test
 
@@ -43,10 +43,30 @@ npx agentsam init \
 
 ## Publish checklist
 
-1. `npm test` passes
-2. Bump version in `package.json`
-3. `npm publish --access public`
-4. Tag: `git tag v1.1.1 && git push origin v1.1.1`
+1. Root `package.json` name is **`@inneranimalmedia/agentsam-sdk`** (never a workspace kit)
+2. `npm test` passes
+3. Bump version in root `package.json`
+4. Confirm `files` includes consumer surfaces (`src`, `bin`, `python`, `protocol`, …)
+5. `npm publish --access public` (manual; requires `npm login` to org)
+6. Tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
+7. Record pairing in [`docs/RELEASES.md`](./docs/RELEASES.md): `iam@<40-sha> ↔ @inneranimalmedia/agentsam-sdk@X.Y.Z`
+
+Workspace packages under `packages/*` (e.g. `@inneranimalmedia/agentsam-shell-kit`) stay
+`private: true` until separately ready — they are **not** the root publish identity.
+
+## Python tooling (`agentsam_sdk`)
+
+Portable stdlib audits live under [`python/`](./python/) (import path `agentsam_sdk.*`).
+
+```bash
+cd python
+python3 -m pip install -e ".[dev]"
+python3 -m pytest
+python3 -m agentsam_sdk.repository.inventory --json --root /path/to/repo
+```
+
+Inner Animal Media keeps a thin shim at `scripts/repo-size-inventory.py` that adds
+`AGENTSAM_SDK_ROOT/python` (or a sibling/`~/agentsam-sdk` checkout) to `sys.path`.
 
 ## Known gaps (roadmap)
 

package/README.md

@@ -6,6 +6,8 @@ Agent Sam is a full-stack autonomous agent SDK built on Cloudflare Workers, D1,
 
 **Repo:** [github.com/SamPrimeaux/agentsam-sdk](https://github.com/SamPrimeaux/agentsam-sdk) · **npm:** `@inneranimalmedia/agentsam-sdk`
 
+**Protocol (dual-home, no drift):** [`protocol/README.md`](./protocol/README.md) — every tool/feature lands in this repo **and** `inneranimalmedia/agentsam-sdk/`; npm publish is manual after mirror. Python lane: [`python/`](./python/).
+
 ---
 
 ## What is Agent Sam?

package/docs/RELEASES.iam-mirror.md

@@ -0,0 +1,20 @@
+# Agent Sam SDK — release pairings (IAM home)
+
+**Status:** Evergreen receipts · **Product:** [README.md](./README.md)
+
+Canonical npm-side table also lives in the SDK repo: `docs/RELEASES.md`.  
+**Keep both updated** when publishing (dual-home of the receipt).
+
+| npm version | Published (UTC) | IAM git SHA (40) | Notes |
+|-------------|-----------------|------------------|-------|
+| 1.7.0 | 2026-07-14 | _(pre-receipt)_ | Prior publish |
+| 1.9.0 | _(pending publish)_ | `fc1628505cb3c9946c149e4c468c2e264d6f381e` | `repository.inspect` + `--dupes`; mirrored from IAM agentsam-sdk |
+| 1.8.0 | 2026-08-02T13:57:12.080Z | `580547301e370b77ec26bd72558979d335feedd9` | `python/` + `protocol/` in tarball; `repository.scan_bloat`; shell-kit under `packages/` |
+
+**Latest pairing (ready to publish):** `iam@fc1628505cb3c9946c149e4c468c2e264d6f381e` ↔ `@inneranimalmedia/agentsam-sdk@1.9.0`
+
+### Receipt rules
+
+- Full 40-char SHA only (AGENTS.md §3)
+- Record the IAM SHA that introduced or mirrored the consumer-facing change
+- Tag SDK repo `vX.Y.Z` on publish

package/docs/RELEASES.md

@@ -0,0 +1,9 @@
+# `@inneranimalmedia/agentsam-sdk` release receipts
+
+| npm version | Published (UTC) | IAM git SHA (40) | Notes |
+|-------------|-----------------|------------------|-------|
+| 1.7.0 | 2026-07-14 | _(pre-receipt)_ | Prior publish |
+| 1.9.0 | _(pending publish)_ | `fc1628505cb3c9946c149e4c468c2e264d6f381e` | `python/agentsam_sdk/repository/inspect.py` (`--dupes`); CLI `agentsam repository inspect` |
+| 1.8.0 | 2026-08-02T13:57:12.080Z | `580547301e370b77ec26bd72558979d335feedd9` | `python/` + `protocol/` in npm `files`; `repository.scan_bloat`; shell-kit folded to `packages/agentsam-shell-kit` (private). SDK git at publish: `ac52669b89ddb16fad87c42fe53f2c93ef13bd1a`. |
+
+**Pairing (ready to publish):** `iam@fc1628505cb3c9946c149e4c468c2e264d6f381e` ↔ `@inneranimalmedia/agentsam-sdk@1.9.0`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "1.7.0",
-  "description": "Agent Sam is a full-stack AI agent SDK for autonomous task execution — covering data management, creative workflows, design commands, and multi-step agentic pipelines.",
+  "version": "1.9.0",
+  "description": "Agent Sam is a full-stack AI agent SDK for autonomous task execution \u2014 covering data management, creative workflows, design commands, and multi-step agentic pipelines.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -18,10 +18,15 @@
     "docs",
     "examples",
     "test",
+    "python",
+    "protocol",
+    "bin",
     "README.md",
     "LICENSE",
-    "DEVELOPMENT.md",
-    "bin"
+    "DEVELOPMENT.md"
+  ],
+  "workspaces": [
+    "packages/*"
   ],
   "scripts": {
     "test": "node test/smoke.mjs",

package/protocol/README.md

@@ -0,0 +1,51 @@
+# agentsam-sdk protocol (LOCKED)
+
+Every Agent Sam **tool / feature SDK surface** is dual-homed. There is no
+“Python audits only in IAM” vs “JS CLI only on npm” split for productized
+tooling.
+
+| Home | Path | Role |
+|------|------|------|
+| **Main platform repo** | `inneranimalmedia/agentsam-sdk/` | Source of truth while building; ships with platform deploy |
+| **Published SDK repo** | `github.com/SamPrimeaux/agentsam-sdk` → npm `@inneranimalmedia/agentsam-sdk` | Same contract + modules for external / CLI consumers |
+
+## Rules
+
+1. **Author once, land twice.** New `agentsam_sdk.*` tools (data, repository,
+   readiness, history, code-intel, …) land in the monorepo package **and** are
+   mirrored into the published `agentsam-sdk` repo in the same change set / PR
+   pair. No silent one-sided land.
+2. **Contract is shared.** `runtime/contract` (`ToolInput` / `ToolResult` /
+   receipts, unixepoch, no hardcoded identity) is the protocol. Language may
+   differ (Python stdlib vs JS), but CLI verbs and JSON shapes must stay
+   aligned — see `protocol/dual-repo-sync.md`.
+3. **No drift.** Publishing npm without updating the monorepo copy (or the
+   reverse) is a protocol violation. Gate: version bump + changelog note that
+   lists mirrored paths.
+4. **Ship is two-sided.**
+   - Platform: Mac `npm run deploy:full` / `deploy:fast` (or GCP `ship:remote`)
+     when the monorepo copy or Worker wiring changed.
+   - SDK: **manual** npm publish / version bump on `agentsam-sdk` after the
+     mirror lands (operator-owned — do not assume CI auto-publishes).
+5. **Inspiration ≠ copy-paste secrets.** In-app surfaces (e.g. `src/core/code-indexer.js`,
+   AST-RAG Phase 1/2) are the reference implementations to port into portable
+   SDK modules — strip platform-only bindings, keep adapters for D1 / git /
+   Hyperdrive.
+
+## Layout (both homes)
+
+```
+agentsam-sdk/
+  protocol/           ← this law
+  python/agentsam_sdk ← Python portable tools (stdlib-first audits / inventory)
+  src/                ← JS CLI / scaffold (published npm entry)
+  packages/           ← optional workspace packages (not always in npm tarball)
+    agentsam-shell-kit/  ← @inneranimalmedia/agentsam-shell-kit (private until ready)
+  docs/gaps.md        ← port status vs IAM scripts + in-app indexers
+```
+
+**npm identity (LOCKED):** root publishable package is always
+`@inneranimalmedia/agentsam-sdk`. Do not overwrite root `package.json` with a
+workspace kit name. Fold UI kits under `packages/*`.
+
+Exact folder names may evolve; the dual-home + root-identity rules do not.

package/protocol/dual-repo-sync.md

@@ -0,0 +1,35 @@
+# Dual-repo sync checklist
+
+Use this every time you add or change an `agentsam_sdk` tool/feature.
+
+## Before coding
+
+- [ ] Name the module (`agentsam_sdk.<domain>.<tool>`) and CLI verb
+- [ ] Confirm it belongs in SDK (portable) vs platform-only Worker hot path
+- [ ] Note in-app inspiration path (if any), e.g. `src/core/code-indexer.js`
+
+## Land
+
+- [ ] Implement + tests in **`inneranimalmedia/agentsam-sdk/`**
+- [ ] Mirror the same module/CLI/docs into **`agentsam-sdk`** (npm repo)
+- [ ] Update `docs/gaps.md` (or equivalent) in **both** trees
+- [ ] Update `protocol/` only in monorepo if law changed; copy README blurb to npm
+
+## Publish / deploy (operator)
+
+- [ ] Platform: commit/push IAM → deploy by host (`deploy:full` / `ship:remote`)
+- [ ] SDK: bump `package.json` version in npm repo → `npm publish` (manual)
+- [ ] Record versions next to each other (PR description or receipt):  
+      `iam@<sha>` ↔ `@inneranimalmedia/agentsam-sdk@<semver>`
+
+## Drift signals (fail the PR)
+
+- Module exists only in one repo
+- CLI flag / JSON field renamed on one side only
+- README claims “this is not the npm package” / “audits don’t belong here”
+- npm publish without a same-day IAM mirror commit (or documented lag ticket)
+
+## jq / host tools
+
+Host tooling (`jq`, `wrangler`, Python ≥3.10) is documented in
+`docs/tooling.md`. Keep that file mirrored when recipes change.

package/python/README.md

@@ -0,0 +1,12 @@
+# agentsam_sdk (Python) — npm mirror
+
+Exact dual-home of `inneranimalmedia/agentsam-sdk/`.
+
+```bash
+cd python && pip install -e .
+agentsam repository inventory --repo-root /path/to/repo --format json
+python3 -m unittest discover -s tests -v
+./scripts/check-host-tooling.sh
+```
+
+Protocol: [`../protocol/README.md`](../protocol/README.md). Do not advance this tree without mirroring the monorepo (or the reverse).

package/python/agentsam_sdk/__init__.py

@@ -0,0 +1,9 @@
+"""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"

package/python/agentsam_sdk/cli.py

@@ -0,0 +1,262 @@
+"""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())

package/python/agentsam_sdk/data/agentsam_walk.py

@@ -0,0 +1,157 @@
+"""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()
+    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