@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/docs/architecture/CODEBASEINDEX_GUIDED_PATH.md

@@ -0,0 +1,202 @@
+# Codebaseindex Guided Path — Template Lanes + Inventory-First UX
+
+**Status:** PLAN · LOCKED intent (2026-09-25)  
+**Product:** AgentSam · pipeline `sam.codebaseindex.index.run` · operation `codebaseindex.ingest`  
+**Audience:** SDK CLI/TUI, Local Studio, future customer “bring your own vector lane” templates
+
+---
+
+## 1. Host SSOT today — Supabase tables (Gemini @ 1536)
+
+Owner IAM path: **Gemini Embedding 2 → 1536-d → Supabase pgvector**, written via **node-api** edge (`POST /codebase/ingest`, vector RPCs). D1 owns control/structure; Postgres owns vectors.
+
+### Live code-intelligence projections (`agentsam` schema)
+
+| Table | Role |
+|-------|------|
+| `agentsam.agentsam_codebase_chunks_gemini_embedding_2_1536` | Chunk-level retrieval vectors (primary ANN for code Q&A) |
+| `agentsam.agentsam_codebase_files_gemini_embedding_2_1536` | File-level vectors |
+| `agentsam.agentsam_codebase_ast_symbols_gemini_embedding_2_1536` | Symbol ANN |
+
+### Related semantic / twin tables (same embed family, different corpora)
+
+| Table | Role |
+|-------|------|
+| `agentsam.agentsam_gemini_semantic_embeddings_1536` | Unified semantic authority (memory + code symbol projections by `corpus_type` / `record_kind`) |
+| `agentsam.agentsam_documents_gemini_embedding_2_1536` | Document ingest twin (node-api `/vectors/ingest`) |
+
+### Retired (do not write for new runs)
+
+| Table | Note |
+|-------|------|
+| `agentsam.agentsam_codebase_*_oai3large_1536` | Legacy OpenAI code lanes |
+
+### Control plane (D1 — not Supabase, but paired)
+
+| Table | Role |
+|-------|------|
+| `code_repositories` | Account-owned repo identity |
+| `agentsam_code_index_job` / `agentsam_code_index_job_file` | Run progress (`cidxrun_*`) |
+| `codebase_ast_nodes` / `codebase_dep_edges` | Structural units + deps |
+| `agentsam_pgvector_lane_registry` | Purpose → live PG table + model + dims |
+| `agentsam_fs_merkle_snapshots` | Merkle evidence receipts |
+| `agentsam_codebase_index_health` | Staleness / weekly health |
+
+**I/O path (owner):** Worker / SDK → **node-api** (Deno edge) → Hyperdrive / session pooler → Supabase PG.
+
+---
+
+## 2. End goal — templateable vector lanes
+
+Owner setup is already live. Customers should get the **same harness**, parameterized:
+
+```text
+                    codebaseindex.ingest (guided)
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+         local_exact     supabase_pgvector   cloudflare_vectorize
+         (SQLite)        (+ node-api edge)   (CF binding)
+              │               │               │
+         Ollama/paid     Gemini@1536     project Vectorize
+         on this machine  BYO Supabase    BYO index/model
+```
+
+| Lane | Who runs compute | Where vectors live | When to offer |
+|------|------------------|--------------------|---------------|
+| **Local** | User machine | `.agentsam/knowledge/index.sqlite` | Default; Ollama free embed OK |
+| **Supabase + node-api** | Their edge (template of IAM node-api) | Their `agentsam.*` PG tables | They opt into hosted ANN |
+| **CF Vectorize** | Worker/plugin binding | Their Vectorize index | They already live on CF |
+
+**Template rule:** ship **contracts + migrations + edge stubs**, not a shared multi-tenant dump of IAM tables into customer projects. Owner IAM remains the reference implementation.
+
+Same-model law still holds per generation: vectors written with profile `P` are only queried with profile `P` (fingerprint of provider/model/dims/params).
+
+---
+
+## 3. Guided path (inventory first — LOCK this UX)
+
+One option at a time. Plan/dry-run is **not** “skip inventory.”
+
+```text
+① Provider / connection
+        ↓
+② Scan → file map inventory (Merkle + facet view)
+        ↓
+③ Include / exclude against the map
+        ▼
+④ Embedding model + dimensions (discovered, not hardcoded)
+        ↓
+⑤ Vector lane / data source
+   · local SQLite
+   · Supabase + node-api (Hyperdrive)
+   · Cloudflare Vectorize
+        ↓
+⑥ Dry-run / plan receipt (work-graph stages)
+        ↓
+⑦ Confirm → run (progress on Gantt + CLI)
+```
+
+### CLI / TUI (lightweight)
+
+| Step | Interaction |
+|------|-------------|
+| ① | `select` configured providers + optional `agentsam providers` deep-link; Ollama online badge from `ollama list` |
+| ② | Run `repository.inspect` / Merkle; print compact tree + counts; `--json` for Studio |
+| ③ | `text` include / exclude; optional local chat assist; never invent denylist |
+| ④ | `select` from **discovered** embed models only |
+| ⑤ | `select` lane; if Supabase → collect URL/env names + offer node-api scaffold; if Vectorize → binding/index |
+| ⑥ | `plan` emits work-graph JSON + pretty plan card |
+| ⑦ | `confirm` then run; stream stage events |
+
+Terminal aesthetic: short notes, one clack prompt per step, `tip: use skill agentsam-codebaseindex`, no wall of presets.
+
+### Studio / localhost Gantt
+
+Work-graph is the **source of truth** for the job; Gantt/timeline are projections.
+
+Example stages (bars):
+
+1. `connect` — providers resolved  
+2. `inventory` — file map / merkle  
+3. `scope` — include/exclude locked  
+4. `embed_profile` — model + dims  
+5. `lane` — local | supabase | vectorize  
+6. `plan` — dry-run receipt  
+7. `index` — parse / chunk / embed  
+8. `activate` — verify + ready  
+
+Local Studio (or this preview) polls `agentsam_code_index_job` / local generation receipts and feeds `createGanttModel(graph)`.
+
+---
+
+## 4. Supabase + node-api customer path (what “template” means)
+
+When the user picks **Supabase / Hyperdrive**:
+
+1. Scaffold edge from IAM `supabase/functions/node-api` **pattern** (ingest + account-scoped vector query RPCs).  
+2. Apply PG migrations that create **their** `agentsam.agentsam_codebase_*` (or lane-registry–driven table names).  
+3. Wire `AGENTSAM_DATABASE_URL` / Hyperdrive binding names into knowledge `lane.backend = supabase_pgvector`.  
+4. Register row in **their** `agentsam_pgvector_lane_registry` (or SDK lane config) pointing at table + model + dims.  
+5. Runs still use `codebaseindex.ingest` / `sam.codebaseindex.index.run` — only the **provider adapter** changes.
+
+Owner machine: skip scaffold; credentials and node-api already exist → wizard jumps to inventory.
+
+---
+
+## 5. CF Vectorize path (valid peer, not code-index SSOT for IAM)
+
+IAM host law keeps **code index vectors off Vectorize**. Customer template may still choose Vectorize for **their** product:
+
+- Plugin scope: binding + index + model + dims  
+- Knowledge `lane.backend = cloudflare_vectorize`  
+- Same guided steps ①–⑦; stage `lane` records Vectorize target in the receipt  
+
+Do not silently redirect owner IAM full-index onto Vectorize.
+
+---
+
+## 6. Local Ollama value (strategic I/O)
+
+| Use | How |
+|-----|-----|
+| Free semantic search | `agentsam search --semantic` against local generation |
+| Pre-filter before paid chat | Retrieve top-k chunks → pass only those to hosted model |
+| Offline agent turns | Shell/agent retrieve while Ollama is up |
+| Scope assist | Chat model (e.g. `qwen2.5-coder`) suggests include/exclude only |
+
+Query must use **same** embed profile as write (e.g. `mxbai-embed-large:latest` @ 1024).
+
+---
+
+## 7. Implementation slices (ordered)
+
+| Slice | Deliverable |
+|-------|-------------|
+| **A** | Reframe CLI wizard to ①→⑦ (inventory before scope); `plan` prints work-graph stages |
+| **B** | Emit `codebaseindex.job.graph.v1` JSON consumed by work-graph Gantt |
+| **C** | Local Studio / preview page binding graph → Gantt (this doc’s companion HTML) |
+| **D** | Lane picker adapters: local (done-ish), supabase+node-api scaffold stub, vectorize scope probe |
+| **E** | Customer template pack: migrations + edge stub + README (no IAM secrets) |
+
+---
+
+## 8. Acceptance checks
+
+- [ ] Wizard never jumps to embed/lane before an inventory receipt exists (or user explicitly skips with `--skip-inventory`).  
+- [ ] Exclude is user-authored (blank = none).  
+- [ ] Embed options come only from credentials + live Ollama tags.  
+- [ ] Plan/dry-run produces work-graph JSON + human card.  
+- [ ] Gantt shows the same stage ids as CLI.  
+- [ ] Choosing Supabase does not mutate owner IAM tables when running as a customer template.  
+- [ ] Semantic retrieve fails closed on embedding-profile mismatch.
+
+---
+
+## Related
+
+- Host SSOT: `inneranimalmedia/docs/platform/codebase-index-ssot-2026-07.md`  
+- SAM kernel: `docs/architecture/SAM_KERNEL.md`  
+- Skill: `skills/agentsam-codebaseindex/SKILL.md`  
+- Work-graph: `packages/work-graph` (`createGanttModel`)  
+- Preview: `docs/architecture/previews/codebaseindex-guided-path/`

