@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/AGENTSAM.md

@@ -32,6 +32,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 +87,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

@@ -19,6 +19,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.2
+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 +53,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 +119,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.