@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

package/docs/architecture/AGENTSAM_RUNTIME_PROTOCOL.md

@@ -1,10 +1,10 @@
 # AgentSam Runtime Protocol
 
-> Branch: `feat/runtime-protocol-agentsamd`. Law: **agentsamd is the machine daemon; providers are adapters.**
+> Standing law: **`agentsam.runtime.v1` is the portable execution contract. `agentsamd` and ExecOS are supported runtime implementations/adapters; neither is a transport.**
 
 ## Architectural law
 
-**agentsamd is the AgentSam machine/runtime daemon. Providers are adapters beneath it.**
+**`agentsam.runtime.v1` is the execution authority. `agentsamd` is the stock portable machine daemon for independent installs; ExecOS is a proven managed/platform runtime and dispatcher used by InnerAnimalMedia. Runtime implementations sit behind the same connection/protocol model, and transports stay separate from them.**
 
 Physical D1 tables stay `terminal_*` for this generation. Domain nouns in code are `RuntimeInstance`, `RuntimeConnection`, `RuntimeAdapter`, `RuntimeCapabilities`.
 
@@ -12,7 +12,7 @@ Physical D1 tables stay `terminal_*` for this generation. Domain nouns in code a
 |---|---|
 | **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 |
+| **ExecOS / EXECOS Worker** (`env.EXECOS` / `EXECOS_IAM`) | Supported managed/platform runtime + cloud→machine dispatch used by InnerAnimalMedia. Historical rows may use `runtime_adapter=execos_legacy`; that compatibility id does **not** imply a retirement decision. |
 | **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 |
@@ -35,12 +35,30 @@ Examples:
 | lifecycle | persistent | persistent | ephemeral |
 | provider_product | (host) | compute_engine | sandbox |
 | protocol | agentsam.runtime.v1 | same | same |
-| runtime_adapter | agentsamd | agentsamd | cloudflare_sandbox |
+| runtime_adapter | agentsamd or ExecOS | agentsamd or ExecOS | 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.
 
+### ExecOS support status
+
+ExecOS is **supported working machinery**, not presumed deprecated. Current InnerAnimalMedia production/runtime paths still use it for governed dispatch, enrolled-device execution, bridge authentication, terminal/session routing, and `user_hosted_tunnel` flows.
+
+`execos_legacy` exists because earlier rows encoded `execos` as a transport and needed a compatibility mapping into the newer four-axis model. The word `legacy` in that identifier is migration vocabulary; it is **not** authorization to delete, disable, or silently replace ExecOS.
+
+The portability goal is additive:
+
+```text
+agentsam.runtime.v1
+        ├── agentsamd              stock portable/local runtime
+        ├── ExecOS                 supported managed/platform runtime
+        ├── cloudflare_sandbox     sandbox adapter
+        └── future adapters
+```
+
+Where implementations overlap, converge on protocol semantics and acceptance tests. A future deprecation is a separate, evidence-backed product decision.
+
 ---
 
 ## Runtime Registry (D1 spine — preserve)
@@ -57,7 +75,7 @@ ACCOUNT
        ▼
     terminal_connections         HOW AGENTSAM TALKS TO IT
        ├── protocol = agentsam.runtime.v1
-       ├── runtime_adapter = agentsamd | execos_legacy | …
+       ├── runtime_adapter = agentsamd | execos_legacy (ExecOS compatibility id) | …
        ├── transport = direct_https | cloudflare_tunnel | vpc_service | …
        ├── auth_mode
        ├── terminal_connection_credentials
@@ -118,16 +136,16 @@ 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
+1. Freeze vocabulary (this doc + `packages/runtime-protocol`).
+2. Rebuild `terminal_instances` (local_device→host).
+3. Normalize historical `transport=execos` records into **adapter + real transport** fields. Existing `runtime_adapter=execos_legacy` is a compatibility identifier for ExecOS-backed connections, not a support/deprecation state.
+4. Stock independent/local installs may default to `runtime_adapter=agentsamd`; managed/platform installs may continue to use ExecOS. Both remain valid registered runtimes.
+5. `execos_run_id` → protocol-neutral `runtime_run_id` where that column still encodes implementation detail.
+6. Widen `cloud_provider_connections`.
+7. Heartbeats fill `capabilities_json`, `provider_product`, and lifecycle facts from the selected runtime.
+8. `agentsam setup runtime` writes records from GOAP plans without assuming one runtime implementation.
+9. Prove overlapping ExecOS / agentsamd operations against the same `agentsam.runtime.v1` semantics instead of removing one merely because the other exists.
+10. Any future narrowing or retirement of ExecOS requires an explicit product decision, inventory of production callers, proven replacement parity, migration plan, acceptance tests, and approval.
 
 ---
 
@@ -144,8 +162,10 @@ system.inspect
 
 ## 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