package/docs/architecture/FS_E2E_CLOSURE_RECEIPT.md

@@ -0,0 +1,59 @@
+# Filesystem E2E closure receipt
+
+**Status:** COMPLETE (product adapter + real PTY + identity + conflict)  
+**Commit target:** agentsam-sdk `main`  
+**Date:** 2026-09-25
+
+## UI workflow exercised
+
+1. `startLocalPtyServer` bound to disposable git root (same as `agentsam start-local`)
+2. Studio bootstrap: `GET /v1/workspace/bootstrap` → capability
+3. Monaco path: `RuntimeFilesystemAdapter.read/write` (identical contract to FilesStage save)
+4. Real PTY WebSocket with same `workspace_id` / root / capability
+5. `git diff -- README.md` in PTY shows Monaco marker
+6. External disk edit → version change → stale write → `version_conflict`
+7. Studio UI: Projects → Open filesystem… binds to authorized runtime root only
+
+## Proof artifacts (from last green run)
+
+| Field | Value |
+|------|--------|
+| disposable root | tmp `agentsam-fs-e2e-*` git repo |
+| workspace_id | minted `ws_…` |
+| runtime | `http://127.0.0.1:<ephemeral>` |
+| PTY session | `pty_…` via workspace_identity |
+| Monaco path | `README.md` |
+| PTY path | `NOTES.md` |
+| stale write | `code: version_conflict` |
+| scratch fallback | **disabled** for filesystem projects |
+
+Automated: `test/integration/studio-fs-pty-e2e.test.mjs`  
+Receipt JSON written under `$TMPDIR/agentsam-fs-e2e-receipt-*.json` on each run.
+
+## Authorization model
+
+See `docs/architecture/LOCAL_FS_AUTHORITY.md`.
+
+- Loopback bind only
+- Capability required (not API key)
+- Arbitrary root claim rejected
+- CORS allowlist (no `*`)
+
+## Remaining (not blockers for FS closure)
+
+- Native FS watcher → `workspace.file.changed` (today: focus/interval version check + conflict)
+- Go agentsamd implementing `protocol/runtime/workspace-fs.v1.schema.json`
+- Hosted account → enrolled instance graduation
+- Computational Hyperspace Activity tab (separate product sprint; event-driven, not demo timer)
+
+## Checklist
+
+- [x] filesystem workspace opens (Studio dialog + runtime bind)
+- [x] Monaco adapter reads/writes real file
+- [x] Studio real PTY same root + identity frame
+- [x] `git diff` sees Monaco edit
+- [x] PTY/external edit observable; stale save conflicts
+- [x] Scratch remains virtual; filesystem refuses virtual shell
+- [x] no arbitrary path authority
+- [x] filesystem contents not localStorage authority
+- [x] integration receipt records workspace/root/runtime/session

