@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/AGENTSAM.md

@@ -2,6 +2,12 @@
 
 This file defines stable behavior for AgentSam agents using the portable SDK. It is not account state, project state, a run log, or a replacement for repository-specific `.agentsamrules`.
 
+**Naming:** AgentSam is the product. **SAM** means **Systematic Autonomous Machinery** — the typed
+operation/execution spine (`sam.invoke`, modules, receipts). In docs and code, `sam` is the
+conventional client variable for that machinery, never a human identity. Prefer “SAM resolves…” /
+“AgentSam executes through SAM…” over anthropomorphic phrasing. Architecture SSOT:
+`docs/architecture/SAM_KERNEL.md`.
+
 ## Execution
 
 - Infer routine implementation details when repository evidence makes the answer clear; do not block on unnecessary questions.
@@ -32,6 +38,44 @@ This file defines stable behavior for AgentSam agents using the portable SDK. It
 - Git owns source-control history. Merkle owns filesystem evidence and snapshot lineage. Runtime/hosted stores own run and execution history.
 - Portable project configuration must not become an account/session/run database.
 
+## Storage architecture law
+
+- Ordinary AgentSam operation is local first. Its own ProjectSession, runs,
+  receipts, and resumability use the project-owned
+  `.agentsam/data/agentsam.sqlite` and versioned `migrations/runtime/` by
+  default. The project root, rather than a moving shell cwd or model choice,
+  determines that database.
+- Durable Objects are **not** part of the default AgentSam SDK runtime or
+  execution path. A product may opt into an actor adapter only for a proven
+  distributed actor requirement; ordinary sessions, plans, tools, terminals,
+  and task state must not acquire a hidden Durable Object dependency.
+- A project's application data keeps its existing authority. This repository's
+  live Local Studio Worker uses its real D1, Hyperdrive, R2, AI, and service
+  bindings for the purposes they already serve. AgentSam's local session
+  SQLite does not replace those bindings or silently sync to them. A user may
+  explicitly choose connected infrastructure where it fits the required data.
+  For application features, inspect and prefer the user's real project storage;
+  use local SQLite for application data when selected or clearly beneficial.
+- Persist only state that supports continuity, recovery, meaningful receipts,
+  or valuable caches. Give new state a persistent, session, work_cycle, ttl,
+  or scratch lifecycle; expire disposable planner/search state. Do not persist
+  hidden reasoning, unlimited transcripts, or credential values in generic
+  runtime state.
+- Provider-returned compacted continuation windows are session-scoped protocol
+  state, stored separately from generic session JSON in the project SQLite.
+  Preserve their exact output until successful continuation replaces it; never
+  promote them into knowledge or interpret encrypted provider content.
+- Blackboard state describes the current work cycle; knowledge describes reusable
+  understanding; evidence supports either. Provider continuation is a separate
+  inference artifact. None substitutes for the other authorities.
+- Keep runtime relational persistence behind the existing SQLite runtime and
+  migration path. Object/blob, vector, and optional actor semantics remain
+  separate capabilities. Declare storage capabilities truthfully; do not
+  pretend SQLite provides distributed actor behavior.
+
+See [Storage architecture](docs/architecture/STORAGE.md) for enforcement and
+the current compatibility boundary.
+
 ## Model and run policy
 
 - Model, reasoning effort, service tier, budget, and permissions are runtime configuration, not hidden prompt instructions.
@@ -49,7 +93,13 @@ This file defines stable behavior for AgentSam agents using the portable SDK. It
 
 AgentSam compiles instructions deterministically in this order:
 
-1. `AGENTSAM.md` — stable runtime behavior.
+1. `AGENTSAM.md` — stable runtime behavior (this file).
 2. `.agentsamrules` — repository-specific rules, loaded after the stable contract and therefore more specific where the two address the same repository behavior.
 
