@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/docs/plans/AGENTSAM-MCP-CLIENT-2026-09-19.md

@@ -0,0 +1,181 @@
+# AgentSam as an MCP client — plan
+
+`main` @ `14b6454` (PR #58 merged). Read this whole file before touching
+anything. This closes a real, verified gap, not a speculative feature:
+`agentsam_tool_call_log` — the account's own real call-telemetry table —
+shows zero rows with `source_client: cursor` or `codex`, ever, while
+`chatgpt` and `claude_ai` have thousands between them. Cursor's own
+`~/.cursor/mcp.json` is `{"mcpServers": {}}` — genuinely never configured,
+globally. `agentsam mcp add` does not exist; `agentsam add` is a different,
+unrelated command (`runAdd()` writes `.agentsam/features.json` for product
+add-ons, nothing to do with MCP).
+
+## Why this is worth building now, not later
+
+`inneranimalmedia-mcp-server` is proven infrastructure — real accounts, ~218
+tools, actively used daily by two people, with its own D1-backed telemetry
+already built for exactly this purpose (`agentsam_tool_call_log`,
+`agentsam_mcp_tool_execution`). Making `agentsam` itself a client of it means
+every native-agentsam tool call gets the same receipt quality Cursor/Codex
+calls already get when they're properly connected — not a separate
+observability project, a side effect of wiring this correctly once.
+
+The live server: `https://mcp.inneranimalmedia.com/mcp`, OAuth beginning at
+`https://mcp.inneranimalmedia.com/auth/connect`. The external-client spine
+already recognizes Cursor specifically —
+`src/mcp/dispatch/external-mcp-spine.js` (in `inneranimalmedia`) mints
+`cursor_mcp:<external-chat>` conversation ids, `arun_mcp_cursor_<short>` run
+ids, `source_client: cursor` — the server side is ready and waiting. The gap
+is entirely client-side, in `agentsam-sdk`.
+
+## What NOT to build
+
+- Don't hand-roll the MCP JSON-RPC protocol. Use `@modelcontextprotocol/sdk`
+  — a standard client library exists; this is transport plumbing, not novel
+  design.
+- Don't make `~/.cursor/mcp.json` (or any one client's config file) the
+  authority. It's an adapter output, not the source of truth — same pattern
+  as everything else in this repo. AgentSam's own connection state is
+  authoritative; each client config gets generated/synced from it.
+- Don't overload the existing `agentsam add` command. MCP is a distinct
+  first-class noun.
+- Don't conflate this with `agentsam eval live` (below) — MCP client wiring
+  produces the raw telemetry; eval-live turns telemetry into graded
+  observations. Two different pieces, sequenced, not merged into one PR.
+
+## CLI surface
+
+```
+agentsam mcp add inneranimalmedia
+agentsam mcp add inneranimalmedia --client cursor
+agentsam mcp status
+agentsam mcp doctor inneranimalmedia
+agentsam mcp list
+agentsam mcp remove inneranimalmedia
+```
+
+`agentsam mcp add inneranimalmedia` flow:
+
+```
+agentsam mcp add inneranimalmedia
+       │
+       ├── detect installed clients (Cursor / Claude / etc.)
+       ├── open IAM OAuth (mcp.inneranimalmedia.com/auth/connect)
+       ├── user consents
+       ├── receive MCP credential
+       ├── store credential securely under ~/.agentsam/mcp/inneranimalmedia.json
+       ├── materialize client adapter(s)
+       │      └── e.g. ~/.cursor/mcp.json, generated from AgentSam's own state
+       ├── call MCP initialize
+       ├── tools/list
+       ├── ping
+       └── ✓ connected
+```
+
+Same shape as `codex mcp add cloudflare-api --url ... ` — that's the UX bar,
+not just an analogy.
+
+## Where state lives
+
+`~/.agentsam/mcp/<server-name>.json` is the connection authority. Client
+configs (`~/.cursor/mcp.json`, Claude Desktop's config, etc.) are generated
+adapters written *from* that state, not edited by hand and not treated as
+sources of truth. Same "one authority, N adapters" pattern as everything
+else audited in this repo tonight — don't special-case MCP.
+
+### The role of `~/.agentsam/mcp.json` vs the connection authority
+
+A natural question arises: why not also materialize `~/.agentsam/mcp.json`?
+
+1. **Not for the main CLI itself (avoiding self-indirection):**
+   The main CLI process is the codebase that owns the authority
+   (`~/.agentsam/mcp/<server>.json`). That authoritative file holds rich
+   metadata: protocol, auth flow details, registered clients, health metrics,
+   and custom headers. Having the main CLI write a stripped-down
+   `~/.agentsam/mcp.json` (`{ mcpServers: { ... } }`) and then read that back
+   would be pure self-indirection and introduces drift between two
+   representations of the same state in the exact same process.
+
+2. **As the portable adapter for the `apps/` family and standalone SEAs:**
+   Where `~/.agentsam/mcp.json` is genuinely useful is serving other
+   independent binaries in the AgentSam ecosystem (`apps/cad-creator`,
+   `apps/local-studio`, `agentsam-cms`, or standalone Node-free SEAs). These
+   are separate executables that may act as MCP clients. They must NOT be
+   tightly coupled to the CLI's internal `authority.js` module or its internal
+   file layout. Materializing `~/.agentsam/mcp.json` provides a standard,
+   portable, standards-compliant `{ "mcpServers": { ... } }` config that any
+   sibling app can read directly without module coupling.
+
+Therefore, `~/.agentsam/mcp.json` is treated strictly as an **adapter for
+sibling apps/binaries**, never as the CLI's internal source of truth.
+
+## Catalog merging — the actual hard part
+
+Once connected, an MCP server's tool list has to sit alongside the native
+`protocol/capabilities/manifest.json` catalog for whatever model the
+interactive session is driving — not as a second, separately-searched
+system. Extend the existing `src/tools/search.js`/`hydrate.js` layer to
+treat a connected MCP server's `tools/list` result as another source
+feeding the same search/hydrate index, tagged with its origin so collisions
+(a connected server offering something the native manifest already has) are
+detectable the same way the tools.js dedup audit found `handler_key`
+collisions earlier tonight. Don't build a second, parallel discovery path.
+
+## Telemetry — the actual payoff
+
+Every call made through a connected MCP server from an `agentsam` session
+should land in `agentsam_tool_call_log` with real `source_client`
+attribution (`agentsam`, not blank/unknown), the same schema Cursor and
+Codex would use if *they* were writing there. This is what closes the
+observability gap — not a new table, just making sure agentsam's own calls
+go through the same pipe.
+
+## Related, sequenced after this: `agentsam eval live`
+
+Don't overload the existing deterministic `agentsam eval context` (which
+explicitly reports `live_provider_used: false` — it's offline/deterministic
+by design, leave it that way). Add a separate live-capture path:
+
+```
+agentsam eval live start \
+  --suite sdk-real-work-20260919 \
+  --case cad-shell-unification \
+  --client cursor \
+  --provider cursor \
+  --model "Muse Spark 1.3" \
+  --reasoning high
+
+... real work happens, MCP calls land in agentsam_tool_call_log /
+    agentsam_mcp_tool_execution / agentsam_tool_call_outcomes /
+    agentsam_tool_chain via the client wired above ...
+
+agentsam eval live finish
+```
+
+`eval live finish` aggregates the real receipts collected during the
+session and writes to `agentsam_eval_runs` (the primary model-comparison
+row) and `agentsam_model_eval_observations` (supporting evidence) —
+built from *actual* tool-call receipts, not re-typed after the fact. One
+important constraint to respect: the MCP server can know what tool was
+called, when, duration, success/failure, cache state, resource touched,
+retries, authorization outcome — it cannot know a connected client's own
+hidden model token usage. Combine what MCP telemetry actually knows with
+whatever the client/CLI session itself reports (git/test/CI evidence,
+commit/PR references) rather than inventing precision that isn't there.
+Model tokens/cost from a third-party client should read "unknown /
+client-reported if available," not a fabricated number.
+
+## Order of operations
+
+1. `agentsam mcp add/status/doctor/list/remove` — the client transport +
+   connection-state authority + first adapter (Cursor, since that's the
+   proven daily-use client with zero current telemetry).
+2. Catalog merge in `search.js`/`hydrate.js`.
+3. Telemetry wiring into `agentsam_tool_call_log` with correct
+   `source_client`.
+4. `agentsam eval live start/finish`, once real MCP telemetry is flowing —
+   this step is worthless without step 3 landing first.
+
+Do not skip ahead to `eval live` before the transport and telemetry wiring
+are real — that would just recreate the exact "manual/intentional eval
+recording, not an automatic facility" gap this plan exists to close.