package/docs/architecture/LOCAL_FS_AUTHORITY.md

@@ -0,0 +1,38 @@
+# Local filesystem / PTY authority (closure sprint)
+
+## What protects `/v1/fs` today
+
+| Control | Behavior |
+|--------|----------|
+| **Binding** | Loopback only (`127.0.0.1`). Non-loopback host refused at start. |
+| **Root** | Process-bound at `agentsam start-local` cwd. Clients cannot submit an arbitrary absolute root to gain authority. |
+| **Capability** | Short-lived `awc_…` minted per runtime. Required on all `/v1/fs/*` and PTY attach (`?capability=`). Distinct from `AGENTSAM_API_KEY`. |
+| **Bootstrap** | `GET /v1/workspace/bootstrap` — loopback + Studio origin allowlist. Rejects `?root=` that ≠ authorized cwd. |
+| **CORS** | Not `*`. Allowlist of local Studio origins only. |
+| **Containment** | All paths resolved via `resolveContainedPath` (traversal + symlink escape rejected). |
+| **PTY cwd** | Must equal authorized root or a contained path; mismatch closes the socket. |
+
+## Trust chain (local → hosted)
+
+```
+AGENTSAM_API_KEY          (account/API — not used as PTY attach)
+        ↓
+local workspace capability awc_…   (this sprint)
+        ↓
+PTY session + /v1/fs under one root
+
+Later:
+account → terminal:connect → enrolled instance → approved workspace root
+```
+
+## Studio identity
+
+Filesystem project stores:
+
+- `workspaceRoot` (= runtime authorized root)
+- `runtimeBaseUrl`
+- `workspaceId`
+- `runtimeCapability`
+
+Scratch projects never receive these; they keep the virtual shell.
+Filesystem projects **refuse** virtual-shell fallback.

