@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/docs/product/AGENTSAM_PRODUCT_EXPERIENCE_STANDARD.md

@@ -0,0 +1,280 @@
+# AgentSam Product Experience Standard
+
+**Status:** Internal product law  
+**Applies to:** AgentSam SDK · Local Studio · packaged AgentSam apps · runtime surfaces · developer tooling  
+**Product:** `@inneranimalmedia/agentsam-sdk`  
+**Machinery:** SAM — **Systematic Autonomous Machinery**
+
+> **Complex underneath. Effortless above.**
+
+## Product posture
+
+AgentSam is a professional software platform, not a prototype dashboard, chatbot wrapper, or collection of demos. The UI communicates maturity through **clarity, speed, consistency, depth, and restraint**.
+
+A user should feel that the system is capable without being forced to look at all of the machinery that makes it capable.
+
+## Progressive discovery
+
+> **Reveal a capability when context makes it useful; do not advertise the entire machinery permanently.**
+
+This applies to terminals, runtimes, languages, forwarding, LSP, databases, cloud providers, CMS, CAD, machine inspection, identity, install/setup, and AgentSam itself.
+
+If only one healthy runtime exists, do not show a runtime picker. If a repository requires Go, surface Go when the user runs or inspects that repository. Context creates discovery.
+
+## Local Studio is a real desktop work application
+
+Local Studio is not a PWA pretending to be desktop software, a hosted website hidden behind a native wrapper, a bootstrap/status page users must escape before doing work, or a chatbot with tools bolted on.
+
+Expected launch path:
+
+```text
+Launch AgentSam Local Studio.app
+        ↓
+bundled Local Studio application
+        ↓
+restore last workspace/session
+        ↓
+local runtime becomes available quietly
+        ↓
+account/cloud/provider state hydrates without blocking local work
+```
+
+The shipped `.app` must boot directly into the real application interface. A thin **Open Studio UI / Stay on this shell** runtime-status page is a development or recovery fallback, not a shippable default.
+
+## Local-first contract
+
+Local functionality remains useful without authentication or network availability: files, local projects, SQLite, PTY/terminal, agentsamd, repository inspection, local language tooling, and installed local CAD/modeling integrations.
+
+Authentication enhances the product. It does not gate the user's computer.
+
+## Visual identity
+
+The default visual language is **quiet, dark, precise, desktop-native, and content-first**.
+
+Prefer near-black neutral work surfaces, restrained borders, compact chrome, crisp typography, careful spacing, small precise active states, limited iconography, contextual panels that disappear when closed, and motion that communicates state changes.
+
+Avoid particle effects as ordinary product chrome, glowing dashboard cards, pulsing status indicators, decorative telemetry, giant capability dashboards, nested cards without purpose, permanent status rails, and "AI is thinking" theater.
+
+Motion should be experienced as smoothness, not watched as entertainment.
+
+## Canonical layout modes
+
+### Focused work
+
+```text
+project/history rail | main work/chat | contextual editor/browser/details
+```
+
+### Code / file work
+
+```text
+project/history rail | editor/work surface | file tree/workspace/context
+```
+
+### Full workbench
+
+```text
+minimal nav | primary surface | optional contextual secondary pane
+```
+
+The active task owns the screen. Secondary panes support it.
+
+A user should move naturally among recent work, projects, Git worktrees, local folders, attached runtimes, containers, and future remote workspaces without needing to understand the transport underneath.
+
+## The work surface defines the experience
+
+Browsing should feel like a browser; coding like an editor; data work like a database editor; CMS work like a CMS; CAD work like CAD; terminal work like a terminal.
+
+AgentSam intelligence is contextual infrastructure, not permanent visual chrome.
+
+> Every capability should feel native to the surface where it is used.
+
+## Tabs, split panes, browser, and annotation
+
+Tabs are first-class desktop primitives. State should preserve and restore per workspace, split panes should feel like one application, and contextual panels should disappear completely when closed.
+
+The in-app browser is a serious work primitive, not an iframe preview.
+
+Annotation is a signature AgentSam interaction. A user should be able to select a real DOM element, code range, file, database object, CMS section, CAD object, browser region, artifact, runtime, or job and open a minimal contextual composer against that structured selection.
+
+AgentSam should know **what was selected**, not merely where the user clicked.
+
+## Terminal and runtime model
+
+Do not create separate terminal architectures for each language.
+
+```text
+terminal_instance   → where compute lives
+terminal_connection → how AgentSam reaches it
+terminal_session    → interactive PTY
+terminal_job        → detached/background work
+```
+
+Capabilities hang off the target:
+
+```text
+pty
+exec
+filesystem
+ports
+forwarding
+jobs
+lsp
+docker
+node
+python
+go
+rust
+freecad
+openscad
+blender
+```
+
+"Go service", "Rust task", "Python worker", and "Node dev server" are process profiles, not new PTY technologies.
+
+Forwarding should be first-class but mostly invisible. If a process exposes a port, Local Studio can offer **Open preview** and resolve forwarding underneath.
+
+## Databases
+
+AgentSam's own `.agentsam/data/agentsam.sqlite` is application state, not a claim that Local Studio supports only one SQLite database.
+
+User-owned SQLite is first-class: create/open arbitrary databases, attach/detach, CRUD, scoped SQL, duplicate/backup, rename/delete with confirmation, and offline operation.
+
+## Identity and storage authority
+
+Local Studio ships the AgentSam identity **UI and client contract** inside the app. The official connected AgentSam distribution does not create a second canonical account database on the device.
+
+```text
+packaged AgentSam auth UI
+        ↓
+identity_bridge
+        ↓
+configured identity service / Worker
+        ↓
+main account database
+```
+
+The installed app receives a native bearer session from the same identity service and keeps that credential in the platform secure store. The main database remains authoritative for account, user, session, grant, billing, membership, provider-connection, and other shared/cloud state.
+
+Device-local SQLite has a different authority:
+
+```text
+main DB        = account/shared/cloud truth
+local SQLite   = device/workspace/cache/offline-outbox/runtime truth
+secure store   = secret/credential truth
+```
+
+Do not dual-write canonical server records into SQLite. A local cached server record must be explicitly cache/sync state and disposable. Offline mutations to server-owned resources use an idempotent outbox and are committed through the Worker when connectivity returns.
+
+The portable identity package still supports an explicit standalone SQLite identity adapter for independent/offline products. That is a deployment choice, not the default authority of the official connected AgentSam download.
+
+Platform secure storage is a contract, not a macOS assumption: macOS uses Keychain; Windows uses Credential Manager; Linux uses the platform secret service; iOS and Android use their native secure-storage adapters.
+
+## External desktop escape hatches
+
+Useful actions include Open in Cursor, default app, Terminal, iTerm2, Reveal in Finder, Open on GitHub, and Save as.
+
+These are convenience paths. They do not replace Local Studio's own editor, PTY, browser, files, database, or runtime system.
+
+## Donor extraction and dependency direction
+
+InnerAnimalMedia is a donor and proving ground. It is not a runtime dependency of Local Studio.
+
+```text
+                  agentsam-sdk
+                      │
+          reusable packages/contracts
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+   Local Studio  InnerAnimalMedia  customer apps
+```
+
+Never make Local Studio import portable runtime/UI truth from the InnerAnimalMedia repository.
+
+Salvage proven UI, adapters, contracts, browser/editor/file behaviors, OAuth work, CMS mechanics, runtime patterns, and interaction components; remove InnerAnimalMedia-specific tenancy, branding, URLs, customer IDs, bindings, and deployment policy; land reusable ownership once in AgentSam SDK; let InnerAnimalMedia consume it through explicit adapters.
+
+Portability test:
+
+> Could a developer clone only `agentsam-sdk`, build/install Local Studio, and get the core experience without an `inneranimalmedia` checkout?
+
+For portable functionality, the answer must be yes.
+
+## Authority and registry discipline
+
+Do not flatten product, app, package, service, feature, capability, operation, tool, runtime, and install state into one registry.
+
+Preserve:
+
+```text
+APP
+apps/*/agentsam.app.json
+
+PACKAGE / SERVICE
+agentsam.package.json / package metadata
+
+FEATURE
+agentsam.feature.json
+
+CAPABILITY
+protocol/capabilities/manifest.json
+
+OPERATION
+protocol/sam/* + defineSamOperation()
+
+TOOL
+platform / MCP bounded registry
+
+RUNTIME
+agentsam.runtime.v1 + terminal_* state
+
+INSTALL
+.agentsam state + receipts
+```
+
+The official platform product inventory remains `agentsam_products` and its platform relationships.
+
+Any source-controlled `registry/products/*` layer is a **thin relationship/index seed**: product IDs, authority paths, host/mount relationships, service relationships, and platform linkage. It must not copy versions, commands, capability lists, runtime facts, or other fields already owned elsewhere.
+
+## Product quality bar
+
+Local Studio should feel deliberate, quiet, responsive, high-confidence, contextual, predictable, and deeply capable.
+
+Never gimmicky, demo-first, fake, capability-theater, or overloaded with status chrome.
+
+Infrastructure earns its value by making visible work reliable.
+
+## Acceptance rules
+
+1. **Real over fake** — no fake green states or pretend integrations.
+2. **Context over dashboards** — surface capabilities where they matter.
+3. **Local-first** — local work does not wait on account/cloud availability.
+4. **Progressive discovery** — advanced controls appear when useful.
+5. **One coherent product** — browser, files, editor, terminal, database, CMS, CAD, Work, and AgentSam share interaction language.
+6. **No permanent noise** — closed panels disappear.
+7. **Native platform behavior** — tabs/splits where appropriate, native file dialogs, OS secure storage, external-open actions, and platform-appropriate local capabilities.
+8. **Capability truth** — UI affordances derive from real runtime/provider capability.
+9. **Smoothness is functional** — animation reduces friction.
+10. **AgentSam remains contextual** — intelligence supports the work instead of competing with it.
+
+## Design test
+
+Before adding a permanent control, panel, badge, dashboard, runtime selector, or status surface, ask:
+
+```text
+Does the user need this visible right now?
+Can context reveal it later?
+Can the system infer this safely?
+Is it useful to the task, or merely proof that our backend exists?
+Would a mature professional application expose this continuously?
+```
+
+If the answer points toward hiding it, hide it.
+
+## North star
+
+> **A serious desktop work environment where browser, files, code, terminal, data, CMS, CAD, runtimes, cloud resources, and AgentSam intelligence behave as if they were designed together from the beginning.**
+
+AgentSam makes complex infrastructure feel simple without pretending the infrastructure is simple.
+
+That is the brand.

