@inneranimalmedia/agentsam-sdk 2.6.3 → 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.

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
@@ -25,7 +40,7 @@ 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 -- --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
 ```

package/bin/agentsam

@@ -1,2 +1,17 @@
 #!/usr/bin/env node
-import '../src/cli.js';
+/**
+ * AgentSam CLI entry.
+ * Suppress only the node:sqlite ExperimentalWarning — keep other warnings visible.
+ */
+process.on("warning", (warning) => {
+  if (
+    warning?.name === "ExperimentalWarning" &&
+    /SQLite is an experimental feature/i.test(String(warning.message || ""))
+  ) {
+    return;
+  }
+  // Mirror default Node warning printer for everything else.
+  console.error(warning.stack || `${warning.name}: ${warning.message}`);
+});
+
+await import("../src/cli.js");

package/docs/BRAND_INTELLIGENCE.md

@@ -17,7 +17,7 @@
 | 11. TUI views | partial | activity panel during scan; full shell mockup not rebuilt |
 | 12. No-model experience | implemented | tests + CLI without model |
 | 13. Model-assisted | not applicable yet | brand.plan marked model_assisted_optional |
-| 14. GOAP integration | partial | `--goap` greedy sequencer + action catalog |
+| 14. GOAP integration | done | `--goap` uses `sam-goap-astar-v1` (A* over brand GOAP actions) |
 | 15. Receipts | partial | `receipt` + `next_actions` on scan/plan |
 | 16. Presets | implemented | cms → cms,knowledge,brand,theme |
 | 17. CLI commands | implemented | `brand`, `plan brand` |

package/docs/architecture/AGENTSAM_DISTRIBUTION_OWNERSHIP.md

@@ -0,0 +1,176 @@
+# AgentSam Distribution, Ownership, and Telemetry Boundaries
+
+## Principle
+
+One AgentSam ecosystem does not mean one giant package, one credential domain, one runtime, or one analytics signal.
+
+Keep these authorities distinct:
+
+- SDK/CLI — umbrella entry point, protocols, orchestration, discovery.
+- Products — things users independently install/open, such as Local Studio and CAD Creator.
+- Services — independently deployed backends such as agentsam-go-worker.
+- Machine runtime — one agentsamd installation per user machine where required.
+- InnerAnimalMedia infrastructure — InnerAnimalMedia-owned Cloudflare, D1/R2, Workers, ExecOS, MCP, Tail, VMs.
+- Customer/self-host infrastructure — resources owned by the customer's explicitly connected account.
+
+## Normal user vs self-host vs official release
+
+### Normal user
+
+    @inneranimalmedia/agentsam-sdk
+              │
+              ▼
+          AgentSam CLI
+          Local Studio
+              │
+       ┌──────┴─────────┐
+       ▼                ▼
+    agentsamd      official hosted
+    user machine       services
+
+Normal users do not need service source trees or InnerAnimalMedia infrastructure credentials.
+
+### Advanced self-host
+
+    installed @inneranimalmedia/agentsam-go-worker
+                    │
+                    ▼
+            Wrangler identity
+                    │
+                    ▼
+        explicit USER Cloudflare account
+                    │
+                    ▼
+             user's Worker/Container
+                    │
+                    ▼
+             local AgentSam registry
+
+A self-host operation never writes inneranimalmedia-business.
+
+### InnerAnimalMedia official release
+
+    clean maintainer source
+             │
+             ▼
+      explicit InnerAnimalMedia release guard
+             │
+             ▼
+      explicit InnerAnimalMedia CF account
+             │
+             ▼
+    official Worker/Container
+             │
+        healthy proof
+             │
+             ▼
+    inneranimalmedia-business
+    agentsam_products
+    asset_relationships
+
+The official registry path is not imported as the default meaning of deploy.
+
+## Cloudflare identity boundary
+
+Wrangler is the deploy authority. AgentSam uses wrangler whoami --json, requires an authenticated account, requires explicit selection when multiple accounts are available, binds the chosen account into the child process, and records only non-secret account metadata in receipts.
+
+Distributed packages never include InnerAnimalMedia Cloudflare credentials.
+
+## Repository/package boundary
+
+@inneranimalmedia/agentsam-sdk remains the umbrella package. Deployable or independently installable products/services can be their own packages.
+
+The Go service is:
+
+    @inneranimalmedia/agentsam-go-worker
+
+The SDK discovers that package instead of assuming:
+
+    <sdk install>/apps/agentsam-go-worker
+
+This lets a normal SDK tarball remain focused while preserving a single AgentSam user experience.
+
+## Local state boundary
+
+Installed packages are source artifacts, not mutable user state.
+
+Use:
+
+    <caller>/.agentsam/
+
+for build/deploy receipts, local product projections, and transient proof artifacts.
+
+Do not write runtime state into:
+
+    node_modules/@inneranimalmedia/...
+
+## Product/runtime boundary
+
+User-facing products should declare runtime requirements rather than bundle complete daemons.
+
+    Local Studio ──┐
+    CAD Creator ───┼──► one agentsamd ─► capability inventory
+    Ecommerce ─────┘
+
+Hosted services such as agentsam-go-worker remain services. agentsamd remains the user-machine execution runtime.
+
+## Distribution analytics: keep funnel stages separate
+
+Do not turn package installation into hidden database access.
+
+Measure distinct signals:
+
+    DISCOVERY
+      npm aggregate downloads
+      docs/site interest
+          ↓
+    ACTIVATION
+      AgentSam first run
+      Local Studio opened
+      agentsamd booted
+          ↓
+    ADOPTION
+      products/apps enabled
+      repositories registered
+          ↓
+    VALUE
+      successful runs
+      packages/deployments verified
+          ↓
+    RETENTION
+      returning active installations/accounts/projects
+          ↓
+    INFRA HEALTH
+      Workers
+      Go runtime
+      ExecOS
+      agentsamd
+      MCP
+
+Npm download counts are distribution metrics, not unique-user counts.
+
+Do not add a postinstall phone-home path. First-run/product telemetry should be disclosed/configurable and constrained to product facts. Do not collect home directories, working paths, repository names, git remotes, hostnames, usernames, command contents, credentials, or environment variables as activation telemetry.
+
+If an anonymous installation identifier is used, generate a random local UUID; never derive it from hardware identifiers.
+
+## Telemetry authorities
+
+Use separate authorities:
+
+- npm/registry data — aggregate package distribution.
+- AgentSam analytics ingestion service — validated activation/adoption/value events.
+- inneranimalmedia-tail — InnerAnimalMedia runtime/Worker observability where Cloudflare Tail is the appropriate primitive.
+
+Do not make inneranimalmedia-tail the install counter. Treat it as a registered infrastructure primitive in SAM's topology and assign it runtime-observability responsibilities deliberately.
+
+A future analytics ingestion path can normalize events from CLI, Local Studio, agentsamd, hosted services, npm metric collectors, and Tail into aggregate analytics without granting distributed clients direct D1 access.
+
+## Scale objective
+
+The purpose is not to collapse dozens of repositories and Workers into one monolith.
+
+The objective is to give every asset a known identity, capabilities, dependencies, health state, deployment receipt, ownership boundary, and protocol relationship so SAM can operate a large software estate systematically.
+
+Protect this rule:
+
+One authority per concept; multiple implementations/adapters where appropriate.

package/docs/architecture/AGENTSAM_GO_RUNTIME.md

@@ -0,0 +1,282 @@
+# AgentSam Go Runtime
+
+## Purpose
+
+Go is AgentSam's native deterministic machinery layer. It is reused by two different ownership surfaces:
+
+- agentsam-go-worker — an independently deployed hosted/self-host service.
+- agentsamd — the user-machine runtime that products can share.
+
+Those are not the same product. They should reuse protocol-compatible native core code without sharing deployment authority.
+
+The TypeScript/protocol layer remains canonical contract authority.
+
+## Current hosted-service topology
+
+    AgentSam / SAM
+          |
+          v
+    canonical runtime protocol
+          |
+          v
+    Cloudflare Worker
+          |
+          v
+      Go Container
+
+The Worker owns edge routing and deploy-time identity. The container owns native Go execution.
+
+Normal AgentSam users consume the official hosted service where appropriate. They do not need to deploy this Worker just to use AgentSam.
+
+## User-machine topology
+
+    Local Studio ──┐
+    CAD Creator ───┼──► agentsamd
+    Ecommerce ─────┘       |
+                           ├─ filesystem
+                           ├─ watcher
+                           ├─ Merkle
+                           ├─ jobs
+                           ├─ PTY/process
+                           └─ activity
+
+Products declare runtime capabilities. They do not each clone a complete daemon.
+
+## Contract authority
+
+TypeScript/protocol remains canonical. Go implements shared contracts.
+
+Consequences:
+
+- no Go-only public ErrorEnvelope,
+- no Go-only activity vocabulary,
+- no Go-only planning semantics,
+- no browser contract moves into Go,
+- shared behavior is judged by conformance fixtures.
+
+Rust/Tauri remains responsible for desktop-shell concerns such as folder selection, keychain, application lifecycle, updater, deep links, and launching/supervising agentsamd.
+
+## Current Go service capabilities
+
+The deployed service currently owns:
+
+- health/build identity,
+- runtime inventory,
+- capability inventory,
+- deterministic SHA-256,
+- deterministic static inspection,
+- canonical AgentSam ErrorEnvelope-compatible request failures.
+
+The Worker exposes edge health separately so operators can distinguish edge availability from native-container health.
+
+## Source and build identity
+
+Source identity must remain truthful across development and distribution.
+
+Maintainer checkout:
+
+    git:<commit-sha>
+
+Published service artifact:
+
+    npm:@inneranimalmedia/agentsam-go-worker@<version>
+
+Fallback only when neither authority is available:
+
+    tree:<deterministic-source-digest>
+
+The build receipt also records the deterministic source-tree digest.
+
+The local/native build proof requires:
+
+- go test ./...,
+- go vet ./...,
+- native binary build,
+- SHA-256 binary digest,
+- native process boot,
+- source identity match,
+- health/runtime/capabilities/hash/inspect probes,
+- canonical malformed-request ErrorEnvelope,
+- graceful shutdown.
+
+The Linux verification container receives the same intended source identity and must be linux/amd64 and nonroot.
+
+The live deployment is not accepted merely because Wrangler returned success. External edge and native health must report the intended source identity.
+
+## Distribution boundary
+
+The Go service is packaged independently:
+
+    @inneranimalmedia/agentsam-go-worker
+
+The SDK does not assume its own npm tarball contains apps/agentsam-go-worker.
+
+Installed-package discovery resolves the service package through Node package resolution. User state belongs under the caller's .agentsam directory; the package under node_modules remains source-only.
+
+## Cloudflare account authority
+
+Before any self-host or official live deployment AgentSam asks Wrangler for identity:
+
+    wrangler whoami --json
+
+The deploy path fails closed when authentication is missing, when no account is available, or when multiple accounts exist without an explicit selection.
+
+The chosen account is observable and bound into the Wrangler process with CLOUDFLARE_ACCOUNT_ID.
+
+No distributed package contains an InnerAnimalMedia production credential.
+
+## Self-host lifecycle
+
+Self-host is an advanced opt-in path:
+
+    agentsam go --cloudflare agentsam-go-worker \
+      --account <user-cloudflare-account-id> \
+      --yes
+
+The sequence is:
+
+    installed or development service source
+       |
+       v
+    source identity
+       |
+       v
+    Go tests + vet
+       |
+       v
+    native binary + digest
+       |
+       v
+    native boot/probes/shutdown
+       |
+       v
+    linux/amd64 nonroot container
+       |
+       v
+    container boot/probes/shutdown
+       |
+       v
+    explicit USER Cloudflare account
+       |
+       v
+    Wrangler deploy
+       |
+       v
+    Cloudflare deployment/version identity
+       |
+       v
+    external edge + native probes
+       |
+       v
+    deployment receipt
+       |
+       v
+    local AgentSam registry
+
+Self-host never mutates inneranimalmedia-business.
+
+## InnerAnimalMedia official-release lifecycle
+
+InnerAnimalMedia product registration is a separate authority:
+
+    AGENTSAM_INNERANIMALMEDIA_OFFICIAL_RELEASE=1 \
+      agentsam go --cloudflare agentsam-go-worker \
+      --official-release \
+      --account <iam-account-id> \
+      --yes
+
+Requirements:
+
+- maintainer/development source,
+- explicit InnerAnimalMedia release guard,
+- explicit InnerAnimalMedia Cloudflare account,
+- healthy live probes,
+- deployment/version identity,
+- only then remote agentsam_products and asset_relationships projection.
+
+The InnerAnimalMedia D1 adapter lives in official-registry.js specifically so generic self-host deployment does not import InnerAnimalMedia registration as a default side effect.
+
+## Dry run
+
+Dry run is:
+
+    agentsam go --cloudflare agentsam-go-worker \
+      --dry-run \
+      --account <cloudflare-account-id>
+
+It still performs Go build/probes, Linux container build/probes, Wrangler identity/account resolution, and Wrangler deploy --dry-run.
+
+It does not create a live deployment and does not mutate InnerAnimalMedia D1.
+
+Skip-deploy is a different explicit local-only mode and cannot be used as deployment proof.
+
+## Errors and recovery
+
+Go preserves native evidence when present, but public failures classify through AgentSam's canonical ErrorEnvelope.
+
+Recovery remains centralized in AgentSam. ErrorEnvelope feeds planRecovery / agentsam.recovery.v1 semantics used by other runtimes. Go does not own an independent retry brain.
+
+Unsafe writes with unknown side effects must reconcile before retry. Provider/model fallback follows shared semantic-compatibility rules.
+
+## Activity
+
+Native operations feed agentsam.activity.v1; Go does not create a separate event vocabulary.
+
+Near-term events include runtime.started, filesystem.read, filesystem.write, watcher.resync, merkle.updated, job.started, job.completed, and runtime.degraded. Studio Activity / Computational Hyperspace and the CLI in-flight TUI consume the same stream.
+
+## Graduation toward agentsamd
+
+The reusable native core should progressively own:
+
+    runtime/
+      workspace/
+      filesystem/
+      watch/
+      hash/
+      merkle/
+      jobs/
+      runtimeinfo/
+      health/
+
+Executables/adapters reuse that core:
+
+    cmd/server
+    cmd/agentsamd
+
+The same core can support Cloudflare Container, local daemon, and remote daemon execution. Deployment/auth/ownership adapters remain target-specific.
+
+## Conformance
+
+Where TypeScript and Go implement the same protocol, use the same fixtures.
+
+First conformance targets:
+
+- runtime response shape,
+- SHA-256 result,
+- ErrorEnvelope classification for invalid input,
+- path containment,
+- version conflict semantics.
+
+Then:
+
+- file-watch events,
+- Merkle roots/deltas,
+- workspace filesystem behavior,
+- cancellable job behavior.
+
+A language-specific reinterpretation of a canonical contract is a failure.
+
+## Next native capabilities
+
+After the deployed service seed remains boring and repeatable, graduate capabilities in this order:
+
+1. workspace filesystem behind workspace-fs.v1,
+2. native filesystem watcher,
+3. SHA/Merkle branch updates,
+4. runtime capability/health state,
+5. cancellable durable jobs,
+6. PTY coordination where it belongs.
+
+A* remains TypeScript-canonical until real workload measurements justify a native planner.
+
+See AGENTSAM_DISTRIBUTION_OWNERSHIP.md for package, credential, registry, and telemetry ownership boundaries.