@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/docs/AGENTSAM_WORKBENCH.md

@@ -0,0 +1,30 @@
+# AgentSam shared workbench boundary
+
+The SDK has one shared AgentSam interaction layer for product applications:
+
+```text
+packages/agentsam-contracts       pure TypeScript, no React
+            ↑
+packages/agentsam-workbench       reusable React/browser workbench
+            ↑
+    ┌───────┼────────┐
+    │       │        │
+ Local    CAD      CMS
+ Studio   Studio    Studio
+```
+
+`apps/*` are development products and remain independent workspace roots. They may consume the shared packages, but shared packages must never import an app.
+
+## Contracts
+
+`@inneranimalmedia/agentsam-contracts` owns messages, runs, events, tools/capabilities, artifacts/attachments, model options, explicit context, and runtime adapter interfaces. Context is supplied by the host through an explicit `AgentContextProvider`; the workbench does not scrape app state implicitly.
+
+## Workbench
+
+`@inneranimalmedia/agentsam-workbench` owns reusable controlled UI primitives. Product-specific state stores, route trees, auth implementations, repo/CAD/CMS schemas, and deployment wiring remain outside it.
+
+Local Studio is the first proof consumer. CAD and CMS should consume this layer through domain adapters rather than cloning Local Studio components.
+
+## Authentication and execution
+
+The workbench does not own identity authority. Identity establishes an authenticated principal first; application authorization then creates any optional browser/container/terminal execution session. Cache and execution bindings are never account/session authority.

package/docs/AUTH_IDENTITY_CONTRACT.md

@@ -0,0 +1,52 @@
+# AgentSam identity/auth configuration contract
+
+The `agentsam-sdk` package owns the portable public configuration contract. Consuming applications implement storage, authorization, and host routes against this contract instead of defining competing environment names.
+
+## Canonical variables
+
+| Variable | Meaning |
+| --- | --- |
+| `IAM_ORIGIN` | Canonical IAM authority and browser/OAuth/API origin. |
+| `IAM_CLIENT_ID` | OAuth client id for an application using IAM identity. |
+| `IAM_CLIENT_SECRET` | OAuth client secret. Keep it server-side. |
+| `AGENTSAM_SDK_KEY` | Account/delegated SDK bearer. Raw values use the `sdk_` prefix and are sent as `Authorization: Bearer …`. |
+| `AGENTSAM_BRIDGE_KEY` | Machine/integration credential. It is never a substitute for user SDK authentication. |
+
+The host-side durable verifier for SDK credentials is `agentsam_sdk_tokens`. The SDK defines the public credential semantics; the host owns the database and authorization implementation.
+
+`AGENTSAM_BRIDGE_KEY` remains the direct machine-secret environment variable. A host may additionally resolve a hashed credential from `agentsam_sdk_tokens` when that row has `token_type='integration'`. That does not turn the bridge credential into user authentication.
+
+## Migration compatibility
+
+The current migration window accepts two deprecated read fallbacks:
+
+```text
+IAM_ORIGIN
+  fallback: IAM_OAUTH_ISSUER
+
+AGENTSAM_SDK_KEY
+  fallback: AGENTSAM_SDK_TOKEN
+```
+
+Canonical names always win when both are present. New scaffolds, docs, and writes emit only the canonical names. Compatibility aliases are intentionally not a permanent parallel configuration surface.
+
+Older platform-base aliases (`IAM_CORE_URL`, `AGENTSAM_CORE_URL`, `AGENTSAM_BASE_URL`) are compatibility-only. SDK clients prefer `IAM_ORIGIN`.
+
+## Credential boundaries
+
+```text
+human/account SDK lane
+  AGENTSAM_SDK_KEY
+    -> sdk_* bearer
+    -> Authorization: Bearer <sdk_*>
+    -> account/delegated authority
+    -> agentsam_sdk_tokens
+
+machine/integration lane
+  AGENTSAM_BRIDGE_KEY
+    -> machine principal
+    -> no user/workspace identity injection
+    -> host env secret OR agentsam_sdk_tokens(token_type='integration')
+```
+
+Browser OAuth uses `IAM_ORIGIN` together with `IAM_CLIENT_ID` and `IAM_CLIENT_SECRET`. Repository identity, workspace labels, or machine trust do not prove account authority.

package/docs/CAPABILITIES.md

