@inneranimalmedia/agentsam-sdk 1.5.1 → 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.1",
+  "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",

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/ui/splash-xterm.js

@@ -0,0 +1,290 @@
+/**
+ * @file src/ui/splash-xterm.js
+ * @description In-app splash renderer for xterm.js panels.
+ *
+ * Same choreography as splash.js (CLI) but writes to an xterm Terminal
+ * instance instead of process.stdout. Used by XTermShell.tsx.
+ *
+ * Usage in XTermShell.tsx:
+ *   import { runXtermSplash } from '@inneranimalmedia/agentsam-sdk/ui/splash-xterm';
+ *   import { getXtermOptions } from '@inneranimalmedia/agentsam-sdk/ui/theme';
+ *
+ *   const targetType = connection?.target_type ?? 'platform_vm';
+ *   const term = new Terminal({
+ *     ...getXtermOptions(targetType),
+ *     cols: dimensions.cols,
+ *     rows: dimensions.rows,
+ *   });
+ *
+ *   // After term.open(containerRef.current):
+ *   const stopFlicker = await runXtermSplash(term, {
+ *     apiBase: 'https://inneranimalmedia.com',
+ *     workspaceId: activeWorkspace?.id,
+ *     authToken: session?.token,
+ *     targetType,
+ *     skipArt: !isFirstSession,
+ *   });
+ *
+ *   // On cleanup:
+ *   return () => { stopFlicker(); term.dispose(); };
+ */
+
+import { PALETTE, getLaneTheme } from './theme.js';
+import { probeAll } from './splash.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// xterm write helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ESC = '\x1b';
+const CSI = `${ESC}[`;
+
+const X = {
+  reset:     `${CSI}0m`,
+  bold:      `${CSI}1m`,
+  hide:      `${CSI}?25l`,
+  show:      `${CSI}?25h`,
+  clearLine: `${CSI}2K\r`,
+  up:        (n = 1) => `${CSI}${n}A`,
+  fg: (hex) => {
+    const h = hex.replace('#', '');
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    return `${CSI}38;2;${r};${g};${b}m`;
+  },
+};
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// COLOR BUILDER (per-lane)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildColors() {
+  const R = X.reset;
+  const B = X.bold;
+  return {
+    R, B,
+    TEAL:   X.fg(PALETTE.teal300),
+    AMBER:  X.fg(PALETTE.amber300),
+    STONE:  X.fg('#3a3530'),
+    STONE2: X.fg('#2a2520'),
+    VINE:   X.fg('#1a4a2a'),
+    VINE2:  X.fg('#0f6b3a'),
+    FIRE1:  X.fg('#f97316'),
+    FIRE2:  X.fg('#ef4444'),
+    FIREY:  X.fg('#fef08a'),
+    GRILL:  X.fg('#1e2830'),
+    GRILL2: X.fg('#2d3d4a'),
+    PELT:   X.fg('#8b6f5a'),
+    DIM:    X.fg('#444444'),
+    GHOST:  X.fg('#888888'),
+    WHT:    X.fg('#e2e8f0'),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SCENE DATA
+// ─────────────────────────────────────────────────────────────────────────────
+
+function gorillaRows(C) {
+  const { R, GRILL, GRILL2, PELT, DIM } = C;
+  return [
+    `            ${DIM}░░▒${R}${GRILL2}▓▓▓▓▓▓▓▓${R}${DIM}▒░░${R}`,
+    `          ${DIM}░${R}${GRILL2}▒▓▓${R}${GRILL}█████████████${R}${GRILL2}▓▓▒${R}${DIM}░${R}`,
+    `         ${GRILL2}▒▓${R}${GRILL}███${R}${GRILL2}▒▒${R}${GRILL}████████${R}${GRILL2}▒▒${R}${GRILL}███${R}${GRILL2}▓▒${R}`,
+    `         ${GRILL2}▓${R}${GRILL}████${R}  ${DIM}▒▒▒▒▒▒▒▒${R}  ${GRILL}████${R}${GRILL2}▓${R}`,
+    `        ${GRILL}▓███${R}${GRILL2}▒${R} ${PELT}██${R}${DIM}▒${R}${PELT}████${R}${DIM}▒${R}${PELT}██${R} ${GRILL2}▒${R}${GRILL}███▓${R}`,
+    `        ${GRILL}████${R}  ${PELT}███${R}${DIM}▒▒▒▒${R}${PELT}███${R}  ${GRILL}████${R}`,
+    `        ${GRILL}████${R}${GRILL2}▒${R}  ${PELT}██████████${R}  ${GRILL2}▒${R}${GRILL}████${R}`,
+    `        ${GRILL}████${R}   ${DIM}▒▒▒▒▒▒▒▒▒▒${R}   ${GRILL}████${R}`,
+    `       ${GRILL2}▒${R}${GRILL}████${R}${GRILL2}▓▓▓${R}${GRILL}████████████${R}${GRILL2}▓▓▓${R}${GRILL}████${R}${GRILL2}▒${R}`,
+    `       ${GRILL}██████████████████████████${R}`,
+    `     ${DIM}▒▒${R}${GRILL}████████${R}${GRILL2}▒▒▒▒▒▒▒▒▒▒▒▒${R}${GRILL}████████${R}${DIM}▒▒${R}`,
+    `    ${PELT}▓${R}${GRILL}██████████${R}${DIM}░░░░░░░░░░░░░░${R}${GRILL}██████████${R}${PELT}▓${R}`,
+  ];
+}
+
+function titleBoxLines(C) {
+  const { R, B, TEAL, AMBER } = C;
+  const wide = 26;
+  const h = `${TEAL}═${R}`;
+  return [
+    `${TEAL}╔${R}${h.repeat(wide)}${TEAL}╗${R}`,
+    `${TEAL}║${R}  ${B}${AMBER}INNERANIMAL MEDIA${R}  ${TEAL}║${R}`,
+    `${TEAL}║${R}  ${TEAL}inneranimalmedia.com${R}     ${TEAL}║${R}`,
+    `${TEAL}╚${R}${h.repeat(wide)}${TEAL}╝${R}`,
+  ];
+}
+
+function ladderRows(C) {
+  const { R, TEAL } = C;
+  return [
+    `    ${TEAL}║${R}   ${TEAL}║${R}`,
+    `    ${TEAL}╠═══╣${R}`,
+    `    ${TEAL}║${R}   ${TEAL}║${R}`,
+    `    ${TEAL}╠═══╣${R}`,
+    `    ${TEAL}║${R}   ${TEAL}║${R}`,
+    `    ${TEAL}╠═══╣${R}`,
+    `    ${TEAL}║${R}   ${TEAL}║${R}`,
+  ];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HUD RENDER
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HUD_ITEMS = [
+  { key: 'workspace', icon: '⊞', label: 'Workspace' },
+  { key: 'runtime',   icon: '▣', label: 'Runtime'   },
+  { key: 'tunnel',    icon: '⟁', label: 'Tunnel'    },
+  { key: 'agent',     icon: '⬡', label: 'Agent'     },
+];
+
+const READY_LABELS = {
+  workspace: 'active',
+  runtime:   'ready',
+  tunnel:    'connected',
+  agent:     'online',
+};
+
+function renderHUDLine(states, C) {
+  const { R, B, TEAL, GHOST, WHT, DIM } = C;
+  return HUD_ITEMS.map((item, i) => {
+    const state = states[item.key] || 'checking';
+    let stateStr;
+    if (state === 'ready') {
+      stateStr = `${TEAL}● ${READY_LABELS[item.key]}${R}`;
+    } else if (state === 'checking') {
+      stateStr = `${GHOST}◌ checking...${R}`;
+    } else if (state === 'error') {
+      stateStr = `${X.fg('#ef4444')}✗ error${R}`;
+    } else {
+      stateStr = `${X.fg('#666666')}○ offline${R}`;
+    }
+    const div = i < HUD_ITEMS.length - 1 ? `  ${DIM}│${R}  ` : '';
+    return `${GHOST}${item.icon}${R}  ${B}${WHT}${item.label}${R}  ${stateStr}${div}`;
+  }).join('');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MAIN XTERM SPLASH
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {import('@xterm/xterm').Terminal} term
+ * @param {object} opts
+ * @param {string}  opts.apiBase
+ * @param {string}  opts.workspaceId
+ * @param {string}  opts.authToken
+ * @param {'user_hosted_tunnel'|'platform_vm'|'sandbox'} opts.targetType
+ * @param {boolean} opts.skipArt
+ * @returns {Promise<() => void>} stopFlicker — call on unmount
+ */
+export async function runXtermSplash(term, {
+  apiBase = '',
+  workspaceId = '',
+  authToken = '',
+  targetType = 'platform_vm',
+  skipArt = false,
+} = {}) {
+
+  const lane = getLaneTheme(targetType);
+  const C = buildColors();
+  const { R, B, TEAL, AMBER, GHOST, WHT, DIM, STONE, STONE2, FIRE1, FIRE2 } = C;
+  const PRIMARY = X.fg(lane.colors.primary);
+  const W = term.cols || 80;
+
+  const w  = (s) => term.write(s);
+  const wl = (s = '') => term.write(s + '\r\n');
+
+  w(X.hide);
+  w(`${ESC}c`); // full reset
+  await sleep(60);
+
+  // cd verb flash
+  w(`  ${GHOST}$ ${R}${AMBER}cd ~/inneranimalmedia${R}`);
+  await sleep(340);
+  w(`\r${X.clearLine}`);
+  await sleep(60);
+
+  if (!skipArt) {
+    wl();
+
+    const rows  = gorillaRows(C);
+    const title = titleBoxLines(C);
+    const TITLE_START = 3;
+
+    for (let i = 0; i < rows.length; i++) {
+      const titleIdx = i - TITLE_START;
+      const titlePart = (titleIdx >= 0 && titleIdx < title.length)
+        ? '  ' + title[titleIdx]
+        : '';
+      wl(`  ${rows[i]}${titlePart}`);
+      await sleep(24);
+    }
+
+    wl();
+
+    // Torches
+    w(`  ${FIRE1}  ▓▓▓${R}`);
+    await sleep(90);
+    wl(`${' '.repeat(Math.max(0, W - 14))}${FIRE2}▓▓▓${R}`);
+    await sleep(30);
+
+    // Ledge
+    w('  ');
+    for (let i = 0; i < W - 4; i++) {
+      w((i % 2 === 0) ? `${STONE}█${R}` : `${STONE2}▓${R}`);
+      await sleep(4);
+    }
+    wl();
+    wl(`  ${DIM}${'╌'.repeat(W - 4)}${R}`);
+    await sleep(50);
+
+    // Ladder
+    for (const rung of ladderRows(C)) {
+      wl(rung);
+      await sleep(30);
+    }
+  }
+
+  wl();
+
+  // Start prompt
+  await sleep(skipArt ? 0 : 70);
+  wl(`        ${B}${AMBER}Start ${PRIMARY}▸${R}`);
+  await sleep(40);
+  wl(`        ${GHOST}Type a command to begin.${R}`);
+  await sleep(skipArt ? 0 : 70);
+  wl();
+
+  // HUD — fire probes in parallel
+  const probePromise = probeAll({ apiBase, workspaceId, authToken });
+  const initStates = { workspace: 'checking', runtime: 'checking', tunnel: 'checking', agent: 'checking' };
+
+  wl(`  ${DIM}${'─'.repeat(W - 4)}${R}`);
+  wl();
+  w(`  ${renderHUDLine(initStates, C)}`);
+  wl(); wl();
+  wl(`  ${DIM}${'─'.repeat(W - 4)}${R}`);
+  wl();
+
+  // Update HUD in-place when probes resolve
+  const LINES_BELOW = 4;
+  probePromise.then(resolved => {
+    w(X.up(LINES_BELOW));
+    w(`\r${X.clearLine}`);
+    w(`  ${renderHUDLine(resolved, C)}`);
+    w('\r\n'.repeat(LINES_BELOW));
+    w(X.show);
+    w(`  ${PRIMARY}>${R}  `);
+  });
+
+  // Torch flicker is handled via CSS animation on the panel wrapper
+  // (terminal-lanes.css) — xterm.js decoration API in Phase 2.
+  return () => {};
+}
+
+export default { runXtermSplash };