@inneranimalmedia/agentsam-sdk 1.2.0 → 1.5.0

package/src/lib/slash-commands.js

@@ -26,7 +26,7 @@ export const SLASH_COMMANDS = [
 /** Shell UX rollout phases (gorilla-shell → SDK default CLI experience). */
 export const SHELL_PHASES = [
   { id: '0-prototype', label: 'Visual prototype + demo scenarios', status: 'complete' },
-  { id: 'pty-connection', label: 'ExecOS / iam-pty WebSocket bridge', status: 'next' },
+  { id: 'pty-connection', label: 'Local PTY via agentsam start-local', status: 'current' },
   { id: 'hud-layer', label: 'Quest log, tool gate, XP HUD', status: 'planned' },
   { id: 'buddy-system', label: 'In-shell Agent Sam via MCP', status: 'planned' },
   { id: 'dashboard-embed', label: 'Embeddable shell for IAM dashboard', status: 'planned' },

package/src/lib/write-files.js

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Write Agent Sam scaffold files to the user's machine (their repo, not IAM's).
+ * @param {string} targetDir
+ * @param {{ path: string, content: string }[]} files
+ */
+export function writeScaffoldFiles(targetDir, files) {
+  const root = path.resolve(targetDir);
+  if (fs.existsSync(root)) {
+    throw new Error(`Directory already exists: ${root}`);
+  }
+  fs.mkdirSync(root, { recursive: true });
+  for (const file of files) {
+    const dest = path.join(root, file.path);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, file.content, 'utf8');
+  }
+  return root;
+}

package/src/local-pty/server.js

@@ -0,0 +1,133 @@
+/**
+ * Agent Sam local PTY — localhost WebSocket shell, no tunnel, no IAM.
+ * Compatible with iam-pty wire format (raw bytes + JSON resize/slash).
+ */
+import http from 'node:http';
+import { WebSocketServer } from 'ws';
+
+const DEFAULT_PORT = 3099;
+
+function parsePort(value, fallback) {
+  const n = Number.parseInt(String(value || ''), 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+function shellForPlatform() {
+  if (process.platform === 'win32') return process.env.COMSPEC || 'powershell.exe';
+  return process.env.SHELL || '/bin/zsh';
+}
+
+async function loadPty() {
+  try {
+    const mod = await import('node-pty');
+    return mod.default || mod;
+  } catch (e) {
+    throw new Error(
+      `node-pty is required for start-local. Run: npm install node-pty\n${e?.message || e}`,
+    );
+  }
+}
+
+/**
+ * @param {{ cwd?: string, port?: number, host?: string }} [opts]
+ */
+export async function startLocalPtyServer(opts = {}) {
+  const pty = await loadPty();
+  const cwd = opts.cwd || process.cwd();
+  const port = parsePort(opts.port ?? process.env.PTY_PORT, DEFAULT_PORT);
+  const host = opts.host || '127.0.0.1';
+  const shell = shellForPlatform();
+
+  const httpServer = http.createServer((req, res) => {
+    const path = (req.url || '/').split('?')[0];
+    if (path === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          ok: true,
+          service: 'agentsam-local-pty',
+          cwd,
+          port,
+          shell,
+        }),
+      );
+      return;
+    }
+    res.writeHead(404);
+    res.end('not found');
+  });
+
+  const wss = new WebSocketServer({ server: httpServer });
+
+  wss.on('connection', (ws, req) => {
+    const url = new URL(req.url || '/', `http://${host}`);
+    const sessionCwd = url.searchParams.get('cwd')?.trim() || cwd;
+    const cols = parsePort(url.searchParams.get('cols'), 80);
+    const rows = parsePort(url.searchParams.get('rows'), 24);
+
+    const term = pty.spawn(shell, [], {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd: sessionCwd,
+      env: { ...process.env, TERM: 'xterm-256color', AGENTSAM_LOCAL_PTY: '1' },
+    });
+
+    const sessionId = `local_${Date.now().toString(36)}`;
+    ws.send(JSON.stringify({ type: 'session_id', session_id: sessionId }));
+
+    term.onData((data) => {
+      if (ws.readyState === ws.OPEN) ws.send(data);
+    });
+
+    ws.on('message', (raw) => {
+      const text = raw.toString();
+      try {
+        const msg = JSON.parse(text);
+        if (msg.type === 'resize' && msg.cols && msg.rows) {
+          term.resize(msg.cols, msg.rows);
+          return;
+        }
+        if (msg.type === 'slash' && msg.line) {
+          term.write(`${msg.line}\r`);
+          return;
+        }
+      } catch {
+        /* raw PTY input */
+      }
+      term.write(text);
+    });
+
+    const cleanup = () => {
+      try {
+        term.kill();
+      } catch {
+        /* ignore */
+      }
+    };
+    term.onExit(() => {
+      if (ws.readyState === ws.OPEN) ws.close();
+    });
+    ws.on('close', cleanup);
+    ws.on('error', cleanup);
+  });
+
+  await new Promise((resolve) => {
+    httpServer.listen(port, host, resolve);
+  });
+
+  return {
+    port,
+    host,
+    cwd,
+    shell,
+    url: `ws://${host}:${port}`,
+    healthUrl: `http://${host}:${port}/health`,
+    close: () =>
+      new Promise((resolve, reject) => {
+        wss.close(() => {
+          httpServer.close((err) => (err ? reject(err) : resolve()));
+        });
+      }),
+  };
+}

