@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

package/src/commands/preferences.js

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts';
+import { collectModelsStatus } from './models.js';
+import { detectCliProject, readCliPreferences, writeCliPreferences } from '../lib/cli-preferences.js';
+
+function stopIfCancelled(value) {
+  if (!isCancel(value)) return value;
+  cancel('Agent Sam setup cancelled.');
+  const error = new Error('setup_cancelled');
+  error.code = 'AGENTSAM_SETUP_CANCELLED';
+  throw error;
+}
+
+function commandExists(command) {
+  const probe = process.platform === 'win32' ? ['where', [command]] : ['sh', ['-lc', `command -v ${command}`]];
+  return spawnSync(probe[0], probe[1], { stdio: 'ignore' }).status === 0;
+}
+
+export function availableShells(env = process.env) {
+  const values = [];
+  const detected = path.basename(env.SHELL || env.ComSpec || '').trim();
+  if (detected) values.push(detected);
+  for (const shell of ['zsh', 'bash', 'fish', 'pwsh']) {
+    if (!values.includes(shell) && commandExists(shell)) values.push(shell);
+  }
+  return values.length ? values : ['shell'];
+}
+
+function modelOptions(status) {
+  const options = [{ value: 'auto', label: 'Automatic', hint: 'connected host/runtime decides' }];
+  if (status.local?.online) {
+    for (const row of status.local.models || []) {
+      if (row?.name) options.push({ value: `ollama:${row.name}`, label: `Ollama · ${row.name}`, hint: 'local' });
+    }
+  }
+  for (const provider of status.providers || []) {
+    if (provider.configured) options.push({ value: `${provider.id}:auto`, label: provider.label, hint: 'provider configured' });
+  }
+  return options;
+}
+
+export async function configureCliPreferences({ cwd = process.cwd(), firstRun = false } = {}) {
+  let identity = detectCliProject(cwd);
+  const existing = readCliPreferences(identity.root) || {};
+  intro(firstRun ? 'Welcome to Agent Sam' : 'Agent Sam settings');
+
+  const projectChoice = stopIfCancelled(await select({
+    message: 'Where should Agent Sam work?',
+    initialValue: 'current',
+    options: [
+      { value: 'current', label: `This project · ${identity.project}`, hint: identity.root },
+      { value: 'other', label: 'Choose another folder' },
+    ],
+  }));
+
+  if (projectChoice === 'other') {
+    const folder = stopIfCancelled(await text({
+      message: 'Project folder',
+      placeholder: identity.root,
+      defaultValue: identity.root,
+      validate(value) {
+        const resolved = path.resolve(String(value || ''));
+        if (!fs.existsSync(resolved)) return 'Folder does not exist';
+        if (!fs.statSync(resolved).isDirectory()) return 'Path is not a directory';
+      },
+    }));
+    identity = detectCliProject(path.resolve(String(folder)));
+  }
+
+  const runtime = stopIfCancelled(await select({
+    message: 'Runtime',
+    initialValue: existing.runtime || 'local',
+    options: [
+      { value: 'local', label: 'Local machine', hint: 'real shell + filesystem' },
+      { value: 'remote', label: 'Remote', hint: 'connected remote runtime' },
+      { value: 'sandbox', label: 'Sandbox', hint: 'isolated disposable runtime' },
+    ],
+  }));
+
+  const shells = availableShells();
+  const terminal = stopIfCancelled(await select({
+    message: 'Terminal',
+    initialValue: existing.terminal && shells.includes(existing.terminal) ? existing.terminal : shells[0],
+    options: shells.map((shell) => ({ value: shell, label: shell, hint: shell === shells[0] ? 'detected/default' : undefined })),
+  }));
+
+  let status = { providers: [], local: { online: false, models: [] } };
+  try { status = await collectModelsStatus(); } catch { /* inventory is best-effort */ }
+  const models = modelOptions(status);
+  const initialModel = models.some((row) => row.value === existing.modelPreference) ? existing.modelPreference : 'auto';
+  const modelPreference = stopIfCancelled(await select({
+    message: 'Model preference',
+    initialValue: initialModel,
+    options: models,
+  }));
+
+  const preferences = writeCliPreferences(identity.root, { runtime, terminal, modelPreference });
+  outro(`Ready · ${identity.project}`);
+  return { identity, preferences };
+}