package/docs/product/LOCAL_STUDIO_DESKTOP_EXPERIENCE.md

@@ -0,0 +1,139 @@
+# Local Studio Desktop Experience Contract
+
+**Status:** Product acceptance contract  
+**App:** `local-studio`  
+**Desktop shell:** `packages/agentsam-desktop-shell`  
+**Canonical UI:** `apps/local-studio`
+**Identity package:** `packages/identity`
+
+The downloadable Local Studio app must look like Local Studio because it **is** Local Studio.
+
+## Launch contract
+
+Production:
+
+```text
+AgentSam Local Studio.app
+        ↓
+Tauri window
+        ↓
+bundled apps/local-studio desktop SPA
+        ↓
+real AgentSam shell / workspace
+```
+
+Not acceptable as a shipped default:
+
+```text
+bootstrap/status shell
+→ "Open Studio UI"
+→ hosted website
+```
+
+The packager must fail closed if the real desktop SPA is missing. It must never silently substitute a recovery page into a release artifact.
+
+Native capability startup (`agentsamd`, filesystem bridges, database bridges) happens in the background and must not cover the work surface with a diagnostic boot screen.
+
+## Packaged identity UI, shared account authority
+
+Local Studio packages the real AgentSam login/signup/reset UI inside the application. Displaying that UI does not require redirecting to a website.
+
+For the official connected AgentSam distribution, authentication writes to the configured identity service and main database:
+
+```text
+Local Studio / future mobile app
+        ↓
+bundled auth portal
+        ↓
+identity_bridge
+        ↓
+Worker identity API
+        ↓
+main account database
+```
+
+The Worker creates/resolves the canonical user and `auth_sessions` row. Native clients request the same session as a bearer credential rather than relying on a browser cookie. The credential is stored in the platform secure store and `/api/auth/me` validates it against the main database.
+
+There is no desktop-only account table and no duplicate canonical user/session authority.
+
+## Three storage authorities
+
+```text
+MAIN SERVICE / DB
+  accounts, users, auth sessions, OAuth grants, provider connections,
+  billing, memberships, shared/project/cloud records
+
+LOCAL SQLITE
+  installation/device metadata, workspace state, local projects, caches,
+  runtime/job state, sync cursors, offline outbox, user-opened SQLite DBs
+
+OS SECURE STORE
+  account session credential, device credentials, encryption keys,
+  machine-private provider secrets where policy allows
+```
+
+SQLite must not become a shadow copy of the main account database. Cached remote records are explicitly non-authoritative and disposable. Offline server-owned mutations are queued with idempotency keys and committed through the Worker.
+
+The portable identity package may use its SQLite identity adapter only when an installation explicitly selects standalone mode.
+
+## Platform contract
+
+The product contract is broader than macOS:
+
+- **macOS:** Tauri desktop, `agentsamd`, bundled JS bridge runtime, Keychain, POSIX shells.
+- **Windows:** Tauri desktop, `agentsamd`, bundled JS bridge runtime, Credential Manager, `pwsh` → Windows PowerShell → `cmd.exe`.
+- **Linux:** Tauri desktop, `agentsamd`, bundled JS bridge runtime, platform secret service, POSIX shells.
+- **iOS:** same UI/service/storage contracts through mobile-native adapters; no executable Node/`agentsamd` sidecar assumption.
+- **Android:** same UI/service/storage contracts through mobile-native adapters; no executable Node/`agentsamd` sidecar assumption.
+
+Desktop sidecars are an implementation of local-machine capabilities, not part of the cross-platform protocol. Mobile can connect to remote/local AgentSam runtimes where appropriate while keeping account identity and device state contracts unchanged.
+
+## Provider OAuth
+
+Provider grants are separate from the AgentSam account session. Google, Cloudflare, GitHub, GCP, and later providers use their own consent/connection lanes. A system browser may be required for a provider's OAuth consent, but the AgentSam login UI itself remains packaged in the app.
+
+Provider tokens never belong in callback URLs beyond the minimum standard authorization material, and confidential client secrets never belong in downloadable clients.
+
+## Session restoration
+
+```text
+secure store has AgentSam session credential?
+  no  → signed-out cloud/account state; local work remains available
+  yes → /api/auth/me with Bearer credential
+           valid   → canonical account restored from main DB
+           invalid → clear stale credential / signed out
+```
+
+Browser cookies are not required for desktop/mobile session restoration.
+
+## Failure behavior
+
+If a provider, remote account service, or network connection fails, Local Studio remains usable locally.
+
+Ordinary local workflows must never be replaced by a full-screen authentication or infrastructure error.
+
+## Release acceptance
+
+Before shipping a desktop artifact:
+
+- build the Local Studio desktop SPA;
+- copy the packaged auth portal into that SPA;
+- verify the auth portal is AgentSam/host branded rather than donor branded;
+- sync the SPA into the Tauri desktop shell;
+- fail the build if the real SPA is missing or hydrate-only;
+- verify the old `Open Studio UI` / `Stay on this shell` copy is absent;
+- verify native startup work is non-blocking;
+- run the full identity package tests;
+- run Local Studio auth/type/build gates;
+- run Rust checks;
+- verify the packaged identity runtime/migrations are present;
+- build and mount the disk image;
+- launch the app copied from the disk image;
+- verify local signup/login/session restoration without a hosted redirect;
+- verify local files, SQLite, PTY, and `agentsamd` still work signed out.
+
+## Product rule
+
+> **The downloadable Local Studio app is self-contained AgentSam product software.**
+
+Company deployments, customer hosts, and external identity providers are adapters around that product. They are not its intrinsic authority.

