@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/docs/architecture/AGENTSAM_RUNTIME_PROTOCOL.md

@@ -0,0 +1,151 @@
+# AgentSam Runtime Protocol
+
+> Branch: `feat/runtime-protocol-agentsamd`. Law: **agentsamd is the machine daemon; providers are adapters.**
+
+## Architectural law
+
+**agentsamd is the AgentSam machine/runtime daemon. Providers are adapters beneath it.**
+
+Physical D1 tables stay `terminal_*` for this generation. Domain nouns in code are `RuntimeInstance`, `RuntimeConnection`, `RuntimeAdapter`, `RuntimeCapabilities`.
+
+| Noun | Role |
+|---|---|
+| **agentsamd** | Lives with execution: exec, PTY, fs, processes, git, tools, capabilities, attach |
+| **Native helper** (this sprint) | Privileged companion under unprivileged Go: keychain, mounts, devices |
+| **EXECOS Worker** (`env.EXECOS` / `EXECOS_IAM`) | Interim cloud→machine hop + session/job writes. Becomes `runtime_adapter=execos_legacy`, then retires |
+| **PTY_SERVICE** | VPC/PTY health lane — not the daemon |
+| **agentsam-go-worker** | Optional hosted Go service (same Go core). **Not** the Studio control plane |
+| **Local Studio Worker** | Stock app host: auth, D1 SSOT, bindings, runtime APIs |
+
+### Four permanent concepts (never conflate)
+
+```text
+INSTANCE   what computer/execution environment is this?
+ADAPTER    what speaks agentsam.runtime.v1 there?
+TRANSPORT  how do we reach that adapter?
+AUTH       how is this connection authenticated?
+```
+
+Examples:
+
+| | Mac | GCP VM | CF Sandbox |
+|---|---|---|---|
+| provider | local | google_cloud | cloudflare |
+| substrate | host | vm | sandbox |
+| lifecycle | persistent | persistent | ephemeral |
+| provider_product | (host) | compute_engine | sandbox |
+| protocol | agentsam.runtime.v1 | same | same |
+| runtime_adapter | agentsamd | agentsamd | cloudflare_sandbox |
+| transport | cloudflare_tunnel / direct_https | cloudflare_tunnel / vpc_service | service_binding |
+| auth_mode | connection_token | connection_token / platform_bridge | service_binding |
+
+**Forbidden:** `transport IN ('execos','container')` — those were adapter/substrate smuggled into transport.
+
+---
+
+## Runtime Registry (D1 spine — preserve)
+
+```text
+ACCOUNT
+│
+├── agentsam_api_credentials     AAK / BRK
+├── cloud_provider_connections   optional provisioning authority (widen providers)
+│
+└── terminal_instances           WHAT EXISTS
+       ├── provider, substrate, provider_product, lifecycle
+       ├── platform / arch / capabilities_json
+       ▼
+    terminal_connections         HOW AGENTSAM TALKS TO IT
+       ├── protocol = agentsam.runtime.v1
+       ├── runtime_adapter = agentsamd | execos_legacy | …
+       ├── transport = direct_https | cloudflare_tunnel | vpc_service | …
+       ├── auth_mode
+       ├── terminal_connection_credentials
+       ├── terminal_enrollment_tokens
+       ├── terminal_sessions          interactive PTY
+       ├── terminal_jobs              noninteractive (runtime_run_id)
+       └── terminal_port_forwards
+```
+
+**Do not** introduce parallel `runtime_instances` / `runtime_connections` tables this generation.
+
+### Authority ladder (keep)
+
+```text
+AAK / BRK  →  enrollment token  →  connection credential  →  session attach token
+```
+
+### Rebuild now (bounded)
+
+1. **`terminal_instances`** — drop `kind`↔provider CHECK; drop `compute_provider`; add substrate / provider_product / lifecycle / hw_model; normalize arch `x64`→`x86_64`.
+2. **`terminal_connections`** — replace transport=`execos|container` with `protocol` + `runtime_adapter` + real `transport`; fold `transport_provider` into `transport`; add `endpoint_ref`; stop growing provider-specific columns (keep queried CF indexes for now, prefer `provider_metadata_json`).
+3. **`terminal_jobs`** — `execos_run_id` → `runtime_run_id` (all live values null).
+4. **`cloud_provider_connections`** — widen `provider`; remove policy CHECK forcing GCP `provider_connection_id`.
+
+### Do not rebuild unless needed
+
+`terminal_connection_credentials`, `terminal_enrollment_tokens`, `terminal_sessions` (optionally rename `auth_token_hash`→`attach_token_hash` while empty), `terminal_port_forwards`, `agentsam_api_credentials`.
+
+---
+
+## Installation grades (this sprint)
+
+| Grade | What |
+|---|---|
+| **Full daemon** | Go `agentsamd` + enroll + LaunchAgent/systemd |
+| **Native helper** | Rust/Zig privileged helper with daemon |
+| **Provider adapter** | CF Sandbox etc. (`runtime_adapter=cloudflare_sandbox`) |
+
+```bash
+agentsam setup runtime
+# plan → create instance → create connection → mint enrollment → agentsamd enroll
+```
+
+---
+
+## Protocol surface
+
+```text
+identity / capabilities / health
+exec / spawn / signal / terminate
+pty.create|attach|resize|detach
+fs.read|write|list|watch
+ports.list|expose
+system.inspect
+```
+
+---
+
+## Migration priority
+
+1. Freeze vocabulary (this doc + `packages/runtime-protocol`)
+2. Rebuild `terminal_instances` (local_device→host)
+3. Rebuild `terminal_connections` (execos→`runtime_adapter=execos_legacy`)
+4. New enrollments default `runtime_adapter=agentsamd`, `protocol=agentsam.runtime.v1`
+5. `execos_run_id` → `runtime_run_id`
+6. Widen `cloud_provider_connections`
+7. Heartbeat fills `capabilities_json`, `provider_product`, lifecycle facts
+8. `agentsam setup runtime` writes these records from GOAP plans
+9. After agentsamd proven: migrate live ExecOS rows `execos_legacy` → `agentsamd`
+10. Keep ExecOS as adapter during cutover — never as the architecture
+
+---
+
+## Rejected
+
+- Parallel `runtime_*` physical tables beside `terminal_*` this generation
+- `transport = execos` or `container`
+- kind↔provider coupling (VM=Google only, etc.)
+- Soft dual-write forever
+- Casting agentsam-go-worker as the EXECOS/control plane
+- Stock dependence on `load-agent-env.sh`
+
+---
+
+## Success criteria
+
+- User123: Studio → `setup runtime` → enrolled agentsamd (+ native helper on host) → attach
+- Same protocol on Mac / GCP VM / Docker / CF Container; Sandbox via adapter
+- Transport changes without renaming the instance
+- D1 spine stays `terminal_*`; vocabulary is four-axis + adapter + transport
+- ExecOS is `execos_legacy` until retired; agentsamd is the computer

