@inneranimalmedia/agentsam-sdk 2.2.0 → 2.3.0

package/docs/CLI_SHELL.md

@@ -21,7 +21,15 @@ Runs the optional Python Rich renderer. `--install` creates an isolated `.agents
 agentsam shell
 ```
 
-Shows the command catalog and local PTY / DB / TUI surfaces.
+Starts the interactive Agent Sam slash-command shell. Once the `agentsam>` prompt is visible, commands such as `/help`, `/status`, `/pwd`, and `/git` are handled by Agent Sam instead of the host shell (PowerShell, bash, or zsh). Use `/exit` to return to the host terminal.
+
+Do not type `/help` directly at a PowerShell/bash prompt; enter `agentsam shell` first.
+
+For scripts and regression tests, a single slash command can be dispatched without opening the REPL:
+
+```bash
+agentsam shell --command /help
+```
 
 ## Architecture
 
@@ -92,6 +100,7 @@ Gorilla is intentionally not scaffolded by default.
 /logs       local execution events
 /tui        terminal presentation
 /deploy     intentionally add a cloud adapter
+/exit       exit Agent Sam shell and return to the host terminal
 ```
 
 Provider-specific commands such as `/claude` or `/codex` are not part of the generic shell contract. Model routing belongs behind Agent Sam.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Portable AgentSam SDK and CLI kits for local scaffolding, repository intelligence, incremental indexing, identity adapters, and verified dependency maintenance.",
   "type": "module",
   "main": "./src/index.js",

package/packages/identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk-identity",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": true,
   "type": "module",
   "description": "Identity module for @inneranimalmedia/agentsam-sdk (workspace — publish via root SDK)",

package/src/cli.js

@@ -18,6 +18,7 @@ import { runContext } from './commands/context.js';
 import { runDb } from './commands/db.js';
 import { runStatus } from './commands/status.js';
 import { runTui } from './commands/tui.js';
+import { runShell } from './commands/shell.js';
 import { runDockerize } from './commands/dockerize.js';
 import { runMini } from './commands/mini.js';
 import { runMerkle } from './commands/merkle.js';
@@ -26,7 +27,6 @@ import { runSecurity } from './commands/security.js';
 import { runRecon } from './commands/recon.js';
 import { applyPresetSelection, runAdd, runCapabilities, runDev, runInspect } from './commands/product.js';
 import { listPresets, resolvePreset } from './presets/index.js';
-import { SLASH_COMMANDS, SHELL_PHASES } from './lib/slash-commands.js';
 import fs from 'node:fs';
 import { repositoryRoot } from './knowledge/config.js';
 
@@ -70,7 +70,7 @@ function printHelp() {
     agentsam tui               Zero-dependency ANSI Agent Sam dashboard
     agentsam tui rich          Optional Python Rich dashboard (--install for local venv)
     agentsam start-local       Local PTY on ws://127.0.0.1:3099 (no tunnel, no Cloudflare)
-    agentsam shell             Terminal commands + presentation catalog
+    agentsam shell             Interactive Agent Sam slash-command shell
     agentsam tunnel            Explicitly expose local PTY when remote access is wanted
     agentsam deploy            Graduate to Cloudflare / GCP when ready
     agentsam dockerize         Build/run app, knowledge, or CAD containers (--help)
@@ -257,41 +257,6 @@ async function initFromArgs(argv) {
   await runLocalInit({ ...opts, prompt: null });
 }
 
-async function runShellInfo(argv = []) {
-  const sub = argv[0] || 'list';
-  if (sub === 'demo' || sub === 'ansi') {
-    await runTui(['ansi', ...argv.slice(1)]);
-    return;
-  }
-  if (sub === 'rich') {
-    await runTui(['rich', ...argv.slice(1)]);
-    return;
-  }
-  if (sub !== 'list' && sub !== 'status') {
-    throw new Error(`unknown shell command: ${sub}`);
-  }
-
-  const next = SHELL_PHASES.find((p) => p.status === 'next' || p.status === 'current');
-  console.log(`
-  ╔═══════════════════════════════╗
-  ║        Agent Sam Terminal         ║
-  ╚════════════════════════════════╝
-
-  Local PTY   agentsam start-local     ws://127.0.0.1:3099
-  ANSI TUI    agentsam tui             zero-dependency Node UI
-  Rich TUI    agentsam tui rich        optional richer Python UI
-              agentsam tui rich --install
-  DB          agentsam db status       local SQLite
-
-  Current milestone: ${next?.label ?? 'local terminal experience'}
-
-  Slash commands (${SLASH_COMMANDS.length} registered):
-`);
-  for (const row of SLASH_COMMANDS) {
-    console.log(`    ${row.cmd.padEnd(14)} ${row.description}`);
-  }
-}
-
 const command = process.argv[2];
 const rest = process.argv.slice(3);
 
@@ -353,7 +318,7 @@ if (command === '--version' || command === '-v') {
   }
 } else if (command === 'shell') {
   try {
-    await runShellInfo(rest);
+    await runShell(rest);
   } catch (e) {
     console.error(`\n  ✗ ${e?.message || e}\n`);
     process.exit(1);

package/src/commands/shell.js

@@ -0,0 +1,253 @@
+import readline from 'node:readline';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SLASH_COMMANDS, SHELL_PHASES } from '../lib/slash-commands.js';
+import { runContext } from './context.js';
+import { runDb } from './db.js';
+import { runDeploy } from './deploy.js';
+import { runStatus } from './status.js';
+import { runTui } from './tui.js';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+export function tokenizeShellLine(input = '') {
+  const source = String(input);
+  const tokens = [];
+  let token = '';
+  let quote = '';
+  let started = false;
+
+  const flush = () => {
+    if (!started) return;
+    tokens.push(token);
+    token = '';
+    started = false;
+  };
+
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === quote) {
+        quote = '';
+      } else {
+        token += ch;
+      }
+      started = true;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      flush();
+      continue;
+    }
+    token += ch;
+    started = true;
+  }
+  flush();
+  return tokens;
+}
+
+export function renderShellCatalog() {
+  const next = SHELL_PHASES.find((phase) => phase.status === 'next' || phase.status === 'current');
+  const rows = SLASH_COMMANDS.map((row) => `    ${row.cmd.padEnd(14)} ${row.description}`).join('\n');
+  return `
+  ╔════════════════════════════════╗
+  ║        Agent Sam Terminal      ║
+  ╚════════════════════════════════╝
+
+  Local PTY   agentsam start-local     ws://127.0.0.1:3099
+  ANSI TUI    agentsam tui             zero-dependency Node UI
+  Rich TUI    agentsam tui rich        optional richer Python UI
+              agentsam tui rich --install
+  DB          agentsam db status       local SQLite
+
+  Current milestone: ${next?.label ?? 'local terminal experience'}
+
+  Slash commands (${SLASH_COMMANDS.length} registered):
+${rows}
+`;
+}
+
+function parseDeployOptions(args, cwd) {
+  const opts = { cwd, target: '', accountId: '' };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--target') opts.target = args[++i] || '';
+    else if (arg === '--account-id') opts.accountId = args[++i] || '';
+    else throw new Error(`unknown /deploy option: ${arg}`);
+  }
+  return opts;
+}
+
+async function withProcessCwd(cwd, fn) {
+  const previous = process.cwd();
+  process.chdir(cwd);
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+async function runLocalAgent(goal, write) {
+  if (!goal) {
+    writeLine(write, '  Usage: /agent <goal>');
+    writeLine(write, '  Requires the local Agent Sam dev server (default http://127.0.0.1:8787).');
+    return;
+  }
+  const base = String(process.env.AGENTSAM_LOCAL_URL || 'http://127.0.0.1:8787').replace(/\/$/, '');
+  let response;
+  try {
+    response = await fetch(`${base}/api/agentsam/message`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ message: goal }),
+    });
+  } catch (error) {
+    throw new Error(`local Agent Sam unavailable at ${base} — run \`npm run dev\` first (${error?.message || error})`);
+  }
+  const text = await response.text();
+  if (!response.ok) throw new Error(`local Agent Sam returned HTTP ${response.status}: ${text.slice(0, 400)}`);
+  try {
+    writeLine(write, JSON.stringify(JSON.parse(text), null, 2));
+  } catch {
+    writeLine(write, text);
+  }
+}
+
+async function showLocalLogs(cwd, write) {
+  const dbPath = path.join(cwd, '.agentsam', 'data', 'agentsam.sqlite');
+  if (!fs.existsSync(dbPath)) {
+    writeLine(write, '  No local Agent Sam DB found. Run `agentsam init . --yes` first.');
+    return;
+  }
+  const { createLocalSqliteDatabase } = await import('../local/sqlite.js');
+  const db = await createLocalSqliteDatabase(dbPath);
+  try {
+    const calls = await db
+      .prepare('SELECT id, session_id, tool_name, status, created_at, completed_at FROM agent_tool_calls ORDER BY created_at DESC LIMIT 20')
+      .all();
+    if (!calls.results.length) {
+      writeLine(write, '  No local Agent Sam tool-call events yet.');
+      return;
+    }
+    writeLine(write, '');
+    writeLine(write, '  Recent Agent Sam tool calls');
+    for (const row of calls.results) {
+      writeLine(write, `  ${String(row.created_at || '').padEnd(20)} ${String(row.status || '').padEnd(10)} ${row.tool_name}`);
+    }
+    writeLine(write, '');
+  } finally {
+    db.close();
+  }
+}
+
+export async function dispatchShellLine(line, state = {}) {
+  const tokens = tokenizeShellLine(line);
+  const write = state.write || ((text) => process.stdout.write(text));
+  state.cwd = path.resolve(state.cwd || process.cwd());
+  if (!tokens.length) return { handled: true, exit: false, cwd: state.cwd };
+
+  const [command, ...args] = tokens;
+  try {
+    switch (command.toLowerCase()) {
+      case '/help':
+        write(renderShellCatalog());
+        return { handled: true, exit: false, cwd: state.cwd };
+      case '/exit':
+      case '/quit':
+        return { handled: true, exit: true, cwd: state.cwd };
+      case '/status':
+        await runStatus(args, { cwd: state.cwd });
+        break;
+      case '/context':
+        await runContext(['--cwd', state.cwd, ...args]);
+        break;
+      case '/pwd':
+        writeLine(write, state.cwd);
+        break;
+      case '/cd': {
+        const destination = args.length ? args.join(' ') : process.env.HOME || process.env.USERPROFILE || state.cwd;
+        const next = path.resolve(state.cwd, destination);
+        if (!fs.existsSync(next) || !fs.statSync(next).isDirectory()) throw new Error(`directory not found: ${next}`);
+        state.cwd = next;
+        writeLine(write, state.cwd);
+        break;
+      }
+      case '/git': {
+        const gitArgs = args.length ? args : ['status', '--short', '--branch'];
+        const result = spawnSync('git', gitArgs, { cwd: state.cwd, stdio: 'inherit', shell: false });
+        if (result.error) throw result.error;
+        if (result.status !== 0) throw new Error(`git exited ${result.status}`);
+        break;
+      }
+      case '/db':
+        await runDb(args.length ? args : ['status'], { cwd: state.cwd });
+        break;
+      case '/agent':
+        await runLocalAgent(args.join(' '), write);
+        break;
+      case '/logs':
+        await showLocalLogs(state.cwd, write);
+        break;
+      case '/tui':
+        await withProcessCwd(state.cwd, () => runTui(args));
+        break;
+      case '/deploy':
+        await runDeploy(parseDeployOptions(args, state.cwd));
+        break;
+      default:
+        writeLine(write, `  Unknown Agent Sam command: ${command}`);
+        writeLine(write, '  Type /help for available commands.');
+        return { handled: false, exit: false, cwd: state.cwd };
+    }
+  } catch (error) {
+    writeLine(write, `  ✗ ${error?.message || error}`);
+  }
+
+  return { handled: true, exit: false, cwd: state.cwd };
+}
+
+export async function runShell(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const state = { cwd: path.resolve(options.cwd || process.cwd()), write };
+  const sub = argv[0] || '';
+
+  if (sub === 'list' || sub === 'status') {
+    write(renderShellCatalog());
+    return;
+  }
+  if (sub === '--command' || sub === '--once') {
+    const line = argv.slice(1).join(' ');
+    if (!line) throw new Error(`${sub} requires a slash command`);
+    await dispatchShellLine(line, state);
+    return;
+  }
+  if (sub) throw new Error(`unknown shell option: ${sub}`);
+
+  write(renderShellCatalog());
+  writeLine(write, '  Interactive shell ready. Type /help for commands; /exit to return to your host shell.');
+  writeLine(write, '');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+  if (rl.terminal) {
+    rl.setPrompt('agentsam> ');
+    rl.prompt();
+  }
+
+  for await (const line of rl) {
+    const result = await dispatchShellLine(line, state);
+    if (result.exit) {
+      rl.close();
+      break;
+    }
+    if (rl.terminal) rl.prompt();
+  }
+}