@@ -18,7 +18,7 @@ agentsam capabilities
 agentsam capabilities repository.snapshot --json
 ```
 
-This registry is intended to drive CLI/TUI discovery, AgentSam/MCP tool selection, docs, verification, and workflow capability resolution. It is deliberately not a second hosted tools database.
+This registry is intended to drive CLI/terminal UI discovery, AgentSam/MCP tool selection, docs, verification, and workflow capability resolution. It is deliberately not a second hosted tools database.
 
 ## repository.snapshot
 
@@ -26,7 +26,8 @@ This registry is intended to drive CLI/TUI discovery, AgentSam/MCP tool selectio
 
 - Git resource identity and revision
 - Python repository intelligence
-- Merkle root and tree statistics
+- Merkle root, semantic metadata root, execution-domain facts, and tree statistics
+- deterministic client/server trust-boundary contradictions derived from the Merkle-bound AST graph
 - package/manifests
 - local knowledge/index generation when configured
 - last trusted local deployment receipt when available
@@ -36,6 +37,7 @@ It does **not** call an LLM, mutate source, index the repository, provision clou
 
 ```sh
 agentsam inspect --json
+agentsam inspect --execution-domain browser --view files --json
 ```
 
 ```js
@@ -43,7 +45,7 @@ import { repositorySnapshot } from '@inneranimalmedia/agentsam-sdk/repository';
 const snapshot = await repositorySnapshot({ cwd: process.cwd() });
 ```
 
-The timestamp is not included in the content hash, so unchanged evidence produces the same `content_hash` and `snapshot_id`.
+The timestamp is not included in the content hash, so unchanged evidence produces the same `content_hash` and `snapshot_id`. The default bounded index view carries a compact `analysis.trust_boundary` summary (up to 20 contradiction cards) while the canonical full snapshot retains all deterministic findings. `agentsam security scan` consumes the same analyzer rather than maintaining a separate architecture model.
 
 ## Optional AgentSam/LLM composition
 

package/docs/CLI_SHELL.md

@@ -1,129 +1,216 @@
 # Agent Sam SDK — terminal experience
 
-The Agent Sam terminal is a presentation layer over real local capabilities. It is not a second execution engine and it is not tied to Gorilla, Cloudflare, or a particular model provider.
+`agentsam` is the product entrypoint. Users do not choose a renderer or need to know whether a screen is implemented with ANSI, Clack, or another terminal library.
 
-## Default experience
+## Product entrypoint
 
 ```bash
-agentsam tui
+agentsam
 ```
 
-Runs the bundled zero-dependency Node/ANSI renderer. This is the default because it is available anywhere the npm CLI runs.
+On first use in a project, Agent Sam asks whether the directory is trusted before project-local instructions, hooks, or execution policy can load. The setup flow then uses keyboard-driven selectors for runtime and model policy.
 
-```bash
-agentsam tui rich
-agentsam tui rich --install
+Model policy is explicit and is governed by the normative model-selection SSOT contract in `protocol/models/README.md`:
+
+1. **Provider** — the explicit provider lane selected by the user.
+2. **Model** — the exact provider-verified model; provider-level pseudo-models such as `automatic` or `default` are not substitutes for exact selection.
+3. **Reasoning level** — one of the reasoning efforts declared by that model.
+4. **Processing** — Standard, Fast, Flex, or another tier only when that model declares it.
+
+`/models`, `agentsam models`, exact `-m <model_id>` selection, runtime execution, and usage receipts must all resolve through that same inventory/selection authority. AgentSam may curate and rank a useful first page, but provider availability, capabilities, limits, and pricing retain provider-authoritative provenance.
+
+For models with materially different pricing by reasoning, service tier, or context size, these controls are user-visible policy. They are not hidden prompt hints.
+
+After setup, bare text is an Agent Sam request. Slash commands control the runtime.
+
+```text
+sam ~/project > Find why OAuth callback state is failing
+
+  Model request
+  model       openai:gpt-6-astra
+  reasoning   high
+  processing  default
+  context     ~18,240 input tokens
+  max call    $... conservative ceiling
+
+  Send this request?  Yes / No
 ```
 
-Runs the optional Python Rich renderer. `--install` creates an isolated `.agentsam/tui-venv` and installs Rich there; system Python is left alone.
+The model preflight is shown before the first paid request in a session, and again if a later request raises the previously approved conservative cost ceiling. Current active context remains distinct from cumulative session usage.
 