package/docs/architecture/LOCAL_STUDIO_CLOUDFLARE_OAUTH.md

@@ -14,12 +14,20 @@
 Browser GET on connections **start** → 302 to Cloudflare.  
 `fetch` + `Accept: application/json` → `{ authorize_url }`.
 
-## D1
+## D1 tables (Cloudflare connect / approve)
 
-- `identity_oauth_states` — identity PKCE (migration `0013_identity_oauth_states.sql`)
-- `agentsam_cloudflare_oauth_state` — MCP connector PKCE
+| Table | Role |
+|---|---|
+| `oauth_state_nonces` | Short-lived PKCE state for connector `/api/connections/cloudflare/*` |
+| `identity_oauth_states` | Short-lived PKCE for identity “Sign in with Cloudflare” |
+| `user_oauth_tokens` | **SSOT** durable grant: sealed access/refresh, scopes, `account_identifier` (= CF account id), `is_active` |
+| `agentsam_cloudflare_connections` | **Legacy** — migrated/superseded into `user_oauth_tokens`; do not write new rows |
+| `agentsam_cloudflare_oauth_state` | Legacy MCP connector PKCE (prefer `oauth_state_nonces`) |
+
+Vault seals token material; D1 never stores raw refresh/access plaintext in the durable grant row when vault is configured.
+
+Resource discovery (their D1/R2/Workers) uses the sealed token from `user_oauth_tokens` — never the platform `env.DB` binding.
 