package/src/commands/product.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { getCapability, getCapabilityManifest, listCapabilities, repositorySnapshot } from '../capabilities/index.js';
+import { getCapability, getCapabilityManifest, listCapabilities, projectRepositorySnapshot, repositorySnapshot } from '../capabilities/index.js';
 import { getAddon, listAddons, listPresets } from '../presets/index.js';
+import { projectConfigPath, readProjectConfig, setDeployTarget, setProductPreset, writeProjectConfig } from '../lib/project-config.js';
 
 function parseCommon(argv = []) {
   const out = { json: false, cwd: process.cwd(), positionals: [] };
@@ -18,24 +19,94 @@ function parseCommon(argv = []) {
 export async function runInspect(argv = []) {
   const opts = parseCommon(argv);
   let churnDays = 30;
+  let view = 'index';
+  let viewExplicit = false;
+  let limit = 50;
+  let facetLimit = 48;
+  let pretty = false;
+  let snapshotFile = '';
+  let saveSnapshot = '';
+  const filters = {};
+  const addFilter = (field, value) => {
+    const clean = String(value || '').trim();
+    if (!clean) throw new Error(`inspect_${field}_value_required`);
+    (filters[field] ||= []).push(clean);
+  };
+  const filterFlags = new Map([
+    ['--system', 'system'], ['--package', 'package'], ['--category', 'category'], ['--layer', 'layer'],
+    ['--kind', 'kind'], ['--language', 'language'], ['--role', 'role'], ['--execution-domain', 'execution_domain'], ['--tag', 'tag'],
+    ['--path', 'path'], ['--symbol', 'symbol'], ['--import', 'import'], ['--match', 'match'],
+  ]);
   for (let i = 0; i < opts.positionals.length; i += 1) {
-    if (opts.positionals[i] === '--churn-days') churnDays = Number(opts.positionals[++i] || 30);
-    else if (opts.positionals[i] === 'repository') continue;
-    else throw new Error(`unknown inspect option: ${opts.positionals[i]}`);
+    const arg = opts.positionals[i];
+    if (arg === '--churn-days') churnDays = Number(opts.positionals[++i] || 30);
+    else if (arg === '--view') { view = String(opts.positionals[++i] || '').trim().toLowerCase(); viewExplicit = true; }
+    else if (arg === '--limit') limit = Number(opts.positionals[++i] || 50);
+    else if (arg === '--facet-limit') facetLimit = Number(opts.positionals[++i] || 48);
+    else if (arg === '--pretty') pretty = true;
+    else if (arg === '--full') { view = 'full'; viewExplicit = true; }
+    else if (arg === '--index') { view = 'index'; viewExplicit = true; }
+    else if (arg === '--snapshot-file') snapshotFile = String(opts.positionals[++i] || '').trim();
+    else if (arg === '--save-snapshot') saveSnapshot = String(opts.positionals[++i] || '').trim();
+    else if (filterFlags.has(arg)) addFilter(filterFlags.get(arg), opts.positionals[++i]);
+    else if (arg === 'repository') continue;
+    else throw new Error(`unknown inspect option: ${arg}`);
   }
-  const result = await repositorySnapshot({ cwd: opts.cwd, churnDays });
-  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-  else {
+  if (!['full', 'index', 'files'].includes(view)) throw new Error(`invalid inspect view: ${view}`);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error('inspect limit must be an integer from 1..500');
+  if (!Number.isInteger(facetLimit) || facetLimit < 1 || facetLimit > 200) throw new Error('inspect facet limit must be an integer from 1..200');
+  if (Object.keys(filters).length && !viewExplicit) view = 'files';
+  else if (Object.keys(filters).length && view === 'full') view = 'files';
+  if (argv.includes('--snapshot-file') && !snapshotFile) throw new Error('inspect_snapshot_file_value_required');
+  if (argv.includes('--save-snapshot') && !saveSnapshot) throw new Error('inspect_save_snapshot_value_required');
+
+  const result = snapshotFile
+    ? JSON.parse(fs.readFileSync(path.resolve(opts.cwd, snapshotFile), 'utf8'))
+    : await repositorySnapshot({ cwd: opts.cwd, churnDays });
+  if (!result || result.capability !== 'repository.snapshot' || !result.snapshot_id || !result.tree) {
+    throw new Error('inspect_snapshot_file_invalid');
+  }
+  if (saveSnapshot) {
+    const filename = path.resolve(opts.cwd, saveSnapshot);
+    fs.mkdirSync(path.dirname(filename), { recursive: true });
+    fs.writeFileSync(filename, `${JSON.stringify(result)}\n`, 'utf8');
+  }
+  const output = view === 'full' ? result : projectRepositorySnapshot(result, { view, filters, limit, facetLimit });
+  if (opts.json) process.stdout.write(`${JSON.stringify(output, null, pretty ? 2 : 0)}\n`);
+  else if (view !== 'full') {
+    console.log(`\nRepository snapshot ${result.snapshot_id} · ${view}`);
+    console.log(`  repo       ${result.repository.full_name || result.repository.repository_id || '(local)'}`);
+    console.log(`  revision   ${result.repository.revision_sha}`);
+    console.log(`  merkle     ${result.tree.merkle_root}`);
+    console.log(`  metadata   ${result.tree.metadata_root}`);
+    console.log(`  matched    ${output.projection.matched}${output.projection.truncated ? ` (showing ${output.projection.returned})` : ''}`);
+    const systems = output.facets.systems.slice(0, 12).map((row) => `${row.value}:${row.count}`).join(', ');
+    if (systems) console.log(`  systems    ${systems}`);
+    const trust = output.analysis?.trust_boundary;
+    if (trust) {
+      console.log(`  trust      ${trust.status}${trust.finding_count ? ` · ${trust.finding_count} contradiction${trust.finding_count === 1 ? '' : 's'}` : ''}`);
+      for (const finding of trust.findings || []) {
+        console.log(`    ! ${finding.kind}: ${finding.source}${finding.target ? ` → ${finding.target}` : finding.specifier ? ` · ${finding.specifier}` : finding.env ? ` · ${finding.env}` : ''}`);
+        if (finding.repair_action) console.log(`      repair: ${finding.repair_action}`);
+      }
+      if (trust.findings_truncated) console.log(`    … ${trust.finding_count - trust.findings_returned} more contradiction(s); use --view full --json for full evidence`);
+    }
+    if (view === 'files') for (const file of output.files) console.log(`  ${file.path}  [${file.system || '-'} / ${file.category || '-'} / ${file.execution_domain || 'unknown'}]`);
+    console.log('');
+  } else {
     console.log(`\nRepository snapshot ${result.snapshot_id}`);
     console.log(`  repo       ${result.repository.full_name || result.repository.repository_id || '(local)'}`);
     console.log(`  revision   ${result.repository.revision_sha}`);
     console.log(`  merkle     ${result.tree.merkle_root}`);
+    console.log(`  metadata   ${result.tree.metadata_root}`);
     console.log(`  files      ${result.intelligence.summary?.file_count ?? result.tree.stats?.files ?? 'unknown'}`);
     console.log(`  knowledge  ${result.knowledge?.indexed ? result.knowledge.generation_id : result.knowledge?.configured ? 'configured / not indexed' : 'not configured'}`);
+    const trust = result.analysis?.trust_boundary;
+    if (trust) console.log(`  trust      ${trust.status}${trust.findings?.length ? ` · ${trust.findings.length} contradiction${trust.findings.length === 1 ? '' : 's'}` : ''}`);
     console.log(`  deploy     ${result.deploy?.status || 'no trusted receipt'}`);
     console.log(`  content    ${result.content_hash}\n`);
   }
-  return result;
+  return output;
 }
 
 export async function runCapabilities(argv = []) {
@@ -53,16 +124,15 @@ export async function runCapabilities(argv = []) {
   return result;
 }
 
-function projectConfigPath(cwd) { return path.join(cwd, '.agentsam', 'config.json'); }
 function featureStatePath(cwd) { return path.join(cwd, '.agentsam', 'features.json'); }
 
 export function applyPresetSelection(cwd, preset) {
   const filename = projectConfigPath(cwd);
   if (!fs.existsSync(filename)) throw new Error('not_agentsam_project');
-  const config = JSON.parse(fs.readFileSync(filename, 'utf8'));
-  const next = { ...config, preset: preset.id, features: [...preset.features], capabilities: [...preset.capabilities] };
-  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
-  return next;
+  const config = readProjectConfig(cwd);
+  setProductPreset(config, preset);
+  writeProjectConfig(cwd, config);
+  return config;
 }
 
 export async function runAdd(argv = []) {
@@ -84,9 +154,9 @@ export async function runAdd(argv = []) {
   state.features[addon.id] = { selected: true, capabilities: addon.capabilities, selected_at: new Date().toISOString() };
   fs.writeFileSync(featureStatePath(cwd), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
   if (addon.id === 'deploy-cloudflare') {
-    const config = JSON.parse(fs.readFileSync(projectConfigPath(cwd), 'utf8'));
-    config.deploy_target = 'cloudflare';
-    fs.writeFileSync(projectConfigPath(cwd), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    const config = readProjectConfig(cwd);
+    setDeployTarget(config, 'cloudflare');
+    writeProjectConfig(cwd, config);
   }
   const result = { ok: true, feature: addon.id, capabilities: addon.capabilities, description: addon.description, state_file: '.agentsam/features.json' };
   if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/src/commands/security.js

@@ -3,16 +3,16 @@ import { scanProjectSecurity, reportExitCode, repairProject, formatSecurityRepor
 import { runProcess } from '../security/process.js';
 
 const help = [
-  'Agent Sam · dependency health',
+  'Agent Sam · security',
   '  agentsam security scan [--path DIR] [--offline] [--json]',
   '  agentsam security check --log FILE [--path DIR] [--json]',
   '  agentsam security run [--path DIR] [--json] -- COMMAND ARGS...',
   '  agentsam security repair [--path DIR] [--log FILE] [--apply] [--verify SCRIPT] [--json]',
   '  agentsam sca ...                 alias',
   '',
-  'scan/check: exact npm lockfile versions, full OSV advisories, deprecations and log triage.',
+  'scan/check: npm/OSV evidence plus AST+Merkle client/server trust-boundary contradictions.',
   'run: execute an explicitly supplied install/build command, then check its logs and dependencies.',
-  'repair: plan by default; --apply updates an isolated Git worktree, installs, verifies and rescans.',
+  'repair: plans dependency + trust-boundary repairs; --apply automates dependency-only repairs in an isolated worktree.',
   'Online lookup sends package names/versions to OSV, never source code or deployment logs.',
   'Offline is inventory only and exits 2. pnpm/Yarn/Bun graphs are explicitly unsupported.',
   'Exit: 0 clean/verified, 1 unresolved findings or command failure, 2 incomplete/error.',

package/src/commands/shell.js

@@ -1,18 +1,40 @@
 import readline from 'node:readline';
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 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';
+import { runModels } from './models.js';
+import { configureCliPreferences } from './preferences.js';
+import { createRuntimeActivity } from '../ui/runtime-activity.js';
 
 function writeLine(write, value = '') {
   write(`${value}\n`);
 }
 
+export function compactCwd(value, home = process.env.HOME || process.env.USERPROFILE || '') {
+  const cwd = path.resolve(value);
+  const resolvedHome = home ? path.resolve(home) : '';
+  if (!resolvedHome) return cwd;
+  if (cwd === resolvedHome) return '~';
+  return cwd.startsWith(`${resolvedHome}${path.sep}`) ? `~${cwd.slice(resolvedHome.length)}` : cwd;
+}
+
+export function shellUsername(env = process.env) {
+  const fromEnv = String(env.USER || env.USERNAME || '').trim();
+  if (fromEnv) return fromEnv;
+  try { return String(os.userInfo().username || '').trim() || 'user'; }
+  catch { return 'user'; }
+}
+
+export function renderShellPrompt(cwd, env = process.env) {
+  return `${shellUsername(env)} ${compactCwd(cwd, env.HOME || env.USERPROFILE || '')} > `;
+}
+
 export function tokenizeShellLine(input = '') {
   const source = String(input);
   const tokens = [];
@@ -63,9 +85,7 @@ export function renderShellCatalog() {
   ╚════════════════════════════════╝
 
   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
+  Models      agentsam models          providers + local model inventory
   DB          agentsam db status       local SQLite
 
   Current milestone: ${next?.label ?? 'local terminal experience'}
@@ -86,35 +106,44 @@ function parseDeployOptions(args, cwd) {
   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) {
+export async function runLocalAgent(goal, write, options = {}) {
   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(/\/$/, '');
+  const fetchImpl = options.fetchImpl || fetch;
+  const activity = options.activity || createRuntimeActivity({
+    write,
+    phase: 'thinking',
+    interactive: options.interactive,
+  });
   let response;
+  activity.start('thinking');
   try {
-    response = await fetch(`${base}/api/agentsam/message`, {
+    response = await fetchImpl(`${base}/api/agentsam/message`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ message: goal }),
     });
   } catch (error) {
+    activity.fail('unavailable');
     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)}`);
+  let text;
+  try {
+    text = await response.text();
+  } catch (error) {
+    activity.fail('response error');
+    throw new Error(`local Agent Sam response could not be read: ${error?.message || error}`);
+  }
+  if (!response.ok) {
+    activity.fail(`HTTP ${response.status}`);
+    throw new Error(`local Agent Sam returned HTTP ${response.status}: ${text.slice(0, 400)}`);
+  }
+  activity.succeed('done');
   try {
     writeLine(write, JSON.stringify(JSON.parse(text), null, 2));
   } catch {
@@ -192,14 +221,19 @@ export async function dispatchShellLine(line, state = {}) {
         await runDb(args.length ? args : ['status'], { cwd: state.cwd });
         break;
       case '/agent':
-        await runLocalAgent(args.join(' '), write);
+        await runLocalAgent(args.join(' '), write, { interactive: state.interactive });
+        break;
+      case '/models':
+        await runModels(args, { cwd: state.cwd, write });
         break;
+      case '/settings': {
+        const configured = await configureCliPreferences({ cwd: state.cwd, firstRun: false });
+        state.cwd = configured.identity.root;
+        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;
@@ -217,7 +251,7 @@ export async function dispatchShellLine(line, state = {}) {
 
 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 state = { cwd: path.resolve(options.cwd || process.cwd()), write, interactive: options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY) };
   const sub = argv[0] || '';
 
   if (sub === 'list' || sub === 'status') {
@@ -232,13 +266,20 @@ export async function runShell(argv = [], options = {}) {
   }
   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, '');
+  if (options.intro !== 'quiet') {
+    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) });
+  const promptText = () => {
+    if (typeof options.prompt === 'function') return options.prompt(state);
+    if (typeof options.prompt === 'string' && options.prompt) return options.prompt;
+    return renderShellPrompt(state.cwd);
+  };
   if (rl.terminal) {
-    rl.setPrompt('agentsam> ');
+    rl.setPrompt(promptText());
     rl.prompt();
   }
 
@@ -248,6 +289,9 @@ export async function runShell(argv = [], options = {}) {
       rl.close();
       break;
     }
-    if (rl.terminal) rl.prompt();
+    if (rl.terminal) {
+      rl.setPrompt(promptText());
+      rl.prompt();
+    }
   }
 }

package/src/commands/skills.js

@@ -0,0 +1,66 @@
+import { getSkill, listSkills, loadSkill } from '../skills/index.js';
+
+function parse(argv = []) {
+  const out = { id: '', json: false, references: false };
+  for (const arg of argv) {
+    if (arg === '--json') out.json = true;
+    else if (arg === '--references' || arg === '--full') out.references = true;
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg.startsWith('-')) throw new Error(`Unknown skills option: ${arg}`);
+    else if (!out.id) out.id = arg;
+    else throw new Error('Only one skill id or alias may be supplied.');
+  }
+  return out;
+}
+
+function help() {
+  return [
+    'Agent Sam · skills',
+    '  agentsam skills                         list portable skills',
+    '  agentsam skills <id-or-alias>           print compact skill instructions',
+    '  agentsam skills <id-or-alias> --references  include on-demand references',
+    '  agentsam skills <id-or-alias> --json    machine-readable skill payload',
+    '',
+    'Examples:',
+    '  agentsam skills quick-bytes',
+    '  agentsam skills no-regress --references',
+    '',
+  ].join('\n');
+}
+
+export function runSkills(argv = []) {
+  const opts = parse(argv);
+  if (opts.help) {
+    process.stdout.write(help());
+    return null;
+  }
+
+  if (!opts.id) {
+    const skills = listSkills();
+    if (opts.json) process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
+    else {
+      process.stdout.write('Agent Sam · portable skills\n\n');
+      for (const skill of skills) {
+        const aliases = (skill.aliases || []).length ? ` (${skill.aliases.join(', ')})` : '';
+        process.stdout.write(`  ${skill.id}${aliases}\n    ${skill.description}\n`);
+      }
+      process.stdout.write('\n');
+    }
+    return skills;
+  }
+
+  if (!getSkill(opts.id)) throw new Error(`Unknown skill: ${opts.id}`);
+  const loaded = loadSkill(opts.id, { references: opts.references });
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(loaded, null, 2)}\n`);
+    return loaded;
+  }
+
+  process.stdout.write(`${loaded.instructions.trimEnd()}\n`);
+  if (loaded.references?.length) {
+    for (const reference of loaded.references) {
+      process.stdout.write(`\n---\nReference: ${reference.path}\n---\n\n${reference.content.trimEnd()}\n`);
+    }
+  }
+  return loaded;
+}

package/src/commands/start-local.js

@@ -50,7 +50,7 @@ export async function runStartLocal(opts = {}) {
   Project services:
     npm run dev          → local Agent Sam API http://127.0.0.1:${config?.dev_port ?? 8787}
     npm run db:status    → inspect local SQLite
-    npm run tui          → ANSI Agent Sam dashboard
+    npx agentsam          → enter Agent Sam
 
   Press Ctrl+C to stop.
   `);

package/src/commands/tunnel.js

@@ -7,6 +7,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { authenticateViaBrowser } from '../lib/auth.js';
 import { postJson } from '../lib/core-client.js';
+import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
 
 const DEFAULT_PORT = 3099;
 
@@ -32,7 +33,7 @@ function parseArgs(argv) {
     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];
+      process.env.AGENTSAM_SDK_KEY = argv[++i];
     }
   }
   return opts;
@@ -50,12 +51,12 @@ function ensureCloudflared() {
 }
 
 async function resolveToken() {
-  const existing = String(process.env.AGENTSAM_SDK_TOKEN || '').trim();
+  const existing = resolveSdkKey(process.env);
   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;
+  if (!tok.startsWith('sdk_')) throw new Error('IAM auth did not return an sdk_ bearer key');
+  process.env.AGENTSAM_SDK_KEY = tok;
   return tok;
 }
 

package/src/context/budget.js

@@ -0,0 +1,58 @@
+export const DEFAULT_CONTEXT_RATIOS = Object.freeze({
+  targetInputRatio: 0.60,
+  hardInputRatio: 0.85,
+  charsPerToken: 4,
+});
+
+function ratio(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) throw new RangeError(`${label} must be > 0 and <= 1`);
+  return value;
+}
+
+function positiveNumber(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) throw new RangeError(`${label} must be positive`);
+  return value;
+}
+
+function positiveInteger(value, label) {
+  if (!Number.isInteger(value) || value < 1) throw new RangeError(`${label} must be a positive integer`);
+  return value;
+}
+
+export function createContextBudget(options = {}) {
+  const windowTokens = positiveInteger(options.windowTokens, 'windowTokens');
+  const charsPerToken = positiveNumber(options.charsPerToken ?? DEFAULT_CONTEXT_RATIOS.charsPerToken, 'charsPerToken');
+  const targetInputRatio = ratio(options.targetInputRatio ?? DEFAULT_CONTEXT_RATIOS.targetInputRatio, 'targetInputRatio');
+  const hardInputRatio = ratio(options.hardInputRatio ?? DEFAULT_CONTEXT_RATIOS.hardInputRatio, 'hardInputRatio');
+  if (targetInputRatio >= hardInputRatio) throw new RangeError('targetInputRatio must be lower than hardInputRatio');
+
+  const windowChars = Math.floor(windowTokens * charsPerToken);
+  const targetInputTokens = Math.floor(windowTokens * targetInputRatio);
+  const hardInputTokens = Math.floor(windowTokens * hardInputRatio);
+  const targetInputChars = Math.floor(windowChars * targetInputRatio);
+  const hardInputChars = Math.floor(windowChars * hardInputRatio);
+
+  return Object.freeze({
+    windowTokens,
+    windowChars,
+    charsPerToken,
+    targetInputRatio,
+    hardInputRatio,
+    targetInputTokens,
+    hardInputTokens,
+    targetInputChars,
+    hardInputChars,
+    maxSystemChars: positiveInteger(options.maxSystemChars ?? Math.max(4_000, Math.min(60_000, Math.floor(windowChars * 0.05))), 'maxSystemChars'),
+    maxToolSchemaChars: positiveInteger(options.maxToolSchemaChars ?? Math.max(4_000, Math.min(40_000, Math.floor(windowChars * 0.04))), 'maxToolSchemaChars'),
+    maxEvidenceChars: positiveInteger(options.maxEvidenceChars ?? Math.max(8_000, Math.min(100_000, Math.floor(targetInputChars * 0.25))), 'maxEvidenceChars'),
+    maxFileCharsPerRead: positiveInteger(options.maxFileCharsPerRead ?? 32_768, 'maxFileCharsPerRead'),
+    maxFileCharsPerTurn: positiveInteger(options.maxFileCharsPerTurn ?? Math.max(32_768, Math.min(131_072, Math.floor(targetInputChars * 0.25))), 'maxFileCharsPerTurn'),
+    maxToolResultChars: positiveInteger(options.maxToolResultChars ?? 24_000, 'maxToolResultChars'),
+  });
+}
+
+export function estimateContextTokens(chars, charsPerToken = DEFAULT_CONTEXT_RATIOS.charsPerToken) {
+  if (!Number.isFinite(chars) || chars < 0) throw new RangeError('chars must be a non-negative number');
+  if (!Number.isFinite(charsPerToken) || charsPerToken <= 0) throw new RangeError('charsPerToken must be positive');
+  return Math.ceil(chars / charsPerToken);
+}

package/src/context/compact.js

@@ -0,0 +1,28 @@
+import { normalizeContextItem } from './resolve.js';
+
+export const DEFAULT_CONSUMED_CONTEXT_CHARS = 4_000;
+
+export function compactContextItem(value, options = {}) {
+  const item = normalizeContextItem(value);
+  const maxChars = Number(options.maxChars ?? DEFAULT_CONSUMED_CONTEXT_CHARS);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('compact maxChars must be a positive integer');
+  if (item.content.length <= maxChars) return Object.freeze({ ...item, compacted: false });
+  const content = `${item.content.slice(0, Math.max(0, maxChars - 1))}…`;
+  return Object.freeze({
+    ...item,
+    content,
+    chars: content.length,
+    compacted: true,
+    source_chars: item.content.length,
+  });
+}
+
+export function compactConsumedToolResult(value, options = {}) {
+  const ref = String(options.ref || value?.ref || 'tool_result:consumed').trim();
+  const hash = options.hash || value?.hash;
+  const priority = Number.isFinite(options.priority) ? options.priority : Number(value?.priority || 0);
+  const content = typeof value === 'string'
+    ? value
+    : String(value?.content ?? JSON.stringify(value?.content ?? value ?? null));
+  return compactContextItem({ ref, kind: 'tool_result', hash, priority, content }, options);
+}

package/src/context/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_CONTEXT_RATIOS, createContextBudget, estimateContextTokens } from './budget.js';
+export { DEFAULT_RESULT_POLICY, RESULT_DETAIL_ORDER, normalizeResultPolicy, truncateResultText, boundResultItems } from './result-policy.js';
+export { CONTEXT_ITEM_KINDS, normalizeContextItem, resolveContext, resolveProjectContext } from './resolve.js';
+export { PROJECT_RULES_FILENAME, DEFAULT_PROJECT_RULES_MAX_CHARS, defaultProjectRules, ensureProjectRules, findProjectRules, loadProjectRules } from '../lib/project-rules.js';
+export { DEFAULT_CONSUMED_CONTEXT_CHARS, compactContextItem, compactConsumedToolResult } from './compact.js';