package/docs/product/README.md

@@ -0,0 +1,8 @@
+# AgentSam Product Standards
+
+These documents define product-facing laws above implementation-specific architecture.
+
+- [AgentSam Product Experience Standard](./AGENTSAM_PRODUCT_EXPERIENCE_STANDARD.md) — brand posture, visual/interaction language, progressive discovery, Local Studio quality bar, runtime UX, donor extraction, and authority discipline.
+- [Local Studio Desktop Experience Contract](./LOCAL_STUDIO_DESKTOP_EXPERIENCE.md) — launch behavior, bundled UI, desktop OAuth/Keychain behavior, handoff security, and release acceptance.
+
+Architecture contracts remain authoritative for their own namespaces, including `docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md` and `docs/architecture/SAM_KERNEL.md`.

package/docs/rapid-rust-wasm.md

@@ -0,0 +1,35 @@
+# AgentSam Rapid Rust / Wasm
+
+`agentsam rust` and `agentsam-rapid-rust` provide one native Rust CLI for scaffolding and locally proving Cloudflare Rust/Wasm workers.
+
+## Templates
+
+- `api` — compact JSON/health Worker
+- `shared-core` — real Cargo workspace with pure `core/` crate + Cloudflare `worker/` adapter
+- `crypto-auth` — constant-time HMAC-SHA256 request verification
+- `data-processor` — typed JSON batch transform
+
+## Local-first
+
+```bash
+python3 scripts/build_rapid_rust_cli.py --bootstrap --build --install --smoke
+agentsam rust doctor
+agentsam rust new my-edge-api --template api --explain
+cd my-edge-api
+agentsam rust check
+agentsam rust build
+agentsam rust dev
+```
+
+`new`, `doctor`, `check`, and `build` do not deploy. Live deployment is intentionally separate:
+
+```bash
+agentsam rust deploy --dry-run
+agentsam rust deploy --yes
+```
+
+Rust Workers compile to `wasm32-unknown-unknown`; dependencies must be Wasm-compatible. Use a Cloudflare Container instead when the workload needs a normal Linux process model, threaded runtime, large native toolchain, or long-running heavy jobs.
+
+## Wasm strip rule
+
+Generated Workers use `strip = "debuginfo"`, not `strip = true`. Current wasm-bindgen catch-wrapper generation needs the externref table that full symbol stripping can remove.

