@inneranimalmedia/agentsam-sdk 1.1.0 → 1.2.0

package/DEVELOPMENT.md

@@ -0,0 +1,58 @@
+# Developing agentsam-sdk with Inner Animal Media
+
+## Local smoke test
+
+```bash
+cd agentsam-sdk
+npm test
+```
+
+## Link into a scaffolded project
+
+```bash
+cd agentsam-sdk && npm link
+cd /path/to/your-project && npm link @inneranimalmedia/agentsam-sdk
+npm run dev
+```
+
+## Link into inneranimalmedia (monorepo-style)
+
+From the platform repo:
+
+```bash
+cd inneranimalmedia
+npm link ../agentsam-sdk
+```
+
+Then in any Worker or script:
+
+```js
+import { AgentSam } from '@inneranimalmedia/agentsam-sdk';
+```
+
+## Non-interactive init (CI / smoke)
+
+```bash
+npx agentsam init \
+  --name my-agent \
+  --lane fullstack \
+  --provider cloudflare \
+  --agent orchestrator \
+  --yes
+```
+
+## Publish checklist
+
+1. `npm test` passes
+2. Bump version in `package.json`
+3. `npm publish --access public`
+4. Tag: `git tag v1.1.1 && git push origin v1.1.1`
+
+## Known gaps (roadmap)
+
+- `agentsam deploy`, `status`, `logs` — not implemented yet
+- 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inner Animal Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Agent Sam SDK
+
+> The AI agent layer for developers who need more than a chatbot.
+
+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?
+
+Agent Sam is a platform operator AI. It sits on top of your infrastructure and can:
+
+- **Understand intent** — natural language in, real actions out
+- **Execute across surfaces** — terminal, database, browser, CAD, deploy, MCP tools
+- **Route intelligently** — local machine, cloud VM, or sandboxed environment based on context
+- **Gate high-risk actions** — approval flows before anything destructive runs
+- **Leave an audit trail** — every tool call, command run, and decision is logged
+
+It is not a wrapper around a chat API. It is a command fabric with a conversation interface.
+
+---
+
+## Quickstart
+
+```bash
+npx @inneranimalmedia/agentsam-sdk init
+```
+
+Non-interactive (CI / scripts):
+
+```bash
+npx @inneranimalmedia/agentsam-sdk init \
+  --name my-agent \
+  --lane fullstack \
+  --provider cloudflare \
+  --agent orchestrator \
+  --yes
+```
+
+Scaffolded workers expose `GET /health` and `POST /chat` immediately (stub mode without an API key).
+
+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
+npm install @inneranimalmedia/agentsam-sdk
+```
+
+---
+
+## Lanes
+
+| Lane | Best For |
+|------|----------|
+| **Full Stack** | End-to-end apps — agent chat, terminal, deploy, D1, R2, Durable Objects, KV |
+| **CMS** | Content-managed websites — pages, assets, themes, navigation, live edit |
+| **Data Solutions** | Database ops, migrations, queries, Supabase pgvector, Hyperdrive pipelines |
+| **Customer Management** | CRM, contacts, billing, client workflows, multi-tenant isolation |
+| **Creative & Design** | CAD, 3D, media generation, content pipelines |
+
+---
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| **Orchestrator** | General purpose — routes across all lanes and tools |
+| **CMS Agent** | Pages, sections, assets, themes, publishing workflows |
+| **Data Agent** | D1, Supabase, Hyperdrive, migrations, vector search |
+| **CRM Agent** | Customer records, contacts, billing, client isolation |
+| **Creative Agent** | Design commands, 3D generation, CAD, media pipelines |
+
+---
+
+## How It Works
+
+```
+User Intent (chat or CLI)
+        ↓
+   Agent Sam — intent classification + command match
+        ↓
+   Tool Catalog (D1) — policy check + approval gate
+        ↓
+   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.
+
+---
+
+## Infrastructure
+
+Agent Sam scaffolds and operates across the full Cloudflare + Supabase stack:
+
+| Layer | Technology | Role |
+|-------|------------|------|
+| **Compute** | Cloudflare Workers | Edge runtime, API, agent dispatch |
+| **Relational DB** | D1 (SQLite) | Tool catalog, sessions, telemetry, CMS, auth |
+| **Vector DB** | Supabase pgvector via Hyperdrive | RAG, semantic search, agent memory |
+| **Object Storage** | R2 | Assets, media, bundles, CMS content |
+| **Key-Value** | Workers KV | Cache, CMS drafts, feature flags |
+| **Stateful Sessions** | Durable Objects | Terminal sessions, collab, real-time state |
+| **Terminal** | ExecOS over cloudflared tunnel | Shell execution, deploy, git, wrangler |
+| **AI Router** | Anthropic + OpenAI | Adaptive Thompson sampling across models |
+| **Protocol** | MCP (Model Context Protocol) | External agent surface for Cursor, Claude, etc. |
+
+---
+
+## Execution Lanes
+
+Agent Sam routes work to the right environment automatically:
+
+| Lane | Environment | When |
+|------|-------------|------|
+| Local | Your machine | Fastest dev loop |
+| Cloud | Always-on VM via tunnel | Machine asleep or offsite |
+| Sandbox | Isolated workspace | Safe experiments, tenant isolation |
+
+---
+
+## What Gets Scaffolded
+
+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 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
+
+- 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
+- D1 and R2 are scoped per tenant at the binding level
+- Every action produces an audit trail
+
+---
+
+## Roadmap
+
+- [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
+
+---
+
+## Built By
+
+[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.
+
+---
+
+## License
+
+MIT

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)