@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/docs/CLI_SHELL.md

@@ -1,6 +1,6 @@
 # Agent Sam SDK — terminal experience
 
-`agentsam` is the product entrypoint. Users do not choose a renderer or need to know whether a screen is implemented with ANSI, Rich, Clack, or another terminal library.
+`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.
 
 ## Product entrypoint
 
@@ -8,26 +8,166 @@
 agentsam
 ```
 
-On the first run for a project, Agent Sam opens keyboard-driven setup for the project, runtime, terminal, and model preference. On later runs it shows a short project-aware boot transition and enters the Agent Sam prompt.
+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.
+
+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
+```
+
+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.
+
+## 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
+```
+
+Provider-brand commands such as `/claude` or `/codex` are not the generic shell contract. Model execution stays behind Agent Sam.
+
+## Credentials and identity
+
+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 whoami
+agentsam whoami --json
+```
+
+`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
-$ agentsam
+Agent Sam needs execution permission
 
-  Agent Sam
-  my-project · main · qwen2.5-coder
+  action  cloudflare.wrangler.native:whoami
+  target  local runtime · ~/project
+  effect  local_process
+  input   {"command":"whoami"}
 
-  ✓ project
-  ✓ runtime
-  ✓ model
+  secrets remain runtime-owned and are not included in the model-visible result.
 
-  username ~/path/to/project >
+? Allow cloudflare.wrangler.native:whoami?
+  Allow once
+  Always allow cloudflare.wrangler.native:whoami in this project
+  Deny
 ```
 
-The model stored by the CLI is a **preference only**. It does not replace the connected host/runtime as model-routing authority.
+Persistent approvals are exact-operation and exact-project grants. Approving `wrangler whoami` does not authorize another Wrangler operation or another repository.
 
-Live terminal scenes are automatic product behavior. When Agent Sam is actively handling an `/agent` request, the installed CLI renders the compact thinking/activity panel itself; users never run a renderer or preview command. The same shipped activity seam accepts model, tool, and context-compaction lifecycle events from richer hosts. Pipes and CI remain plain/deterministic.
+Commands whose purpose is to disclose a credential, such as `wrangler auth token`, are not model-visible capabilities. Safe identity/authorization probes are preferred.
 
-Use `/settings` inside Agent Sam to revisit the keyboard choices and `/models` to inspect providers and locally available models.
+## Sessions and resume
+
+Every interactive Agent Sam run receives a provider-neutral session identifier:
+
+```text
+asess_<uuid>
+```
+
+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.
+
+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.
+
+Housekeeping actions such as `/exit`, `/help`, and `/session` do not replace that human-readable title.
+
+On Ctrl+C or normal exit, Agent Sam saves the session and prints a compact receipt:
+
+```text
+Token usage: total=21,463 input=21,244 (+ 60,544 cached) output=219 reasoning=...
+Cost: $... · openai:gpt-6-astra · fast
+Active context: ... tokens
+
+To continue this session, run:
+  agentsam resume asess_...
+
+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
+```
+
+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
+
+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.
 
 ## One-shot commands
 
@@ -36,14 +176,15 @@ Normal commands remain deterministic and scriptable:
 ```bash
 agentsam status
 agentsam models
-agentsam inspect --json
+agentsam whoami --json
+agentsam inspect --match oauth --view files --json
 agentsam deploy
 agentsam --help
 ```
 
-`agentsam shell` remains an explicit/secondary way to enter the slash-command shell. Bare `agentsam` is the normal interactive entrypoint.
+`agentsam shell` remains an explicit/secondary way to enter the same shell. Bare `agentsam` is the normal interactive entrypoint.
 
-For regression tests, one slash command can still be dispatched without opening an interactive terminal:
+For regression tests, a slash command can be dispatched without creating interactive-session clutter:
 
 ```bash
 agentsam shell --command /help
@@ -51,56 +192,25 @@ agentsam shell --command /help
 
 ## Internal UI engine
 
