@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/test/smoke.mjs

@@ -55,14 +55,17 @@ await assert.rejects(() => finalizeInboundOAuth({}, new Request('https://x'), {}
 assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/deploy'));
 assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/db'));
 assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/agent'));
+assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/model'));
+assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/reasoning'));
+assert.ok(SLASH_COMMANDS.some((c) => c.cmd === '/fast'));
 assert.deepEqual(
   listSlashCommands({ lane: 'deploy' }).map(({ cmd }) => cmd),
-  ['/help', '/deploy', '/exit'],
+  ['/settings', '/deploy', '/help', '/exit'],
   'deploy lane keeps global shell controls and excludes commands from other lanes',
 );
 
 printContextSummary({
-  iam: { ready: true, source: 'sdk-token', detail: 'AGENTSAM_SDK_TOKEN' },
+  iam: { ready: true, source: 'sdk-key', detail: 'AGENTSAM_SDK_KEY' },
   gcp: { source: 'vm-metadata', email: 'execos@project.iam.gserviceaccount.com' },
   gcp_vm: true,
   github: { source: 'gh-cli', account: 'user@example.com' },

package/test/telemetry.test.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAgentEvent, createUsageSnapshot } from '../src/telemetry/index.js';
+
+test('AgentEvent is compact serializable provider-neutral telemetry', () => {
+  const event = createAgentEvent('context.compaction.completed', { before: 181_000, after: 72_000 }, {
+    runId: 'run_test', sequence: 4, timestamp: '2026-09-12T00:00:00.000Z',
+  });
+  assert.equal(event.type, 'context.compaction.completed');
+  assert.equal(event.run_id, 'run_test');
+  assert.doesNotThrow(() => JSON.stringify(event));
+});
+
+test('current active context and cumulative run usage are different metrics', () => {
+  const usage = createUsageSnapshot({
+    current_context: { input_tokens: 48_000, window_tokens: 1_050_000 },
+    cumulative: { input_tokens: 310_000, output_tokens: 22_000, cached_input_tokens: 120_000, cache_write_tokens: 12_000, reasoning_tokens: 8_000 },
+    estimate_kind: 'provider',
+  });
+  assert.equal(usage.current_context.input_tokens, 48_000);
+  assert.equal(usage.cumulative.input_tokens, 310_000);
+  assert.equal(usage.provider_authoritative, true);
+});
+
+import {
+  createRunReceipt,
+  createUsageReceipt,
+  createApprovalReceipt,
+  createTerminalJobReceipt,
+} from '../src/telemetry/index.js';
+
+test('runtime receipts are account-owned and emit no tenant/workspace/user ownership aliases', () => {
+  const run = createRunReceipt({
+    id: 'arun_1', account_id: 'au_1', mode: 'agent', status: 'running',
+    source_client: 'cli', surface: 'cli', reasoning_effort: 'high', requested_service_tier: 'fast',
+  });
+  assert.equal(run.account_id, 'au_1');
+  assert.equal(run.source_client, 'cli');
+  assert.equal(run.requested_service_tier, 'fast');
+  assert.equal('user_id' in run, false);
+  assert.equal('tenant_id' in run, false);
+  assert.equal('workspace_id' in run, false);
+});
+
+test('usage receipt models exactly one provider call and keeps cache/reasoning economics', () => {
+  const usage = createUsageReceipt({
+    id: 'ue_1', account_id: 'au_1', agent_run_id: 'arun_1', provider: 'openai', model_key: 'gpt-6-astra',
+    model_call_index: 2, provider_request_id: 'resp_1', input_tokens: 1000, cached_input_tokens: 600,
+    cache_write_tokens: 20, output_tokens: 100, reasoning_tokens: 40, cost_usd: 0.12, cost_basis: 'provider',
+  });
+  assert.equal(usage.total_tokens, 1100);
+  assert.equal(usage.cached_input_tokens, 600);
+  assert.equal(usage.reasoning_tokens, 40);
+  assert.equal(usage.model_call_index, 2);
+});
+
+test('approval and terminal receipts preserve lineage without turning D1 into transcript storage', () => {
+  const approval = createApprovalReceipt({
+    id: 'appr_1', account_id: 'au_1', agent_run_id: 'arun_1', tool_call_id: 'call_1', terminal_job_id: 'tjob_1',
+    action_summary: 'Deploy worker', sanitizedInput: { worker: 'api' }, risk_level: 'high',
+  });
+  assert.equal(approval.terminal_job_id, 'tjob_1');
+  assert.match(approval.sanitized_input_json, /worker/);
+
+  const job = createTerminalJobReceipt({
+    id: 'tjob_1', account_id: 'au_1', instance_id: 'tinst_1', connection_id: 'conn_1',
+    execos_run_id: 'xrun_1', status: 'running', idempotency_key: 'idem_1', max_attempts: 1,
+  });
+  assert.equal(job.execos_run_id, 'xrun_1');
+  assert.equal(job.max_attempts, 1);
+  assert.equal('stdout' in job, false);
+  assert.equal('stderr' in job, false);
+  assert.equal('command' in job, false);
+});
+
+test('runtime receipts refuse model-invented account identity', () => {
+  assert.throws(() => createRunReceipt({ id: 'arun_1' }), /account_id is required/);
+  assert.throws(() => createUsageReceipt({ id: 'ue_1', provider: 'openai', model_key: 'gpt-6-astra' }), /account_id is required/);
+});

package/test/theme-portability.test.mjs

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { CLOUD, LOCAL, SANDBOX, getLaneThemeByName } from '../src/ui/theme.js';
+
+test('SDK terminal lane metadata is provider and operator neutral', () => {
+  const serialized = JSON.stringify([LOCAL.meta, CLOUD.meta, SANDBOX.meta]);
+  assert.doesNotMatch(serialized, /sam(smac)?|inneranimalmedia|gcp|cloudflare|MY_CONTAINER/i);
+  assert.equal(LOCAL.meta.tunnelHint, 'current machine · real shell');
+  assert.equal(CLOUD.meta.label, 'Remote');
+  assert.equal(SANDBOX.meta.tunnelHint, 'isolated disposable runtime');
+  assert.equal(getLaneThemeByName('remote'), CLOUD);
+  assert.equal(getLaneThemeByName('cloud'), CLOUD);
+});

package/test/tools-search.test.mjs

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { getToolCatalog } from '../src/lib/tools.js';
+import { hydrateToolSchemas, searchToolCards } from '../src/tools/index.js';
+import { DEFAULT_RESULT_POLICY } from '../src/context/index.js';
+
+test('every built-in SDK tool inherits a bounded result policy', () => {
+  for (const lane of ['fullstack', 'cms', 'data', 'crm', 'creative']) {
+    for (const tool of getToolCatalog(lane)) assert.deepEqual(tool.result_policy, DEFAULT_RESULT_POLICY);
+  }
+});
+
+test('tools.search returns compact cards rather than full schemas', () => {
+  const catalog = Array.from({ length: 20 }, (_, index) => ({
+    name: index === 13 ? 'code.retrieve' : `tool.${index}`,
+    description: index === 13 ? 'Find symbols, callers, and semantic code matches.' : `Capability ${index}`,
+    category: index === 13 ? 'code' : 'misc',
+    risk: 'read',
+    input_schema: { type: 'object', required: ['query'], properties: { query: { type: 'string' }, giant: { description: 'x'.repeat(5000) } } },
+  }));
+  const result = searchToolCards(catalog, 'code symbols');
+  assert.ok(result.cards.length <= 8);
+  assert.equal(result.cards[0].tool, 'code.retrieve');
+  assert.deepEqual(result.cards[0].required, ['query']);
+  assert.equal('input_schema' in result.cards[0], false);
+  assert.ok(result.receipt.chars < 24_000);
+});
+
+test('selected schemas hydrate without loading the full tool catalog', () => {
+  const catalog = Array.from({ length: 50 }, (_, index) => ({
+    name: `tool.${index}`,
+    description: `Capability ${index}`,
+    input_schema: { type: 'object', properties: { value: { type: 'string' }, padding: { description: 'x'.repeat(300) } } },
+  }));
+  const result = hydrateToolSchemas(catalog, ['tool.4', 'tool.22'], { maxTools: 4, maxChars: 5_000 });
+  assert.deepEqual(result.tools.map((tool) => tool.name), ['tool.4', 'tool.22']);
+  assert.equal(result.receipt.catalog_items, 50);
+  assert.equal(result.receipt.hydrated_tools, 2);
+  assert.ok(result.receipt.schema_chars < 5_000);
+});

package/test/whoami-resume.test.mjs

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { saveAccountSession } from '../src/lib/account-session.js';
+import { createLocalSession } from '../src/lib/local-sessions.js';
+import { collectWhoami } from '../src/commands/whoami.js';
+import { runResume } from '../src/commands/resume.js';
+
+function tempHome(t) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-ux-home-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  return home;
+}
+
+test('whoami validates persisted IAM identity while never returning the SDK or provider secret', async t => {
+  const home = tempHome(t);
+  saveAccountSession({ access_token: 'sdk_do_not_print', user_id: 'au_local' }, { home });
+  const envDir = path.join(home, '.agentsam', 'env.d');
+  fs.mkdirSync(envDir, { recursive: true });
+  const openaiFile = path.join(envDir, 'openai.env');
+  fs.writeFileSync(openaiFile, 'OPENAI_API_KEY=sk-never-print-this\n', { mode: 0o600 });
+  if (process.platform !== 'win32') fs.chmodSync(openaiFile, 0o600);
+
+  const status = await collectWhoami({
+    env: {}, home,
+    contextLoader: async token => {
+      assert.equal(token, 'sdk_do_not_print');
+      return { user_id: 'au_server', account_id: 'acct_server', email: 'dev@example.test', cloudflare: { ok: true }, byok: { openai: { configured: true, masked: 'secret' } } };
+    },
+  });
+  assert.equal(status.authenticated, true);
+  assert.equal(status.identity.account_id, 'acct_server');
+  assert.equal(status.sdk_credential.source, 'agentsam_account_session');
+  assert.equal(status.provider_credentials.find(row => row.provider === 'openai').configured, true);
+  const serialized = JSON.stringify(status);
+  assert.doesNotMatch(serialized, /sdk_do_not_print|sk-never-print-this|masked/);
+});
+
+test('resume restores saved cwd and session through the canonical shell runtime', async t => {
+  const home = tempHome(t);
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-resume-project-'));
+  t.after(() => fs.rmSync(cwd, { recursive: true, force: true }));
+  const session = createLocalSession({ cwd, title: 'Run wrangler whoami', model_key: 'openai:gpt-6-astra' }, { home });
+  let called = null;
+  const restored = await runResume([session.id], {
+    home,
+    write() {},
+    runShellImpl: async (argv, options) => { called = { argv, options }; },
+  });
+  assert.equal(restored.id, session.id);
+  assert.deepEqual(called.argv, []);
+  assert.equal(called.options.cwd, cwd);
+  assert.equal(called.options.session.id, session.id);
+});

package/examples/agentsam-tui-ansi.mjs

@@ -1,149 +0,0 @@
-#!/usr/bin/env node
-/**
- * Zero-dependency ANSI companion to the Agent Sam SDK TUI.
- * Use this from Agent Sam PTY / Node scripts when you do not want Python+Rich.
- *
- *   node scripts/demo_agentsam_ansi.mjs
- *   node scripts/demo_agentsam_ansi.mjs --scene sprite
- *   node scripts/demo_agentsam_ansi.mjs --check
- */
-
-const HIDE = "\x1b[?25l";
-const SHOW = "\x1b[?25h";
-const CLEAR_LINE = "\x1b[2K";
-const MAGENTA = "\x1b[38;2;211;54;130m";
-const CYAN = "\x1b[38;2;45;212;191m";
-const MUTED = "\x1b[38;2;122;154;170m";
-const GREEN = "\x1b[38;2;163;184;0m";
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-
-const WALKER = [
-  ["  ·     ", "  ○     ", "  │╲    ", "  │ ○   ", "  ○ ░   ", "  ░     "],
-  ["   ·    ", "   ○    ", "   │╲   ", "  ○  ○  ", "   ░    ", "  ░     "],
-  ["    ·   ", "    ○   ", "    │╲  ", "   ○ │  ", "    ○   ", "   ░    "],
-  ["     ·  ", "    ○   ", "    ╱│  ", "   ○ │  ", "    ○   ", "    ░   "],
-  ["    ·   ", "   ○    ", "   ╱│   ", "  ○  │  ", "   ○ ░  ", "    ░   "],
-  ["   ·    ", "  ○     ", "  ╱│    ", " ○  │   ", "  ○ ░   ", "  ░     "],
-  ["  ·     ", "  ○     ", "  │╲    ", " ○  ○   ", "  ○ ░   ", "  ░     "],
-  [" ·      ", "  ○     ", "  │╲    ", "  │ ○   ", "  ○ ░   ", " ░      "],
-];
-
-const BRAILLE = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function paint(lines) {
-  const payload = lines.map((line) => `${CLEAR_LINE}${line}`).join("\n");
-  process.stdout.write(`${payload}\n`);
-  return lines.length;
-}
-
-function moveUp(n) {
-  if (n > 0) process.stdout.write(`\x1b[${n}A`);
-}
-
-function box(title, bodyLines, width = 42) {
-  const inner = width - 2;
-  const top = `${MAGENTA}╭${"─".repeat(inner)}╮${RESET}`;
-  const label = ` ${title} `;
-  const titled = `${MAGENTA}╭${RESET}${BOLD}${CYAN}${label}${RESET}${MAGENTA}${"─".repeat(Math.max(0, inner - label.length))}╮${RESET}`;
-  const mid = bodyLines.map((line) => {
-    const visible = line.replace(/\x1b\[[0-9;]*m/g, "");
-    const pad = Math.max(0, inner - 2 - visible.length);
-    return `${MAGENTA}│${RESET} ${line}${" ".repeat(pad)} ${MAGENTA}│${RESET}`;
-  });
-  const bot = `${MAGENTA}╰${"─".repeat(inner)}╯${RESET}`;
-  return [titled.length ? titled : top, ...mid, bot];
-}
-
-async function sceneSprite({ ticks, delay }) {
-  let used = 0;
-  for (let i = 0; i < ticks; i += 1) {
-    const frame = WALKER[i % WALKER.length];
-    const caption = `${MUTED}Agent Sam is walking · frame ${String(i + 1).padStart(2, "0")}${RESET}`;
-    const lines = box("agent activity", [...frame.map((row) => `${CYAN}${BOLD}${row}${RESET}`), "", caption], 34);
-    if (used) moveUp(used);
-    used = paint(lines);
-    await sleep(delay);
-  }
-  return used;
-}
-
-async function sceneDashboard({ ticks, delay }) {
-  const total = 2320;
-  let used = 0;
-  const started = Date.now();
-  for (let i = 0; i < ticks; i += 1) {
-    const done = Math.min(total, Math.round(((i + 1) / ticks) * total));
-    const symbols = Math.round(done * 2.76);
-    const elapsed = Math.round((Date.now() - started) / 1000);
-    const spin = BRAILLE[i % BRAILLE.length];
-    const walker = WALKER[i % WALKER.length];
-    const pct = Math.round((done / total) * 100);
-    const barFilled = Math.round(pct / 5);
-    const bar = `${CYAN}${"█".repeat(barFilled)}${MUTED}${"░".repeat(20 - barFilled)}${RESET}`;
-    const body = [
-      `${MUTED}stage${RESET}     ${CYAN}${BOLD}parse_chunks${RESET}  ${spin}`,
-      `${MUTED}files${RESET}     ${done.toLocaleString()} / ${total.toLocaleString()}`,
-      `${MUTED}symbols${RESET}   ${symbols.toLocaleString()}`,
-      `${MUTED}errors${RESET}    ${GREEN}0${RESET}`,
-      `${MUTED}elapsed${RESET}   ${elapsed}s`,
-      `${bar} ${pct}%`,
-      "",
-      ...walker.map((row) => `${CYAN}${row}${RESET}`),
-    ];
-    const lines = box("◉  Code Index", body, 46);
-    if (used) moveUp(used);
-    used = paint(lines);
-    await sleep(delay);
-  }
-  return used;
-}
-
-async function sceneLogs({ delay }) {
-  const rows = [
-    ["INFO", "Connected to Hyperdrive", "471 ms"],
-    ["WORK", "Parsing batch", "24 files"],
-    ["OK", "Checkpoint committed", "durable"],
-  ];
-  const styles = { INFO: "\x1b[38;2;58;159;232m", WORK: "\x1b[38;2;230;172;0m", OK: GREEN };
-  for (const [level, message, detail] of rows) {
-    const now = new Date().toISOString().slice(11, 19);
-    process.stdout.write(
-      `${DIM}${now}${RESET} ${styles[level]}${level.padStart(4)}${RESET} ${message} ${DIM}· ${detail}${RESET}\n`,
-    );
-    await sleep(delay);
-  }
-  return 0;
-}
-
-async function main() {
-  const args = new Set(process.argv.slice(2));
-  const check = args.has("--check");
-  const scene = [...args].find((a) => !a.startsWith("--")) || (args.has("--scene") ? null : "all");
-  const sceneFlagIdx = process.argv.indexOf("--scene");
-  const named = sceneFlagIdx >= 0 ? process.argv[sceneFlagIdx + 1] : scene;
-  const which = named && named !== "all" && !named.startsWith("--") ? named : "all";
-  const delay = check ? 0 : 90;
-  const ticks = check ? 4 : 32;
-
-  process.stdout.write(HIDE);
-  try {
-    if (which === "sprite" || which === "all") await sceneSprite({ ticks, delay });
-    if (which === "dashboard" || which === "all") await sceneDashboard({ ticks, delay });
-    if (which === "logs" || which === "all") await sceneLogs({ delay: check ? 0 : 120 });
-    process.stdout.write(`\n${GREEN}${BOLD}Done.${RESET}  Use the Python agentsam tui command for Rich layouts.\n`);
-  } finally {
-    process.stdout.write(SHOW);
-  }
-}
-
-main().catch((err) => {
-  process.stdout.write(SHOW);
-  console.error(err);
-  process.exit(1);
-});

package/src/commands/tui.js

@@ -1,120 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { collectLocalStatus } from '../lib/local-status.js';
-import { renderLocalStatus } from '../ui/ansi.js';
-import { runMerkle } from './merkle.js';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const ANSI_DEMO = path.join(ROOT, 'examples', 'agentsam-tui-ansi.mjs');
-const PYTHON_ROOT = path.join(ROOT, 'python');
-
-function run(command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      stdio: options.stdio || 'inherit',
-      cwd: options.cwd || process.cwd(),
-      env: options.env || process.env,
-    });
-    child.once('error', reject);
-    child.once('exit', (code, signal) => {
-      if (signal) reject(new Error(`${command} stopped by ${signal}`));
-      else if (code === 0) resolve(0);
-      else reject(new Error(`${command} exited ${code ?? 1}`));
-    });
-  });
-}
-
-function hasScene(args) {
-  return args.includes('--scene') || args.some((arg) => arg.startsWith('--scene='));
-}
-
-function venvPython(venvRoot) {
-  return process.platform === 'win32'
-    ? path.join(venvRoot, 'Scripts', 'python.exe')
-    : path.join(venvRoot, 'bin', 'python');
-}
-
-async function findSystemPython() {
-  for (const candidate of process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python']) {
-    try {
-      await run(candidate, ['--version'], { stdio: 'ignore' });
-      return candidate;
-    } catch {
-      // try next candidate
-    }
-  }
-  return null;
-}
-
-async function pythonHasRich(python) {
-  try {
-    await run(python, ['-c', 'import rich'], { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function runRich(args) {
-  const install = args.includes('--install');
-  const forwarded = args.filter((arg) => arg !== '--install');
-  const projectVenv = path.resolve(process.cwd(), '.agentsam', 'tui-venv');
-  let python = fs.existsSync(venvPython(projectVenv)) ? venvPython(projectVenv) : null;
-
-  if (!python && install) {
-    const systemPython = await findSystemPython();
-    if (!systemPython) throw new Error('Python 3 is required for the optional Rich TUI.');
-    fs.mkdirSync(path.dirname(projectVenv), { recursive: true });
-    console.log(`\n  Agent Sam Rich TUI setup\n  · creating ${projectVenv}`);
-    await run(systemPython, ['-m', 'venv', projectVenv]);
-    python = venvPython(projectVenv);
-    console.log('  · installing rich into isolated Agent Sam venv');
-    await run(python, ['-m', 'pip', 'install', 'rich>=13.7.0']);
-  }
-
-  if (!python) {
-    const systemPython = await findSystemPython();
-    if (systemPython && (await pythonHasRich(systemPython))) python = systemPython;
-  }
-
-  if (!python) {
-    throw new Error(
-      'Rich TUI is optional and not installed. Run `agentsam tui rich --install` to create an isolated .agentsam/tui-venv.',
-    );
-  }
-
-  const env = {
-    ...process.env,
-    PYTHONPATH: [PYTHON_ROOT, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter),
-  };
-
-  if (!hasScene(forwarded)) {
-    const status = await collectLocalStatus();
-    env.AGENTSAM_STATUS_JSON = JSON.stringify(status);
-    await run(python, ['-m', 'agentsam_sdk.tui.status'], { env });
-    return;
-  }
-
-  await run(python, ['-m', 'agentsam_sdk.tui', ...forwarded], { env });
-}
-
-export async function runTui(argv = []) {
-  if (argv[0] === 'merkle') return runMerkle(['tui', ...argv.slice(1)]);
-  const args = [...argv];
-  const mode = args[0] === 'rich' || args[0] === 'ansi' ? args.shift() : 'ansi';
-
-  if (mode === 'rich') {
-    await runRich(args);
-    return;
-  }
-
-  if (!hasScene(args)) {
-    const status = await collectLocalStatus();
-    process.stdout.write(`\n${renderLocalStatus(status)}\n\n`);
-    return;
-  }
-
-  await run(process.execPath, [ANSI_DEMO, ...args]);
-}