-```bash
-agentsam shell
+## Command picker
+
+Typing `/` opens the scrollable command picker in an interactive terminal. The picker is generated from the implemented command catalog; commands should not be advertised before a handler exists.
+
+Current controls include:
+
+```text
+/model       exact model + reasoning + processing selectors
+/reasoning   change the selected model's reasoning effort
+/fast        request the model's Fast processing tier
+/flex        request Flex processing when supported
+/standard    return to Standard processing
+/context     context economics and current active-context information
+/models      safe credential/provider/model inventory
+/whoami      authenticated IAM identity + safe credential status
+/session     current cumulative token/cost/resume receipt
+/cf          bounded Cloudflare/Workers operations
+/status      local project / DB / Git / PTY health
+/settings    project/runtime/terminal/model preferences
+/pwd         working directory
+/cd          change working directory
+/git         Git operations
+/diff        Git diff
+/db          local SQLite
+/agent       local Agent Sam dev-server request
+/logs        local execution events
+/deploy      intentional deployment flow
+/clear       clear the terminal
+/help        show commands
+/exit        save/pause the session and return to the host terminal
 ```
 
-Starts the interactive Agent Sam slash-command shell. Once the `agentsam>` prompt is visible, commands such as `/help`, `/status`, `/pwd`, and `/git` are handled by Agent Sam instead of the host shell (PowerShell, bash, or zsh). Use `/exit` to return to the host terminal.
+Provider-brand commands such as `/claude` or `/codex` are not the generic shell contract. Model execution stays behind Agent Sam.
 
-Do not type `/help` directly at a PowerShell/bash prompt; enter `agentsam shell` first.
+## Credentials and identity
 
-For scripts and regression tests, a single slash command can be dispatched without opening the REPL:
+A user should not need to manually `source` and `unset` provider keys for every Agent Sam command.
+
+Agent Sam resolves credentials in this order:
+
+1. an explicitly supplied credential where a command contract permits one;
+2. the current process environment;
+3. the user's secure Agent Sam provider files under `~/.agentsam/env.d/`.
+
+Provider files are machine-local and must not be group/world-readable on POSIX systems. Agent Sam parses the expected variable from the file rather than evaluating the file as shell code.
+
+`agentsam models` uses the credential internally for safe provider discovery but never returns the secret. Its public status reports only safe facts such as provider, configured state, source class, and provider-verified model availability.
+
+IAM login is also machine-local rather than repository state. A successful browser authentication may persist the `sdk_` bearer under `~/.agentsam/auth/session.json` with restrictive permissions. `agentsam whoami`, deploy, tunnel, and context detection can reuse that validated session. Project `.agentsam/config.json` remains portable and must not become a second identity database.
 
 ```bash
-agentsam shell --command /help
+agentsam whoami
+agentsam whoami --json
 ```
 
-## Architecture
+`whoami` can show safe identity/account information and whether provider credentials are available. It never prints API-key or SDK-bearer values.
+
+## Execution approval
+
+Model reasoning does not itself authorize host execution.
+
+Read-only/no-side-effect capabilities may execute under the current trusted runtime policy. A model-selected capability with declared side effects must pass a runtime-owned approval boundary before its handler is invoked.
 
 ```text
-CLI command / execution state
-        |
-        +--> Node ANSI renderer        default, zero extra dependencies
-        |
-        +--> Python Rich renderer      optional high-fidelity live presentation
-        |
-        +--> browser shell-kit         reusable React components, separate surface
+Agent Sam needs execution permission
+
+  action  cloudflare.wrangler.native:whoami
+  target  local runtime · ~/project
+  effect  local_process
+  input   {"command":"whoami"}
 
-Capabilities underneath presentation:
+  secrets remain runtime-owned and are not included in the model-visible result.
 
-Git context
-Local SQLite
-Local PTY
-Agent/tool execution
-Logs/events
-Deploy adapters
+? Allow cloudflare.wrangler.native:whoami?
+  Allow once
+  Always allow cloudflare.wrangler.native:whoami in this project
+  Deny
 ```
 
-Presentation consumes state. It does not authorize tools, decide policy, own databases, or execute cloud operations by itself.
+Persistent approvals are exact-operation and exact-project grants. Approving `wrangler whoami` does not authorize another Wrangler operation or another repository.
 
-## Local project contract
+Commands whose purpose is to disclose a credential, such as `wrangler auth token`, are not model-visible capabilities. Safe identity/authorization probes are preferred.
+
+## Sessions and resume
 
-`agentsam init` creates:
+Every interactive Agent Sam run receives a provider-neutral session identifier:
 
 ```text