-The renderer is implementation detail:
+Presentation is implementation detail:
 
 ```text
 Agent Sam lifecycle/state
         |
         +--> ANSI / picocolors       semantic color + cursor control
-        +--> Rich renderer           high-fidelity live render experiments
         +--> Clack prompts           arrow-key selects / confirms / text input
-        +--> node-pty                real shell/process/filesystem
-```
-
-SDK developers can preview render experiments from this repository without exposing renderer names as product commands:
-
-```bash
-npm run ui:preview -- tour
-npm run ui:preview -- boot
-npm run ui:preview -- setup
-npm run ui:preview -- thinking
-npm run ui:preview -- ready
-npm run ui:preview -- ansi
-```
-
-These preview commands are a design lab, not part of the installed user vocabulary.
-
-## Slash commands
-
-```text
-/help       show commands
-/status     local project / DB / Git / PTY health
-/context    current repository + revision
-/pwd        working directory
-/cd         change working directory
-/git        Git operations
-/db         local SQLite
-/agent      invoke configured Agent Sam
-/models     inspect available providers and local models
-/settings   choose project/runtime/terminal/model preference
-/logs       local execution events
-/deploy     intentionally add a cloud adapter
-/exit       exit Agent Sam and return to the host terminal
+        +--> runtime activity        thinking/tool/context lifecycle
+        +--> node-pty / host runtime real process/filesystem boundary
 ```
 
-Provider-specific commands such as `/claude` or `/codex` are not part of the generic shell contract. Model execution/routing belongs behind Agent Sam.
+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` creates a local project with Git, `.env`, `.agentsam/config.json`, a committed `.agentsamrules` project-instruction file, local SQLite, and the project runtime files. The setup wizard uses keyboard-driven Clack prompts in an interactive terminal; flags keep non-interactive creation deterministic.
+`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 requires no Worker or cloud account. Cloud infrastructure is added intentionally at deploy time.
+Local development does not require a cloud account. Cloud infrastructure is added intentionally.
 
 ## Design rule
 
-A CLI operation must remain understandable in plain text and deterministic in CI/pipes. Interactive terminals may enhance that state with color, cursor redraw, prompts, progress, and animation. Presentation does not authorize tools, own execution policy, or silently become model-routing authority.
+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/PLATFORM_RUNTIME_EVENTS.md

@@ -0,0 +1,48 @@
+# Platform runtime event dependency
+
+Status: **SDK consumer ready; platform producer pending.**
+
+The standalone CLI does not depend on a platform event endpoint. Local/provider execution emits runtime events directly into the same presenter used by future platform-connected sessions.
+
+The cross-repo dependency is in `SamPrimeaux/inneranimalmedia`: its pending agent-runtime SSE/event channel must eventually deliver the same normalized envelope consumed by:
+
+`src/ui/cli/runtime-events.js -> normalizeRuntimeEventEnvelope()`
+
+The SDK intentionally does **not** invent a route such as `/api/sdk/agent/runs`. Endpoint ownership, authorization, reconnection, and SSE lifecycle belong to the platform repository.
+
+## Producer contract
+
+Each platform event delivered to the SDK must normalize to:
+
+```js
+{
+  schema_version: 1,
+  type: "tool.started",
+  timestamp: "2026-09-18T00:00:00.000Z",
+  run_id: "run_...",
+  sequence: 3,
+  payload: {
+    // event-specific data
+  }
+}
+```
+
+`run_id` and `sequence` are optional when the source cannot supply them. `type` is required. `payload` is always normalized to an object.
+
+The SDK adds the internal contract marker `schema: "agentsam-runtime-event-v1"` after normalization. Platform producers do not need to know about CLI rendering, spinners, plans, approval prompts, compaction UI, or footer layout. They only emit the envelope.
+
+Current event vocabulary is declared in `src/telemetry/events.js`, including model, usage, cost, context, tool, approval, plan/task, timer, waiting-input, error, and run lifecycle events.
+
+## Boundary
+
+Standalone completion is not blocked by this dependency.
+
+The release-blocking standalone path is:
+
+provider/local runtime -> AgentEvent -> normalizeRuntimeEventEnvelope -> CLI presenter
+
+The later platform-connected path should be:
+
+platform runtime -> SSE/WebSocket transport -> normalizeRuntimeEventEnvelope -> same CLI presenter
+
+If platform integration requires changing the presenter contract instead of only adding the transport connection, treat that as a contract regression.