package/docs/plans/ASBD-PORTABLE-WORKGRAPH-UI-DEFERRED.md

@@ -0,0 +1,34 @@
+# Portable WorkGraph / Gantt UI — deferred
+
+**Priority:** low (plan only — do not block ASBD home / help / CMS work)
+
+## Intent
+
+Salvage `agentsam-lab` `prototype-gnantt.html` into a **lightweight portable UI** that can mount inside:
+
+- `apps/local-studio` work surface
+- optional CLI-adjacent localhost monitor for AgentSam agent work
+- future package distribution (not required for first cut)
+
+## Constraints
+
+- Visual shell must use **ASBD** (`asbd-tokens` / header/footer or studio nav from `@inneranimalmedia/agentsam-nav`) — not the purple lab prototype tokens as SSOT
+- Keep WorkGraph data contract aligned with `agentsam-sdk/packages/work-graph` (canonical; lab copy is stale)
+- No new product world; this is a reusable widget, not a standalone app
+
+## Suggested peel
+
+```text
+packages/agentsam-workgraph-ui/   (or apps/local-studio/frontend widget)
+  ├── board/ list/ gantt projections
+  ├── ASBD token mapping
+  └── mount API for Studio + static preview
+```
+
+## Non-goals now
+
+- Full rewrite of lab Worker
+- Shipping Gantt as the AgentSam marketing homepage
+- Blocking packages/services help page publish
+
+Resume after ASBD home + help/doc pattern are live on `agentsam.inneranimalmedia.com`.

