@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.2

package/src/rpc/generated/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/src/security/trust-boundary.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
-import { buildMerkleTree } from '../lib/merkle/index.js';
-import { gitIgnoredPaths } from '../lib/merkle/git-ignore.js';
+import { buildMerkleTree } from '../../packages/agentsam-repository/src/merkle/index.js';
+import { gitIgnoredPaths } from '../../packages/agentsam-repository/src/merkle/git-ignore.js';
 import { analyzeExecutionBoundaries } from '../indexing/execution-boundary.js';
 
 export async function scanTrustBoundary(projectRoot = process.cwd(), options = {}) {

package/src/telemetry/events.js

@@ -5,7 +5,10 @@ export const AGENT_EVENT_TYPES = Object.freeze([
   'usage.snapshot', 'cost.snapshot',
   'context.snapshot', 'context.compaction.started', 'context.compaction.completed',
   'tool.search', 'tool.started', 'tool.completed', 'tool.failed',
-  'task.updated',
+  'approval.requested', 'approval.resolved',
+  'plan.updated', 'task.updated',
+  'timer.started', 'timer.updated', 'timer.completed',
+  'runtime.waiting_input',
 ]);
 
 function integer(value, label) {

package/src/ui/cli/activity.js

@@ -0,0 +1,76 @@
+import pc from 'picocolors';
+
+const CLEAR_LINE = '\x1b[2K';
+const SPINNER = ['◐', '◓', '◑', '◒'];
+
+function elapsed(ms) {
+  if (ms < 1000) return `${Math.max(0, Math.round(ms))}ms`;
+  return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
+}
+
+export function createInlineActivity(options = {}) {
+  const write = options.write || process.stdout.write.bind(process.stdout);
+  const interactive = options.interactive ?? Boolean(process.stdout?.isTTY);
+  const now = options.now || (() => Date.now());
+  const setTimer = options.setInterval || globalThis.setInterval;
+  const clearTimer = options.clearInterval || globalThis.clearInterval;
+  const intervalMs = Math.max(80, Number(options.intervalMs) || 120);
+
+  let label = String(options.label || 'Thinking');
+  let startedAt = 0;
+  let tick = 0;
+  let timer = null;
+  let active = false;
+
+  function frame() {
+    if (!active || !interactive) return;
+    const icon = pc.cyan(SPINNER[tick % SPINNER.length]);
+    write(`\r${CLEAR_LINE}  ${icon} ${label} ${pc.dim('· ' + elapsed(now() - startedAt))}`);
+    tick += 1;
+  }
+
+  function start(nextLabel = label) {
+    if (active) {
+      update(nextLabel);
+      return;
+    }
+    label = String(nextLabel || label);
+    startedAt = now();
+    active = true;
+    if (interactive) {
+      frame();
+      timer = setTimer(frame, intervalMs);
+    }
+  }
+
+  function update(nextLabel) {
+    if (nextLabel) label = String(nextLabel);
+    if (!active) start(label);
+    else frame();
+  }
+
+  function finish(status = 'success', finalLabel = label) {
+    if (!active) return;
+    if (timer) clearTimer(timer);
+    timer = null;
+    const duration = elapsed(now() - startedAt);
+    if (interactive) write(`\r${CLEAR_LINE}`);
+    const icon = status === 'error' ? pc.red('✗') : pc.green('✓');
+    write(`  ${icon} ${finalLabel} ${pc.dim('· ' + duration)}\n`);
+    active = false;
+  }
+
+  return Object.freeze({
+    get active() { return active; },
+    start,
+    update,
+    succeed(labelText) { finish('success', labelText || label); },
+    fail(labelText) { finish('error', labelText || 'Failed'); },
+    clear() {
+      if (timer) clearTimer(timer);
+      timer = null;
+      if (interactive && active) write(`\r${CLEAR_LINE}`);
+      active = false;
+    },
+  });
+}

package/src/ui/cli/compaction.js

@@ -0,0 +1,15 @@
+import pc from 'picocolors';
+
+function n(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(0, Math.round(number)).toLocaleString('en-US') : null;
+}
+
+export function renderCompactionReceipt(payload = {}) {
+  const before = n(payload.tokens_before ?? payload.before_tokens);
+  const after = n(payload.tokens_after ?? payload.after_tokens);
+  const duration = Number(payload.duration_ms);
+  const detail = before && after ? ` ${before} → ${after}` : '';
+  const timing = Number.isFinite(duration) ? ` · ${duration < 1000 ? Math.round(duration) + 'ms' : (duration / 1000).toFixed(1) + 's'}` : '';
+  return `  ${pc.green('↻')} Context compacted${pc.dim(detail + timing)}`;
+}

package/src/ui/cli/footer.js

@@ -0,0 +1,39 @@
+import pc from 'picocolors';
+
+function count(value) {
+  const n = Number(value || 0);
+  if (!Number.isFinite(n)) return '0';
+  if (Math.abs(n) >= 1_000_000) {
+    const scaled = n / 1_000_000;
+    return (Number.isInteger(scaled) ? String(scaled) : scaled.toFixed(Math.abs(n) >= 10_000_000 ? 0 : 1)) + 'm';
+  }
+  if (Math.abs(n) >= 1_000) {
+    const scaled = n / 1_000;
+    return (Number.isInteger(scaled) ? String(scaled) : scaled.toFixed(Math.abs(n) >= 100_000 ? 0 : 1)) + 'k';
+  }
+  return String(Math.round(n));
+}
+
+function ctxLabel(usage) {
+  const active = Number(usage?.current_context?.input_tokens || 0);
+  const window = Number(usage?.current_context?.window_tokens || 0);
+  if (!(window > 0)) return active > 0 ? `ctx ${count(active)} / unknown` : 'ctx unknown';
+  return `ctx ${Math.min(999, Math.round((active / window) * 100))}%`;
+}
+
+export function renderCliFooter(value = {}) {
+  const usage = value.usage || value.usageSnapshot || {};
+  const cumulative = usage.cumulative || {};
+  const model = String(value.model || value.modelLabel || 'model');
+  const tier = String(value.tier || '').trim();
+  const elapsedMs = Number(value.elapsedMs);
+  const parts = [
+    model,
+    ctxLabel(usage),
+    `↑${count(cumulative.input_tokens)} ↓${count(cumulative.output_tokens)}`,
+  ];
+  if (Number(cumulative.cached_input_tokens) > 0) parts.push(`cache ${count(cumulative.cached_input_tokens)}`);
+  if (tier && tier !== 'default') parts.push(tier);
+  if (Number.isFinite(elapsedMs) && elapsedMs >= 0) parts.push(elapsedMs < 60_000 ? `${(elapsedMs / 1000).toFixed(1)}s` : `${Math.floor(elapsedMs / 60_000)}m${Math.floor((elapsedMs % 60_000) / 1000)}s`);
+  return pc.dim('  ' + parts.join(' · '));
+}

package/src/ui/cli/help.js

@@ -0,0 +1,194 @@
+import pc from 'picocolors';
+import { isCancel, select } from '@clack/prompts';
+import pkg from '../../../package.json' with { type: 'json' };
+
+const HELP_TOPICS = Object.freeze([
+  {
+    id: 'start',
+    label: 'Start / resume',
+    summary: 'Enter Agent Sam, resume work, inspect identity, and choose a model.',
+    rows: [
+      ['agentsam', 'Enter the interactive Agent Sam experience'],
+      ['agentsam resume [session]', 'Resume a saved Agent Sam session'],
+      ['agentsam whoami', 'Show authenticated account and credential status'],
+      ['agentsam models', 'Probe account-visible hosted/local models'],
+      ['agentsam providers', 'Configure and verify machine provider credentials'],
+      ['agentsam env init <provider>', 'Low-level provider profile compatibility command'],
+    ],
+  },
+  {
+    id: 'work',
+    label: 'Build / inspect',
+    summary: 'Repository intelligence and normal project work.',
+    rows: [
+      ['agentsam inspect', 'Bounded repository index / authority view'],
+      ['agentsam index', 'Incremental AST and optional embeddings'],
+      ['agentsam search "query"', 'Search indexed code/text'],
+      ['agentsam repo snapshot', 'Git composition/churn snapshot'],
+      ['agentsam security', 'Dependency and trust-boundary scan'],
+      ['agentsam merkle', 'Integrity snapshots and comparisons'],
+    ],
+  },
+  {
+    id: 'runtime',
+    label: 'Runtime / terminal',
+    summary: 'Local, remote, sandbox, and deployment controls.',
+    rows: [
+      ['agentsam status', 'Project, Git, DB, API, and PTY status'],
+      ['agentsam start-local', 'Start the local PTY service'],
+      ['agentsam connections', 'Inspect available execution connections'],
+      ['agentsam tunnel', 'Expose local PTY only when remote access is wanted'],
+      ['agentsam deploy', 'Graduate intentionally to cloud infrastructure'],
+      ['agentsam cloudflare', 'Wrangler and Cloudflare runtime diagnostics'],
+    ],
+  },
+  {
+    id: 'inside',
+    label: 'Inside Agent Sam',
+    summary: 'Commands available while the interactive session is running.',
+    rows: [
+      ['/', 'Open the keyboard command picker'],
+      ['/model', 'Choose model, reasoning, and processing tier'],
+      ['/providers', 'Configure and verify machine provider credentials'],
+      ['/context', 'Show live context economics'],
+      ['/usage', 'Show token/cost/session receipt'],
+      ['/settings', 'Change runtime, terminal, and model policy'],
+      ['/status', 'Show project/runtime health'],
+      ['/help [topic]', 'Show in-session help'],
+      ['/exit', 'Return to the host shell'],
+    ],
+  },
+  {
+    id: 'create',
+    label: 'Create / extend',
+    summary: 'Scaffold and add reusable capabilities.',
+    rows: [
+      ['agentsam create <name> --preset <preset>', 'Create a new AgentSam project'],
+      ['agentsam add <capability>', 'Add a supported capability'],
+      ['agentsam capabilities [id]', 'Inspect capability contracts'],
+      ['agentsam skills [id]', 'Inspect packaged skills'],
+      ['agentsam identity init', 'Add reusable identity surfaces'],
+      ['agentsam dockerize', 'Build supported container targets'],
+    ],
+  },
+]);
+
+const TOPIC_ALIASES = new Map([
+  ['models', 'start'], ['model', 'start'], ['provider', 'start'], ['providers', 'start'], ['resume', 'start'],
+  ['repo', 'work'], ['repository', 'work'], ['inspect', 'work'], ['index', 'work'], ['security', 'work'],
+  ['terminal', 'runtime'], ['connections', 'runtime'], ['remote', 'runtime'], ['sandbox', 'runtime'], ['deploy', 'runtime'],
+  ['slash', 'inside'], ['commands', 'inside'], ['session', 'inside'], ['usage', 'inside'], ['context', 'inside'],
+  ['create', 'create'], ['scaffold', 'create'], ['capabilities', 'create'], ['skills', 'create'],
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim().toLowerCase();
+}
+
+function padRows(rows) {
+  const width = Math.min(42, Math.max(...rows.map(([command]) => command.length), 0));
+  return rows.map(([command, description]) => '    ' + pc.cyan(command.padEnd(width)) + '  ' + pc.dim(description));
+}
+
+export function resolveHelpTopic(value) {
+  const query = clean(value);
+  if (!query) return null;
+  const direct = HELP_TOPICS.find((topic) => topic.id === query || clean(topic.label) === query);
+  if (direct) return direct;
+  const alias = TOPIC_ALIASES.get(query);
+  if (alias) return HELP_TOPICS.find((topic) => topic.id === alias) || null;
+  return HELP_TOPICS.find((topic) =>
+    topic.rows.some(([command, description]) => clean(command).includes(query) || clean(description).includes(query))) || null;
+}
+
+export function renderHelpOverview(version, options = {}) {
+  const lines = [
+    '',
+    '  ' + pc.bold('Agent Sam') + ' ' + pc.dim('v' + version),
+    '  ' + pc.dim('Type normally to work with Agent Sam. Use help only when you need the map.'),
+    '',
+    '  ' + pc.bold('Start'),
+    '    ' + pc.cyan('agentsam') + '                         ' + pc.dim('enter the interactive experience'),
+    '    ' + pc.cyan('agentsam resume') + '                  ' + pc.dim('continue saved work'),
+    '    ' + pc.cyan('agentsam help <topic>') + '            ' + pc.dim('focused help'),
+    '',
+    '  ' + pc.bold('Common'),
+    '    ' + pc.cyan('agentsam inspect') + '                 ' + pc.dim('understand this repository'),
+    '    ' + pc.cyan('agentsam models') + '                  ' + pc.dim('see account-visible models'),
+    '    ' + pc.cyan('agentsam status') + '                  ' + pc.dim('check project/runtime health'),
+    '    ' + pc.cyan('agentsam security') + '                ' + pc.dim('scan dependency + trust boundaries'),
+    '    ' + pc.cyan('agentsam deploy') + '                  ' + pc.dim('graduate intentionally'),
+    '',
+    '  ' + pc.dim('Inside Agent Sam: press / for the command picker. Ask the selected model for natural-language help at any time.'),
+  ];
+  if (options.showTopics !== false) {
+    lines.push('', '  ' + pc.dim('Topics: ' + HELP_TOPICS.map((topic) => topic.id).join(' · ') + ' · all'));
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function renderHelpTopic(topic, version) {
+  if (!topic) return renderHelpOverview(version);
+  return [
+    '',
+    '  ' + pc.bold('Agent Sam') + ' ' + pc.dim('v' + version) + ' ' + pc.dim('·') + ' ' + pc.bold(topic.label),
+    '  ' + pc.dim(topic.summary),
+    '',
+    ...padRows(topic.rows),
+    '',
+    '  ' + pc.dim('Tip: run agentsam help for the map, or agentsam to return to the interactive experience.'),
+    '',
+  ].join('\n');
+}
+
+export function renderAllHelp(version) {
+  const lines = [renderHelpOverview(version, { showTopics: false })];
+  for (const topic of HELP_TOPICS) lines.push(renderHelpTopic(topic, version));
+  return lines.join('');
+}
+
+export async function runHelp(argv = [], options = {}) {
+  const version = String(options.version || pkg.version || 'unknown');
+  const write = options.write || ((value) => process.stdout.write(value));
+  const args = argv.filter((arg) => arg !== '--interactive');
+
+  if (args.includes('--all')) {
+    write(renderAllHelp(version));
+    return;
+  }
+
+  const topicArg = args.find((arg) => !arg.startsWith('-'));
+  if (topicArg) {
+    const topic = resolveHelpTopic(topicArg);
+    if (!topic) {
+      write(renderHelpOverview(version));
+      write('  ' + pc.yellow('No exact help topic matched') + ' ' + topicArg + '\n\n');
+      return;
+    }
+    write(renderHelpTopic(topic, version));
+    return;
+  }
+
+  const interactive = options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!interactive) {
+    write(renderHelpOverview(version));
+    return;
+  }
+
+  const choice = await select({
+    message: 'Agent Sam help',
+    options: [
+      ...HELP_TOPICS.map((topic) => ({ value: topic.id, label: topic.label, hint: topic.summary })),
+      { value: 'all', label: 'All commands', hint: 'Print the complete deterministic help map' },
+      { value: 'exit', label: 'Back', hint: 'Return without printing more help' },
+    ],
+  });
+  if (isCancel(choice) || choice === 'exit') return;
+  if (choice === 'all') write(renderAllHelp(version));
+  else write(renderHelpTopic(resolveHelpTopic(choice), version));
+}
+
+export function listHelpTopics() {
+  return HELP_TOPICS.map((topic) => ({ id: topic.id, label: topic.label, summary: topic.summary }));
+}

package/src/ui/cli/plan.js

@@ -0,0 +1,20 @@
+import pc from 'picocolors';
+
+export function renderPlanUpdate(payload = {}) {
+  const items = Array.isArray(payload.items) ? payload.items : Array.isArray(payload.todos) ? payload.todos : [];
+  if (!items.length) return '';
+  const lines = ['', '  ' + pc.bold(payload.title || 'Plan')];
+  for (const item of items.slice(0, 20)) {
+    const status = String(item.status || 'open');
+    const icon = status === 'complete' || status === 'completed' || status === 'done'
+      ? pc.green('✓')
+      : status === 'running' || status === 'active'
+        ? pc.cyan('●')
+        : status === 'blocked'
+          ? pc.yellow('◆')
+          : pc.dim('○');
+    lines.push(`    ${icon} ${item.title || item.label || item.id || 'task'}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}

package/src/ui/cli/runtime-events.js

@@ -0,0 +1,110 @@
+import { renderPlanUpdate } from './plan.js';
+import { renderWaitingInput } from './waiting.js';
+import { renderCompactionReceipt } from './compaction.js';
+
+export const RUNTIME_EVENT_ENVELOPE_SCHEMA = 'agentsam-runtime-event-v1';
+
+/**
+ * Transport-neutral event contract shared by standalone and future platform-connected runs.
+ * A platform SSE/WebSocket producer only needs to emit this normalized envelope; the SDK does
+ * not hardcode or invent the platform endpoint that will carry it.
+ */
+export function normalizeRuntimeEventEnvelope(value = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('runtime event envelope must be an object');
+  }
+  const type = String(value.type || '').trim();
+  if (!type) throw new TypeError('runtime event envelope type is required');
+  const sequence = Number(value.sequence);
+  const envelope = {
+    schema: RUNTIME_EVENT_ENVELOPE_SCHEMA,
+    schema_version: Number.isInteger(Number(value.schema_version)) ? Number(value.schema_version) : 1,
+    type,
+    timestamp: String(value.timestamp || new Date().toISOString()),
+    ...(value.run_id ? { run_id: String(value.run_id) } : {}),
+    ...(Number.isInteger(sequence) && sequence >= 0 ? { sequence } : {}),
+    payload: value.payload && typeof value.payload === 'object' && !Array.isArray(value.payload)
+      ? value.payload
+      : value.payload == null ? {} : { value: value.payload },
+  };
+  return Object.freeze(envelope);
+}
+
+function line(write, text) {
+  if (text) write(text.endsWith('\n') ? text : text + '\n');
+}
+
+export function createCliRuntimePresenter(options = {}) {
+  const activity = options.activity;
+  const write = options.write || process.stdout.write.bind(process.stdout);
+  const state = options.state || {};
+
+  function handle(event = {}) {
+    const envelope = normalizeRuntimeEventEnvelope(event);
+    const { type, payload } = envelope;
+
+    if (type === 'usage.snapshot') {
+      state.usageSnapshot = payload;
+      return;
+    }
+    if (type === 'cost.snapshot') {
+      state.costSnapshot = payload;
+      return;
+    }
+    if (type === 'model.started') {
+      activity?.update(`Thinking · ${payload.model || payload.provider || 'model'}`);
+      return;
+    }
+    if (type === 'tool.search') {
+      activity?.update('Finding relevant tools');
+      return;
+    }
+    if (type === 'tool.started') {
+      activity?.update(`Using ${payload.capability_id || payload.tool || 'tool'}`);
+      return;
+    }
+    if (type === 'tool.completed') {
+      activity?.update(`Tool complete · ${payload.capability_id || payload.tool || 'tool'}`);
+      return;
+    }
+    if (type === 'tool.failed') {
+      activity?.update(`Tool failed · ${payload.capability_id || payload.tool || 'tool'}`);
+      return;
+    }
+    if (type === 'context.compaction.started') {
+      state.compactionStartedAt = Date.now();
+      activity?.update('Compacting context');
+      return;
+    }
+    if (type === 'context.compaction.completed') {
+      const enriched = {
+        ...payload,
+        duration_ms: payload.duration_ms ?? (state.compactionStartedAt ? Date.now() - state.compactionStartedAt : undefined),
+      };
+      state.lastCompaction = enriched;
+      activity?.update('Context ready');
+      return;
+    }
+    if (type === 'plan.updated') {
+      activity?.clear();
+      line(write, renderPlanUpdate(payload));
+      activity?.start('Working');
+      return;
+    }
+    if (type === 'runtime.waiting_input') {
+      activity?.clear();
+      line(write, renderWaitingInput(payload));
+      return;
+    }
+    if (type === 'run.failed' || type === 'error.observed') {
+      activity?.update('Handling error');
+    }
+  }
+
+  function compactionReceipt() {
+    if (!state.lastCompaction) return '';
+    return renderCompactionReceipt(state.lastCompaction);
+  }
+
+  return Object.freeze({ handle, compactionReceipt, state });
+}

package/src/ui/cli/waiting.js

@@ -0,0 +1,16 @@
+import pc from 'picocolors';
+
+export function renderWaitingInput(payload = {}) {
+  const reason = String(payload.reason || payload.awaiting_input_reason || 'input required');
+  const url = String(payload.url || payload.auth_url || '').trim();
+  const code = String(payload.code || payload.user_code || '').trim();
+  const lines = [
+    '',
+    `  ${pc.yellow('◇')} ${pc.bold('Waiting for you')} ${pc.dim('· ' + reason)}`,
+  ];
+  if (url) lines.push(`    Open  ${pc.cyan(url)}`);
+  if (code) lines.push(`    Code  ${pc.bold(code)}`);
+  lines.push(`    ${pc.dim(payload.message || 'Complete the requested step; Agent Sam will continue when the runtime is ready.')}`);
+  lines.push('');
+  return lines.join('\n');
+}

package/src/ui/merkle/render.js

@@ -1,4 +1,4 @@
-import { comparePaths } from '../../lib/merkle/hash.js';
+import { comparePaths } from '../../../packages/agentsam-repository/src/merkle/hash.js';
 
 export const safeText = (value) => String(value ?? '').replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g,
   (char) => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0'));

package/test/account-session.test.mjs

@@ -3,7 +3,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
-import { accountSessionPath, clearAccountSession, readAccountSession, resolveAccountSdkKey, saveAccountSession } from '../src/lib/account-session.js';
+import {
+  accountSessionPath,
+  clearAccountSession,
+  readAccountSession,
+  resolveAccountApiKey,
+  resolveAccountAuth,
+  resolveBrowserSessionCredential,
+  saveAccountSession,
+} from '../src/lib/account-session.js';
 
 function tempHome(t) {
   const home = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-account-'));
@@ -11,26 +19,55 @@ function tempHome(t) {
   return home;
 }
 
-test('browser-auth SDK bearer persists in machine-local storage, not project state', t => {
+test('opaque browser login persists in machine-local storage and resolves independently from API keys', t => {
   const home = tempHome(t);
-  const saved = saveAccountSession({ access_token: 'sdk_machine_session', user_id: 'au_test', account_id: 'acct_test', email: 'dev@example.test' }, { home });
+  const saved = saveAccountSession({
+    access_token: 'browser_session_machine_test',
+    user_id: 'au_test',
+    account_id: 'acct_test',
+    email: 'dev@example.test',
+  }, { home });
   assert.equal(saved.user_id, 'au_test');
+
   const filename = accountSessionPath({ home });
   assert.equal(fs.existsSync(filename), true);
   if (process.platform !== 'win32') assert.equal(fs.statSync(filename).mode & 0o077, 0);
 
   const loaded = readAccountSession({ home });
-  assert.equal(loaded.sdk_key, 'sdk_machine_session');
-  const resolved = resolveAccountSdkKey({ env: {}, home });
-  assert.equal(resolved.source, 'agentsam_account_session');
-  assert.equal(resolved.value, 'sdk_machine_session');
+  assert.equal(loaded.access_token, 'browser_session_machine_test');
+  const browser = resolveBrowserSessionCredential({ env: {}, home });
+  assert.equal(browser.source, 'agentsam_browser_oauth');
+  assert.equal(browser.kind, 'browser_oauth');
+  assert.equal(browser.value, 'browser_session_machine_test');
+  assert.equal(resolveAccountApiKey({ env: {}, home }).value, '');
+  assert.equal(resolveAccountAuth({ env: {}, home }).value, 'browser_session_machine_test');
+
   assert.equal(clearAccountSession({ home }), true);
   assert.equal(readAccountSession({ home }), null);
 });
 
-test('explicit/environment SDK bearer remains higher authority than local session fallback', t => {
+test('explicit/environment aak_ API key outranks browser login while legacy SDK env names are ignored', t => {
+  const home = tempHome(t);
+  saveAccountSession({ access_token: 'browser_session_disk' }, { home });
+
+  assert.equal(
+    resolveAccountAuth({ env: { AGENTSAM_API_KEY: 'aak_env_test' }, home }).value,
+    'aak_env_test',
+  );
+  assert.equal(
+    resolveAccountAuth({ env: { AGENTSAM_API_KEY: 'aak_env_test' }, explicit: 'aak_explicit_test', home }).value,
+    'aak_explicit_test',
+  );
+  assert.equal(
+    resolveAccountAuth({ env: { AGENTSAM_SDK_KEY: 'legacy_ignored' }, home }).value,
+    'browser_session_disk',
+  );
+});
+
+test('browser session storage refuses reusable aak_ credentials', t => {
   const home = tempHome(t);
-  saveAccountSession({ access_token: 'sdk_disk' }, { home });
-  assert.equal(resolveAccountSdkKey({ env: { AGENTSAM_SDK_KEY: 'sdk_env' }, home }).value, 'sdk_env');
-  assert.equal(resolveAccountSdkKey({ env: { AGENTSAM_SDK_KEY: 'sdk_env' }, explicit: 'sdk_explicit', home }).value, 'sdk_explicit');
+  assert.throws(
+    () => saveAccountSession({ access_token: 'aak_should_not_be_browser_session' }, { home }),
+    /account_browser_oauth_session_required/,
+  );
 });

package/test/apps-scaffold-contract.test.mjs

@@ -13,6 +13,10 @@ function packageJson(...parts) {
   return JSON.parse(fs.readFileSync(at(...parts, 'package.json'), 'utf8'));
 }
 
+function read(...parts) {
+  return fs.readFileSync(at(...parts), 'utf8');
+}
+
 test('product apps are self-contained npm workspace roots with one lockfile', () => {
   for (const app of productApps) {
     const base = ['apps', app];
@@ -54,3 +58,42 @@ test('Local Studio retired donor-era duplicate deployment configs', () => {
     assert.equal(exists('apps', 'local-studio', 'backend', file), false, `retire ${file}`);
   }
 });
+
+test('CAD creator app package is curated for third-party installation', () => {
+  const pkg = packageJson('apps', 'cad-creator');
+  const manifest = JSON.parse(read('apps', 'cad-creator', 'agentsam.app.json'));
+
+  assert.equal(pkg.name, '@inneranimalmedia/agentsam-sdk-cad-creator');
+  assert.notEqual(pkg.private, true);
+  assert.equal(pkg.bin['agentsam-cad-creator'], 'bin/agentsam-cad-creator.mjs');
+  assert.equal(pkg.publishConfig.access, 'public');
+  assert.ok(pkg.files.includes('frontend/dist/'));
+  assert.ok(pkg.files.includes('backend/dist/'));
+  assert.ok(pkg.files.includes('backend/worker/'));
+  assert.equal(pkg.files.some((entry) => entry.startsWith('reference')), false);
+  assert.equal(pkg.files.some((entry) => entry.includes('.wrangler/state')), false);
+
+  assert.equal(manifest.schema, 'agentsam.app.v1');
+  assert.equal(manifest.id, 'cad-creator');
+  assert.equal(manifest.package, pkg.name);
+  assert.equal(manifest.runtime.local_preview, 'ready');
+  assert.equal(manifest.runtime.source_scaffold, 'ready');
+  assert.equal(manifest.runtime.cloudflare, 'scaffold');
+});
+
+test('CAD creator keeps the robotics runtime lazy and the perception key server-side', () => {
+  const app = read('apps', 'cad-creator', 'frontend', 'src', 'App.tsx');
+  const lazy = read('apps', 'cad-creator', 'frontend', 'src', 'workspaces', 'robotics', 'lazy.tsx');
+  const httpProvider = read('apps', 'cad-creator', 'frontend', 'src', 'lib', 'robotics', 'perception', 'http-provider.ts');
+  const perception = read('apps', 'cad-creator', 'backend', 'src', 'robotics', 'perception.ts');
+  const worker = read('apps', 'cad-creator', 'backend', 'worker', 'index.js');
+
+  assert.doesNotMatch(app, /from ['\"]\.\/workspaces\/robotics\/RoboticsWorkspace['\"]/);
+  assert.doesNotMatch(app, /MujocoSimulationProvider/);
+  assert.match(app, /LazyRoboticsWorkspace/);
+  assert.match(lazy, /import\(['\"]\.\/RoboticsWorkspace['\"]\)/);
+  assert.match(httpProvider, /\/api\/robotics\/perception\/detect/);
+  assert.doesNotMatch(httpProvider, /GEMINI_API_KEY|GOOGLE_API_KEY/);
+  assert.match(perception, /env\.GEMINI_API_KEY/);
+  assert.match(worker, /\/api\/robotics\/perception\/detect/);
+});

package/test/cli/preferences-runtime.test.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { runtimeOptions } from '../../src/commands/preferences.js';
+
+test('standalone users only see local execution', () => {
+  assert.deepEqual(runtimeOptions({ accountConnected: false }).map((row) => row.value), ['local']);
+});
+
+test('IAM-connected users can choose enrolled remote and sandbox lanes', () => {
+  assert.deepEqual(runtimeOptions({ accountConnected: true }).map((row) => row.value), ['local', 'remote', 'sandbox']);
+});