package/docs/RELEASES.md

@@ -1,14 +1,22 @@
 # `@inneranimalmedia/agentsam-sdk` release receipts
 
-**2.5.0 is the current release candidate on `main`; it is not published yet.**
-The npm `latest` dist-tag is **2.4.1**. The private identity workspace continues to
+**2.6.0 is published and is the npm `latest` release.** The private identity workspace continues to
 ship through root SDK exports and is not published separately.
 
-Release-candidate base: `236afa84b553fb0d0109abe41939488945c4fc74`. The final tagged
-publish commit will be recorded here after release. Publishing remains manual and
-`prepublishOnly` runs `npm run verify:release`.
+Published at `2026-09-12T21:14:57.827Z` from git SHA
+`ae32fba0a761cb18c5f940957bdcd58e3cab6072`, tagged `v2.6.0`. Registry integrity:
+`sha512-98xvyIXGcX6/S0nFUkB2+s4zPxF5WvN/eYBjt6s575uC/ux/xB9Y0dH+pw7ur5TMRkQj7JDR4XN5cSy6I2Hr+w==`.
+Publishing remains manual and `prepublishOnly` runs `npm run verify:release`.
 
-## 2.5.0 candidate highlights
+## 2.6.0 highlights
+
+- Interactive AgentSam now has persistent machine-local account/session identity with explicit `login`, `logout`, `whoami`, and `resume` flows.
+- `/models` and model-selection UX bind to the canonical model inventory v2 contract instead of maintaining a second CLI catalog.
+- Provider credentials and account BYOK resolution are scoped, source-aware, and reusable across interactive, deploy, and tunnel flows without storing secrets in project state.
+- Runtime receipts now model account-owned runs, provider usage, approvals, and terminal jobs with stable lineage and no tenant/workspace/user ownership aliases.
+- Cloudflare diagnostics, context economics, repository evidence, and security/indexing contracts accumulated after 2.5.0 are included in the same verified release lineage.
+
+## 2.5.0 highlights
 
 - `agentsam` is the interactive product entrypoint; renderer selection is internal, and live thinking/activity scenes now run automatically around real Agent Sam work.
 - Portable project authority is `.agentsam/config.json` + `.agentsamrules`; local CLI preferences remain non-authoritative.
@@ -23,7 +31,8 @@ publish commit will be recorded here after release. Publishing remains manual an
 
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
-| 2.5.0 | _(pending)_ | _(tag at publish)_ | Release candidate; full verification required immediately before publish. |
+| 2.6.0 | 2026-09-12T21:14:57.827Z | `ae32fba0a761cb18c5f940957bdcd58e3cab6072` | Published package; npm `latest`; registry `gitHead`, shasum, integrity, and `v2.6.0` tag verified. |
+| 2.5.0 | 2026-09-11T21:27:11.516Z | `da28623dc4808025b77605ed09aa16217b1db607` | Published package; registry `gitHead` receipt. |
 | 2.4.1 | 2026-09-11T05:45:03.622Z | `a256ababededd904da555e7898bc8afd753737d2` | Latest published package before 2.5.0. |
 | 2.4.0 | 2026-09-11T05:29:02.811Z | `81c8659977953bed53c2adb0a341ce7382be4794` | Published 2.4 line. |
 | 2.3.0 | 2026-09-11T05:09:40.046Z | `b517a720fb9b90f35c26f9ef87a84abd60d7ee01` | Published 2.3 line. |