+- User123 can install Studio → `setup runtime` → enroll the stock `agentsamd` runtime (+ native helper where needed) → attach without InnerAnimalMedia infrastructure.
+- Existing InnerAnimalMedia ExecOS connections remain supported and functional while sharing protocol-neutral registry/session concepts.
+- Same protocol semantics can be implemented across Mac / GCP VM / Docker / CF Container; Sandbox remains an adapter.
+- Transport can change without renaming the instance or changing runtime/session semantics.
+- D1 spine stays `terminal_*`; vocabulary remains instance + adapter + transport + auth.
+- The historical string `execos_legacy` is treated as compatibility vocabulary only. **Do not infer support lifecycle from the identifier.**
+- Duplication between ExecOS and agentsamd is resolved by shared contracts/tests and explicit routing, not by deleting proven machinery without parity.

package/docs/content-studio/REVISION_GATE_2026-09-27.md

@@ -24,7 +24,7 @@ or a hardcoded provider — it is not finished.
    `protocol/assets/`) owns canonical asset identity (`ast_*`), machine facts,
    provenance and provider **representations**.
 
-3. **BrandPack** (`brand.pack.json` / `@inneranimalmedia/agentsam-sdk-brand`)
+3. **BrandPack** (`brand.pack.json` / `@inneranimalmedia/agentsam-brand`)
    owns the canonical brand system **AND brand-scoped assets**: logos, icons,
    fonts, imagery, video, models, themes, styles, tokens, motion, semantic
    roles and brand delivery rules. BrandPack does **not** own physical storage

package/docs/plans/LOCAL_STUDIO_DESKTOP_RELEASE_2026-09-29.md

