@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/docs/local-studio/WORKMODE_DONOR_NOTES.md

@@ -0,0 +1,485 @@
+AgentSam Workmode ( agent reading this-- we will clone/repackage the build mentioned, RULES==== 1- this becomes a shell, but not a shallow placeholder. baseline- agentsam/cli packages come prebuilt in this app so user installing could get a local prebuilt agentsam editor. RULES- no hardcoded credentials ( remove my account info/urls etc ) 
+├─ src/
+│  ├─ commands/
+│  ├─ local-pty/
+│  ├─ local-portal/
+│  └─ ui/ GOAL======= WE FULLY BUILD OUT, an agent/ide ui/ux dashboard, local pty/cli use = default basic. if user chooses to use ai, they may be prompted to connect/deploy to cloudflare or github for secret encryption. once adding their api key and or scaffolding their repo/worker, the agentsam/ide = fully agentic automated code/web browsing multi agent orchistration system. tui/cli ui/ux = prebuilt into terminal ( dont even mention it, just design it so every in app user experience cli is clean/branded/interactive cli interactions. 
+Calm vibecode bench: persistent trails, helper chats, in-app browser, Monaco, xterm CLI, projects/artifacts, model picker, and GitHub / Cloudflare ship.
+
+Repo: SamPrimeaux/AgentSam-Grok-Workmode
+Account ID: ede6590ac0d2fb7daf155b35653457b2
+Canonical D1: inneranimalmedia-business (cf87b717-d4e2-4cf8-bab0-a81268e32d49)
+Product domain: https://simple.inneranimalmedia.com
+UI Worker: agentsam-grok-workmode → https://agentsam-grok-workmode.meauxbility.workers.dev
+Vault Worker: agentsam-workmode → https://agentsam-workmode.meauxbility.workers.dev
+Vault on domain: GET https://simple.inneranimalmedia.com/health · /api/vault/*
+
+What works today
+Surface	Behavior
+Trails	Left rail; persist in the browser
+Helper chat	Ephemeral side stage until you Keep trail
+Browser	Lookup without leaving the bench
+Files / Monaco	Agent-written code, editable
+CLI	`Ctrl+`` — git, vibe, wrangler helpers
+Ship	GitHub push + Cloudflare Pages via /api/github + /api/cloudflare
+Tokens (interim)	Plaintext localStorage (agentsam-ship-secrets) — replace with vault
+Side chats stay ephemeral until kept. Shell fences in replies have a Run control that sends the command to the CLI.
+
+Quick start (local)
+npm install
+npm run dev          # preview on 0.0.0.0:8080
+npm run typecheck
+npm run build
+Scaffold a new AgentSam product
+Use the published SDK for a clean local project (identity + SQLite + CLI). This Workmode repo is the UI/template lane; the SDK is the portable scaffold lane.
+
+# one-shot
+npx @inneranimalmedia/agentsam-sdk init --name my-agent --yes
+cd my-agent
+npm install
+npm run smoke
+npm run dev
+
+# or global CLI
+npm install -g @inneranimalmedia/agentsam-sdk
+agentsam init --name my-agent --yes
+agentsam status
+Optional: index an existing tree before wiring cloud ops.
+
+agentsam init . --yes --include src,docs
+agentsam index plan
+agentsam index run
+agentsam search "oauth vault secrets"
+Docs: agentsam-sdk
+
+Deploy / bind Cloudflare Worker + D1
+Account + database (SSOT)
+Binding	Value
+Account ID	ede6590ac0d2fb7daf155b35653457b2
+Account	Inner Animal Media Cloudflare account
+D1 name	inneranimalmedia-business
+D1 UUID	cf87b717-d4e2-4cf8-bab0-a81268e32d49
+Product host	simple.inneranimalmedia.com
+UI Worker	agentsam-grok-workmode (SPA on /*)
+Vault Worker	agentsam-workmode (/health, /api/vault*)
+workers.dev (UI)	agentsam-grok-workmode.meauxbility.workers.dev
+workers.dev (vault)	agentsam-workmode.meauxbility.workers.dev
+Copy the example Worker config:
+
+cp wrangler.toml.example wrangler.toml
+# live SSOT is wrangler.workmode.toml (account_id + domain routes baked in)
+Auth for Wrangler (never commit tokens)
+# preferred: OAuth login (interactive)
+npx wrangler login
+
+# or export a scoped API token in your shell only
+export CLOUDFLARE_ACCOUNT_ID="ede6590ac0d2fb7daf155b35653457b2"
+export CLOUDFLARE_API_TOKEN="<token-with-workers+d1>"
+On the IAM Mac desk, prefer the monorepo env wrappers instead of pasting tokens into chat:
+
+# from SamPrimeaux/inneranimalmedia
+./scripts/with-cloudflare-env.sh npx wrangler whoami
+D1 inspect / one-off SQL (production DB)
+Do not blindly migrations apply against production. Use reviewed one-off files (same rule as the platform deploy guide).
+
+# list remote DBs
+npx wrangler d1 list
+
+# informational migration ledger
+npx wrangler d1 migrations list inneranimalmedia-business --remote
+
+# execute a reviewed SQL file against the business DB
+npx wrangler d1 execute inneranimalmedia-business --remote \
+  --file=./migrations/workmode/<your-reviewed-migration>.sql
+
+# ad-hoc read (example)
+npx wrangler d1 execute inneranimalmedia-business --remote \
+  --command="SELECT name FROM sqlite_master WHERE name IN ('user_secrets','user_oauth_tokens','agentsam_user_ui_preferences');"
+Worker secrets (vault + app)
+# master key for AES-GCM vault (generate once; store only in CF Secrets)
+openssl rand -base64 32 | npx wrangler secret put VAULT_MASTER_KEY
+
+# optional aliases used by platform workers
+npx wrangler secret put VAULT_KEY          # same value if you keep one master
+npx wrangler secret put BETTER_AUTH_SECRET
+npx wrangler secret put XAI_API_KEY        # server-only model calls
+Deploy this Worker (vault API — live)
+Entry: worker/index.js · config: wrangler.workmode.toml
+
+# from IAM desk (credentials via .env.cloudflare wrapper)
+./scripts/with-cloudflare-env.sh npx wrangler deploy -c wrangler.workmode.toml
+
+# secrets (once per account/script)
+openssl rand -base64 32 | npx wrangler secret put VAULT_MASTER_KEY --name agentsam-workmode
+openssl rand -hex 24   | npx wrangler secret put WORKMODE_API_KEY --name agentsam-workmode
+Smoke (replace bearer + user):
+
+curl -sS https://agentsam-workmode.meauxbility.workers.dev/health
+curl -sS https://simple.inneranimalmedia.com/health
+
+curl -sS -X POST https://simple.inneranimalmedia.com/api/vault/secrets \
+  -H "Authorization: Bearer $WORKMODE_API_KEY" \
+  -H "X-User-Id: au_…" \
+  -H "content-type: application/json" \
+  -d '{"service_name":"github","secret_name":"ship","value":"ghp_…"}'
+Routes: GET/POST /api/vault/secrets, DELETE /api/vault/secrets/:id, POST /api/vault/unwrap (server-only).
+
+For the full IAM platform (dashboard + R2 + Worker), use the monorepo ship lane — not a bare wrangler deploy from that repo:
+
+# Mac operator desk (inneranimalmedia)
+npm run deploy
+# or
+bin/agentsam deploy fast
+
+# phone / GCP iam-tunnel (push; Cloudflare Builds does the heavy lift)
+bash scripts/ship-remote.sh
+See docs/DEPLOY_AND_AGENT_GUIDE.md in SamPrimeaux/inneranimalmedia.
+
+GitHub Actions sketch (Worker)
+# .github/workflows/deploy-worker.yml
+name: Deploy Workmode Worker
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci && npm run build
+      - uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: deploy -c wrangler.toml
+Repo secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID only — never put user BYOK keys in Actions.
+
+Encrypted secrets plan (required for Connect)
+Status: planned / schema already exists on inneranimalmedia-business.
+Interim: plaintext browser localStorage — not acceptable for multi-user or cross-device.
+
+Full design: docs/SECRETS_VAULT_PLAN.md
+
+Non-negotiables
+Never store GitHub / Cloudflare / model API keys in localStorage, client state, or chat logs.
+One vault lane: ciphertext in D1 (user_secrets, user_oauth_tokens, env_secrets); plaintext only in Worker memory at use-time.
+OAuth preferred for GitHub + Cloudflare; paste-token is fallback that still goes through the vault encrypt path.
+Decrypt only server-side for the authenticated user_id / tenant_id / workspace_id that owns the row.
+Audit every read/write/rotate via secret_audit_log (last4 only in logs).
+Existing tables (reuse — do not invent parallel vaults)
+Table	Role
+user_secrets	BYOK API keys (secret_value_encrypted, service_name, vault_secret_id)
+user_oauth_tokens	Provider tokens (access_token_encrypted / refresh_token_encrypted + vault ids)
+env_secrets	Worker/env registry (encrypted_d1 vs workers_secret)
+secret_audit_log	Rotate / use / revoke events
+agentsam_user_ui_preferences	Theme / accent / density JSON (non-secret)
+oauth_providers	Platform OAuth client config (client_secret_encrypted)
+Crypto contract (Worker)
+Algorithm: AES-256-GCM
+Key: VAULT_MASTER_KEY (Worker secret, 32 bytes raw or base64)
+Stored blob: base64(iv || ciphertext || tag) or separate iv column where the table already has one (env_secrets.iv)
+AAD (optional but recommended): user_id:service_name:secret_name to bind ciphertext to owner
+Connect UX (target)
+Sign in → session carries verified user_id
+Connect Cloudflare → OAuth (docs/auth/CLOUDFLARE_OAUTH_CLIENT_SCOPES.md in monorepo) → store tokens encrypted
+Connect GitHub → GitHub App / OAuth → store tokens encrypted
+BYOK API key → Settings form posts to /api/vault/secrets → encrypt → D1; UI shows masked last4 only
+Ship / deploy / model routes resolve secrets by id, decrypt once, call provider, drop plaintext
+Until Connect ships, Settings must keep warning that tokens are browser-local only.
+
+Theme / prefs (non-secret)
+Persist UI customization in agentsam_user_ui_preferences.ui_preferences_json keyed by (workspace_id, user_id):
+
+{
+  "theme": "studio-dark",
+  "accent": "#c4a574",
+  "density": "comfortable",
+  "defaultModel": "grok-4-6"
+}
+Cache a copy locally for snappy paint; server row wins after sign-in.
+
+Product direction (short)
+Identity gate
+Vault-backed Connect (CF + GitHub + BYOK)
+Mobile single-pane shell
+Theme prefs on D1
+Agent run finalization / reliability
+Package as agentsam-sdk workmode lane
+Related
+Platform deploy guide: SamPrimeaux/inneranimalmedia → docs/DEPLOY_AND_AGENT_GUIDE.md start-local should launch the Studio shell
+
+I would change the mental model from:
+
+agentsam start-local
+→ starts PTY
+
+to:
+
+agentsam start-local
+→ starts AgentSam Local
+
+Underneath it starts several local capabilities:
+
+AgentSam Local
+│
+├─ HTTP portal
+├─ PTY WebSocket
+├─ project API
+├─ template catalog
+├─ preview server
+└─ optional helper/chat bridge
+
+Then terminal output:
+
+Agent Sam Local
+
+Project    my-app
+Studio     http://127.0.0.1:3099
+Terminal   ready
+Shell      /bin/zsh
+
+Press ENTER to open AgentSam.
+
+Browser:
+
+┌─────────────────────────────────────────────────────┐
+│ ●                                                   │
+│ ◻   Studio                                          │
+│ ◇                                                   │
+│ ▣      Welcome back                                 │
+│ >                                                   │
+│        What do you want to build?                   │
+│                                                     │
+│        [ CMS ] [ App ] [ Data ] [ Agent ]           │
+│                                                     │
+│        ┌─────────────────────────────────┐          │
+│        │ actual interactive preview      │          │
+│        │                                 │          │
+│        └─────────────────────────────────┘          │
+│                                                     │
+│                 Preview     Use template             │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│ Terminal                                      ↑     │
+└─────────────────────────────────────────────────────┘
+
+Click the terminal button:
+
+┌─────────────────────────────────────────────────────┐
+│                                                     │
+│                 normal Studio                       │
+│                                                     │
+├─────────────────────────────────────────────────────┤
+│ Terminal                                      ─ □ x │
+│                                                     │
+│ sam $                                               │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+
+That matches what you’re describing much better than your second screenshot where CLI owns the entire viewport.
+
+I’d make terminal drawer states:
+
+closed
+peek       ~180px
+half       ~40vh
+large      ~70vh
+fullscreen explicit only
+
+On mobile:
+
+closed
+half
+full
+
+Same PTY underneath. No separate runtime.
+
+Make each good preset a real mini app
+
+Your instinct here is right.
+
+The existing preset catalog currently mostly describes capabilities — fullstack, CMS, prototype, data — rather than actual visual products.
+
+Upgrade the contract to connect a preset with an actual starter app:
+
+{
+  "id": "cms",
+  "version": 2,
+  "lane": "cms",
+
+  "template": {
+    "app": "cms",
+    "scaffold": "generated/cms",
+    "preview": "cms"
+  },
+
+  "presentation": {
+    "title": "CMS Studio",
+    "description": "Content editing, assets and publishing.",
+    "category": "content",
+    "thumbnail": "/gallery/cms.webp"
+  },
+
+  "features": [
+    "cms",
+    "knowledge"
+  ],
+
+  "capabilities": [
+    "scaffold.create",
+    "repository.snapshot",
+    "knowledge.index",
+    "knowledge.search",
+    "site.scrape"
+  ]
+}
+
+Then the catalog becomes the joining point between:
+
+visual card
+    │
+    ├─ preview
+    ├─ scaffold source
+    ├─ features
+    ├─ capabilities
+    └─ CLI preset ID
+
+So:
+
+click "Use CMS"
+
+and:
+
+agentsam create acme-site --preset cms
+
+invoke the exact same backend function.
+
+That's the architecture you want.
+
+Preview them without creating them
+
+This part would make the gallery feel dramatically better.
+
+Build each apps/starters/* project to a static preview bundle:
+
+apps/starters/cms
+        ↓ build
+dist/gallery/cms/
+
+Then AgentSam Local can mount it read-only:
+
+http://127.0.0.1:3099/previews/cms/
+
+and the gallery renders:
+
+<iframe src="/previews/cms/">
+
+So the user can actually click around a convincing app before scaffolding it.
+
+That is much more useful than screenshots alone.
+
+For starter types that need backend behavior, make the gallery build use demo/mock data:
+
+CMS preview
+├─ sample posts
+├─ sample assets
+└─ fake publish state
+
+No credentials.
+
+No database setup.
+
+No deploy.
+
+Just enough to communicate what they’re selecting.
+
+Your existing minis still fit
+
+Keep these:
+
+mini/gadget
+mini/page
+mini/data
+
+They already represent tiny zero-install examples.
+
+But I’d establish tiers:
+
+AgentSam catalog
+│
+├─ Mini
+│  ├─ focus timer
+│  ├─ landing page
+│  └─ JSON viewer
+│
+├─ Starter
+│  ├─ CMS
+│  ├─ dashboard
+│  ├─ agent workspace
+│  └─ data explorer
+│
+└─ Stack
+   ├─ fullstack
+   ├─ CMS + knowledge
+   └─ data + knowledge
+
+Users don’t need to know the internal distinction necessarily; it gives you a sane packaging model.
+
+I would not publish every source app in the npm tarball
+
+This is the other important piece.
+
+Develop with:
+
+apps/
+
+but publish:
+
+dist/local-studio/
+templates/generated/
+protocol/presets/catalog.json
+
+The npm package does not need your entire dev source tree for every React starter.
+
+So:
+
+apps/*            development SSOT
+       ↓ build
+dist/gallery/*    runtime previews
+       ↓ export
+templates/*       scaffold payload
+
+That keeps AgentSam itself relatively lean.
+
+You already have npm pack --dry-run verification, so add assertions such as:
+
+✓ local Studio bundle packaged
+✓ every catalog preset has a scaffold payload
+✓ every visual starter has preview assets
+✓ no node_modules in templates
+✓ no .env files
+✓ no .git directories
+✓ no source repo-specific IDs
+My strongest recommended split
+apps/
+├─ local-studio/          AgentSam's own localhost interface
+└─ starters/              polished real example apps
+
+templates/
+└─ generated/             what gets copied onto users' disks
+
+src/local-portal/         tiny Node server that serves Studio
+src/local-pty/            PTY backend you already have
+
+protocol/presets/         metadata joining all of it
+
+Then agentsam start-local becomes the entrypoint to the whole local product, not “start a WebSocket and good luck.”
+
+And your screenshot #1 is much closer to the right north star: keep the rail and workspace, make helper/chat optional, and move CLI into a bottom drawer rather than treating terminal as a destination page. 
+Cloudflare OAuth scopes: docs/auth/CLOUDFLARE_OAUTH_CLIENT_SCOPES.md
+SDK: @inneranimalmedia/agentsam-sdk
+Vault plan (this repo): docs/SECRETS_VAULT_PLAN.md
+ 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Portable AgentSam SDK and CLI kits for local scaffolding, repository intelligence, incremental indexing, identity adapters, and verified dependency maintenance.",
   "type": "module",
   "main": "./src/index.js",
@@ -32,6 +32,7 @@
     "./identity/contracts/session": "./packages/identity/src/contracts/session.js",
     "./identity/contracts/provider": "./packages/identity/src/contracts/provider.js",
     "./identity/contracts/external-identity": "./packages/identity/src/contracts/external-identity.js",
+    "./identity/contracts/auth-config": "./packages/identity/src/contracts/auth-config.js",
     "./identity/oauth/callback": "./packages/identity/src/oauth/callback.js",
     "./identity/oauth/finalize-inbound": "./packages/identity/src/oauth/finalize-inbound.js",
     "./identity/oauth/redirect-paths": "./packages/identity/src/oauth/redirect-paths.js",
@@ -45,23 +46,39 @@
     "./package.json": "./package.json",
     "./security": "./src/security/index.js",
     "./cad": "./src/lib/cad/index.js",
-    "./cad-docker": "./src/lib/cad-docker.js"
+    "./cad-docker": "./src/lib/cad-docker.js",
+    "./context": "./src/context/index.js",
+    "./indexing": "./src/indexing/index.js",
+    "./tools": "./src/tools/index.js",
+    "./models": "./src/models/index.js",
+    "./telemetry": "./src/telemetry/index.js",
+    "./providers": "./src/providers/index.js",
+    "./errors": "./src/errors/index.js",
+    "./cloudflare": "./src/cloudflare/index.js",
+    "./eval": "./src/eval/index.js",
+    "./context/result-policy-schema": "./protocol/context/result-policy.schema.json",
+    "./context/budget-schema": "./protocol/context/context-budget.schema.json",
+    "./context/pack-schema": "./protocol/context/resolved-context-pack.schema.json",
+    "./skills": "./src/skills/index.js",
+    "./skills/catalog": "./skills/catalog.json"
   },
   "bin": {
-    "agentsam": "src/cli.js",
-    "agentsam-sdk": "src/cli.js",
+    "agentsam": "bin/agentsam",
+    "agentsam-sdk": "bin/agentsam",
     "agentsam-scaffold": "bin/scaffold.mjs",
     "agentsam-auth-portal": "packages/identity/scripts/preview-auth-portal.mjs"
   },
   "files": [
     "src",
     "packages/identity",
+    "packages/connectors/cloudflare",
     "templates",
     "docs",
     "examples",
     "test",
     "python",
     "protocol",
+    "skills",
     "services/knowledge/package.json",
     "services/knowledge/package-lock.json",
     "services/cad/server.py",
@@ -69,14 +86,17 @@
     "bin",
     "README.md",
     "LICENSE",
-    "DEVELOPMENT.md"
+    "DEVELOPMENT.md",
+    "AGENTSAM.md"
   ],
   "workspaces": [
     "packages/agentsam-shell-kit",
-    "packages/identity"
+    "packages/identity",
+    "packages/agentsam-contracts",
+    "packages/agentsam-workbench"
   ],
   "scripts": {
-    "test": "node test/smoke.mjs && node --test test/*.test.mjs && npm --prefix packages/identity test",
+    "test": "node test/smoke.mjs && node --test test/*.test.mjs && npm --prefix packages/identity test && npm run test:connectors",
     "test:identity": "npm --prefix packages/identity test",
     "smoke": "node test/smoke.mjs",
     "verify:package": "node scripts/verify-package.mjs",
@@ -92,10 +112,14 @@
     "preview:auth-portal": "node packages/identity/scripts/preview-auth-portal.mjs --open",
     "prepublishOnly": "npm run verify:release",
     "security:check": "node src/security/cli.mjs scan",
-    "security:repair": "node src/security/cli.mjs repair"
+    "security:repair": "node src/security/cli.mjs repair",
+    "ui:preview": "node scripts/ui-preview.mjs",
+    "test:connectors": "node --test packages/connectors/cloudflare/tests/**/*.test.mjs",
+    "verify:npm10-lock": "node apps/local-studio/scripts/verify-npm10-lock.mjs"
   },
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22 <25",
+    "npm": ">=10 <12"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
@@ -133,5 +157,6 @@
   "devDependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9"
-  }
+  },
+  "packageManager": "npm@10.9.2"
 }

package/packages/connectors/cloudflare/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@inneranimalmedia/agentsam-connector-cloudflare",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  }
+}