package/test/smoke.mjs

@@ -3,7 +3,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { AgentSam, routeIntent, getToolCatalog } from '../src/index.js';
-import { scaffoldProject } from '../src/lib/scaffold.js';
+import { buildLocalScaffoldMeta } from '../src/lib/local-scaffold.js';
+import { writeScaffoldFiles } from '../src/lib/write-files.js';
+import { printContextSummary, missingForInit } from '../src/lib/detect-context.js';
 
 const app = new AgentSam({ project: 'smoke', lane: 'cms', agent: 'cms' });
 let res = await app.handle(new Request('https://example.com/api/health'));
@@ -27,10 +29,11 @@ assert.equal(routeIntent({ message: 'drop table users' }).requires_approval, tru
 assert.ok(getToolCatalog('Data Solutions').some((tool) => tool.name === 'query'));
 
 const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-sdk-test-'));
-const cwd = process.cwd();
-process.chdir(tmp);
-const dir = scaffoldProject({ projectName: 'CMS Demo', lane: 'CMS', provider: 'Cloudflare Workers', agent: 'cms' });
-process.chdir(cwd);
+const dir = writeScaffoldFiles(path.join(tmp, 'demo-project'), [
+  { path: 'src/index.js', content: 'export default {};\n' },
+  { path: 'migrations/0001_agentsam_core.sql', content: 'CREATE TABLE cms_pages (id TEXT);\n' },
+  { path: 'package.json', content: '{"name":"demo","devDependencies":{"wrangler":"^4"}}\n' },
+]);
 assert.ok(fs.existsSync(path.join(dir, 'src/index.js')));
 assert.ok(fs.readFileSync(path.join(dir, 'migrations/0001_agentsam_core.sql'), 'utf8').includes('cms_pages'));
 assert.ok(fs.readFileSync(path.join(dir, 'package.json'), 'utf8').includes('wrangler'));
@@ -39,4 +42,20 @@ import { SLASH_COMMANDS, listSlashCommands } from '../src/lib/slash-commands.js'
 assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/deploy'));
 assert.equal(listSlashCommands({ lane: 'deploy' }).length, 2);
 
+printContextSummary({
+  iam: { ready: true, source: 'sdk-token', detail: 'AGENTSAM_SDK_TOKEN' },
+  gcp: { source: 'vm-metadata', email: 'execos@project.iam.gserviceaccount.com' },
+  gcp_vm: true,
+  github: { source: 'gh-cli', account: 'connor@example.com' },
+  cloudflare: { source: 'wrangler', account: 'connor@cloudflare.test' },
+});
+assert.deepEqual(missingForInit({ iam: { ready: false } }, '', { runTarget: 'local' }), []);
+assert.deepEqual(missingForInit({ iam: { ready: false } }, '', { runTarget: 'cloudflare' }), ['iam']);
+
+const localMeta = buildLocalScaffoldMeta({ projectName: 'demo', lane: 'cms', runTarget: 'local' });
+assert.equal(localMeta.laneKey, 'cms');
+assert.ok(localMeta.files.some((f) => f.path === '.agentsam/start-local.md'));
+assert.ok(localMeta.files.some((f) => f.path === 'wrangler.toml'));
+assert.ok(!localMeta.files.some((f) => f.path.includes('execos')));
+
 console.log('SDK smoke tests passed');