@@ -0,0 +1,150 @@
+# Local Studio desktop release graduation — 2.6.6
+
+**Owner lane:** installed/downloadable Local Studio only
+**Branch:** `feat/local-studio-desktop-release-20260929`
+**Canonical UI:** `apps/local-studio`
+**Native shell:** `packages/agentsam-desktop-shell`
+**Do not absorb:** Agent 1's hosted Worker/CMS finishing work
+
+## Current verified baseline
+
+- The installed `/Applications/AgentSam Local Studio.app` is stale `2.6.5`.
+- `apps/local-studio` is already `2.6.6` and builds a real bundled desktop SPA.
+- `npm --prefix apps/local-studio run verify:desktop` passes.
+- `cargo check --manifest-path packages/agentsam-desktop-shell/src-tauri/Cargo.toml` passes.
+- The packaged `2.6.6` Tauri app launches and exposes the real Local Studio UI: navigation, Chat/Work, composer, model picker, and Send.
+- The current `2.6.6` DMG exists, but the app is ad-hoc signed; Gatekeeper rejects it.
+- This machine currently has no valid Apple code-signing identity and no Tauri updater private-key environment configured.
+- `agentsam-desktop-updates` is deployed, but updater checks fail because production D1 lacks `desktop_shell_releases`.
+- `updates.agentsam.dev` does not currently resolve.
+- `apps/local-studio/agentsam.app.json` still advertises an npm install for a private package. That install contract is stale.
+
+## Product law
+
+Local Studio desktop is not a website wrapper and not an npm package masquerading as an app.
+
+```text
+AgentSam Local Studio.app
+  -> bundled apps/local-studio SPA
+  -> Tauri native commands
+  -> agentsamd / SQLite / filesystem / keychain / identity adapters
+```
+
+The npm release and desktop release may share a version, but they are separate artifacts:
+
+```text
+@inneranimalmedia/agentsam-sdk  -> npm registry
+AgentSam Local Studio          -> signed/notarized native artifact + updater/download service
+```
+
+## Release gate 1 — source and native parity
+
+Required green checks:
+
+1. `npm --prefix apps/local-studio run verify:desktop`
+2. Local Studio typecheck/tests relevant to desktop and auth
+3. `npm --prefix packages/identity test`
+4. `cargo check` and `cargo test` for `agentsam-desktop-shell`
+5. Build the shell from the current Local Studio SPA, never from a recovery/bootstrap page
+6. Launch the packaged `.app` and confirm the Local Studio accessibility tree contains the real workspace
+7. Exercise native startup without blocking the work surface
+8. Exercise SQLite, local content/files, PTY/agentsamd, keychain/session restoration, and deep-link callback paths
+
+No release may proceed if the UI only works in Chrome while the packaged WebView is blank.
+
+## Release gate 2 — one version authority
+
+Before release, these must agree:
+
+- root SDK package version
+- `apps/local-studio/package.json`
+- `packages/agentsam-desktop-shell/manifests/local-studio.json`
+- generated Tauri config / bundle Info.plist
+- DMG filename
+- updater registry row
+
+For this graduation target, the intended version is `2.6.6`.
+
+## Release gate 3 — updater/download backend
+
+1. Apply `migrations/d1/0017_desktop_shell_releases.sql` to `inneranimalmedia-business`.
+2. Re-test `agentsam-desktop-updates` updater lookup; missing table must be gone.
+3. Keep one backend: D1 release metadata + R2 artifact bytes.
+4. Decide the canonical public updater hostname and make it resolve. Do not leave Tauri configured to a dead hostname.
+5. Publish immutable release artifacts under:
+   `native/release/local-studio/<target>/<arch>/<version>/<filename>`.
+6. Registry rows must point at the exact downloadable artifact and include a valid Tauri updater signature.
+
+## Release gate 4 — signing and notarization
+
+A public macOS build is not complete while `codesign` reports `Signature=adhoc` or `spctl` rejects it.
+
+Required for release channel:
+
+- Developer ID Application signing identity
+- hardened-runtime-compatible signing through Tauri
+- Apple notarization
+- stapled notarization ticket where applicable
+- `codesign --verify --deep --strict` passes
+- `spctl -a -vv` accepts the final app copied from the DMG
+- Tauri updater private key available at build time and `.sig` generated
+
+Unsigned/ad-hoc artifacts may only be used in a clearly named test lane.
+
+## Release gate 5 — installer and CLI contract
+
+`agentsam app install local-studio` must stop advertising `npm install @inneranimalmedia/agentsam-local-studio`.
+
+Target behavior:
+
+1. resolve OS + architecture;
+2. resolve the current release artifact from the desktop release service;
+3. present/download the native installer for that platform;
+4. keep source/npm installation separate from native application installation;
+5. fail visibly when no signed release exists.
+
+The hosted `/install/studio` route must not claim to install Local Studio while it only installs the SDK CLI.
+
+## Release gate 6 — clean-machine acceptance
+
+For macOS 2.6.6:
+
+1. download the release DMG through the public release URL;
+2. mount the DMG;
+3. copy `AgentSam Local Studio.app` to `/Applications`;
+4. launch the copied app, not the build-tree app;
+5. confirm real Local Studio shell renders;
+6. confirm signed-out local usage remains available;
+7. test AgentSam account login/session restore through the shared IAM authority;
+8. test local filesystem/content, SQLite/database UI, terminal/PTY, and agentsamd;
+9. restart the app and verify state/session restoration;
+10. confirm updater check works from an older known build.
+
+## Release gate 7 — npm SDK release
+
+Only after desktop acceptance is green:
+
+1. reconcile root SDK version to `2.6.6`;
+2. run the full npm release verification gates;
+3. `npm pack` and inspect the consumer artifact;
+4. publish `@inneranimalmedia/agentsam-sdk@2.6.6`;
+5. verify npm `latest` points to the intended version;
+6. verify CLI `agentsam app install local-studio` resolves the native app release rather than a private npm package.
+
+## Hosted/web Agent 1 handoff boundary
+
+Agent 1 owns the hosted `agentsam.inneranimalmedia.com` completion lane: marketing/download surface, hosted `/agentsam`, CMS, and web routing. Desktop work may consume the final public download/updater hostname but must not revert to a hosted WebView as its application runtime.
+
+## Hard stop conditions
+
+Do not call the desktop release complete if any of these are true:
+
+- installed app opens blank;
+- packaged app is only a website redirect;
+- version sources disagree;
+- updater endpoint returns 5xx;
+- download URL is dead;
+- updater signature is absent;
+- Gatekeeper rejects the release artifact;
+- CLI advertises a private/unpublished npm package as the desktop installer;
+- native local features require a hosted login page just to render the app.

package/migrations/d1/0017_identity_native_oauth.sql

@@ -0,0 +1,21 @@
+-- Native (desktop) OAuth handoff for the portable identity package.
+-- Additive only: browser OAuth keeps working before and after this applies.
+-- auth_sessions.type already exists in live D1 (DEFAULT 'browser').
+
+ALTER TABLE identity_oauth_states ADD COLUMN client_type TEXT;
+ALTER TABLE identity_oauth_states ADD COLUMN native_challenge TEXT;
+ALTER TABLE identity_oauth_states ADD COLUMN native_redirect TEXT;
+
+-- Single-use, PKCE-bound pickup of a desktop session. Only the sha256 of the
+-- handoff code is stored; the session id never appears in a URL.
+CREATE TABLE IF NOT EXISTS identity_native_handoffs (
+  handoff_hash TEXT PRIMARY KEY,
+  session_id   TEXT NOT NULL,
+  challenge    TEXT NOT NULL,
+  expires_at   INTEGER NOT NULL,
+  created_at   INTEGER NOT NULL,
+  consumed_at  INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_identity_native_handoffs_expires
+  ON identity_native_handoffs(expires_at);