@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.5

package/src/commands/runtime.js

@@ -0,0 +1,313 @@
+/**
+ * agentsam runtime — local machine runtime (agentsamd) install / doctor / status.
+ * Distinct from agentsam go (cloud service agentsam-go-worker).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import {
+  discoverRuntimeFacts,
+  ensureRuntimeStateDir,
+  runtimeStateDir,
+  writeRuntimeInstallReceipt,
+  RUNTIME_SETUP_SCHEMA,
+} from '../lib/setup/runtime.js';
+import {
+  DARWIN_LAUNCH_LABEL,
+  writeLaunchAgent,
+  writeWindowsScheduledTask,
+  startWindowsScheduledTask,
+  stopWindowsScheduledTask,
+  bootstrapDarwinLaunchAgent,
+  unloadDarwinLaunchAgent,
+} from '../lib/setup/runtime-persist.js';
+import { RUNTIME_PROTOCOL_SCHEMA } from '../../packages/runtime-protocol/src/index.js';
+
+const execFileAsync = promisify(execFile);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const GO_RUNTIME_ROOT = path.join(REPO_ROOT, 'apps/agentsam-go-worker/runtime');
+const AGENTSAMD_MAIN = path.join(GO_RUNTIME_ROOT, 'cmd/agentsamd');
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+function printHelp(write) {
+  writeLine(write, '');
+  writeLine(write, '  Agent Sam · runtime (agentsamd)');
+  writeLine(write, '');
+  writeLine(write, '  agentsam runtime status [--json]');
+  writeLine(write, '  agentsam runtime doctor [--json]');
+  writeLine(write, '  agentsam runtime install [--yes]   build agentsamd + install persistence/bin');
+  writeLine(write, '  agentsam runtime start');
+  writeLine(write, '  agentsam runtime stop');
+  writeLine(write, '  agentsam runtime probe');
+  writeLine(write, '');
+  writeLine(write, '  Persistence: LaunchAgent (Mac) · Scheduled Task (Windows) · spawn+pid (Linux).');
+  writeLine(write, '  Machine daemon ≠ agentsam-go-worker (Cloudflare service).');
+  writeLine(write, '  Setup planner: agentsam setup runtime');
+  writeLine(write, '');
+}
+
+function binDir(home = os.homedir()) {
+  return path.join(home, '.agentsam', 'bin');
+}
+
+function agentsamdPath(home = os.homedir()) {
+  return path.join(binDir(home), process.platform === 'win32' ? 'agentsamd.exe' : 'agentsamd');
+}
+
+function pidPath(home = os.homedir()) {
+  return path.join(runtimeStateDir(home), 'agentsamd.pid');
+}
+
+function listenAddr() {
+  return process.env.AGENTSAMD_LISTEN || '127.0.0.1:18765';
+}
+
+function darwinPlistPath(home) {
+  return path.join(home, 'Library', 'LaunchAgents', `${DARWIN_LAUNCH_LABEL}.plist`);
+}
+
+async function buildAgentsamd(write) {
+  if (!fs.existsSync(path.join(AGENTSAMD_MAIN, 'main.go'))) {
+    throw new Error(`agentsamd source missing at ${AGENTSAMD_MAIN}`);
+  }
+  const out = agentsamdPath();
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  writeLine(write, `  Building agentsamd → ${out}`);
+  await execFileAsync('go', ['build', '-o', out, './cmd/agentsamd'], {
+    cwd: GO_RUNTIME_ROOT,
+    env: { ...process.env, CGO_ENABLED: '0' },
+    timeout: 120000,
+  });
+  try { fs.chmodSync(out, 0o755); } catch { /* ignore */ }
+  return out;
+}
+
+async function probeAgentsamd() {
+  const addr = listenAddr();
+  const url = addr.startsWith('http') ? `${addr}/health` : `http://${addr}/health`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+    const body = await res.json().catch(() => ({}));
+    return { ok: res.ok, status: res.status, body, url };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err), url };
+  }
+}
+
+async function startAgentsamd(home, write) {
+  const bin = agentsamdPath(home);
+  if (!fs.existsSync(bin)) throw new Error('agentsamd_not_installed');
+
+  if (process.platform === 'win32') {
+    try {
+      await startWindowsScheduledTask();
+      writeLine(write, `  Started Scheduled Task · ${listenAddr()}`);
+      await new Promise((r) => setTimeout(r, 600));
+      return probeAgentsamd();
+    } catch (err) {
+      writeLine(write, `  ○ Scheduled Task start failed (${err.message || err}); falling back to spawn`);
+    }
+  }
+
+  if (process.platform === 'darwin') {
+    const plist = darwinPlistPath(home);
+    if (fs.existsSync(plist)) {
+      const boot = await bootstrapDarwinLaunchAgent(plist);
+      if (boot.ok) {
+        writeLine(write, `  Loaded LaunchAgent ${DARWIN_LAUNCH_LABEL}`);
+        await new Promise((r) => setTimeout(r, 400));
+        return probeAgentsamd();
+      }
+    }
+  }
+
+  const child = spawn(bin, ['--listen', listenAddr()], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, AGENTSAMD_ROLE: 'machine' },
+    windowsHide: true,
+  });
+  child.unref();
+  ensureRuntimeStateDir(home);
+  fs.writeFileSync(pidPath(home), String(child.pid));
+  writeLine(write, `  Started agentsamd pid ${child.pid} · ${listenAddr()}`);
+  await new Promise((r) => setTimeout(r, 400));
+  return probeAgentsamd();
+}
+
+async function stopAgentsamd(home, write) {
+  if (process.platform === 'win32') {
+    try {
+      await stopWindowsScheduledTask();
+      writeLine(write, '  Ended Windows Scheduled Task');
+    } catch (err) {
+      writeLine(write, `  ○ Scheduled Task end: ${err.message || err}`);
+    }
+  }
+
+  if (process.platform === 'darwin') {
+    const plist = darwinPlistPath(home);
+    if (fs.existsSync(plist)) {
+      await unloadDarwinLaunchAgent(plist);
+      writeLine(write, `  Unloaded LaunchAgent ${DARWIN_LAUNCH_LABEL}`);
+    }
+  }
+
+  const file = pidPath(home);
+  if (!fs.existsSync(file)) {
+    if (process.platform !== 'win32' && process.platform !== 'darwin') {
+      writeLine(write, '  No pid file — nothing to stop');
+    }
+    return { ok: true, stopped: false };
+  }
+  const pid = Number(fs.readFileSync(file, 'utf8').trim());
+  try {
+    if (Number.isFinite(pid) && pid > 0) process.kill(pid, 'SIGTERM');
+  } catch {
+    /* already dead */
+  }
+  try { fs.unlinkSync(file); } catch { /* ignore */ }
+  writeLine(write, `  Stopped agentsamd${pid ? ` pid ${pid}` : ''}`);
+  return { ok: true, stopped: true, pid };
+}
+
+export async function runRuntime(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+  const json = argv.includes('--json');
+  const yes = argv.includes('--yes') || argv.includes('-y');
+  const args = argv.filter((a) => !['--json', '--yes', '-y', 'help', '--help', '-h'].includes(a));
+  const sub = args[0] || 'status';
+
+  if (argv.includes('help') || argv.includes('--help') || argv.includes('-h')) {
+    printHelp(write);
+    return 0;
+  }
+
+  if (sub === 'status' || sub === 'doctor') {
+    const facts = await discoverRuntimeFacts({ env, home });
+    const probe = await probeAgentsamd();
+    const out = {
+      schema: RUNTIME_SETUP_SCHEMA,
+      protocol: RUNTIME_PROTOCOL_SCHEMA,
+      role: 'machine_daemon',
+      product: 'agentsamd',
+      distinct_from: 'agentsam-go-worker',
+      facts,
+      listen: listenAddr(),
+      probe,
+    };
+    if (json) {
+      write(`${JSON.stringify(out, null, 2)}\n`);
+    } else {
+      writeLine(write, '');
+      writeLine(write, '  Agent Sam · runtime');
+      writeLine(write, `  Protocol   ${RUNTIME_PROTOCOL_SCHEMA}`);
+      writeLine(write, `  Binary     ${facts.agentsamd.installed ? facts.agentsamd.binary : '(not installed)'}`);
+      writeLine(write, `  Listen     ${listenAddr()}`);
+      writeLine(write, `  Health     ${probe.ok ? '✓' : '○'} ${probe.ok ? probe.url : (probe.error || 'unreachable')}`);
+      if (probe.ok && probe.body?.implementation) {
+        writeLine(write, `  Impl       ${probe.body.implementation}`);
+      }
+      writeLine(write, '');
+      writeLine(write, '  Next');
+      writeLine(write, '    agentsam setup runtime');
+      writeLine(write, '    agentsam runtime install --yes');
+      writeLine(write, '');
+    }
+    return probe.ok || facts.agentsamd.installed ? 0 : (sub === 'doctor' ? 2 : 0);
+  }
+
+  if (sub === 'probe') {
+    const probe = await probeAgentsamd();
+    if (json) write(`${JSON.stringify(probe, null, 2)}\n`);
+    else writeLine(write, probe.ok ? `  ✓ ${probe.url}` : `  ✕ ${probe.error || probe.url}`);
+    return probe.ok ? 0 : 2;
+  }
+
+  if (sub === 'stop') {
+    const result = await stopAgentsamd(home, write);
+    if (json) write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  }
+
+  if (sub === 'start') {
+    const probe = await startAgentsamd(home, write);
+    if (json) write(`${JSON.stringify(probe, null, 2)}\n`);
+    else writeLine(write, probe.ok ? '  ✓ agentsamd healthy' : `  ✕ probe failed: ${probe.error || probe.status}`);
+    return probe.ok ? 0 : 2;
+  }
+
+  if (sub === 'install') {
+    if (!yes && process.stdin.isTTY) {
+      writeLine(write, '  Pass --yes to build and install agentsamd into ~/.agentsam/bin');
+    }
+    if (!yes && !process.stdin.isTTY) {
+      writeLine(write, '  Non-interactive: pass --yes');
+      return 1;
+    }
+    if (!yes) {
+      writeLine(write, '  Re-run: agentsam runtime install --yes');
+      return 1;
+    }
+    let binary;
+    try {
+      binary = await buildAgentsamd(write);
+    } catch (err) {
+      writeLine(write, `  ✕ build failed: ${err.message || err}`);
+      return 2;
+    }
+
+    const listen = listenAddr();
+    let persistence = writeLaunchAgent(home, binary, listen);
+    if (persistence) {
+      writeLine(write, `  LaunchAgent  ${persistence.plist}`);
+      const boot = await bootstrapDarwinLaunchAgent(persistence.plist);
+      if (!boot.ok && boot.error) writeLine(write, `  ○ launchctl: ${boot.error}`);
+    } else if (process.platform === 'win32') {
+      persistence = await writeWindowsScheduledTask(home, binary, listen);
+      if (persistence?.xmlPath) writeLine(write, `  Task XML    ${persistence.xmlPath}`);
+      if (persistence?.registered) writeLine(write, `  Scheduled   ${persistence.taskName}`);
+      else if (persistence?.error) writeLine(write, `  ○ schtasks: ${persistence.error}`);
+    } else {
+      writeLine(write, '  Persistence  spawn+pid (Linux — no systemd unit in this cut)');
+    }
+
+    const probe = await startAgentsamd(home, write);
+    const receiptPath = writeRuntimeInstallReceipt({
+      profile_id: 'my_computer',
+      product: 'agentsamd',
+      protocol: RUNTIME_PROTOCOL_SCHEMA,
+      runtime_adapter: 'agentsamd',
+      binary,
+      listen,
+      persistence,
+      launch_agent: persistence?.kind === 'launch_agent' ? persistence : null,
+      scheduled_task: persistence?.kind === 'scheduled_task' ? persistence : null,
+      probe,
+      host: {
+        platform: process.platform,
+        arch: process.arch,
+        hostname: os.hostname(),
+      },
+    }, home);
+    writeLine(write, `  Receipt     ${receiptPath}`);
+    writeLine(write, probe.ok ? '  ✓ agentsamd installed and healthy' : '  ○ installed; start/probe manually');
+    if (json) {
+      write(`${JSON.stringify({ binary, persistence, probe, receiptPath }, null, 2)}\n`);
+    }
+    return probe.ok ? 0 : 2;
+  }
+
+  printHelp(write);
+  writeLine(write, `  Unknown subcommand: ${sub}`);
+  return 1;
+}