-## IAM AS redirect (required)
 
 Register on client `iam_agentsam_sdk_web`:
 

package/docs/architecture/R2_SLUG_NAMESPACE.md

@@ -0,0 +1,20 @@
+# AgentSam R2 layout — slug-keyed customer namespaces (not account_id)
+#
+# Path identity = brand.slug (UNIQUE in D1). account_id lives inside manifest.json
+# as ownership data for auth checks — never as a directory segment.
+#
+# {slug}/
+#   brand/identity.json
+#   brand/assets/{asset_key}/{version}/   ← brand_asset / brand_asset_variant
+#   site/public/…  site/draft/…
+#   frontend/dist/
+#   backend/
+#   manifest.json                         ← account_id, oauth defaults, included_apps
+#
+# Platform chrome (not a customer):
+#   _platform/shared/…
+#
+# Product surface for non-git customers:
+#   agentsam scaffold new <slug>
+#     → provisions R2 prefix + Worker + D1 rows from an npm-packaged app scaffold
+#     → customers never see the monorepo

package/docs/architecture/WORK_PRODUCT_EXTRACTION.md

@@ -0,0 +1,97 @@
+# AgentSam Work product extraction
+
+## Product boundary
+
+AgentSam Work is a **private monorepo workspace package**, not a separately
+published product package. It is reusable UI/runtime contract code consumed by
+Local Studio and can later be composed into other AgentSam apps.
+
+```
+packages/agentsam-work
+  contracts       normalized Work view/runtime models
+  frontend        shell, mini navigation, right rail, surfaces
+  client          transport adapter
+  fixtures        production-shaped localhost data
+
+apps/local-studio
+  frontend        route composition + LocalStudio WorkHost
+  backend/server/work
+                  authenticated provider/storage adapters
+```
+
+The package is intentionally parallel to `@inneranimalmedia/agentsam-settings`:
+presentation/contracts are reusable; Local Studio remains the first host and
+owns backend authority.
+
+## Donor material
+
+The current InnerAnimalMedia dashboard remains a donor, not a dependency.
+
+The extraction studied:
+
+- `CollaborateWorkShell.tsx`
+- `CollaboratePageRail.tsx`
+- `collaborateRailNav.ts`
+- `shellNav.ts`
+- `LaunchDeskPage.tsx`
+- `CollaborateTasksPanel.tsx`
+- `MailPage.tsx`
+- `api/tickets.ts`
+- `api/projects.ts`
+- calendar/mail/Gmail OAuth backend modules
+
+The useful product grammar is retained:
+
+- one Work mini navigation family;
+- optional narrow right utility rail;
+- Calendar/Tickets/Mail as one Work workbench;
+- ticket `surface` separates engineering/platform tickets from Collaborate
+  tickets without duplicating the ticket runtime;
+- Artifacts and Projects share the same Work chrome;
+- Projects keep their card-grid information architecture;
+- project detail keeps its main AgentSam composer plus the quick-stats and
+  project-context rail.
+
+Dashboard-specific route prefixes, workspace navigation infrastructure, and
+host-specific CSS are not imported into the package.
+
+## Flat route contract
+
+```
+/collaborate
+/collaborate?seg=tickets
+/mail
+/artifacts
+/artifacts/tickets
+/artifacts/tickets/:ticketId
+/projects
+/projects/:projectId
+```
+
+`seg=tasks` may remain a compatibility alias at a host boundary, but reusable
+links emit `seg=tickets`.
+
+## Theme contract
+
+The default theme intentionally follows the simple Google Workspace/Cloud
+visual grammar visible in the donor Work pages: bright canvas, subtle blue
+selection, compact rows, restrained borders, little shadow, and rounded
+controls.
+
+It is not hard-coded as brand authority. Work surfaces consume semantic
+`--agentsam-work-*` CSS variables. `applyWorkThemeTokens()` lets Local
+Studio project a Settings → Themes selection into the Work package without
+making Work import Settings.
+
+## Backend extraction order
+
+1. Keep all routes on the production-shaped fixture host until the UI shell is
+   approved.
+2. Implement read-only Local Studio adapters for projects, artifacts, tickets,
+   calendar, and mail.
+3. Switch Local Studio from `createFixtureWorkHost` to the HTTP host.
+4. Add mutations (ticket CRUD, calendar CRUD, mail actions/compose) behind the
+   same adapters.
+5. Normalize Gmail OAuth return paths to flat `/mail`.
+6. Only then evaluate database migrations; do not reshape live D1 just to
+   satisfy the frontend scaffold.