package/src/lib/slash-commands.js

@@ -1,6 +1,6 @@
 /**
  * Canonical slash-command surface for Agent Sam SDK CLI / shell UX.
- * Consumed by the gorilla-shell example and future `agentsam shell` PTY bridge.
+ * Consumed by the interactive `agentsam shell` REPL and presentation layers.
  */
 
 export const SHELL_THEMES = ['NIGHT', 'DAY', 'LAVA', 'VOID'];
@@ -18,6 +18,7 @@ export const SLASH_COMMANDS = [
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
   { cmd: '/tui', description: 'Switch or preview terminal presentation', lane: 'terminal' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
+  { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];
 
 /** Shell UX rollout phases (gorilla-shell → SDK default CLI experience). */

package/test/shell.test.mjs

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { dispatchShellLine, renderShellCatalog, tokenizeShellLine } from '../src/commands/shell.js';
+
+const repoRoot = path.resolve(new URL('..', import.meta.url).pathname);
+
+test('shell tokenizer preserves Windows paths and quoted arguments', () => {
+  assert.deepEqual(tokenizeShellLine('/cd C:\\Users\\conno\\fuelnreetime'), ['/cd', 'C:\\Users\\conno\\fuelnreetime']);
+  assert.deepEqual(tokenizeShellLine('/cd "C:\\Users\\Connor Smith\\repo"'), ['/cd', 'C:\\Users\\Connor Smith\\repo']);
+  assert.deepEqual(tokenizeShellLine('/agent "inspect this repo"'), ['/agent', 'inspect this repo']);
+});
+
+test('shell catalog advertises commands that the REPL owns', () => {
+  const catalog = renderShellCatalog();
+  assert.match(catalog, /\/help\s+Show Agent Sam commands/);
+  assert.match(catalog, /\/status\s+Local project/);
+  assert.match(catalog, /\/exit\s+Exit Agent Sam shell/);
+});
+
+test('dispatch handles help, pwd, cd, and exit without falling through to host shell', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-shell-'));
+  const child = path.join(root, 'child folder');
+  fs.mkdirSync(child);
+  let output = '';
+  const state = { cwd: root, write: (text) => { output += text; } };
+
+  let result = await dispatchShellLine('/help', state);
+  assert.equal(result.handled, true);
+  assert.equal(result.exit, false);
+  assert.match(output, /Slash commands/);
+
+  output = '';
+  result = await dispatchShellLine('/pwd', state);
+  assert.equal(result.handled, true);
+  assert.equal(output.trim(), root);
+
+  output = '';
+  result = await dispatchShellLine('/cd "child folder"', state);
+  assert.equal(result.handled, true);
+  assert.equal(state.cwd, child);
+  assert.equal(output.trim(), child);
+
+  result = await dispatchShellLine('/exit', state);
+  assert.equal(result.exit, true);
+});
+
+test('CLI supports a deterministic one-shot slash command for regression tests', () => {
+  const result = spawnSync(process.execPath, ['src/cli.js', 'shell', '--command', '/help'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /Agent Sam Terminal/);
+  assert.match(result.stdout, /\/help/);
+  assert.match(result.stdout, /\/exit/);
+});

package/test/smoke.mjs

@@ -57,8 +57,8 @@ assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/db'));
 assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/agent'));
 assert.deepEqual(
   listSlashCommands({ lane: 'deploy' }).map(({ cmd }) => cmd),
-  ['/help', '/deploy'],
-  'deploy lane keeps global help and excludes commands from other lanes',
+  ['/help', '/deploy', '/exit'],
+  'deploy lane keeps global shell controls and excludes commands from other lanes',
 );
 
 printContextSummary({