package/docs/plans/ASTRA-BRIEF-2026-09-18.md

@@ -0,0 +1,258 @@
+# Astra Brief — agentsam-sdk consolidation, 2026-09-18
+
+> **HISTORICAL / BACKLOG ONLY — not live status.**
+>
+> Current status authority:
+> [`RECONCILIATION-2026-09-19.md`](./RECONCILIATION-2026-09-19.md)
+>
+> As of 2026-09-19, `main` / `origin/main` is
+> `88cb30daadf20b8ca22aad29dad826055cec6998` (PR #51 merged — project-owned
+> SQLite runtime). Do **not** use the old “main is at 0795d92 (PR #50)” line.
+>
+> Also superseded here: auth-closure “still open”, `help all` broken,
+> work-graph still orphaned, and treating `platform_identity_missing` as an
+> OAuth/auth-closure fix. Remote terminal enrollment remains open as a
+> **separate** pairing/provisioning gap — see the reconciliation doc.
+
+This file remains useful as backlog/reference for architectural drift items
+and scaffold-from-real-app design questions. It is **not** ground truth over
+live git. Recheck every “still open” claim against the reconciliation doc
+and `origin/main` before acting.
+
+---
+
+## 0. Operating rules (apply to all of this, not just one task)
+
+- Patches over rewrites. Backup before editing (`cp file file.bak`), verify
+  with `node -c` after any JS edit, diff against the backup before trusting
+  a change.
+- Never hardcode IDs (account IDs, D1 database IDs, etc). Auto-detect from
+  existing credential/registry systems — see the Cloudflare account fix
+  below for the pattern.
+- Non-fatal DB writes always.
+- No `npm publish` unless explicitly told to. The human publishes after
+  final validation.
+- Before declaring anything "done," run it live and paste the actual
+  output. Do not report completion on code you haven't executed.
+- Do not delete useful historical branches/worktrees.
+- If you find a scaffold/generator/duplicate that already exists somewhere
+  else in the repo or in a sibling app, map old → new capability before
+  writing anything new. Do not silently reinvent something already built —
+  check `protocol/capabilities/manifest.json` and the D1 `agentsam_tools`
+  registry first.
+
+---
+
+## 1. Already done tonight — do not redo, verify then build on top
+
+1. **`src/cli.js`**: `scaffold` is now a registered command
+   (`agentsam scaffold`, `agentsam scaffold cms`, `agentsam scaffold
+   worker-api` all reach the wizard — previously "Unknown command").
+   Backup: `src/cli.js.bak`.
+2. **Cloudflare account auto-detection**: `src/commands/env.js` now
+   exports `detectCloudflareAccounts()` (was private). New shared module
+   `src/lib/scaffold/resolve-cloudflare-account.js` wraps it — auto-fills
+   the account ID silently when exactly one account is detected, offers a
+   picker when there are multiple, only falls back to manual text entry if
+   detection genuinely fails. Both `wizards/cms.js` and
+   `wizards/worker-api.js` now call this instead of a raw `text()` prompt
+   asking the user to hand-paste an ID that `agentsam cloudflare` already
+   knows. Verified live: resolves to `ede6590ac0d2fb7daf155b35653457b2`
+   ("Info@inneranimals.com's Account") with zero prompts.
+3. **`src/lib/scaffold/templates/worker-api/index.js` +
+   `templates/cms/index.js` + `templates/wrangler-dev/...`** (3 templates
+   total, confirmed by grep): added `RUN apk add --no-cache python3 make
+   g++` before `npm ci`/`npm install` in every generated Dockerfile. Root
+   cause was `node-pty` (and any other native addon) failing to build
+   inside `node:20-alpine` because alpine ships no Python/build toolchain
+   by default. Verified against the actual `docker build` failure log from
+   `agentsam dockerize`.
+4. **Downloads cleanup**: `~/Downloads/agentsam-cmsstack-sdk` (+ `.zip`)
+   deleted — confirmed to be a stray duplicate download of this exact repo
+   (identical `cms.js`, same package name/version, contained a dead
+   `/mnt/user-data/outputs/` container path proving it was a leftover AI
+   session export). Nothing unique was lost.
+5. **`~/agent-worktrees/`**: pruned from 4.1GB/140 dirs to 1.6GB/8 dirs.
+   Every deletion was verified via `git merge-base --is-ancestor <sha>
+   origin/main` before removal — nothing unmerged was touched. `git
+   worktree prune` was run on all 5 affected canonical repos afterward so
+   git's own metadata doesn't reference dead paths.
+6. **`.bak` file sweep**: cleared stray `.bak` files across the user's
+   home directory. Deliberately left alone: anything inside another app's
+   own state (Chrome, Codex, pm2, CapCut), anything in a named backup
+   directory (`.agentsam/backups/`, `.local-backups/`), and
+   `agentsam-sdk/src/cli.js.bak`/`env.js.bak`/wizard `.bak` files created
+   tonight as active revert points for the fixes above — do not delete
+   those without checking they're no longer needed first.
+
+---
+
+## 2. The real architectural problem: three overlapping "AgentSam" truths
+
+This surfaced from an external audit (pasted into this session, not
+generated by me) auditing `agentsam-sdk/main @ c8461522`. It is accurate
+and still the single highest-leverage finding. Full detail in that audit;
+summary of what to actually do:
+
+- **Legacy runtime island.** `src/AgentSam.js`, `src/lib/router.js`,
+  `src/lib/sessions.js`, `src/lib/tools.js` are a compatibility surface
+  still publicly exported, coexisting with the real modern runtime
+  (`src/local/runtime-store.js` → `agentsam_agent_run`). Label this
+  `LEGACY COMPATIBILITY SURFACE / NOT RUNTIME AUTHORITY`, don't delete
+  blind — consumer-search → deprecate → adapter → remove.
+- **Tool duplication.** `src/lib/tools.js` (fake `fullstack/cms/data` tool
+  names) duplicates the real, much more mature
+  `protocol/capabilities/manifest.json` + `src/tools/search.js` +
+  `src/tools/hydrate.js` (search cheap cards → hydrate full schema only
+  when needed). `tools.js` should not remain a second tool authority —
+  route everything through the capability manifest + search/hydrate
+  pattern instead.
+- **Command dispatcher drift.** `src/cli.js`'s if/else chain (~35 cases),
+  `src/lib/slash-commands.js` (27 interactive commands), and help text are
+  three independently-maintained descriptions of the same surface. Target:
+  a single command manifest (schema: cli aliases, slash aliases, handler
+  module, capability id, requirements, side effects, help text) that
+  generates CLI routing, slash routing, help output, and tool-card
+  discovery from one source. `printLegacyHelp()` is already known-stale —
+  delete/replace it once the manifest exists.
+- **`agentsam help all`** — **superseded 2026-09-19:** implemented in
+  `src/ui/cli/help.js` (`all` / `--all` → full map). Verified live on main.
+- **Stale vocabulary.** `workspace_id` is marked deprecated in
+  `protocol/knowledge/retrieval-query.schema.json` but still actively
+  validated in `src/knowledge/contracts.js`. Needs a
+  `architecture/vocabulary.yaml` with `forbidden_new_identifiers` that CI
+  enforces, with explicit exemptions for genuine back-compat code.
+- **No lineage object.** IDs exist everywhere (trace_id, run_id,
+  tool_call_id, terminal_job_id) but nothing ties them together end to
+  end. Introduce a minimal `ExecutionLineage` identity object (see full
+  audit for the shape) — not a mega-record, just an id-correlation type
+  that every subsystem's receipts carry.
+- **`architecture/modules.yaml` + extend `scripts/verify-source-boundaries.mjs`.**
+  The verifier already catches cross-boundary imports; it doesn't yet know
+  about module ownership/authority. Define modules (identity, models,
+  repository, workbench, telemetry, knowledge, etc.) with declared
+  ownership and forbidden dependencies, then let CI enforce it.
+
+None of this is urgent-tonight work. It's the map for anything bigger than
+a one-off patch — check it before doing structural work so you're not
+fighting the same drift the audit already named.
+
+---
+
+## 3. Scaffold system: real apps exist, `scaffold` doesn't know about them
+
+**Confirmed by direct inspection, not assumption:**
+
+- `apps/client-cms-editor/` — real backend Worker (`backend/src`,
+  `backend/worker`), real frontend (Vite, has a built `dist/`),
+  `shared/cms/`, `IMPORT_PROVENANCE.json` tracking a donor import. This is
+  a working CMS editor app — the actual thing shown live at
+  `inneranimalmedia.com/dashboard/cms/templates` (media panel,
+  Content/Style/Page/Theme/Crm tabs, Publish button, draft/live state).
+- `apps/cad-creator/` — same shape: real backend + frontend, `shared/cad/`,
+  its own `bin/agentsam-cad-creator.mjs`, a pre-built publishable tarball
+  (`inneranimalmedia-agentsam-sdk-cad-creator-0.1.0.tgz`), a
+  `scripts/verify-publish-package.mjs`. Sam calls this "still in shambles"
+  visually/UX-wise, not structurally — the plumbing toward "this becomes
+  its own installable package" already exists.
+- `apps/local-studio/` — this **is** `agentsam.inneranimalmedia.com`,
+  confirmed live (HTTP 200, serving the real production app — the
+  lead-chat + co-worker split-pane + in-browser preview + Monaco file
+  browser UX shown in tonight's screenshots).
+
+**The gap:** `agentsam scaffold cms` currently runs the old, thin
+`wizards/cms.js` → `templates/cms/index.js` generator, which produces a
+disconnected static Worker+D1+R2 skeleton with content *routes* but zero
+editor (`grep -il "editor\|admin\|dashboard"` across its generated file
+tree returns nothing). `agentsam scaffold cad-creator` doesn't exist at
+all. Both scaffolds should instead **stand up a real instance of the
+actual app** (`apps/client-cms-editor`, `apps/cad-creator`) — parameterized
+the way `client-cms-editor`'s own `IMPORT_PROVENANCE.json` already tracks
+donor-import parameterization — not regenerate a toy from scratch.
+
+**Task, when picked up:** design the scaffold-from-real-app flow. Open
+questions to resolve, don't guess:
+- What's template vs. fixed platform code in each app (which files get
+  parameterized per new project vs. which are shared platform code that
+  shouldn't fork).
+- Whether D1/R2/Worker bindings get created fresh per scaffolded project or
+  reuse a shared multi-tenant backend.
+- Whether this is a `git subtree`/template-repo mechanism or an explicit
+  file-copy-and-parameterize step in `src/lib/scaffold/`.
+
+Do not build this blind — come back with the plan before writing scaffold
+code for either.
+
+---
+
+## 4. `packages/work-graph` — pull it out of `agentsam-lab`, register it
+
+`~/agent-worktrees/agentsam-lab/packages/work-graph/` has a real, working
+implementation: `src/index.js`, `renderers/{gantt-model,timeline}.js`,
+`adapters/engineering/{git,mcp}.js`, `adapters/business/projects.js`. One
+graph model (WorkItem, Dependency, TimelineEvent, Artifact, Evidence,
+Actor) powers two adapters (engineering: git/MCP/tests/deploys; business:
+projects/clients/approvals/milestones) with the Gantt/timeline UI as a
+pure renderer over it — correct architecture, just orphaned. It was
+deployed once to `agentsam.inneranimalmedia.com` but that route is now
+superseded by the real production app (`local-studio`); the prototype
+(`prototype-gnantt.html` + `workgraph-runtime.js` + `timeline-model.js` +
+`demo-workgraph.js`) is intact but unreachable.
+
+Given the existing `packages/` layout (`agentsam-contracts`,
+`agentsam-repository`, `agentsam-shell-kit`, `agentsam-site-scrape`,
+`agentsam-workbench`, `connectors`, `identity`), this becomes its own
+sibling: **`packages/work-graph`** — not folded into `agentsam-workbench`
+(that's UI-only) or `agentsam-contracts` (that's schemas). Once it has a
+real `package.json`, register it in
+`protocol/capabilities/manifest.json` so it's the answer next time
+anything (local-studio, client-cms-editor, cad-creator) needs a task
+timeline instead of a fresh one-off getting built and re-orphaned.
+
+Mechanical, low-risk — good first pickup if the scaffold-app design work
+above is blocked on decisions.
+
+---
+
+## 5. `release/2.6.2-auth-closure` — SUPERSEDED (merged)
+
+**Superseded 2026-09-19:** this branch tip is an ancestor of `main`. Do not
+treat auth-closure as still open.
+
+**Remote terminal note (corrected):** `platform_identity_missing` on
+`terminal_remote` is **not** the CLI OAuth bug and was **not** closed by
+auth-closure / PR #450. Live host evidence showed `connection_key_set: false`
+with null `account_id` / `connection_id` / `instance_id` under
+`control_plane_auth_mode: platform_bridge` — an enrollment/pairing gap.
+See `RECONCILIATION-2026-09-19.md` §B.
+
+---
+
+## 6. Small standalone fix, do anytime — `agentsam` self-update UX
+
+Codex CLI (`~/.nvm/.../bin/codex`) shows a clean "Update available:
+0.154.0 → 0.155.1, release notes: <link>, [1] Update now / [2] Skip / [3]
+Skip until next version" prompt on launch. `agentsam` has no equivalent —
+add a lightweight version-check-on-launch (compare local package version
+against the published npm registry version, non-blocking, same
+update-now/skip/skip-until-next-version shape). Keep it out of the hot
+path if the check would add latency — background check + cache is fine.
+
+---
+
+## 7. Suggested order of operations
+
+Order superseded — use `RECONCILIATION-2026-09-19.md` §D. Historical list
+kept only for archaeology:
+
+1. ~~`agentsam help all`~~ done on main.
+2. ~~`packages/work-graph` extraction~~ present on main.
+3. Scaffold-from-real-app design doc for `cms`/`cad-creator` (still open).
+4. ~~`release/2.6.2-auth-closure`~~ merged; remote terminal is a separate enrollment track.
+5. `agentsam` self-update UX (still open, low priority).
+6. Bigger architectural items in §2 — backlog only.
+
+Report back the way the auth-closure brief specifies: what's done, what's
+verified live (paste actual output, not "should work"), what's
+intentionally deferred and why, and the exact single next action if
+something needs Sam directly (a credential, a login, a decision).