package/docs/brand/AGENT_SAM_ICON_GRAMMAR.md

@@ -0,0 +1,70 @@
+# AgentSam icon & motion grammar
+
+Family system for product marks and UI glyphs. Static identity stays quiet and architectural; runtime motion (Computational Hyperspace) is spectral and dimensional — not the icon itself.
+
+## Brand hierarchy
+
+```text
+AgentSam                         master brand
+├── Local Studio                 product identity
+├── CAD Creator                  product identity
+├── Ecommerce                    product identity
+├── CLI                          surface identity
+└── future apps
+```
+
+Related without sharing the exact same icon. One recognizable **master silhouette** (abstract SAM core / aperture / dimensional mark — readable at 16–24 px). Each product adds a single cue:
+
+| Product | Cue on master geometry |
+|---|---|
+| Local Studio | workspace / portal |
+| CAD Creator | dimensional plane / cube |
+| Ecommerce | modular product-card |
+
+## Icon grammar
+
+| Attribute | Rule |
+|---|---|
+| Base | graphite / near-black dimensional surface |
+| Accent | spectral blue → violet; amber only for special active states |
+| Geometry | rounded, slightly architectural |
+| Detail | one dominant shape, max 2–3 secondary forms |
+| Text | never in the app icon |
+| Lighting | restrained edge/highlight — not glossy clip-art |
+| Small sizes | simplify rather than shrink detail |
+| Status icons | separate semantic system from product logos |
+| Motion | slow depth/parallax; no bouncing/spinning clutter |
+
+## Asset drop paths (desktop shell)
+
+| Asset | Path |
+|---|---|
+| App / Dock / tray PNG (prefer **1024×1024**) | `packages/agentsam-desktop-shell/icons/<app_id>/icon.png` |
+| Vector mark | `packages/agentsam-desktop-shell/icons/<app_id>/*.svg` |
+| Manifest | `packages/agentsam-desktop-shell/manifests/<app_id>.json` → `icon_set`, `icon_mark_svg` |
+
+Build: `cd packages/agentsam-desktop-shell && npm run build:brand -- local-studio`  
+Optional: `AGENTSAM_ICON_URL=https://…/logo.png` overrides local files.
+
+`build-brand.mjs` must honor `icon_mark_svg` when `icon.png` is missing (rasterize → `src-tauri/icons/`).
+
+## UI glyphs (not product logos)
+
+One semantic layer — design system picks the glyph family:
+
+```jsx
+<Icon name="workspace" />
+<Icon name="terminal" />
+<Icon name="activity" />
+<Icon name="repository" />
+<Icon name="warning" />
+```
+
+Do not mix Heroicons / Lucide / random SVGs / macOS symbols as the AgentSam brand identity. Platform-native symbols OK only for OS chrome.
+
+## Identity vs motion
+
+- **Static identity:** quiet / recognizable / architectural  
+- **Runtime motion:** spectral / dimensional / computational (Hyperspace)
+
+See also: `docs/plans/LOCAL-STUDIO-GRADUATION-2026-09-26.md`.

package/docs/content-studio/HOST_MOUNT_CHECKLIST.md