package/src/commands/rust.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const entry = path.resolve(here, '../../bin/agentsam-rapid-rust');
+
+export async function runRust(argv = [], options = {}) {
+  const node = options.node || process.execPath;
+  const stdio = options.stdio || 'inherit';
+  return await new Promise((resolve, reject) => {
+    const child = spawn(node, [entry, ...argv], { stdio, env: process.env });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (signal) return reject(new Error(`agentsam rust terminated by ${signal}`));
+      if (code && code !== 0) {
+        const error = new Error(`agentsam rust exited with code ${code}`);
+        error.exitCode = code;
+        return reject(error);
+      }
+      resolve(code ?? 0);
+    });
+  });
+}

package/src/commands/setup.js

@@ -0,0 +1,279 @@
+/**
+ * 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';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+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, '    agentsam gcloud auth login');
+      writeLine(write, '    agentsam google-cloud connection set --identity EMAIL --project PROJECT');
+      writeLine(write, '    agentsam 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');
+      writeLine(write, '  Next: agentsam doctor · agentsam capabilities · agentsam google-cloud doctor');
+      writeLine(write, '');
+    }
+    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, '');
+  writeLine(write, '  Next');
+  writeLine(write, '    agentsam doctor');
+  writeLine(write, '    agentsam capabilities');
+  if (capabilityIds.includes('google.cloud')) {
+    writeLine(write, '    agentsam setup google.cloud --inventory');
+    writeLine(write, '    agentsam gcloud auth login');
+  }
+  if (capabilityIds.includes('image.vectorize')) {
+    writeLine(write, '    agentsam image optimize ./logo.png   # when image command ships');
+  }
+  writeLine(write, '');
+
+  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.`);