@inneranimalmedia/agentsam-sdk 1.1.1 → 1.5.0

package/DEVELOPMENT.md

@@ -51,5 +51,8 @@ npx agentsam init \
 ## Known gaps (roadmap)
 
 - `agentsam deploy`, `status`, `logs` — not implemented yet
-- CMS lane in README — CLI has 4 lanes today (Full Stack, Data, CRM, Creative)
+- Gorilla Shell Phase 1 — PTY WebSocket bridge to ExecOS
+- CMS lane in README — CLI has 5 lanes (Full Stack, CMS, Data, CRM, Creative)
 - Published API route may differ; stub mode works without `AGENTSAM_API_KEY`
+
+See [docs/CLI_SHELL.md](./docs/CLI_SHELL.md) for the game-feel terminal UX path.

package/README.md

@@ -4,6 +4,8 @@
 
 Agent Sam is a full-stack autonomous agent SDK built on Cloudflare Workers, D1, Supabase, Durable Objects, and MCP — designed to converse, plan, and execute real work across your entire stack. CMS websites, full-stack applications, data pipelines, creative workflows, terminal execution, deployments, and multi-step agentic pipelines — all through one unified agent interface.
 
+**Repo:** [github.com/SamPrimeaux/agentsam-sdk](https://github.com/SamPrimeaux/agentsam-sdk) · **npm:** `@inneranimalmedia/agentsam-sdk`
+
 ---
 
 ## What is Agent Sam?
@@ -20,34 +22,74 @@ It is not a wrapper around a chat API. It is a command fabric with a conversatio
 
 ---
 
-## Quickstart
+## Quickstart (local-first — Node only)
 
-\`\`\`bash
+```bash
 npx @inneranimalmedia/agentsam-sdk init
-\`\`\`
+```
+
+Default path: **localhost**. No IAM login, no Cloudflare OAuth, no accounts. Under 2 minutes with Node 20+ installed.
+
+```bash
+cd my-project
+npm install
+npm run smoke
+npx agentsam start-local   # local PTY on ws://127.0.0.1:3099
+npm run dev                # http://127.0.0.1:8787
+npm run db:migrate         # local D1 schema
+```
+
+When you're ready to ship to **your** Cloudflare account:
+
+```bash
+npx agentsam deploy
+```
 
-Non-interactive (CI / scripts):
+Cloudflare OAuth is prompted **only at deploy** — not at init.
 
-\`\`\`bash
-npx @inneranimalmedia/agentsam-sdk init \\
-  --name my-agent \\
-  --lane fullstack \\
-  --provider cloudflare \\
-  --agent orchestrator \\
+Non-interactive init:
+
+```bash
+npx @inneranimalmedia/agentsam-sdk init \
+  --name my-agent \
+  --lane fullstack \
+  --run-target local \
   --yes
-\`\`\`
+```
 
-Scaffolded workers expose \`GET /health\` and \`POST /chat\` immediately (stub mode without an API key).
+Run targets at init: `local` (default) · `cloudflare` · `gcp` — all scaffold locally first; cloud credentials come at deploy.
 
 See [DEVELOPMENT.md](./DEVELOPMENT.md) for linking the SDK into Inner Animal Media locally.
 
 ---
 
+## CLI Shell Experience (Gorilla)
+
+The SDK ships a **game-feel terminal UX** alongside the scaffold CLI — consolidated from the Gorilla Mode experiment:
+
+```bash
+npx @inneranimalmedia/agentsam-sdk shell
+```
+
+| Piece | Location |
+|-------|----------|
+| Slash command registry | `src/lib/slash-commands.js` |
+| Phase 0 visual prototype | `examples/gorilla-shell/` |
+| Architecture + phases | [docs/CLI_SHELL.md](./docs/CLI_SHELL.md) |
+
+Run the prototype:
+
+```bash
+cd examples/gorilla-shell && npm install && npm run dev
+```
+
+---
+
 ## Installation
 
-\`\`\`bash
+```bash
 npm install @inneranimalmedia/agentsam-sdk
-\`\`\`
+```
 
 ---
 
@@ -77,7 +119,7 @@ npm install @inneranimalmedia/agentsam-sdk
 
 ## How It Works
 
-\`\`\`
+```
 User Intent (chat or CLI)
         ↓
    Agent Sam — intent classification + command match
@@ -87,7 +129,7 @@ User Intent (chat or CLI)
    Execution — terminal / D1 / Supabase / R2 / KV / DO / browser / deploy / MCP
         ↓
    Telemetry — every action logged, measured, improvable
-\`\`\`
+```
 
 Capabilities are data-driven — new tools are added via D1, not Worker redeployments. The same tool catalog powers the dashboard, the CLI, and any MCP-connected client like Cursor or Claude Desktop.
 
@@ -125,35 +167,25 @@ Agent Sam routes work to the right environment automatically:
 
 ## What Gets Scaffolded
 
-Running \`agentsam init\` generates a production-ready project for your lane:
+Running `agentsam init` generates a production-ready project for your lane:
 
 **All lanes include:**
-- \`agentsam.config.js\` — project config, lane, provider, agent
-- \`wrangler.toml\` — Worker, D1, R2, KV, Durable Object bindings
-- \`.env.example\` — all required secrets pre-listed
-- \`src/index.js\` — Worker entry point wired to your agent
-- \`README.md\` — setup and deploy instructions
-
-**CMS lane adds:**
-- Page, section, asset, and theme schema migrations
-- CMS worker with live edit, draft/publish, and R2 asset pipeline
-
-**Data lane adds:**
-- D1 + Supabase Hyperdrive connection config
-- Vector embedding pipeline scaffold
-- Migration templates for core data models
-
-**Full Stack adds:**
-- Durable Object session scaffold
-- Auth tables and session management
-- Full agent chat + tool loop worker
+- `agentsam.config.js` — project config, lane, provider, agent
+- `wrangler.toml` — Worker, D1, R2, KV, Durable Object bindings
+- `.env.example` — all required secrets pre-listed
+- `src/index.js` — Worker entry point wired to your agent
+- `README.md` — setup and deploy instructions
+
+**CMS lane adds:** page/section/asset schema migrations and CMS worker scaffold.
+
+**Data lane adds:** D1 + Hyperdrive config and migration templates.
+
+**Full Stack adds:** Durable Object session scaffold, auth tables, full agent chat loop.
 
 ---
 
 ## Multi-Tenant & Client Policy
 
-Agent Sam is built for isolation from the ground up:
-
 - Each user or client gets a scoped workspace
 - Terminal execution is path-isolated — no cross-tenant access
 - AI usage is policy-gated — BYOK, managed, or disabled per client
@@ -164,10 +196,12 @@ Agent Sam is built for isolation from the ground up:
 
 ## Roadmap
 
-- [ ] \`agentsam deploy\` — push your project from CLI
-- [ ] \`agentsam status\` — live agent and infrastructure health
-- [ ] \`agentsam logs\` — tail tool call and command logs
-- [ ] \`agentsam kit\` — install pre-built capability kits
+- [x] `agentsam shell` — shell UX info + slash command registry
+- [x] Gorilla Shell Phase 0 prototype in `examples/gorilla-shell/`
+- [ ] `agentsam deploy` — push your project from CLI
+- [ ] `agentsam status` — live agent and infrastructure health
+- [ ] `agentsam logs` — tail tool call and command logs
+- [ ] PTY bridge (Phase 1) — ExecOS WebSocket in shell
 - [ ] Kit marketplace — CMS, ecommerce, nonprofit, SaaS starters
 - [ ] BYOK AI key support per project
 
@@ -175,7 +209,9 @@ Agent Sam is built for isolation from the ground up:
 
 ## Built By
 
-[Inner Animal Media](https://inneranimalmedia.com) — Agent Sam is the operator brain behind the Inner Animal Media platform. The SDK is how we share that infrastructure with other developers.
+[Inner Animal Media](https://inneranimalmedia.com) — Agent Sam is the operator brain behind the platform. The SDK is how we productize that infrastructure for other developers.
+
+**Legacy:** [InnerAnimal/gorilla-mode](https://github.com/InnerAnimal/gorilla-mode) → consolidated here.
 
 ---
 

package/docs/CLI_SHELL.md

@@ -0,0 +1,90 @@
+# Agent Sam SDK — CLI Shell Experience
+
+The SDK ships two complementary surfaces:
+
+1. **`agentsam init`** — scaffold Workers + D1 + agent loop (resell/scale path)
+2. **Gorilla Shell** (`examples/gorilla-shell/`) — game-feel terminal UX layer (unique install experience)
+
+Gorilla Mode was consolidated from the standalone [InnerAnimal/gorilla-mode](https://github.com/InnerAnimal/gorilla-mode) experiment into this repo. **Do not start new work in gorilla-mode** — extend here.
+
+---
+
+## Why a game shell?
+
+Developers installing `@inneranimalmedia/agentsam-sdk` get:
+
+- Efficient tooling (`init`, future `deploy` / `status` / `logs`)
+- A **memorable CLI identity** — pixel HUD, slash commands, themed moods, deploy reactions
+
+The shell is not a toy terminal emulator. It is a **presentation layer** on real PTY + MCP + D1 tool execution — the same stack IAM runs in production.
+
+---
+
+## Architecture
+
+```
+User
+  └─ agentsam shell (CLI) or embedded <AgentSamShell />
+       └─ Gorilla HUD (themes, sprite, quest log)
+            └─ xterm.js ↔ ExecOS / iam-pty WebSocket
+                 └─ Slash commands → SDK router → MCP / wrangler / D1
+```
+
+| Layer | Location in SDK |
+|-------|-----------------|
+| Slash command registry | `src/lib/slash-commands.js` |
+| Phase 0 visual prototype | `examples/gorilla-shell/App.tsx` |
+| Scaffold + Worker agent | `src/lib/scaffold.js`, `src/AgentSam.js` |
+| Future PTY bridge | `src/lib/shell/` (Phase 1) |
+
+---
+
+## Phases
+
+See `SHELL_PHASES` in `src/lib/slash-commands.js`. Current status:
+
+| Phase | Status |
+|-------|--------|
+| 0 — Visual prototype | **Complete** (demo scenarios, themes, sprite) |
+| 1 — Real PTY | **Next** — wire to ExecOS / `terminal.inneranimalmedia.com` |
+| 2 — HUD (quest log, tool gate, XP) | Planned |
+| 3 — Buddy (`/buddy`, MCP stream) | Planned |
+| 4 — Dashboard embed | Planned |
+| 5 — Standalone PWA as SDK default | Planned |
+
+---
+
+## Run the prototype
+
+```bash
+cd examples/gorilla-shell
+npm install
+npm run dev
+```
+
+Deploy preview (Cloudflare Pages):
+
+```bash
+npm run build
+npx wrangler pages deploy dist
+```
+
+---
+
+## Platform linkage (IAM)
+
+| Shell feature | IAM SSOT |
+|---------------|----------|
+| PTY sessions | `terminal_connections` + ExecOS |
+| Tool execution | `agentsam_tools` → catalog executor |
+| Buddy / MCP | `mcp.inneranimalmedia.com` |
+| XP (future) | `gorilla_xp` D1 table |
+| Themes (future) | user preferences / `cms_themes` pattern |
+
+---
+
+## Repo history
+
+- **Before:** `InnerAnimal/gorilla-mode` (Phase 0 only, single-file React artifact)
+- **Now:** `SamPrimeaux/agentsam-sdk/examples/gorilla-shell`
+- **D1 project:** `proj_agentsam_sdk` (replaces `proj_gorilla_mode` on the IAM projects grid)