@@ -0,0 +1,71 @@
+# Host mount checklist — Content Studio (Path A / Commit 6)
+
+Portable packages are ready for host adapters. Full OAuth / production mounts
+are Path B / host-app work — do **not** fork packages per host.
+
+## Shared mount contract
+
+Each host supplies a `ContentRuntime` via `createContentRuntime({...})`:
+
+| Seam | Local Studio | IAM dashboard | Fuel & Free Time (customer) |
+|---|---|---|---|
+| `account` / `actor` | desktop session | IAM auth session | customer tenant session |
+| `providers` / capability adapters | local + optional CF | R2 / Images / Drive / Stream | customer-scoped providers |
+| `brandResolver` | project BrandPack projection | org BrandPack projection | customer BrandPack projection |
+| `knowledge` | local / injected | host Vectorize/AutoRAG/pgvector | customer knowledge adapter |
+| `localHost` | Tauri / agentsamd bridge | usually `unavailable` | usually `unavailable` |
+| `routes` / `permissions` | desktop RouteMap | IAM RouteMap | customer RouteMap |
+| UI | `<ContentStudio runtime={rt} />` | same | same |
+
+## Do
+
+1. Build runtime in the **host** app (not inside `agentsam-content-studio`).
+2. Derive UI tabs/actions from `await runtime.capabilities()`.
+3. Keep BrandPack authority in `agentsam-brand` / `brand.pack.json`.
+4. Use `inferBrandAssociation` only as proposals + ScoreCard evidence.
+5. Use `@inneranimalmedia/agentsam-cloudflare-images` for CF Images HTTP.
+
+## Don't
+
+- Import Tauri / raw `fs` / agentsamd into reusable UI packages.
+- Hardcode R2 / Images / Drive / Vectorize tabs in Content Studio.
+- Embed real customer BrandPack fixtures in generic packages.
+- Seed fictional `DEMO_BRAND_PROJECTIONS` into production `/content` runtimes.
+- Run IAM `deploy:full` from this SDK repo for content-studio work.
+
+## Local Studio mount (wired)
+
+- Route: `/content` → `ContentStudioPage` mounts `<ContentStudio runtime={…} />`
+- Runtime factory: `apps/local-studio/frontend/src/lib/content/createLocalStudioContentRuntime.ts`
+- **Identity:** resolved from `useCurrentUserState()` / Auth session — fail closed when missing.
+  No `acct_local_studio` / `local-studio-user` production defaults.
+- **Brand:** empty `ContentBrandResolver` projections until host injects BrandPack (Path B).
+  Fictional demos live only in `demoBrandProjections.ts` (tests/examples).
+- **LocalContentHost (desktop):** native Rust Tauri `local_content_bridge` —
+  `rfd` pickers, opaque `localref_*` / `localdir_*`, granted roots, browse in place,
+  copy only on `import_to_library`. **Does not require** monorepo Node or global Node.
+- **LocalContentHost (browser/dev):** File System Access API when available; else
+  explicit browser-import (`import_bytes`, 32 MiB) via Node `/api/content/local/bridge`.
+- Knowledge / BrandSimilarity: noop adapters (no Vectorize hardcode)
+- agentsamd: probed via Tauri `ensure_agentsamd` / health; FS ops are native Rust until
+  agentsamd ships native `/v1/fs` (documented migration target)
+
+## Packaged-app contract
+
+| Requirement | Status |
+|---|---|
+| Works from `/Applications` without repo checkout | Native Rust FS — yes |
+| No global Node for content FS | Desktop native — yes; Node bridge is browser/dev only |
+| Native Open File / Open Folder | `rfd` via `pick_files` / `pick_directory` |
+| Selected file not copied until import | Yes — `import_to_library` is separate |
+| Opaque refs only to UI/models | Yes — absolute paths stay in Rust/grant store |
+
+## Remaining for true 3-host E2E (Path B)
+
+- agentsamd native `/v1/fs` + watch (migration from native Rust bridge)
+- IAM dashboard route + OAuth-scoped providers
+- F&F admin mount with customer account scope
+- Production BrandPack projection into Local Studio `brandResolver`
+- Harvest Go pipeline → SiteGraph / TokenGraph → package-readiness ScoreCards
+- Brand package migration onto shared CF Images transport (content already uses it)
+- Beta / outcome calibration receipts for accept/reject (does not mutate evidence)