@inneranimalmedia/agentsam-sdk 1.5.1 → 1.7.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/bin/scaffold.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * agentsam scaffold
+ * Usage:
+ *   npx @inneranimalmedia/agentsam-sdk scaffold
+ *   npx @inneranimalmedia/agentsam-sdk scaffold cms
+ *   npx @inneranimalmedia/agentsam-sdk scaffold worker-api
+ */
+
+import { runScaffold } from '../src/lib/scaffold/index.js';
+
+const type = process.argv[2] ?? null;
+
+runScaffold(type).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "1.5.1",
+  "version": "1.7.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",
@@ -9,7 +9,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "agentsam": "src/cli.js"
+    "agentsam": "src/cli.js",
+    "agentsam-scaffold": "bin/scaffold.mjs"
   },
   "files": [
     "src",
@@ -19,7 +20,8 @@
     "test",
     "README.md",
     "LICENSE",
-    "DEVELOPMENT.md"
+    "DEVELOPMENT.md",
+    "bin"
   ],
   "scripts": {
     "test": "node test/smoke.mjs",
@@ -30,7 +32,9 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "node-pty": "^1.0.0",
+    "picocolors": "^1.1.1",
     "ws": "^8.18.0"
   },
   "publishConfig": {
@@ -54,5 +58,8 @@
   "bugs": {
     "url": "https://github.com/SamPrimeaux/agentsam-sdk/issues"
   },
-  "homepage": "https://github.com/SamPrimeaux/agentsam-sdk#readme"
+  "homepage": "https://github.com/SamPrimeaux/agentsam-sdk#readme",
+  "allowScripts": {
+    "node-pty@1.1.0": true
+  }
 }

package/src/cli.js

@@ -8,6 +8,7 @@ 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';
 
@@ -28,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
@@ -36,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>
@@ -193,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/scaffold/index.js

@@ -0,0 +1,61 @@
+/**
+ * @inneranimalmedia/agentsam-sdk — scaffold system
+ * Entry point for all guided scaffold wizards.
+ *
+ * Usage:
+ *   npx @inneranimalmedia/agentsam-sdk scaffold
+ *   npx @inneranimalmedia/agentsam-sdk scaffold cms
+ *   npx @inneranimalmedia/agentsam-sdk scaffold worker-api
+ */
+
+import { intro, outro, select, cancel, isCancel, note } from '@clack/prompts';
+import { runCmsWizard } from './wizards/cms.js';
+import { runWorkerApiWizard } from './wizards/worker-api.js';
+import pc from 'picocolors';
+
+const SCAFFOLDS = {
+  cms: {
+    label: 'CMS Site',
+    description: 'Cloudflare Worker + D1 + R2 with nav, pages, and reusable templates',
+    run: runCmsWizard,
+  },
+  'worker-api': {
+    label: 'Worker API',
+    description: 'Bare Cloudflare Worker with typed route handlers and D1 binding',
+    run: runWorkerApiWizard,
+  },
+};
+
+export async function runScaffold(type) {
+  intro(pc.bgCyan(pc.black(' Agent Sam Scaffold ')));
+
+  // If a type was passed directly (e.g. `scaffold cms`), run it
+  if (type && SCAFFOLDS[type]) {
+    await SCAFFOLDS[type].run();
+    outro(pc.green('Done. Files written — check the output above.'));
+    return;
+  }
+
+  if (type && !SCAFFOLDS[type]) {
+    note(`Unknown scaffold type: "${type}"\nAvailable: ${Object.keys(SCAFFOLDS).join(', ')}`, 'Error');
+    process.exit(1);
+  }
+
+  // No type passed — show picker
+  const choice = await select({
+    message: 'What do you want to scaffold?',
+    options: Object.entries(SCAFFOLDS).map(([value, { label, description }]) => ({
+      value,
+      label,
+      hint: description,
+    })),
+  });
+
+  if (isCancel(choice)) {
+    cancel('Cancelled.');
+    process.exit(0);
+  }
+
+  await SCAFFOLDS[choice].run();
+  outro(pc.green('Done. Files written — check the output above.'));
+}