@inneranimalmedia/agentsam-sdk 1.5.0 → 1.6.0

package/README.md

@@ -35,10 +35,12 @@ cd my-project
 npm install
 npm run smoke
 npx agentsam start-local   # local PTY on ws://127.0.0.1:3099
+npx agentsam tunnel        # cloudflared → register with IAM (dashboard Local lane)
 npm run dev                # http://127.0.0.1:8787
 npm run db:migrate         # local D1 schema
 ```
 
+`agentsam tunnel` (default `--quick`) starts a Cloudflare quick tunnel to `:3099` and POSTs the `wss://` URL to `/api/sdk/terminal/register-local` so `agentsam_terminal_local` can reach your machine. Use `--named --tunnel-name … --hostname … --zone-id …` for a stable BYOK named tunnel.
 When you're ready to ship to **your** Cloudflare account:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Agent Sam is a full-stack AI agent SDK for autonomous task execution — covering data management, creative workflows, design commands, and multi-step agentic pipelines.",
   "type": "module",
   "main": "./src/index.js",
@@ -13,6 +13,7 @@
   },
   "files": [
     "src",
+    "templates",
     "docs",
     "examples",
     "test",

package/src/cli.js

@@ -4,9 +4,11 @@ import pkg from '../package.json' with { type: 'json' };
 import readline from 'readline';
 import { buildLocalScaffoldMeta, LANE_KEYS, RUN_TARGETS } from './lib/local-scaffold.js';
 import { writeScaffoldFiles } from './lib/write-files.js';
+import { copyGorillaTemplate } from './lib/gorilla-template.js';
 import { printContextSummary } from './lib/detect-context.js';
 import { promptOptionalByokKeys } from './lib/prompt-byok.js';
 import { runStartLocal } from './commands/start-local.js';
+import { runTunnel } from './commands/tunnel.js';
 import { runDeploy } from './commands/deploy.js';
 import { SLASH_COMMANDS, SHELL_PHASES } from './lib/slash-commands.js';
 
@@ -27,6 +29,7 @@ function printHelp() {
   Usage:
     agentsam init              Local-first project scaffold (default: localhost, no accounts)
     agentsam start-local       Local PTY on ws://127.0.0.1:3099 (no tunnel, no Cloudflare)
+    agentsam tunnel            Expose local PTY to IAM (cloudflared + register)
     agentsam deploy            Graduate to Cloudflare / GCP when ready
     agentsam shell             Slash commands + shell UX info
     agentsam --version
@@ -35,6 +38,12 @@ function printHelp() {
   Init is completable with Node only — no IAM login, no OAuth, no Cloudflare.
   Prove locally first; deploy prompts for accounts only when you choose to ship.
 
+  Tunnel options:
+    --quick                    Quick tunnel (default) — trycloudflare.com URL
+    --named                    Named CF tunnel (needs --tunnel-name --hostname --zone-id)
+    --port <n>                 Local PTY port (default 3099)
+    --token <sdk_…>            Use existing AGENTSAM_SDK_TOKEN (skip browser auth)
+
   Init options:
     --name <name>              Project directory name
     --lane <fullstack|cms|data|crm|creative>
@@ -89,9 +98,11 @@ async function runLocalInit(config) {
   `);
 
   const dir = writeScaffoldFiles(meta.projectName, meta.files);
+  copyGorillaTemplate(dir, meta);
 
   console.log(`
   ✓ Project ready: ${dir}
+  ✓ Gorilla Mode UI → gorilla/ (http://localhost:5173 after npm run dev)
 
   Next steps:`);
   for (const step of meta.next_steps) {
@@ -105,9 +116,8 @@ async function runLocalInit(config) {
 
   console.log(`
   Local in ~60 seconds:
-    cd ${meta.projectName} && npm install && npm run smoke
-    npx agentsam start-local
-    npm run dev
+    cd ${meta.projectName} && npm install && npm run smoke && npm run dev
+    open http://localhost:5173
   `);
 }
 
@@ -191,6 +201,13 @@ if (command === '--version' || command === '-v') {
   await runShellInfo();
 } else if (command === 'start-local') {
   await runStartLocal({});
+} else if (command === 'tunnel') {
+  try {
+    await runTunnel(rest);
+  } catch (e) {
+    console.error(`\n  ✗ ${e?.message || e}\n`);
+    process.exit(1);
+  }
 } else if (command === 'deploy') {
   try {
     await runDeploy(parseDeployArgs(rest));

package/src/commands/http-server.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * AgentSam HTTP API server for containerized deployments
+ * Exposes the AgentSam SDK as HTTP endpoints (compatible with Cloudflare Workers pattern)
+ */
+import http from 'node:http';
+import { AgentSam } from './AgentSam.js';
+
+const PORT = process.env.PORT || 8080;
+const HOST = process.env.HOST || '0.0.0.0';
+
+const agentSam = new AgentSam({
+  env: process.env,
+  agent: process.env.AGENT || 'orchestrator',
+  lane: process.env.LANE || 'fullstack',
+  project: process.env.PROJECT || 'agentsam-docker',
+});
+
+/**
+ * Adapt Web API Request to Node HTTP
+ */
+class NodeRequest {
+  constructor(req, body) {
+    this.url = `http://${req.headers.host || 'localhost'}${req.url}`;
+    this.method = req.method;
+    this.headers = req.headers;
+    this.body = body;
+  }
+
+  async json() {
+    if (!this.body) return {};
+    try {
+      return JSON.parse(this.body);
+    } catch {
+      return {};
+    }
+  }
+}
+
+const server = http.createServer(async (req, res) => {
+  let body = '';
+
+  // Read request body
+  req.on('data', (chunk) => {
+    body += chunk.toString();
+  });
+
+  req.on('end', async () => {
+    try {
+      const request = new NodeRequest(req, body);
+      const response = await agentSam.handle(request);
+
+      // Write response headers
+      const headers = {};
+      if (response.headers && response.headers.entries) {
+        for (const [key, value] of response.headers.entries()) {
+          headers[key] = value;
+        }
+      }
+      res.writeHead(response.status, headers);
+
+      // Write response body
+      const text = await response.text();
+      res.end(text);
+    } catch (error) {
+      console.error('Error handling request:', error);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: error.message }));
+    }
+  });
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`
+✓ Agent Sam API Server listening on http://${HOST === '0.0.0.0' ? 'localhost' : HOST}:${PORT}
+
+  Routes:
+    GET  /api/health               → service health
+    GET  /api/agentsam/info        → agent capabilities
+    POST /api/agentsam/session     → create session
+    GET  /api/agentsam/session/:id → get session
+    POST /api/agentsam/message     → route message
+
+  Environment: AGENT=${process.env.AGENT || 'orchestrator'} LANE=${process.env.LANE || 'fullstack'}
+`);
+});
+
+// Graceful shutdown
+const shutdown = async () => {
+  console.log('\nShutting down...');
+  server.close(() => {
+    process.exit(0);
+  });
+  setTimeout(() => process.exit(1), 5000);
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/src/commands/tunnel.js

@@ -0,0 +1,232 @@
+/**
+ * agentsam tunnel — expose local PTY (:3099) to the IAM platform.
+ *
+ * Default (--quick): cloudflared quick tunnel → register ws_url via SDK API.
+ * Named (--named): platform provisions CF named tunnel + DNS; run with --token.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { authenticateViaBrowser } from '../lib/auth.js';
+import { postJson } from '../lib/core-client.js';
+
+const DEFAULT_PORT = 3099;
+
+function parseArgs(argv) {
+  const opts = {
+    mode: 'quick',
+    port: DEFAULT_PORT,
+    tunnelName: '',
+    hostname: '',
+    zoneId: '',
+    platform: process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'macos' : 'linux',
+    shell: process.platform === 'win32' ? 'powershell' : process.env.SHELL || '/bin/zsh',
+    skipAuth: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--quick') opts.mode = 'quick';
+    else if (a === '--named') opts.mode = 'named';
+    else if (a === '--port') opts.port = Number(argv[++i]) || DEFAULT_PORT;
+    else if (a === '--tunnel-name') opts.tunnelName = argv[++i] || '';
+    else if (a === '--hostname') opts.hostname = argv[++i] || '';
+    else if (a === '--zone-id') opts.zoneId = argv[++i] || '';
+    else if (a === '--platform') opts.platform = argv[++i] || opts.platform;
+    else if (a === '--shell') opts.shell = argv[++i] || opts.shell;
+    else if (a === '--token' && argv[i + 1]) {
+      process.env.AGENTSAM_SDK_TOKEN = argv[++i];
+    }
+  }
+  return opts;
+}
+
+function ensureCloudflared() {
+  const which = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['cloudflared'], {
+    encoding: 'utf8',
+  });
+  if (which.status !== 0) {
+    throw new Error(
+      'cloudflared not found. Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/',
+    );
+  }
+}
+
+async function resolveToken() {
+  const existing = String(process.env.AGENTSAM_SDK_TOKEN || '').trim();
+  if (existing.startsWith('sdk_')) return existing;
+  const session = await authenticateViaBrowser();
+  const tok = String(session?.access_token || '').trim();
+  if (!tok.startsWith('sdk_')) throw new Error('IAM auth did not return an sdk_ bearer token');
+  process.env.AGENTSAM_SDK_TOKEN = tok;
+  return tok;
+}
+
+async function assertLocalPty(port) {
+  const url = `http://127.0.0.1:${port}/health`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(2500) });
+    if (!res.ok) throw new Error(`health ${res.status}`);
+    return true;
+  } catch {
+    throw new Error(
+      `Local PTY not reachable at ${url}. In another terminal run: npx agentsam start-local`,
+    );
+  }
+}
+
+function httpsToWss(url) {
+  const u = String(url || '').trim();
+  if (!u) return '';
+  if (u.startsWith('wss://') || u.startsWith('ws://')) return u.replace(/\/$/, '');
+  if (u.startsWith('https://')) return `wss://${u.slice(8)}`.replace(/\/$/, '');
+  if (u.startsWith('http://')) return `ws://${u.slice(7)}`.replace(/\/$/, '');
+  return `wss://${u.replace(/^\/+/, '')}`.replace(/\/$/, '');
+}
+
+/**
+ * Parse trycloudflare.com URL from cloudflared stderr/stdout.
+ * @param {import('node:child_process').ChildProcessWithoutNullStreams} child
+ * @returns {Promise<string>}
+ */
+function waitForQuickTunnelUrl(child) {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    const timer = setTimeout(() => {
+      reject(new Error('Timed out waiting for cloudflared quick tunnel URL (60s)'));
+    }, 60_000);
+
+    const onData = (chunk) => {
+      const text = chunk.toString();
+      buf += text;
+      process.stderr.write(text);
+      const m =
+        buf.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i) ||
+        buf.match(/https:\/\/[a-z0-9.-]+\.cfargotunnel\.com/i);
+      if (m) {
+        clearTimeout(timer);
+        child.stdout?.off('data', onData);
+        child.stderr?.off('data', onData);
+        resolve(m[0]);
+      }
+    };
+
+    child.stdout?.on('data', onData);
+    child.stderr?.on('data', onData);
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      reject(new Error(`cloudflared exited early (code ${code})`));
+    });
+  });
+}
+
+async function runQuick(opts, token) {
+  await assertLocalPty(opts.port);
+  ensureCloudflared();
+
+  console.log(`
+  Agent Sam — tunnel (quick)
+  Local PTY  http://127.0.0.1:${opts.port}
+  Mode       cloudflared quick tunnel → IAM register-local
+  `);
+
+  const child = spawn(
+    'cloudflared',
+    ['tunnel', '--url', `http://127.0.0.1:${opts.port}`, '--no-autoupdate'],
+    { stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+
+  const publicUrl = await waitForQuickTunnelUrl(child);
+  const wsUrl = httpsToWss(publicUrl);
+  console.log(`\n  ✓ Public URL  ${publicUrl}`);
+  console.log(`  ✓ Registering  ${wsUrl}\n`);
+
+  const registered = await postJson(
+    '/api/sdk/terminal/register-local',
+    {
+      ws_url: wsUrl,
+      platform: opts.platform,
+      shell: opts.shell,
+    },
+    token,
+  );
+
+  console.log(`  ✓ IAM local lane active`);
+  if (registered?.connection?.id) {
+    console.log(`  ✓ connection   ${registered.connection.id}`);
+  }
+  console.log(`
+  Keep this process running. In the dashboard: Terminal → Local.
+
+  Ctrl+C stops the tunnel.
+  `);
+
+  await new Promise((resolve) => {
+    child.on('exit', resolve);
+    process.on('SIGINT', () => {
+      child.kill('SIGINT');
+    });
+    process.on('SIGTERM', () => {
+      child.kill('SIGTERM');
+    });
+  });
+}
+
+async function runNamed(opts, token) {
+  if (!opts.tunnelName || !opts.hostname || !opts.zoneId) {
+    throw new Error(
+      'Named mode requires --tunnel-name, --hostname, and --zone-id (from your CF zone).',
+    );
+  }
+  await assertLocalPty(opts.port);
+  ensureCloudflared();
+
+  console.log(`
+  Agent Sam — tunnel (named)
+  Provisioning Cloudflare tunnel ${opts.tunnelName} → ${opts.hostname}
+  `);
+
+  const provisioned = await postJson(
+    '/api/sdk/terminal/tunnel/provision',
+    {
+      tunnel_name: opts.tunnelName,
+      hostname: opts.hostname,
+      zone_id: opts.zoneId,
+      port: opts.port,
+      platform: opts.platform,
+      shell: opts.shell,
+    },
+    token,
+  );
+
+  const runToken = String(provisioned?.run_token || '').trim();
+  if (!runToken) throw new Error('Platform did not return a cloudflared run_token');
+
+  console.log(`  ✓ ws_url       ${provisioned.ws_url || `wss://${opts.hostname}`}`);
+  console.log(`  ✓ Starting     cloudflared tunnel run --token …\n`);
+
+  const child = spawn('cloudflared', ['tunnel', 'run', '--token', runToken, '--no-autoupdate'], {
+    stdio: 'inherit',
+  });
+
+  await new Promise((resolve, reject) => {
+    child.on('error', reject);
+    child.on('exit', resolve);
+    process.on('SIGINT', () => child.kill('SIGINT'));
+  });
+}
+
+/**
+ * @param {string[]} [argv]
+ */
+export async function runTunnel(argv = []) {
+  const opts = parseArgs(argv);
+  const token = await resolveToken();
+
+  if (opts.mode === 'named') {
+    await runNamed(opts, token);
+  } else {
+    await runQuick(opts, token);
+  }
+}

package/src/lib/gorilla-template.js

@@ -0,0 +1,54 @@
+/**
+ * Copy Gorilla Mode pixel UI into scaffolded projects (fully local).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE_FILES = ['App.tsx', 'main.jsx', 'index.html'];
+const ROOT_FILES = ['vite.config.js'];
+
+export function resolveGorillaTemplateDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', '..', 'templates', 'gorilla-shell');
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ projectName: string, laneKey: string, agent: string, laneLabel: string }} meta
+ */
+export function copyGorillaTemplate(projectRoot, meta) {
+  const srcDir = resolveGorillaTemplateDir();
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Gorilla template not found at ${srcDir}`);
+  }
+
+  const destDir = path.join(path.resolve(projectRoot), 'gorilla');
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const vars = {
+    '{{PROJECT_NAME}}': meta.projectName,
+    '{{LANE_KEY}}': meta.laneKey,
+    '{{LANE_LABEL}}': meta.laneLabel,
+    '{{AGENT}}': meta.agent,
+  };
+
+  for (const name of TEMPLATE_FILES) {
+    const src = path.join(srcDir, name);
+    if (!fs.existsSync(src)) continue;
+    let content = fs.readFileSync(src, 'utf8');
+    for (const [token, value] of Object.entries(vars)) {
+      content = content.split(token).join(value);
+    }
+    fs.writeFileSync(path.join(destDir, name), content, 'utf8');
+  }
+
+  const root = path.resolve(projectRoot);
+  for (const name of ROOT_FILES) {
+    const src = path.join(srcDir, name);
+    if (!fs.existsSync(src)) continue;
+    fs.copyFileSync(src, path.join(root, name));
+  }
+
+  return destDir;
+}

package/src/lib/local-scaffold.js

@@ -125,7 +125,7 @@ export function buildLocalScaffoldFiles({
   laneLabel,
   agent,
   runTarget,
-  sdkVersion = '1.5.0',
+  sdkVersion = '1.5.1',
 }) {
   const sdkRange = `^${sdkVersion.split('.').slice(0, 2).join('.')}.0`;
   const migration = migrationSql(laneKey);
@@ -153,6 +153,8 @@ export function buildLocalScaffoldFiles({
           deploy_target: runTarget === 'local' ? null : runTarget,
           pty_port: 3099,
           dev_port: 8787,
+          ui_port: 5173,
+          ui: 'gorilla',
           scaffold_version: sdkVersion,
         },
         null,
@@ -169,11 +171,13 @@ Agent Sam runs a PTY on **your machine** — no accounts, no cloudflared, no IAM
 # Terminal 1 — local PTY (Agent Sam shell bridge)
 npx agentsam start-local
 
-# Terminal 2 — app dev server
+# Terminal 2 — Gorilla Mode UI + local Worker API
 npm run dev
 npm run db:migrate   # first time only
 \`\`\`
 
+Open **http://localhost:5173** — pixel Gorilla shell proxies \`/api\` → Worker on :8787.
+
 PTY listens on \`ws://127.0.0.1:3099\`. Health: \`curl http://127.0.0.1:3099/health\`
 
 When you're ready to ship to Cloudflare or GCP:
@@ -202,7 +206,9 @@ dist/
           type: 'module',
           private: true,
           scripts: {
-            dev: 'wrangler dev --local',
+            dev: 'concurrently -k "npm run dev:worker" "npm run dev:ui"',
+            'dev:worker': 'wrangler dev --local --port 8787',
+            'dev:ui': 'vite',
             'dev:node': 'node --watch src/dev-server.js',
             deploy: 'wrangler deploy',
             smoke: 'node ./scripts/smoke.mjs',
@@ -211,15 +217,27 @@ dist/
           },
           dependencies: {
             '@inneranimalmedia/agentsam-sdk': sdkRange,
+            react: '^19.0.0',
+            'react-dom': '^19.0.0',
           },
           devDependencies: {
             wrangler: '^4.0.0',
+            vite: '^6.0.0',
+            '@vitejs/plugin-react': '^4.0.0',
+            concurrently: '^9.0.0',
           },
         },
         null,
         2,
       )}\n`,
     },
+    {
+      path: '.env',
+      content: `VITE_PROJECT_NAME=${projectName}
+VITE_LANE_KEY=${laneKey}
+VITE_AGENT=${agent}
+`,
+    },
     {
       path: 'wrangler.toml',
       content: `name = "${projectName}"
@@ -317,13 +335,18 @@ console.log('AgentSam smoke test passed:', data);
 
 Built locally with [Agent Sam SDK](https://inneranimalmedia.com) — **${laneLabel}** lane, \`${agent}\` agent.
 
-## Local-first (default)
+## Gorilla Mode (default UI)
 
 \`\`\`bash
 npm install
 npm run smoke
-npx agentsam start-local    # Terminal 1 — local PTY
-npm run dev                 # Terminal 2 — http://127.0.0.1:8787
+npm run dev                 # Worker :8787 + Vite :5173
+\`\`\`
+
+Open **http://localhost:5173** — pixel Gorilla shell. Live \`/health\`, \`/samiam\`, and demo scenarios proxy to your local Worker.
+
+\`\`\`bash
+npx agentsam start-local    # optional — local PTY on :3099
 npm run db:migrate          # apply local D1 schema
 \`\`\`
 
@@ -343,7 +366,7 @@ Run target selected at init: **${runTarget}**
   ];
 }
 
-export function buildLocalScaffoldMeta(body, sdkVersion = '1.5.0') {
+export function buildLocalScaffoldMeta(body, sdkVersion = '1.5.1') {
   const projectName = String(body.projectName || body.project_name || 'agentsam-project')
     .trim()
     .toLowerCase()
@@ -364,9 +387,10 @@ export function buildLocalScaffoldMeta(body, sdkVersion = '1.5.0') {
     next_steps: [
       'npm install',
       'npm run smoke',
-      'npx agentsam start-local',
       'npm run dev',
+      'Open http://localhost:5173 — Gorilla Mode UI',
       'npm run db:migrate',
+      'Optional: npx agentsam start-local',
       'When ready: npx agentsam deploy',
     ],
   };