+Compatibility adapters for other coding agents (`AGENTS.md` for Cursor/Codex,
+`CLAUDE.md` for Claude Code) must only redirect here. They must not duplicate
+AgentSam policy. If a shim and this file conflict, this file is authoritative.
+Nested app-level `AGENTS.md` files under `apps/` are app-specific contracts,
+not substitutes for this runtime file.
+
 Live account, authorization, model, run, task, terminal, and usage state never belong in either file.

package/README.md

@@ -5,6 +5,21 @@ security, identity, scaffolding, and delivery capabilities with optional AgentSa
 The interactive CLI can run the same bounded capabilities through an explicitly selected model while
 keeping model choice, reasoning effort, processing tier, credentials, approvals, context, and cost inspectable.
 
+**SAM** = **Systematic Autonomous Machinery** — the execution spine under AgentSam (not a person).
+The conventional client variable is `sam`:
+
+```js
+import { AgentSamClient } from '@inneranimalmedia/agentsam-sdk';
+
+const sam = new AgentSamClient();
+const repo = await sam.invoke('repository.inspect', { root: '.' });
+// or: await sam.repository.inspect({ root: '.' });
+console.log(repo.data.summary, repo.receipt.id);
+```
+
+See [SAM Kernel](docs/architecture/SAM_KERNEL.md) for `invoke` / `describe` / `discover`,
+operation IDs, and the universal `SamResult` envelope.
+
 **npm:** `@inneranimalmedia/agentsam-sdk` · **Source:** [GitHub](https://github.com/SamPrimeaux/agentsam-sdk)
 
 Node 22.5+ is required. Docker is optional for container commands. Python 3.10+ is required
@@ -19,6 +34,17 @@ npm install @inneranimalmedia/agentsam-sdk
 npm install -g @inneranimalmedia/agentsam-sdk
 ```
 
+Or install without a local Node/npm setup via the hosted installer (currently
+an npm-bootstrap script; standalone SEA binaries are planned, not shipped yet):
+
+```sh
+curl -fsSL https://agentsam.inneranimalmedia.com/install | bash
+# a specific version, channel, or bundled app launcher:
+curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --version 2.6.3
+curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --channel beta
+curl -fsSL https://agentsam.inneranimalmedia.com/install | bash -s -- --app cad
+```
+
 The identity workspace is included through `@inneranimalmedia/agentsam-sdk/identity`.
 It is not a separate npm installation. A container is not required to import SDK modules
 or use local scaffolding/indexing.
@@ -42,8 +68,28 @@ The generated project contains a Git repository, local SQLite database, environm
 API, and terminal commands. Local setup does not require an IAM account, cloud credentials, a model, or
 a tunnel. Use `agentsam add <feature>` to record an explicit feature selection and its capability set.
 
+AgentSam's own local session and run state uses one SQLite database at
+`<projectRoot>/.agentsam/data/agentsam.sqlite`. A deployed project's application
+storage remains its declared infrastructure; see [storage architecture](docs/architecture/STORAGE.md).
+
 Without a global install, use `npx @inneranimalmedia/agentsam-sdk create my-agent --preset fullstack`.
 
+## MCP setup
+
+Cloudflare's API MCP server uses `https://mcp.cloudflare.com/mcp`. Add that URL
+to the agent client you use, then complete its Cloudflare OAuth flow. For Codex:
+
+```sh
+codex mcp add cloudflare-api --url https://mcp.cloudflare.com/mcp
+codex mcp login cloudflare-api
+```
+
+`agentsam mcp add cloudflare-api --url https://mcp.cloudflare.com/mcp` is not
+currently an AgentSam CLI command. The repo's `.agentsam/config.json` is a
+portable project manifest, not an MCP client configuration; it cannot register
+this server for every agent tool on clone. Keep OAuth tokens in each client's
+credential store rather than committing them to the repository.
+
 ## Index an existing repository
 
 ```sh
@@ -88,6 +134,55 @@ read-only `repository.snapshot` composition primitive. See [Capabilities and pre
 Export suffixes such as `/identity` mean imports from
 `@inneranimalmedia/agentsam-sdk/identity`. Use `agentsam <command> --help` where supported.
 
+## AgentSam apps
+
+Reusable, independently runnable products live under `apps/` — currently
+`cad-creator` (CAD/robotics engineering station) and `client-cms-editor`
+(CMS authoring), with `local-studio` as the hosting Worker. Each declares an
+`agentsam.app.json` manifest (id, package name, surfaces, runtime readiness,
+and its own `preview`/`info`/`doctor`/`scaffold` commands) and ships its
+own `bin/` entry point, so an app is usable standalone via its own binary
+(e.g. `agentsam-cad-creator`) or discoverable through the parent CLI:
+
+```sh
+agentsam app list
+agentsam app info cad-creator
+agentsam app doctor cad-creator
+agentsam app preview cad-creator
+agentsam app scaffold cad-creator ./my-project
+```
+
+An app remaining independently runnable/testable/packageable while AgentSam
+gives it a uniform discovery surface is the intended shape — not every app is
+equally far along yet; `agentsam app info <id>` reports each app's actual
+runtime readiness rather than assuming parity.
+
+## MCP client & client adapters
+
+AgentSam manages MCP server connections as the connection authority (`~/.agentsam/mcp/`)
+and materializes client configurations for installed editors (Cursor `~/.cursor/mcp.json`,
+Claude Desktop config):
+
+```sh
+agentsam mcp add inneranimalmedia
+agentsam mcp list
+agentsam mcp status inneranimalmedia
+agentsam mcp doctor inneranimalmedia
+agentsam mcp remove inneranimalmedia --client cursor
+```
+
+## Live agent evaluation telemetry
+
+Capture real live agent receipts (MCP tool telemetry, git diff, gate verification,
+and run metadata) into `agentsam_eval_runs` and `agentsam_model_eval_observations`:
+
+```sh
+agentsam eval live start --suite sdk-real-work-20260919 --case cad-shell-unification --client cursor --model "Muse Spark 1.3"
+# ... agent executes real work ...
+agentsam eval live status
+agentsam eval live finish --gate PASS --remote
+```
+
 ## Optional background service
 
 ```sh

package/apps/README.md

@@ -0,0 +1,34 @@
+# AgentSam apps
+
+`apps/` is the development/authoring source of truth for runnable AgentSam product surfaces. Product apps are independently extractable and are intentionally **not** members of the SDK root npm workspace graph.
+
+## Product app law
+
+Every deployable product app follows the same ownership boundary:
+
+```text
+apps/<app>/
+├─ package.json
+├─ package-lock.json          one lockfile for the whole app
+├─ frontend/
+│  └─ package.json
+├─ backend/
+│  ├─ package.json
+│  ├─ wrangler.jsonc         Cloudflare binding/deploy SSOT
+│  ├─ worker/
+│  │  └─ index.js            canonical Cloudflare Worker entry
+│  └─ server/ or src/        application/backend modules
+└─ shared/<domain>/
+   └─ package.json
+```
+
+Rules:
+
+- `apps/<app>/` is a self-contained npm workspace root with workspaces `frontend`, `backend`, and `shared/*`.
+- Frontend/backend do not get independent lockfiles.
+- `backend/worker/index.js` is the checked-in Cloudflare runtime boundary. Generated framework output may be imported by it, but generated output is not the deployment owner.
+- `backend/wrangler.jsonc` is the app's Cloudflare configuration SSOT. Do not add app Workers or Wrangler configs at the SDK repository root.
+- `shared/<domain>/` is app-local shared code. Promote code to `packages/*` only when it is genuinely SDK-wide/reusable.
+- The SDK root owns package/tooling release concerns; app workspace dependencies stay inside each app.
+
+Current product apps governed by the architecture test are `local-studio/`, `cad-creator/`, and `client-cms-editor/`. `frontend/` remains a public-site seed lane rather than a self-contained product workspace, and `_incoming/` is an import drop zone.