@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/src/commands/setup.js

@@ -0,0 +1,296 @@
+/**
+ * Interactive Agent Sam setup — discover → plan → approve → execute → verify + receipt.
+ */
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { discoverEnvironment, renderEnvironment } from '../lib/setup/discover.js';
+import { buildSetupPlan, renderSetupPlan } from '../lib/setup/planner.js';
+import {
+  collectGooglePermissionInventory,
+  executeSetupPlan,
+} from '../lib/setup/execute.js';
+import { listCapabilityRecipes } from '../lib/setup/recipes.js';
+import {
+  planRuntimeSetup,
+  renderRuntimePlan,
+  writeRuntimePlanReceipt,
+  writeRuntimeInstallReceipt,
+  RUNTIME_PROFILES,
+} from '../lib/setup/runtime.js';
+import { runRuntime } from './runtime.js';
+import { getCliCommand } from '../cli/command-catalog.js';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+function catalogCommand(id, args = '') {
+  const entry = getCliCommand(id);
+  if (!entry) throw new Error(`setup_next_command_not_catalogued: ${id}`);
+  return `agentsam ${entry.id}${args ? ` ${args}` : ''}`;
+}
+
+export function setupNextCommands(capabilityIds = []) {
+  const commands = [
+    catalogCommand('status'),
+    catalogCommand('capabilities'),
+    catalogCommand('google-cloud', 'doctor'),
+  ];
+  if (capabilityIds.includes('google.cloud')) {
+    commands.push(catalogCommand('setup', 'google.cloud --inventory'));
+  }
+  if (capabilityIds.includes('image.vectorize')) {
+    commands.push(catalogCommand('capabilities', 'image.vectorize'));
+  }
+  return [...new Set(commands)];
+}
+
+function writeSetupNext(write, capabilityIds = []) {
+  writeLine(write, '  Next');
+  for (const command of setupNextCommands(capabilityIds)) writeLine(write, `    ${command}`);
+  writeLine(write, '');
+}
+
+function printHelp(write) {
+  writeLine(write, '');
+  writeLine(write, '  Agent Sam · setup');
+  writeLine(write, '');
+  writeLine(write, '  agentsam setup                      interactive discover + plan');
+  writeLine(write, '  agentsam setup --yes                 approve plan non-interactively');
+  writeLine(write, '  agentsam setup --dry-run             plan only');
+  writeLine(write, '  agentsam setup runtime               Discover → profiles → GOAP → receipts');
+  writeLine(write, '  agentsam setup runtime --profile my_computer --yes');
+  writeLine(write, '  agentsam setup image.vectorize       specific capability');
+  writeLine(write, '  agentsam setup google.cloud');
+  writeLine(write, '  agentsam setup google.cloud --inventory');
+  writeLine(write, '  agentsam setup --list');
+  writeLine(write, '  agentsam setup --json');
+  writeLine(write, '');
+  writeLine(write, '  Stages: discover → plan → explain → approve → execute → verify + receipt');
+  writeLine(write, '  Native installers: Homebrew / apt / winget / npm — Agent Sam does not replace them.');
+  writeLine(write, '');
+}
+
+async function confirmProceed(write, { yes = false } = {}) {
+  if (yes) return true;
+  if (!input.isTTY || !output.isTTY) {
+    writeLine(write, '  Non-interactive shell — pass --yes to execute, or --dry-run to plan only.');
+    return false;
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = String(await rl.question('  Proceed? [y/N] ')).trim().toLowerCase();
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+async function runSetupRuntime(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const home = options.home;
+  const json = argv.includes('--json');
+  const yes = argv.includes('--yes') || argv.includes('-y');
+  const dryRun = argv.includes('--dry-run');
+  const profileIdx = argv.findIndex((a) => a === '--profile' || a === '-p');
+  const profileId =
+    profileIdx >= 0 && argv[profileIdx + 1]
+      ? argv[profileIdx + 1]
+      : argv.find((a) => a.startsWith('--profile='))?.slice('--profile='.length) || null;
+
+  if (argv.includes('help') || argv.includes('--help') || argv.includes('-h')) {
+    writeLine(write, '');
+    writeLine(write, '  agentsam setup runtime');
+    writeLine(write, '  Profiles:');
+    for (const p of RUNTIME_PROFILES) {
+      writeLine(write, `    ${p.id.padEnd(18)} ${p.label} — ${p.description}`);
+    }
+    writeLine(write, '');
+    writeLine(write, '  agentsam setup runtime --dry-run');
+    writeLine(write, '  agentsam setup runtime --profile my_computer --yes');
+    writeLine(write, '  Receipts under ~/.agentsam/runtime/');
+    writeLine(write, '');
+    return 0;
+  }
+
+  if (argv.includes('--list')) {
+    if (json) {
+      write(`${JSON.stringify(RUNTIME_PROFILES, null, 2)}\n`);
+    } else {
+      writeLine(write, '');
+      writeLine(write, '  Runtime profiles');
+      for (const p of RUNTIME_PROFILES) {
+        writeLine(write, `    ${p.id.padEnd(18)} ${p.label} — ${p.description}`);
+      }
+      writeLine(write, '');
+    }
+    return 0;
+  }
+
+  const plan = await planRuntimeSetup({ home, profileId });
+  const planPath = writeRuntimePlanReceipt(plan, home);
+  write(renderRuntimePlan(plan));
+
+  if (json && (dryRun || !yes)) {
+    write(JSON.stringify({ plan, plan_receipt: planPath, executed: false }, null, 2) + '\n');
+    return plan.recommended?.eligible ? 0 : 2;
+  }
+
+  if (dryRun || !yes) {
+    writeLine(write, `  Plan receipt  ${planPath}`);
+    if (!yes) {
+      writeLine(write, '  Pass --yes to install agentsamd (when profile needs it) and write install receipt.');
+    }
+    writeLine(write, '');
+    return 0;
+  }
+
+  const recommended = plan.recommended;
+  if (!recommended?.eligible) {
+    writeLine(write, '  ✕ No eligible profile — resolve missing tools/capabilities first.');
+    writeLine(write, '');
+    return 2;
+  }
+
+  let installResult = null;
+  if (recommended.target.runtime_adapter === 'agentsamd') {
+    const code = await runRuntime(['install', '--yes'], { write, home });
+    installResult = { code, adapter: 'agentsamd' };
+    if (code !== 0) return code;
+  }
+
+  const receiptPath = writeRuntimeInstallReceipt({
+    product: 'agentsam-setup-runtime',
+    profile_id: recommended.profile.id,
+    target: recommended.target,
+    goap: recommended.goap,
+    install: installResult,
+    plan_receipt: planPath,
+  }, home);
+
+  writeLine(write, `  ✓ Runtime setup receipt  ${receiptPath}`);
+  writeLine(write, '');
+  if (json) {
+    write(JSON.stringify({
+      plan,
+      plan_receipt: planPath,
+      install_receipt: receiptPath,
+      executed: true,
+    }, null, 2) + '\n');
+  }
+  return 0;
+}
+
+export async function runSetup(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const env = options.env || process.env;
+  const json = argv.includes('--json');
+  const yes = argv.includes('--yes') || argv.includes('-y');
+  const dryRun = argv.includes('--dry-run');
+  const inventory = argv.includes('--inventory');
+  const args = argv.filter(
+    (a) => !['--json', '--yes', '-y', '--dry-run', '--inventory', '--list', 'help', '--help', '-h', '--profile', '-p'].includes(a)
+      && !String(a).startsWith('--profile='),
+  );
+
+  if (argv.includes('help') || argv.includes('--help') || argv.includes('-h')) {
+    printHelp(write);
+    return 0;
+  }
+
+  if (args[0] === 'runtime') {
+    return runSetupRuntime(argv.filter((a) => a !== 'runtime'), options);
+  }
+
+  if (argv.includes('--list')) {
+    const recipes = listCapabilityRecipes();
+    if (json) {
+      write(JSON.stringify(recipes.map((r) => ({
+        id: r.id,
+        displayName: r.displayName,
+        description: r.description,
+        risk: r.risk,
+      })), null, 2) + '\n');
+    } else {
+      writeLine(write, '');
+      writeLine(write, '  Installable capabilities');
+      for (const r of recipes) {
+        writeLine(write, `    ${r.id.padEnd(22)} ${r.displayName}`);
+      }
+      writeLine(write, '');
+    }
+    return 0;
+  }
+
+  if (args[0] === 'google.cloud' && inventory) {
+    const inv = await collectGooglePermissionInventory({ env });
+    if (json) write(JSON.stringify(inv, null, 2) + '\n');
+    else {
+      writeLine(write, '');
+      writeLine(write, '  Agent Sam · Google Cloud permission inventory');
+      writeLine(write, '');
+      const active = inv.config?.core?.account || '(unset)';
+      const project = inv.config?.core?.project || '(unset)';
+      writeLine(write, `  active account   ${active}`);
+      writeLine(write, `  project          ${project}`);
+      writeLine(write, `  auth accounts    ${(inv.auth_list || []).length}`);
+      const scopes = String(inv.user_token_scopes?.scope || '').split(/\s+/).filter(Boolean);
+      writeLine(write, `  token scopes     ${scopes.length ? scopes.length : 'unknown'}`);
+      for (const s of scopes.slice(0, 12)) writeLine(write, `    • ${s}`);
+      const roles = inv.iam_roles_for_active_user?.roles || [];
+      writeLine(write, `  IAM roles        ${roles.length ? roles.join(', ') : '—'}`);
+      writeLine(write, `  projects visible ${(inv.projects || []).length}`);
+      writeLine(write, `  billing accts    ${(inv.billing_accounts || []).length}`);
+      if (inv.errors?.length) {
+        writeLine(write, '');
+        writeLine(write, '  Errors');
+        for (const e of inv.errors) writeLine(write, `    ✕ ${e}`);
+      }
+      writeLine(write, '');
+      writeLine(write, '  Next');
+      writeLine(write, `    ${catalogCommand('google-cloud', 'auth login')}`);
+      writeLine(write, `    ${catalogCommand('google-cloud', 'connection set --identity EMAIL --project PROJECT')}`);
+      writeLine(write, `    ${catalogCommand('google-cloud', 'doctor')}`);
+      writeLine(write, '');
+    }
+    return inv.errors?.length ? 2 : 0;
+  }
+
+  const capabilityIds = args.length ? args : listCapabilityRecipes().map((r) => r.id);
+  const environment = await discoverEnvironment({ env });
+  const plan = await buildSetupPlan({ environment, capabilityIds });
+
+  if (json && dryRun) {
+    write(JSON.stringify({ environment, plan }, null, 2) + '\n');
+    return 0;
+  }
+
+  write(renderEnvironment(environment));
+  write(renderSetupPlan(plan));
+
+  if (dryRun || !plan.would_install.length) {
+    if (!plan.would_install.length) {
+      writeLine(write, '  ✓ setup complete — requested capabilities already satisfied');
+      writeSetupNext(write, capabilityIds);
+    }
+    if (json) write(JSON.stringify({ environment, plan, executed: false }, null, 2) + '\n');
+    return 0;
+  }
+
+  const approved = await confirmProceed(write, { yes });
+  if (!approved) {
+    writeLine(write, '  Cancelled. Re-run with --yes to install, or --dry-run to plan only.');
+    writeLine(write, '');
+    return 1;
+  }
+
+  const receipt = await executeSetupPlan(plan, { env, write, home: options.home });
+  writeLine(write, '');
+  writeLine(write, receipt.ok ? '  ✓ Agent Sam setup complete' : '  ✕ Setup finished with failures');
+  writeLine(write, `  Receipt  ${receipt.path}`);
+  writeLine(write, '');
+  writeSetupNext(write, capabilityIds);
+
+  if (json) write(JSON.stringify({ environment, plan, receipt }, null, 2) + '\n');
+  return receipt.ok ? 0 : 2;
+}

package/src/commands/shell.js

@@ -31,6 +31,9 @@ import { createLocalSession, saveLocalSession, localSessionElapsedMs, loadSessio
 import { runtimeDatabasePath } from '../local/runtime-store.js';
 import { grantExecutionApproval, isExecutionApproved, toolApprovalKey } from '../lib/execution-approvals.js';
 import { runWhoami } from './whoami.js';
+import { runCredentials } from './credentials.js';
+import { runCheatSheet } from './cheat-sheet.js';
+import pkg from '../../package.json' with { type: 'json' };
 import { runLogin, runLogout } from './account-auth.js';
 import { runHelp } from '../ui/cli/help.js';
 import { hydrateSecureCredentials } from '../security/local-vault.js';
@@ -598,7 +601,7 @@ async function runInteractiveModelTurn(prompt, state) {
   const provider = createProviderAdapter({
     modelRecord: model,
     credential,
-    endpoint: model.provider === 'ollama' ? process.env.OLLAMA_BASE_URL : undefined,
+    endpoint: model.provider === 'ollama' ? (process.env.AGENTSAM_OLLAMA_ENDPOINT || process.env.OLLAMA_BASE_URL || process.env.OLLAMA_HOST) : undefined,
     fetchImpl: state.providerFetchImpl,
   });
   const capabilityAdapter = createCapabilityAdapter();
@@ -789,12 +792,14 @@ export async function dispatchShellLine(line, state = {}) {
     const commonVerbs = [
       'help', 'exit', 'quit', 'clear', 'status', 'models', 'model',
       'whoami', 'cf', 'cloudflare', 'db', 'tunnel', 'connections',
-      'connect', 'usage', 'session', 'providers', 'settings', 'logs',
+      'connect', 'usage', 'session', 'providers', 'credentials', 'cheatsheet',
+      'settings', 'logs',
       'git', 'diff', 'pwd', 'cd', 'fast', 'flex', 'standard', 'reasoning',
     ];
     if (commonVerbs.includes(bare)) {
-      tokens[0] = `/${bare}`;
+      tokens[0] = bare === 'cheatsheet' ? '/cheat-sheet' : `/${bare}`;
     }
+    if (bare === 'cheat-sheet') tokens[0] = '/cheat-sheet';
   }
 
   const [command, ...args] = tokens;
@@ -866,6 +871,14 @@ export async function dispatchShellLine(line, state = {}) {
           state.rl?.resume?.();
         }
         break;
+      case '/credentials':
+      case '/credential':
+        await runCredentials(args.length ? args : ['audit'], { write, home: state.home });
+        break;
+      case '/cheat-sheet':
+      case '/cheatsheet':
+        runCheatSheet(args, { write, version: pkg.version });
+        break;
       case '/login':
         await runLogin(args, { write, home: state.home });
         break;

package/src/commands/start-local.js

@@ -32,8 +32,8 @@ export async function runStartLocal(opts = {}) {
   const port = opts.port ?? config?.pty_port ?? 3099;
 
   console.log(`
-  Agent Sam — local PTY
-  No Cloudflare · no tunnel · no IAM login
+  Agent Sam — local Studio plane (PTY + FS)
+  Loopback only · no tunnel · not ExecOS enroll
   `);
   if (!config) {
     console.log(`  ⚠ No .agentsam/config.json found; using current repository/directory as the PTY root.`);

package/src/commands/status.js

@@ -4,6 +4,7 @@ import { buildStatusActionPlan } from '../status/actions.js';
 import { openExternalUrl } from '../lib/open-url.js';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
+import { renderCommandHelp } from '../ui/cli/help.js';
 
 function parseStatusArgs(argv = []) {
   const opts = {
@@ -11,12 +12,14 @@ function parseStatusArgs(argv = []) {
     offline: false,
     discoverModels: true,
     interactive: false,
+    help: false,
   };
   for (const arg of argv) {
     if (arg === '--json') opts.json = true;
     else if (arg === '--offline') opts.offline = true;
     else if (arg === '--no-discover') opts.discoverModels = false;
     else if (arg === '--interactive' || arg === '-i') opts.interactive = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
     else throw new Error(`unknown status option: ${arg}`);
   }
   return opts;
@@ -68,13 +71,17 @@ async function runInteractiveMenu(status, write) {
 
 export async function runStatus(argv = [], opts = {}) {
   const parsed = parseStatusArgs(argv);
+  const write = opts.write || ((value) => process.stdout.write(value));
+  if (parsed.help) {
+    write(renderCommandHelp('status'));
+    return null;
+  }
   const status = await (opts.collectRuntime || collectRuntimeStatus)({
     ...opts,
     cwd: opts.cwd || process.cwd(),
     offline: parsed.offline,
     discoverModels: parsed.discoverModels,
   });
-  const write = opts.write || ((value) => process.stdout.write(value));
   if (parsed.json) {
     const plan = buildStatusActionPlan(status);
     write(`${JSON.stringify({ ...status, next: plan }, null, 2)}\n`);

package/src/commands/terminal.js

@@ -0,0 +1,171 @@
+/**
+ * Device identity + ExecOS pairing.
+ *
+ * Two AgentSam lanes (see docs/contracts/environment-vocabulary.md):
+ *   AGENTSAM_API_KEY    — account / human (CLI, whoami, mint enrollment)
+ *   AGENTSAM_BRIDGE_KEY — one ExecOS terminal_connection (enroll --pair writes it)
+ *
+ * local_device PTY daemons enroll with connection_token → AGENTSAM_BRIDGE_KEY
+ * in ~/.execos/profiles/<instance_id>.env. IAM_CONNECTION_KEY is retired
+ * (dual-read only during migration).
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { postJson } from '../lib/core-client.js';
+import { collectMachineIdentity } from '../lib/terminal/machine-identity.js';
+
+function flag(argv, name) {
+  const index = argv.indexOf(name);
+  if (index === -1) return null;
+  const value = argv[index + 1];
+  if (!value || value.startsWith('--')) return null;
+  return value;
+}
+
+function printIdentity(identity, write) {
+  write(`hostname:  ${identity.hostname || 'unknown'}`);
+  write(`platform:  ${identity.platform || 'unknown'}`);
+  write(`arch:      ${identity.arch || 'unknown'}`);
+  write(`hw_model:  ${identity.model || 'unknown'}`);
+}
+
+function defaultExecosEnrollBin() {
+  return path.join(homedir(), 'ExecOS', 'bin', 'enroll.mjs');
+}
+
+function pairWithExecos(enrollmentToken, options = {}) {
+  const enrollBin = options.enrollBin || process.env.EXECOS_ENROLL_BIN || defaultExecosEnrollBin();
+  const endpoint = options.endpoint || null;
+  const args = [enrollBin, '--token', enrollmentToken, '--force'];
+  if (endpoint) args.push('--tunnel-url', endpoint);
+  const result = spawnSync(process.execPath, args, {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  return {
+    ok: (result.status ?? 1) === 0,
+    status: result.status ?? 1,
+    enroll_bin: enrollBin,
+  };
+}
+
+export async function runTerminal(argv = [], options = {}) {
+  const write = options.write || ((line) => console.log(line));
+  const sub = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'identity';
+  const json = argv.includes('--json') || options.json === true;
+  const pair = argv.includes('--pair') || options.pair === true;
+  const identity = await (options.collectIdentity || collectMachineIdentity)();
+  const payload = {
+    hostname: identity.hostname || null,
+    platform: identity.platform || null,
+    arch: identity.arch || null,
+    hw_model: identity.model || null,
+  };
+
+  if (sub === 'identity') {
+    if (json) write(JSON.stringify(payload));
+    else printIdentity(identity, write);
+    return { ok: true, ...payload };
+  }
+
+  if (sub !== 'enroll') {
+    write([
+      'Usage: agentsam terminal identity [--json]',
+      '       agentsam terminal enroll --instance <id> [--endpoint <url>] [--pair] [--json]',
+      '',
+      'Lanes:',
+      '  AGENTSAM_API_KEY      account (CLI / whoami / mint enrollment) — required for this command',
+      '  AGENTSAM_BRIDGE_KEY   one terminal_connection secret (written by --pair into ExecOS profile)',
+    ].join('\n'));
+    return { ok: false, error: 'terminal_usage' };
+  }
+
+  const instanceId = flag(argv, '--instance') || options.instanceId || null;
+  const endpoint = flag(argv, '--endpoint') || options.endpoint || null;
+  if (!instanceId && !endpoint) {
+    if (json) {
+      write(JSON.stringify({ ...payload, enrolled: false, reason: 'instance_or_endpoint_required' }));
+    } else {
+      printIdentity(identity, write);
+      write('');
+      write('Pass --instance <id> to stamp/re-pair an existing device, or --endpoint <url> for a new local_device.');
+      write('Requires AGENTSAM_API_KEY in the shell (source ~/.agentsam/load-agent-env.sh).');
+      write('Add --pair to mint a connection_token and run ExecOS enroll (writes AGENTSAM_BRIDGE_KEY).');
+    }
+    return { ok: true, enrolled: false, ...payload };
+  }
+
+  const body = {
+    hostname: payload.hostname,
+    platform: payload.platform,
+    arch: payload.arch,
+    hw_model: payload.hw_model,
+    kind: 'local_device',
+    name: payload.hostname || undefined,
+  };
+  if (instanceId) {
+    body.instance_id = instanceId;
+    body.create_transport = false;
+  }
+  if (endpoint) body.endpoint_url = endpoint;
+
+  const post = options.postJson || postJson;
+  let result;
+  try {
+    result = await post('/api/terminal/connections/enrollment-token', body, options);
+  } catch (error) {
+    const message = error?.message || String(error);
+    if (json) {
+      write(JSON.stringify({ ok: false, error: message, ...payload }));
+    } else {
+      write(`enroll failed: ${message}`);
+      if (/Unauthorized|SESSION_MISSING|IAM_OAUTH_ISSUER/i.test(message)) {
+        write('next: source ~/.agentsam/load-agent-env.sh   # AGENTSAM_API_KEY + IAM_OAUTH_ISSUER');
+      }
+    }
+    return { ok: false, error: message, ...payload };
+  }
+
+  const out = {
+    ...payload,
+    enrolled: true,
+    instance_id: result?.instance_id || null,
+    connection_id: result?.connection_id || null,
+    enrollment_token_id: result?.enrollment_token_id || null,
+    auth_mode: 'connection_token',
+  };
+
+  let paired = null;
+  if (pair && result?.enrollment_token) {
+    if (options.pairImpl) {
+      paired = await options.pairImpl(result.enrollment_token, { endpoint: result.endpoint_url || endpoint });
+    } else {
+      paired = pairWithExecos(result.enrollment_token, {
+        endpoint: result.endpoint_url || endpoint,
+        enrollBin: options.enrollBin,
+      });
+    }
+    out.paired = paired?.ok === true;
+  }
+
+  if (json) write(JSON.stringify({ ...out, enrollment_token: pair ? undefined : (result?.enrollment_token || null) }));
+  else {
+    write(`instance:   ${out.instance_id || 'unknown'}`);
+    write(`connection: ${out.connection_id || 'unknown'}`);
+    printIdentity(identity, write);
+    write('auth_mode:  connection_token → AGENTSAM_BRIDGE_KEY (one terminal_connection)');
+    write('account:    AGENTSAM_API_KEY (CLI / whoami — keep loaded in the shell)');
+    if (pair) {
+      write(paired?.ok ? '✓ ExecOS paired — AGENTSAM_BRIDGE_KEY written to private profile' : '✗ ExecOS pair failed');
+    } else if (result?.enrollment_token) {
+      write('Finish on that machine: node ~/ExecOS/bin/enroll.mjs --token <token> --force');
+    }
+  }
+  return {
+    ok: true,
+    ...out,
+    enrollment_token: result?.enrollment_token || null,
+    pair_result: paired,
+  };
+}