@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.1

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,192 @@
+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 env init <provider>', 'Create a secure local provider profile'],
+    ],
+  },
+  {
+    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'],
+      ['/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/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']);
+});

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

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createInlineActivity } from '../../src/ui/cli/activity.js';
+import { renderCliFooter } from '../../src/ui/cli/footer.js';
+import { createCliRuntimePresenter, normalizeRuntimeEventEnvelope, RUNTIME_EVENT_ENVELOPE_SCHEMA } from '../../src/ui/cli/runtime-events.js';
+import { renderWaitingInput } from '../../src/ui/cli/waiting.js';
+
+test('CLI footer reports unknown context honestly', () => {
+  const text = renderCliFooter({
+    model: 'claude-test',
+    usageSnapshot: {
+      current_context: { input_tokens: 1234, window_tokens: 0 },
+      cumulative: { input_tokens: 5000, output_tokens: 600, cached_input_tokens: 2000 },
+    },
+  });
+  assert.match(text, /claude-test/);
+  assert.match(text, /ctx 1\.2k \/ unknown/);
+  assert.match(text, /↑5k ↓600/);
+  assert.match(text, /cache 2k/);
+});
+
+test('runtime event envelope is the single standalone/platform producer contract', () => {
+  const envelope = normalizeRuntimeEventEnvelope({
+    schema_version: 1,
+    type: 'tool.started',
+    timestamp: '2026-09-18T00:00:00.000Z',
+    run_id: 'run_1',
+    sequence: 3,
+    payload: { capability_id: 'repo.inspect' },
+  });
+  assert.equal(envelope.schema, RUNTIME_EVENT_ENVELOPE_SCHEMA);
+  assert.equal(envelope.schema_version, 1);
+  assert.equal(envelope.type, 'tool.started');
+  assert.equal(envelope.run_id, 'run_1');
+  assert.equal(envelope.sequence, 3);
+  assert.deepEqual(envelope.payload, { capability_id: 'repo.inspect' });
+  assert.throws(() => normalizeRuntimeEventEnvelope({ payload: {} }), /type is required/);
+});
+
+test('runtime presenter turns events into one-line activity and waiting handoff', () => {
+  let output = '';
+  let now = 1_000;
+  const timers = [];
+  const activity = createInlineActivity({
+    write: (value) => { output += value; },
+    interactive: false,
+    now: () => now,
+    setInterval: (fn) => { timers.push(fn); return timers.length; },
+    clearInterval() {},
+  });
+  const state = {};
+  const presenter = createCliRuntimePresenter({ activity, write: (value) => { output += value; }, state });
+  activity.start('Thinking');
+  presenter.handle({ type: 'tool.started', payload: { capability_id: 'repo.inspect' } });
+  presenter.handle({ type: 'usage.snapshot', payload: { current_context: { input_tokens: 10, window_tokens: 100 }, cumulative: {} } });
+  presenter.handle({ type: 'context.compaction.started', payload: { provider: 'test' } });
+  now += 500;
+  presenter.handle({ type: 'context.compaction.completed', payload: { provider: 'test', tokens_before: 80, tokens_after: 20, summary_text: 'kept state' } });
+  presenter.handle({ type: 'runtime.waiting_input', payload: { reason: 'authentication', auth_url: 'https://example.test/auth', user_code: 'ABCD' } });
+  assert.equal(state.usageSnapshot.current_context.input_tokens, 10);
+  assert.equal(state.lastCompaction.tokens_before, 80);
+  assert.match(output, /Waiting for you/);
+  assert.match(output, /https:\/\/example\.test\/auth/);
+  assert.match(output, /ABCD/);
+  assert.match(presenter.compactionReceipt(), /80 → 20/);
+});
+
+test('waiting renderer gives CLI-native auth instructions', () => {
+  const text = renderWaitingInput({ awaiting_input_reason: 'otp', auth_url: 'https://example.test/login', user_code: '123456' });
+  assert.match(text, /Waiting for you/);
+  assert.match(text, /otp/);
+  assert.match(text, /Open/);
+  assert.match(text, /123456/);
+});

package/test/error-diagnostics.test.mjs

@@ -1,6 +1,17 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { classifyOpenAIError, createOpenAIHttpError, diagnosticFromError } from '../src/errors/index.js';
+import {
+  ERROR_CODE,
+  ERROR_REASON,
+  canonicalCodeFromGrpcStatus,
+  classifyCloudflareFailure,
+  classifyOAuthFailure,
+  classifyOpenAIError,
+  createErrorEnvelope,
+  createOpenAIHttpError,
+  diagnosticFromError,
+  grpcStatusForCode,
+} from '../src/errors/index.js';
 import { createOpenAIResponsesAdapter } from '../src/providers/openai-responses.js';
 
 function response(status, body, headers = {}) { return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } }); }
@@ -57,3 +68,48 @@ test('Responses adapter throws a diagnostic error instead of flattening the prov
     },
   );
 });
+
+
+test('canonical error contract preserves transport-neutral code and reason mappings', () => {
+  const envelope = createErrorEnvelope({
+    code: ERROR_CODE.UNAVAILABLE,
+    reason: ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE,
+    message: 'Local terminal tunnel has no healthy connector.',
+    retryable: true,
+    http_status: 530,
+    provider: 'cloudflare',
+    provider_code: '1033',
+    transport: 'cloudflare_tunnel',
+  });
+  assert.equal(envelope.ok, false);
+  assert.equal(envelope.code, 'UNAVAILABLE');
+  assert.equal(envelope.reason, 'tunnel_connector_unavailable');
+  assert.equal(envelope.http_status, 530);
+  assert.equal(envelope.grpc_status, 14);
+  assert.equal(envelope.retryable, true);
+  assert.equal(canonicalCodeFromGrpcStatus(14), ERROR_CODE.UNAVAILABLE);
+  assert.equal(grpcStatusForCode(ERROR_CODE.UNAUTHENTICATED), 16);
+});
+
+test('Cloudflare and OAuth boundary classifiers map native failures into canonical AgentSam semantics', () => {
+  assert.deepEqual(classifyCloudflareFailure({ httpStatus: 530, cloudflareCode: 1033 }), {
+    code: ERROR_CODE.UNAVAILABLE,
+    reason: ERROR_REASON.TUNNEL_CONNECTOR_UNAVAILABLE,
+    retryable: true,
+  });
+  assert.deepEqual(classifyCloudflareFailure({ httpStatus: 526 }), {
+    code: ERROR_CODE.UNAVAILABLE,
+    reason: ERROR_REASON.TLS_CERTIFICATE_INVALID,
+    retryable: false,
+  });
+  assert.deepEqual(classifyOAuthFailure('invalid_grant'), {
+    code: ERROR_CODE.UNAUTHENTICATED,
+    reason: ERROR_REASON.AUTH_INVALID,
+    retryable: false,
+  });
+  assert.deepEqual(classifyOAuthFailure('access_denied'), {
+    code: ERROR_CODE.PERMISSION_DENIED,
+    reason: ERROR_REASON.PERMISSION_DENIED,
+    retryable: false,
+  });
+});