package/docs/architecture/LOCAL_STUDIO_CLOUDFLARE_OAUTH.md

@@ -0,0 +1,28 @@
+# Cloudflare OAuth — AgentSam Local Studio
+
+**Client:** AgentSam Local Studio · PKCE · secret `CLOUDFLARE_OAUTH_CLIENT_ID` on Worker
+
+## Flows
+
+| Flow | Start | Callback |
+|------|-------|----------|
+| Identity (“Sign in with Cloudflare”) | `/api/oauth/cloudflare/start?next=/agentsam` | `/api/oauth/cloudflare/callback` |
+| MCP / account connector (`@agentsam-mcp`) | `/api/connections/cloudflare/start` | `/api/connections/cloudflare/callback` |
+| Platform identity (`inneranimalmedia`) | `/api/oauth/inneranimalmedia/start` | `/api/oauth/inneranimalmedia/callback` |
+| Legacy alias | `/api/oauth/iam/start` | `/api/oauth/iam/callback` |
+
+Browser GET on connections **start** → 302 to Cloudflare.  
+`fetch` + `Accept: application/json` → `{ authorize_url }`.
+
+## D1
+
+- `identity_oauth_states` — identity PKCE (migration `0013_identity_oauth_states.sql`)
+- `agentsam_cloudflare_oauth_state` — MCP connector PKCE
+
+## IAM AS redirect (required)
+
+Register on client `iam_agentsam_sdk_web`:
+
+`https://agentsam.inneranimalmedia.com/api/oauth/inneranimalmedia/callback`
+
+(Keep legacy `/api/oauth/iam/callback` during migration.)

package/docs/architecture/PLAN_CLI_AND_LOCAL_STUDIO_DESKTOP.md