-.git/
-.env
-.env.example
-agentsam.config.js
-.agentsam/config.json
-.agentsam/data/agentsam.sqlite
-db/schema.sql
-src/agent.js
-src/dev-server.js
-scripts/smoke.mjs
+asess_<uuid>
 ```
 
-There is no Worker requirement in this contract.
+Provider response IDs live beneath the Agent Sam session and are not the public session identity. Session files are machine-local under `~/.agentsam/sessions/` and use restrictive permissions.
 
-`src/agent.js` is runtime-neutral. The Node development adapter injects local SQLite. A cloud adapter may later inject D1 or another compatible store.
+The session retains enough runtime state to continue a compatible provider conversation, including selected model policy, provider continuation reference, current usage snapshot, cumulative usage, accumulated catalog-calculated cost, last safe error receipt, cwd, and the last substantive user request/command used as the session title.
 
-## TUI ownership
+Housekeeping actions such as `/exit`, `/help`, and `/session` do not replace that human-readable title.
 
-| Surface | Location | Role |
-|---|---|---|
-| ANSI | `examples/agentsam-tui-ansi.mjs` | npm-native default terminal renderer |
-| Rich | `python/agentsam_sdk/tui/` | optional richer cards, progress, events, logs |
-| shell-kit | `packages/agentsam-shell-kit/` | reusable React/browser work-surface components |
-| Gorilla | `templates/gorilla-shell/` | visual/theme experiment only |
+On Ctrl+C or normal exit, Agent Sam saves the session and prints a compact receipt:
 
-Gorilla is intentionally not scaffolded by default.
+```text
+Token usage: total=21,463 input=21,244 (+ 60,544 cached) output=219 reasoning=...
+Cost: $... · openai:gpt-6-astra · fast
+Active context: ... tokens
 
-## Commands
+To continue this session, run:
+  agentsam resume asess_...
 
-```text
-/help       show commands
-/status     local project / DB / Git / PTY health
-/context    current repository + revision
-/pwd        working directory
-/cd         change directory
-/git        Git operations
-/db         local SQLite
-/agent      invoke configured Agent Sam
-/logs       local execution events
-/tui        terminal presentation
-/deploy     intentionally add a cloud adapter
-/exit       exit Agent Sam shell and return to the host terminal
+Or run:
+  agentsam resume
+
+and select:
+  Run wrangler whoami
+```
+
+Provider-reported token usage is authoritative when available. Cached input is reported separately rather than added to normal input. Cost is calculated from Agent Sam's active model/pricing authority and is not presented as a provider invoice unless the provider supplied one.
+
+Resume commands:
+
+```bash
+agentsam resume asess_...
+agentsam resume              # scrollable recent-session picker in a TTY
+agentsam resume --list
+agentsam resume --json
 ```
 
-Provider-specific commands such as `/claude` or `/codex` are not part of the generic shell contract. Model routing belongs behind Agent Sam.
+Changing model, reasoning effort, or processing tier breaks provider-continuation compatibility for the next turn; Agent Sam starts a fresh provider continuation while retaining cumulative Agent Sam session accounting.
+
+## Error presentation
 
-Workspace switching is not required for local tooling. Authenticated user/session identity is the security boundary; workspace/project labels are organizational metadata.
+Errors preserve machine identity instead of becoming generic prose. Where available the terminal should surface HTTP status, provider error type/code, request or Ray ID, retry metadata, requested/resolved service tier, and retry classification. Secrets and authorization headers are redacted before an error receipt enters model-visible output or a persisted session.
 
-## Cloud graduation
+## One-shot commands
 
-Cloud infrastructure is generated when requested, not during local init.
+Normal commands remain deterministic and scriptable:
+
+```bash
+agentsam status
+agentsam models
+agentsam whoami --json
+agentsam inspect --match oauth --view files --json
+agentsam deploy
+agentsam --help
+```
+
+`agentsam shell` remains an explicit/secondary way to enter the same shell. Bare `agentsam` is the normal interactive entrypoint.
+
+For regression tests, a slash command can be dispatched without creating interactive-session clutter:
+
+```bash
+agentsam shell --command /help
+```
+
+## Internal UI engine
+
+Presentation is implementation detail:
 
 ```text
-local project
-   |
-   +--> agentsam deploy --target cloudflare
-           |
-           +--> src/cloudflare-worker.js
-           +--> wrangler.toml
-           +--> migrations/0001_agentsam_core.sql
-           +--> provisioned account bindings
+Agent Sam lifecycle/state
+        |
+        +--> ANSI / picocolors       semantic color + cursor control
+        +--> Clack prompts           arrow-key selects / confirms / text input
+        +--> runtime activity        thinking/tool/context lifecycle
+        +--> node-pty / host runtime real process/filesystem boundary
 ```
 