package/migrations/d1/0010_portable_tickets_memory.sql

@@ -0,0 +1,140 @@
+-- 0010_portable_tickets_memory.sql
+-- Portable GOAP / ticket + memory spine for new AgentSam projects (local SQLite or D1).
+-- Account-owned tickets — NOT Inner Animal Media's shared platform DB.
+-- Every write path MUST populate account_id and repository_id (NULL = broken implementation).
+
+CREATE TABLE IF NOT EXISTS agentsam_tickets (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  status TEXT NOT NULL
+    CHECK (status IN ('backlog', 'active', 'blocked', 'in_review', 'shipped', 'abandoned')),
+  status_reason TEXT,
+  project TEXT,
+  subsystem TEXT,
+  tags TEXT,
+  priority TEXT,
+  doc_path TEXT,
+  blocks TEXT,
+  blocked_by TEXT,
+  supersedes TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  closed_at INTEGER,
+  dedup_key TEXT,
+  consecutive_pass_count INTEGER,
+  last_gate_run_id INTEGER,
+  last_gate_ok_at INTEGER,
+  required_pass_count INTEGER,
+  description TEXT,
+  client_id TEXT,
+  due_at INTEGER,
+  surface TEXT NOT NULL DEFAULT 'platform',
+  start_at INTEGER,
+  estimated_minutes INTEGER,
+  percent_complete INTEGER NOT NULL DEFAULT 0,
+  owner_kind TEXT NOT NULL DEFAULT 'unassigned',
+  owner_ref TEXT,
+  parent_ticket_id TEXT,
+  agent_run_id TEXT,
+  worktree TEXT,
+  linked_commit TEXT,
+  source TEXT NOT NULL DEFAULT 'manual',
+  account_id TEXT NOT NULL,
+  repository_id TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_tickets_account_repository
+  ON agentsam_tickets(account_id, repository_id, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_tickets_status
+  ON agentsam_tickets(account_id, status, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS agentsam_ticket_events (
+  id TEXT PRIMARY KEY,
+  ticket_id TEXT NOT NULL REFERENCES agentsam_tickets(id) ON DELETE CASCADE,
+  event_type TEXT NOT NULL,
+  from_status TEXT,
+  to_status TEXT,
+  detail TEXT,
+  commit_sha TEXT,
+  created_at INTEGER NOT NULL,
+  actor_type TEXT,
+  actor_id TEXT,
+  media_asset_id TEXT,
+  account_id TEXT NOT NULL,
+  repository_id TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_ticket_events_ticket
+  ON agentsam_ticket_events(ticket_id, created_at);
+
+CREATE TABLE IF NOT EXISTS agentsam_memory (
+  id TEXT PRIMARY KEY NOT NULL,
+  account_id TEXT NOT NULL,
+  repository_id TEXT NOT NULL,
+  project_id TEXT,
+  memory_key TEXT NOT NULL,
+  memory_type TEXT NOT NULL
+    CHECK (memory_type IN (
+      'fact', 'preference', 'decision', 'policy', 'state', 'procedure'
+    )),
+  title TEXT,
+  content TEXT NOT NULL,
+  summary TEXT,
+  importance INTEGER NOT NULL DEFAULT 5
+    CHECK (importance BETWEEN 1 AND 10),
+  tags TEXT NOT NULL DEFAULT '[]',
+  status TEXT NOT NULL DEFAULT 'active'
+    CHECK (status IN ('active', 'archived', 'deleted')),
+  is_pinned INTEGER NOT NULL DEFAULT 0,
+  content_hash TEXT NOT NULL,
+  source TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  revision INTEGER NOT NULL DEFAULT 1,
+  semantic_hash TEXT,
+  sensitivity TEXT NOT NULL DEFAULT 'normal'
+    CHECK (sensitivity IN ('normal','internal','confidential','secret')),
+  source_client TEXT,
+  source_ref TEXT,
+  supersedes_id TEXT,
+  expires_at INTEGER,
+  scope_type TEXT,
+  scope_id TEXT,
+  idempotency_key TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}'
+    CHECK (json_valid(metadata_json)),
+  UNIQUE(account_id, memory_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_memory_account_repo
+  ON agentsam_memory(account_id, repository_id, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS agentsam_memory_outbox (
+  id TEXT PRIMARY KEY NOT NULL,
+  memory_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  repository_id TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  semantic_hash TEXT NOT NULL,
+  operation TEXT NOT NULL DEFAULT 'upsert'
+    CHECK (operation IN ('upsert','deactivate','delete')),
+  projection_target TEXT NOT NULL DEFAULT 'node_api_pgvector'
+    CHECK (projection_target = 'node_api_pgvector'),
+  payload_json TEXT NOT NULL DEFAULT '{}'
+    CHECK (json_valid(payload_json)),
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending','processing','completed','failed')),
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER,
+  locked_at INTEGER,
+  last_error TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE(memory_id, revision, operation)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_memory_outbox_pending
+  ON agentsam_memory_outbox(status, next_attempt_at)
+  WHERE status IN ('pending','failed');