@@ -0,0 +1,96 @@
+# Plan of action — CLI cutover + Local Studio desktop = apps/local-studio
+
+**Status:** active · 2026-09-25  
+**Shipped tonight:** `58fddae` (SAM/codebaseindex WIP) · Local Studio Worker `c62a7350` on `agentsam.inneranimalmedia.com`  
+**Desktop note:** installed `.app` still needs a Tauri rebuild to pick up `launch_path: /agentsam`
+
+---
+
+## A. Finish CLI / SAM machine revisions
+
+1. **Catalog owns dispatch** — migrate remaining `cli.js` if/else handlers into `src/cli/dispatch.js` lazy loaders; shrink `cli.js` to bootstrap + resolve + dispatch + errors.
+2. **Delete legacy help authority** — remove `printLegacyHelp()`; help/overview only from `CLI_COMMAND_CATALOG`.
+3. **Per-command skill law** — every machine command declares `skill` or explicit exemption; human tip on stderr; `--json` stays clean (`help.skill` in envelope when graduated).
+4. **`--format pretty|json|jsonl`** — normalize machine output; keep `--json` alias.
+5. **Shared material resolver** — promote `src/lib/ingest/materials.js` for brand/cad/security; archive sandbox limits + tests.
+6. **Embedding dims are per-provider profile fingerprints** — not Ollama SSOT. Ollama is an *optional* local offer only. When CF credentials are present, Workers AI **Text Embeddings** models must appear in the ingest pool (chat allowlist must not hide them) so Vectorize lanes work from the same account model pool. Prefer adapter/probe length when available; name heuristics are hints only.
+7. **Storage lanes object** — `metadata` vs `vectors` in knowledge config (local / supabase / vectorize presets).
+8. **`agentsam app options`** — discover `apps/*/`, theme packages, manifests (kill hardcoded init menus).
+9. **Graduate ops** — `brand.preview`, BrandPack export/import; keep scan read-only.
+10. **Skills + tools registry parity** — portable `skills/catalog.json` ↔ D1 `agentsam_skill`; filesystem/AST/DAG tools in `agentsam_tools` schema+seed so new users get the same inspection surface as the IAM host. No stale skills.
+11. **Tests from sprint §31** — catalog help, JSON tips absent, inventory-before-scope, profile mismatch, archive fixtures, CF embed discovery.
+
+## B. Installed AgentSam Local Studio = apps/local-studio experience
+
+### Product surfaces (locked)
+
+| Surface | URL | Role |
+|---------|-----|------|
+| PUBLIC | `/` | Marketing — never desktop home |
+| IDENTITY | `/auth/login` | Real portal (email + OAuth) |
+| PRODUCT | `/agentsam` | Local Studio / Workbench (`apps/local-studio`) |
+
+### Desktop chain
+
+```text
+AgentSam Local Studio.app  (Tauri · agentsam-desktop-shell)
+        │
+        ▼  launch_url
+https://agentsam.inneranimalmedia.com/agentsam
+        │
+        ▼  session check (server-authoritative)
+   ┌────┴────┐
+valid      missing
+   │          │
+   ▼          ▼
+Workbench   /auth/login?next=/agentsam
+              │
+              ▼ success
+           /agentsam
+```
+
+### Steps
+
+1. **Rebuild desktop** (picks up manifest `/agentsam`):
+   ```bash
+   cd packages/agentsam-desktop-shell
+   node scripts/build-brand.mjs local-studio
+   npm run build   # or: npx tauri build  after build-brand
+   ```
+   Install/replace `/Applications/AgentSam Local Studio.app` from the new `.app`/DMG.
+
+2. **Auth adapter (tiny)** — session status → begin login → deep-link `agentsamstudio://callback` → logout. No Tauri auth DB; reuse `packages/identity` + same-origin cookies for email/password.
+
+3. **Gate `/agentsam`** — unauthenticated users always land on `/auth/login?next=/agentsam`; never fall back to `/`.
+
+4. **Logged-in dashboard UX** — audit Workbench routes under `apps/local-studio/frontend/src/routes/(apps)/agentsam*` (Chat/Work/Browser/terminal); fix any deep-link that returns to marketing home.
+
+5. **Native affordances** — tray, keychain (session/account state only — not raw API keys in webview), updater later, local-node enrollment when agentsamd lands.
+
+6. **Parity QA checklist**
+   - Cold launch → `/agentsam` (or login), never homepage
+   - Email login → return `/agentsam`
+   - OAuth (Google/GitHub/CF) → deep link → `/agentsam`
+   - Logout → identity, re-open app → login again
+   - Hosted browser vs installed app show same Workbench build (Worker version)
+
+7. **Later** — bundle Local Studio assets offline + agentsamd IPC; keep same route/auth contract.
+
+## C. Order of attack (recommended)
+
+| # | Work | Outcome |
+|---|------|---------|
+| 1 | Tauri rebuild `local-studio` + reinstall | Installed app opens `/agentsam` |
+| 2 | Session gate + login next= | Login ↔ Workbench loop solid |
+| 3 | CLI catalog cutover (dispatch) | No dual truth in `cli.js` |
+| 4 | Material + format + app options | Machine CLI usable without LLM |
+| 5 | brand.preview + BrandPack | Brand product path |
+| 6 | agentsamd + bundled UI | Desktop = workstation, not wrapper |
+
+---
+
+## Proof already live
+
+- Git: `58fddae` on `main`
+- Worker: `agentsam-sdk` version `c62a7350-f68d-40cb-9a45-a4fe5b3d48f5`
+- `GET /agentsam` → 200 · `GET /auth/login` → 200