-The same `src/agent.js` remains application authority.
+SDK developers can preview rendering experiments from this repository, but those are design-lab commands rather than installed product vocabulary.
+
+## Local project contract
+
+`agentsam init` owns portable repository/project setup. User identity, provider secrets, session history, execution approvals, and provider continuation state are machine/account runtime state and must not be written into portable project configuration.
+
+Local development does not require a cloud account. Cloud infrastructure is added intentionally.
 
 ## Design rule
 
-A CLI operation should be understandable in plain text first, then enhanced by ANSI/Rich presentation. CI and agent capture must always have a deterministic non-interactive path (`--check`, JSON receipts where applicable).
+A CLI operation must remain understandable in plain text and deterministic in CI/pipes. Interactive terminals may enhance state with color, cursor redraw, selectors, confirmation, progress, and animation. Presentation does not authorize tools, own credentials, or silently become model-routing authority. Runtime contracts do.

package/docs/CMS_STUDIO.md

@@ -0,0 +1,101 @@
+# AgentSam CMS Studio architecture
+
+The SDK treats CMS authoring and the public website as separate deployment products that share publication contracts.
+
+```text
+apps/client-cms-editor/                 authenticated authoring/control app
+        │
+        ├─ pages / sections / themes / assets
+        ├─ AgentSam workbench
+        ├─ preview
+        └─ publish
+                ↓
+        structured publication snapshot
+             ┌──┴──┐
+             │     │
+            D1     R2 WEBSITE_ASSETS
+        metadata   content/media/theme artifacts
+             │     │
+             └──┬──┘
+                ↓
+        small public CMS runtime
+```
+
+The public runtime must not inherit the full authoring dependency graph. Monaco, terminal, browser automation, authenticated admin UI, and the AgentSam workbench stay in the authoring application unless a public feature explicitly requires them.
+
+## Shared AgentSam platform
+
+CMS consumes `@inneranimalmedia/agentsam-contracts` and `@inneranimalmedia/agentsam-workbench`, the same product-neutral layer proven first by Local Studio. `CmsAgentSurface` supplies explicit CMS context to the shared `AgentWorkbenchAdapter`; it does not scrape editor state or invent a CMS-specific chat transport.
+
+Identity is resolved before AgentSam execution:
+
+```text
+IAM
+ ↓
+authenticated principal (accountId + authUserId)
+ ↓
+application authorization
+ ↓
+CMS context / capabilities
+ ↓
+optional browser or container runtime
+```
+
+`SESSION_CACHE` is an optional cache only. `MY_CONTAINER` and `MYBROWSER` are execution infrastructure only. None may become identity/session authority.
+
+## Cloudflare capability contract
+
+Baseline `cms-cloud` requires `DB` and `WEBSITE_ASSETS`. Other bindings are capability-driven:
+
+- `iam` → `IAM_CLIENT_ID`, `IAM_CLIENT_SECRET`, `IAM_ORIGIN`
+- `workers-ai` → `AGENTSAM_WAI`
+- `browser` → `MYBROWSER`
+- `container` → `MY_CONTAINER`
+- `encrypted-secrets` → `SECRETS_ENCRYPTION_KEY`
+- `acp` → `ACP_CLIENT_ID`, `ACP_CLIENT_SECRET`
+
+`IAM_ORIGIN` means the canonical IAM issuer/auth service. It must not silently mean the current website origin.
+
+## Routes
+
+The intended ownership boundary is:
+
+```text
+/*                    public CMS
+/auth/*                identity
+/dashboard/*           authenticated application
+/dashboard/agentsam    authenticated AgentSam product
+/dashboard/cms         authenticated CMS Studio
+/api/public/*          visitor-safe CMS APIs
+/api/auth/*            identity/session
+/api/cms/*             authenticated editor/publishing APIs
+/api/agentsam/*        authenticated AgentSam APIs
+```
+
+## Publication data
+
+Prefer versioned structured sections such as:
+
+```json
+{
+  "publicationId": "pub_example",
+  "route": "/about",
+  "revision": 18,
+  "theme": "iam-classy",
+  "sections": [
+    {
+      "type": "hero",
+      "props": {
+        "title": "About us",
+        "imageAsset": "asset_example"
+      }
+    }
+  ]
+}
+```
+
+The renderer may produce sanitized HTML/static snapshots from this data. Arbitrary executable HTML from the editor is not the public-content authority.
+
+## Current server authority
+
+The imported app contains only the portable CMS API/routing/preview bridge. The current full CMS domain remains in `inneranimalmedia/src/core/agentsam/cms/` at the import provenance revision. The next server-side extraction should create reusable `packages/agentsam-cms-*` packages rather than copy that domain into this app.