package/docs/SOURCE_ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# AgentSam SDK source architecture
+
+The SDK root is the product/package composition layer, not the permanent home for every reusable subsystem.
+
+## Ownership rule
+
+New reusable code should have an explicit owner:
+
+- `packages/agentsam-contracts/` — framework-neutral wire/types vocabulary shared across AgentSam products and repositories.
+- `packages/identity/` — identity/auth contracts and adapters.
+- `packages/connectors/*/` — provider-specific connectors.
+- `packages/agentsam-workbench/` — reusable UI/workbench primitives.
+- `apps/*/` — self-contained applications with their own frontend/backend/shared package boundaries.
+- root `src/commands/`, `src/cli.js`, and `src/index.js` — SDK/CLI composition and public facade.
+
+`src/lib/` is a legacy extraction zone. Its current files are supported, but new unrelated reusable modules must not be added there. The source-boundary verifier freezes that surface so it can shrink over time.
+
+## Package extraction status
+
+Do not split the repo into micro-packages for their own sake. Extract a subsystem when it has a coherent public responsibility and can own its tests.
+
+**Extracted:** `packages/agentsam-repository/` now owns Git identity, Merkle/filemeta algorithms, repository graph runtime normalization, and snapshot persistence. Root SDK exports and CLI/runtime consumers compose that package without restoring `src/lib/merkle` or `src/lib/git-context.js`.
+
+Next coherent extractions:
+
+1. **Runtime/core** — account session, provider credentials, execution approvals, run/session primitives, and telemetry composition that are not CLI-specific.
+2. **Knowledge/indexing** — repository knowledge engine, stores, indexing provider contracts, and service client/runtime seams.
+
+The root CLI should depend on these packages; packages must not depend on root CLI/commands/UI internals.
+
+## Test placement
+
+Package behavior belongs with the package:
+
+```text
+packages/identity/tests/*
+packages/agentsam-contracts/test/*
+packages/agentsam-workbench/test/*
+packages/connectors/cloudflare/tests/*
+```
+
+Root SDK tests should move toward explicit roles:
+
+```text
+test/integration/*   cross-package/root-facade behavior
+test/cli/*           CLI command behavior
+test/release/*       packaging/release hygiene
+```
+
+The existing flat `test/*.test.mjs` set is legacy debt. It is frozen: old tests may remain while their owning subsystem is extracted, but new flat tests are rejected by `npm run verify:boundaries`.
+
+## App isolation
+
+Every `apps/<name>/` is a self-contained application boundary. Apps may consume documented SDK/package exports, but must not deep-import root `src/` implementation files. Reusable app logic should live in that app's `shared/` package first, then move to a top-level package only when it is genuinely cross-application.
+
+## Company graph / Merkle authority
+
+`agentsam-sdk` defines the portable vocabulary and deterministic algorithms. `inneranimalmedia` owns account-scoped operational persistence. The SDK must not introduce tenant/workspace/user ownership aliases or environment variables that impersonate authenticated account/repository authority.

package/docs/TEST_TIERS.md

@@ -0,0 +1,26 @@
+# AgentSam SDK test tiers
+
+The release-blocking test gate must be deterministic and must not require ExecOS, a user-hosted terminal tunnel, a cloud VM, or any other live external daemon.
+
+## Release-blocking tiers
+
+`npm test` runs these tiers:
+
+- `npm run test:unit` — deterministic unit/contract tests.
+- `npm run test:integration:mock` — integration behavior against local or mocked dependencies.
+- `npm run test:terminal:mock` — terminal/PTY behavior through an injected mock PTY transport. No ExecOS or tunnel is contacted.
+- identity and connector tests already included by the root `npm test` script.
+
+These tiers are the standard release gate and are suitable for GitHub Actions.
+
+## Live terminal tier
+
+`npm run test:live:terminal` is deliberately outside `npm test` and `npm run verify`.
+
+Set `AGENTSAM_LIVE_TERMINAL_WS_URL` to a real enrolled terminal WebSocket URL when an operator intentionally wants to exercise a live transport. `AGENTSAM_LIVE_TERMINAL_AUTH` may be supplied when that endpoint requires an Authorization header.
+
+If no live URL is supplied, the live test is skipped. A tunnel outage must never make the package release gate red.
+
+## Rule
+
+Tests may verify terminal protocol semantics in the release-blocking suite only through a local/mock transport. Any test that depends on ExecOS, a provisioned IAM terminal connection, Cloudflare Tunnel, or a real remote PTY belongs in the explicit live tier.