package/docs/architecture/PROVIDER-TOOLS-AND-COMPACTION.md

@@ -0,0 +1,60 @@
+# Provider tools and conversation compaction
+
+Canonical capability schemas stay in `protocol/`. The Responses runner validates
+selected schemas before any paid pre-turn compaction or inference. Provider
+adapters also compile at their HTTP boundary for direct SDK callers.
+
+`src/providers/tool-schema.js` owns a bounded supported JSON Schema dialect:
+objects, scalar types/enums, arrays and nested anyOf, with supported scalar bounds.
+It strips annotation metadata without confusing schema keywords with property
+names. OpenAI/Grok strict projections close every object and make optional
+properties required-and-nullable. The runtime restores those optional nulls to
+omission before invoking canonical handlers. Gemini uses its JSON Schema field,
+`parametersJsonSchema`, not the incompatible OpenAPI `parameters` field.
+
+Unknown/unsupported validation keywords, refs, dynamic dictionaries, malformed
+required arrays, missing array items and invalid types fail locally with the
+provider, tool and schema path. This is deliberately not a general JSON Schema
+compiler: adding refs/compositions requires a tested projection, not dropping
+validation keywords or changing strict mode. Provider/API acceptance still needs
+live integration evidence; local validation cannot prove model availability or
+all future provider restrictions.
+
+`knowledge.search` has a real schema for text, bounded search limits, semantic
+selection and generation. Runtime-owned cwd is injected by the runner.
+
+## Interactive compaction
+
+- `/compact` uses the selected active session/model's existing native `compact()`.
+- `/compact status` reports support, active context, canonical threshold,
+  automatic state and the latest receipt.
+- `/context` includes the same model-policy threshold and compaction support.
+- `/session` and `/usage` include provider compaction usage/cost in cumulative totals.
+
+The exact returned output is canonical continuation input. It may contain both
+ordinary provider-returned items and encrypted items; it must not be filtered to
+only encrypted items, decoded, or turned into a homemade summary. A dedicated
+session record in the same project SQLite stores only the latest pending returned
+window (maximum 10 MiB), separately from generic session JSON. It is atomically
+saved with its usage/cost receipt, survives resume, and is deleted when a new
+provider response ID successfully replaces it. This storage is local access-
+restricted SQLite, not an application-level encrypted store; it must never be
+exported as knowledge, telemetry, or model reasoning logs.
+
+Automatic pre-turn compaction includes usage/cost in totals and can checkpoint
+its output before the subsequent model call. A failed continuation leaves the
+saved compacted window available for retry. Providers lacking declared native
+compaction fail closed for the manual command. The local context-item truncation
+module is unchanged.
+
+OpenAI normal requests use server-side `context_management` when the model
+explicitly declares compaction and a canonical policy threshold. The same
+`autoCompact: false` option disables both automatic paths. Response-ID chaining
+sends only new input; standalone compaction clears the old ID and uses the exact
+returned window. Server-side usage is accounted from the normal response.
+
+Sources checked during implementation:
+- https://developers.openai.com/api/docs/guides/function-calling
+- https://ai.google.dev/api/generate-content#FunctionDeclaration
+- https://developers.openai.com/api/docs/guides/compaction
+- https://developers.openai.com/api/reference/python/resources/beta/subresources/responses/methods/compact

package/docs/architecture/SAM_ACTIVITY_RECOVERY_RECEIPT.md

@@ -0,0 +1,39 @@
+# Sprint receipt — decisions observable + recovery semantics
+
+**Commit target:** agentsam-sdk  
+**Scope:** Connect SAM decisions to runs/outcomes/activity; add RecoveryPlan. No new choose/score/check primitives.
+
+## Shipped
+
+### 1. Outcome capture + run linkage
+- Receipts carry `run_id`, `step_id`, `action_id`, `outcome_id`
+- `attachAction(receipt, action)`
+- `appendOutcome` dispositions: accepted / rejected / overridden / corrected_to / retry_required / verification_failed / user_intervened
+- `label_strength`: supervised | explicit_accept | weak_passive  
+  (passive /why with no correction ≠ strong calibration label)
+
+### 2. Activity stream (`agentsam.activity.v1`)
+- `createActivityStore(run_id)` · `activityFromDecision` · `decision.made`
+- User-facing labels ("Selecting execution path") — primitives only in `evidence`
+- `evaluate({ activity, run_id })` emits events for Studio/CLI subscribers
+
+### 3. Error recovery (not more ERROR_REASON sprawl)
+- Optional envelope fields: `failure_class`, `operation.side_effect_state`, `retry`, `fallback`, `notify`, `cause`, partial status
+- `planRecovery(error, operationContext)` → `agentsam.recovery.v1`
+- **Unknown side effects ⇒ reconcile, never blind retry**
+
+### 4. Protocols
+- `protocol/sam/activity.v1.schema.json`
+- `protocol/errors/recovery.v1.schema.json`
+- receipt/outcome schemas extended
+- error-envelope optional recovery dimensions
+
+## Intentionally deferred
+- IAM `attach_token_hash` rename + `terminal:connect` on control plane (IAM repo)
+- Studio Activity SideStage / Hyperspace canvas wiring (consume activity store next)
+- CLI TUI live region
+- Go watcher → decision.evaluate loop
+- Full ERROR_REASON enum expansion for every FS/PTY string (use failure_class + native evidence)
+
+## Tests
+`test/integration/sam-activity-recovery.test.mjs` (+ prior decision/error suites green)

package/docs/architecture/SAM_DECISION_WORK_RECEIPT.md

@@ -0,0 +1,54 @@
+# SAM Decision Layer — Work Receipt
+
+**Package:** `@inneranimalmedia/agentsam-sdk`  
+**Scope:** AgentSam-native choose / score / check (no TypeSafe/Jev)  
+**Date:** 2026-09-25
+
+## Files changed
+
+### Core
+- `src/sam/decision/` — types, state, validate, confidence, questions, evaluate, policy, receipt, calibration, hierarchical
+- `src/sam/decision/evaluators/` — deterministic, heuristic, semantic, select
+- `src/sam/operations/decision-evaluate.js`
+- `src/sam/seed.js`, `src/sam/index.js`, `src/sam/client.js`
+- `package.json` — protocol subpath exports
+
+### Protocols
+- `protocol/sam/state.v1.schema.json`
+- `protocol/sam/question.v1.schema.json`
+- `protocol/sam/answer.v1.schema.json`
+- `protocol/sam/evaluation.v1.schema.json`
+- `protocol/sam/decision-receipt.v1.schema.json`
+- `protocol/sam/outcome.v1.schema.json`
+- `protocol/sam/calibration.v1.schema.json`
+
+### Tests
+- `test/integration/sam-decision.test.mjs` (35 cases) + A*/GOAP remain green
+
+## Evaluators implemented
+| Kind | Status |
+|------|--------|
+| deterministic | terminal_lane, retrieval_mode, change_risk, requires_approval, security_review_required, verification_scope, skill_candidate |
+| heuristic | fact-backed score/check |
+| semantic | optional via `createSemanticEvaluator({ complete })`; fails closed if unconfigured |
+| calibrated-statistical | deferred (contract + metrics only) |
+
+## Decision use cases
+1. **terminal_lane** — local files + healthy local → `local`
+2. **cross-cutting change fan-out** — risk / approval / sandbox / security / verification_scope in one batch
+3. **skill_candidate** — OAuth migration → `mcp-oauth`
+
+## Raw vs calibrated semantics
+- Default labels: `scores`, `support`, `confidence_estimate`
+- `probabilities` only when evaluator marks probabilistic interpretation
+- `calibrated_probability` requires `calibration_id`
+- Semantic answers always warn: estimates, not calibrated probabilities
+
+## Intentionally deferred
+- Learned classifiers / held-out training
+- Go `/v1/sam/evaluate` host
+- Live Merkle/filesystem decision signals
+- IAM `attach_token_hash` rename (not present in agentsam-sdk; IAM-side)
+
+## Auth note (architecture only)
+`AGENTSAM_API_KEY` ≠ terminal attach token. Prefer `attach_token_hash` naming on IAM terminal sessions when that sprint lands.