@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/rpc/generated/package.json

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

package/src/security/process.js

@@ -1,31 +1,57 @@
 import { spawn } from 'node:child_process';
+import { createProcessDiagnosticError } from '../errors/index.js';
 
 export function runProcess(command, args, { cwd, timeoutMs = 300_000, signal, env = process.env, maxBytes = 8 * 1024 * 1024 } = {}) {
   return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(new Error('Command cancelled'));
-    const child = spawn(command, args, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    const safeArgs = Array.isArray(args) ? args : [];
+    const diagnostic = (code, message, extra = {}) => createProcessDiagnosticError({
+      code,
+      message,
+      command,
+      args: safeArgs,
+      cwd,
+      stdout,
+      stderr,
+      ...extra,
+    });
     let stdout = '', stderr = '', size = 0, failure, hardKill;
+    if (signal?.aborted) return reject(createProcessDiagnosticError({ code: 'process_cancelled', message: 'Command cancelled', command, args: safeArgs, cwd }));
+    const child = spawn(command, safeArgs, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
     function kill(sig) {
       try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, sig); } catch { /* already exited */ }
     }
-    function stop(reason) {
+    function stop(error) {
       if (failure) return;
-      failure = reason;
+      failure = error;
       kill('SIGTERM');
       hardKill = setTimeout(() => kill('SIGKILL'), 1000);
     }
-    const timer = setTimeout(() => stop('Command timed out'), timeoutMs);
-    const abort = () => stop('Command cancelled');
+    const timer = setTimeout(() => stop(diagnostic('process_timeout', 'Command timed out', { retriable: false })), timeoutMs);
+    const abort = () => stop(diagnostic('process_cancelled', 'Command cancelled'));
     signal?.addEventListener('abort', abort, { once: true });
     const receive = (key) => chunk => {
       size += chunk.length;
-      if (size > maxBytes) return stop('Command output exceeded 8 MiB');
+      if (size > maxBytes) return stop(diagnostic('process_output_limit', `Command output exceeded ${maxBytes} bytes`));
       if (key === 'stdout') stdout += chunk.toString(); else stderr += chunk.toString();
     };
     child.stdout.on('data', receive('stdout'));
     child.stderr.on('data', receive('stderr'));
     const cleanup = () => { clearTimeout(timer); clearTimeout(hardKill); signal?.removeEventListener('abort', abort); };
-    child.on('error', () => { cleanup(); reject(new Error('Cannot start requested command')); });
-    child.on('close', code => { cleanup(); failure ? reject(new Error(failure)) : resolve({ code: code ?? 1, stdout, stderr }); });
+    child.on('error', (cause) => {
+      cleanup();
+      reject(createProcessDiagnosticError({
+        code: cause?.code || 'process_spawn_failed',
+        message: cause?.message || 'Cannot start requested command',
+        command,
+        args: safeArgs,
+        cwd,
+        cause,
+      }));
+    });
+    child.on('close', (code, closeSignal) => {
+      cleanup();
+      if (failure) return reject(failure);
+      resolve({ code: code ?? 1, signal: closeSignal || null, stdout, stderr });
+    });
   });
 }

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/contracts.js

@@ -0,0 +1,203 @@
+export const RUNTIME_RECEIPT_SCHEMA_VERSION = 1;
+
+const RUN_MODES = new Set(['ask', 'plan', 'agent', 'debug', 'multitask']);
+const RUN_STATUSES = new Set(['queued', 'running', 'completed', 'failed', 'partial', 'cancelled']);
+const APPROVAL_STATUSES = new Set(['pending', 'approved', 'denied', 'expired']);
+const TERMINAL_STATUSES = new Set(['queued', 'running', 'completed', 'failed', 'cancelled', 'unknown']);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function required(value, label) {
+  const text = clean(value);
+  if (!text) throw new TypeError(`${label} is required`);
+  return text;
+}
+
+function optional(value) {
+  const text = clean(value);
+  return text || null;
+}
+
+function nonNegativeInteger(value, fallback = 0) {
+  const number = Number(value ?? fallback);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError('expected a non-negative number');
+  return Math.floor(number);
+}
+
+function optionalNonNegativeInteger(value) {
+  if (value == null || value === '') return null;
+  return nonNegativeInteger(value);
+}
+
+function nonNegativeNumber(value, fallback = 0) {
+  const number = Number(value ?? fallback);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError('expected a non-negative number');
+  return number;
+}
+
+function canonicalMode(value) {
+  const mode = clean(value || 'agent').toLowerCase();
+  if (!RUN_MODES.has(mode)) throw new RangeError(`unsupported run mode: ${mode}`);
+  return mode;
+}
+
+function canonicalRunStatus(value) {
+  const status = clean(value || 'queued').toLowerCase();
+  if (!RUN_STATUSES.has(status)) throw new RangeError(`unsupported run status: ${status}`);
+  return status;
+}
+
+function jsonText(value, fallback) {
+  if (value == null || value === '') return JSON.stringify(fallback);
+  if (typeof value === 'string') {
+    JSON.parse(value);
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Provider-neutral execution receipt. The authenticated host supplies account_id;
+ * tenant/workspace/user aliases are deliberately not part of this contract.
+ */
+export function createRunReceipt(value = {}) {
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id ?? value.run_id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    conversation_id: optional(value.conversation_id ?? value.conversationId),
+    external_agent_id: optional(value.external_agent_id ?? value.externalAgentId),
+    parent_run_id: optional(value.parent_run_id ?? value.parentRunId),
+    source_client: optional(value.source_client ?? value.sourceClient),
+    surface: optional(value.surface),
+    mode: canonicalMode(value.mode),
+    model_key: optional(value.model_key ?? value.modelKey),
+    reasoning_effort: optional(value.reasoning_effort ?? value.reasoningEffort),
+    requested_service_tier: optional(value.requested_service_tier ?? value.requestedServiceTier),
+    actual_service_tier: optional(value.actual_service_tier ?? value.actualServiceTier),
+    selected_by: optional(value.selected_by ?? value.selectedBy),
+    routing_arm_id: optional(value.routing_arm_id ?? value.routingArmId),
+    status: canonicalRunStatus(value.status),
+    cancel_requested: value.cancel_requested === true || value.cancel_requested === 1 ? 1 : 0,
+    error_code: optional(value.error_code ?? value.errorCode),
+    error_message: optional(value.error_message ?? value.errorMessage),
+    model_call_count: nonNegativeInteger(value.model_call_count ?? value.modelCallCount),
+    tool_call_count: nonNegativeInteger(value.tool_call_count ?? value.toolCallCount),
+    input_tokens: nonNegativeInteger(value.input_tokens ?? value.inputTokens),
+    cached_input_tokens: nonNegativeInteger(value.cached_input_tokens ?? value.cachedInputTokens),
+    output_tokens: nonNegativeInteger(value.output_tokens ?? value.outputTokens),
+    reasoning_tokens: nonNegativeInteger(value.reasoning_tokens ?? value.reasoningTokens),
+    cost_usd: nonNegativeNumber(value.cost_usd ?? value.costUsd),
+    created_at_unix: optionalNonNegativeInteger(value.created_at_unix ?? value.createdAtUnix),
+    started_at_unix: optionalNonNegativeInteger(value.started_at_unix ?? value.startedAtUnix),
+    completed_at_unix: optionalNonNegativeInteger(value.completed_at_unix ?? value.completedAtUnix),
+    updated_at_unix: optionalNonNegativeInteger(value.updated_at_unix ?? value.updatedAtUnix),
+    latency_ms: optionalNonNegativeInteger(value.latency_ms ?? value.latencyMs),
+  });
+}
+
+/** One authoritative provider/model call receipt. */
+export function createUsageReceipt(value = {}) {
+  const inputTokens = nonNegativeInteger(value.input_tokens ?? value.inputTokens);
+  const cachedInputTokens = nonNegativeInteger(value.cached_input_tokens ?? value.cachedInputTokens);
+  const cacheWriteTokens = nonNegativeInteger(value.cache_write_tokens ?? value.cacheWriteTokens);
+  const outputTokens = nonNegativeInteger(value.output_tokens ?? value.outputTokens);
+  const reasoningTokens = nonNegativeInteger(value.reasoning_tokens ?? value.reasoningTokens);
+  const totalTokens = value.total_tokens == null && value.totalTokens == null
+    ? inputTokens + outputTokens
+    : nonNegativeInteger(value.total_tokens ?? value.totalTokens);
+
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    agent_run_id: optional(value.agent_run_id ?? value.agentRunId),
+    conversation_id: optional(value.conversation_id ?? value.conversationId),
+    repository_id: optional(value.repository_id ?? value.repositoryId),
+    source_client: optional(value.source_client ?? value.sourceClient),
+    usage_kind: optional(value.usage_kind ?? value.usageKind) || 'model',
+    provider: required(value.provider, 'provider'),
+    model_key: required(value.model_key ?? value.modelKey, 'model_key'),
+    model_call_index: optionalNonNegativeInteger(value.model_call_index ?? value.modelCallIndex),
+    provider_request_id: optional(value.provider_request_id ?? value.providerRequestId),
+    requested_service_tier: optional(value.requested_service_tier ?? value.requestedServiceTier),
+    actual_service_tier: optional(value.actual_service_tier ?? value.actualServiceTier),
+    input_tokens: inputTokens,
+    cached_input_tokens: cachedInputTokens,
+    cache_write_tokens: cacheWriteTokens,
+    output_tokens: outputTokens,
+    reasoning_tokens: reasoningTokens,
+    total_tokens: totalTokens,
+    cost_usd: nonNegativeNumber(value.cost_usd ?? value.costUsd),
+    cost_basis: optional(value.cost_basis ?? value.costBasis),
+    duration_ms: optionalNonNegativeInteger(value.duration_ms ?? value.durationMs),
+    status: optional(value.status) || 'ok',
+    error_code: optional(value.error_code ?? value.errorCode),
+    ref_table: optional(value.ref_table ?? value.refTable),
+    ref_id: optional(value.ref_id ?? value.refId),
+    created_at_unix: optionalNonNegativeInteger(value.created_at_unix ?? value.createdAtUnix),
+  });
+}
+
+/** Approval receipt linked to execution/tool/process lineage without ownership aliases. */
+export function createApprovalReceipt(value = {}) {
+  const status = clean(value.status || 'pending').toLowerCase();
+  if (!APPROVAL_STATUSES.has(status)) throw new RangeError(`unsupported approval status: ${status}`);
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    agent_run_id: optional(value.agent_run_id ?? value.agentRunId),
+    tool_call_id: optional(value.tool_call_id ?? value.toolCallId),
+    terminal_job_id: optional(value.terminal_job_id ?? value.terminalJobId),
+    conversation_id: optional(value.conversation_id ?? value.conversationId),
+    capability_key: optional(value.capability_key ?? value.capabilityKey),
+    tool_key: optional(value.tool_key ?? value.toolKey),
+    action_summary: required(value.action_summary ?? value.actionSummary, 'action_summary'),
+    sanitized_input_json: jsonText(value.sanitized_input_json ?? value.sanitizedInput, {}),
+    risk_level: optional(value.risk_level ?? value.riskLevel) || 'medium',
+    approval_type: optional(value.approval_type ?? value.approvalType) || 'tool',
+    status,
+    response_json: jsonText(value.response_json ?? value.response, {}),
+    approved_by: optional(value.approved_by ?? value.approvedBy),
+    created_at: optionalNonNegativeInteger(value.created_at ?? value.createdAt),
+    expires_at: optionalNonNegativeInteger(value.expires_at ?? value.expiresAt),
+    decided_at: optionalNonNegativeInteger(value.decided_at ?? value.decidedAt),
+    metadata_json: jsonText(value.metadata_json ?? value.metadata, {}),
+  });
+}
+
+/** Thin durable process-control receipt; full terminal transcripts stay elsewhere. */
+export function createTerminalJobReceipt(value = {}) {
+  const status = clean(value.status || 'queued').toLowerCase();
+  if (!TERMINAL_STATUSES.has(status)) throw new RangeError(`unsupported terminal job status: ${status}`);
+  return Object.freeze({
+    schema_version: RUNTIME_RECEIPT_SCHEMA_VERSION,
+    id: required(value.id, 'id'),
+    account_id: required(value.account_id ?? value.accountId, 'account_id'),
+    instance_id: required(value.instance_id ?? value.instanceId, 'instance_id'),
+    connection_id: required(value.connection_id ?? value.connectionId, 'connection_id'),
+    session_id: optional(value.session_id ?? value.sessionId),
+    source_run_id: optional(value.source_run_id ?? value.sourceRunId),
+    tool_call_id: optional(value.tool_call_id ?? value.toolCallId),
+    execos_run_id: optional(value.execos_run_id ?? value.execosRunId),
+    status,
+    cwd: optional(value.cwd),
+    timeout_ms: optionalNonNegativeInteger(value.timeout_ms ?? value.timeoutMs),
+    exit_code: value.exit_code == null && value.exitCode == null ? null : Number(value.exit_code ?? value.exitCode),
+    failure_code: optional(value.failure_code ?? value.failureCode),
+    log_ref: optional(value.log_ref ?? value.logRef),
+    output_artifact_ref: optional(value.output_artifact_ref ?? value.outputArtifactRef),
+    artifact_refs_json: jsonText(value.artifact_refs_json ?? value.artifactRefs, []),
+    idempotency_key: optional(value.idempotency_key ?? value.idempotencyKey),
+    attempt: nonNegativeInteger(value.attempt),
+    max_attempts: Math.max(1, nonNegativeInteger(value.max_attempts ?? value.maxAttempts, 1)),
+    last_observed_at: optionalNonNegativeInteger(value.last_observed_at ?? value.lastObservedAt),
+    created_at: optionalNonNegativeInteger(value.created_at ?? value.createdAt),
+    started_at: optionalNonNegativeInteger(value.started_at ?? value.startedAt),
+    finished_at: optionalNonNegativeInteger(value.finished_at ?? value.finishedAt),
+    updated_at: optionalNonNegativeInteger(value.updated_at ?? value.updatedAt),
+  });
+}

package/src/telemetry/events.js

@@ -0,0 +1,51 @@
+export const AGENT_EVENT_TYPES = Object.freeze([
+  'run.started', 'run.status', 'run.completed', 'run.failed',
+  'error.observed',
+  'model.started', 'model.delta', 'model.completed',
+  'usage.snapshot', 'cost.snapshot',
+  'context.snapshot', 'context.compaction.started', 'context.compaction.completed',
+  'tool.search', 'tool.started', 'tool.completed', 'tool.failed',
+  'approval.requested', 'approval.resolved',
+  'plan.updated', 'task.updated',
+  'timer.started', 'timer.updated', 'timer.completed',
+  'runtime.waiting_input',
+]);
+
+function integer(value, label) {
+  const number = Number(value ?? 0);
+  if (!Number.isFinite(number) || number < 0) throw new RangeError(`${label} must be a non-negative number`);
+  return Math.floor(number);
+}
+
+export function createAgentEvent(type, payload = {}, options = {}) {
+  if (!AGENT_EVENT_TYPES.includes(type)) throw new RangeError(`unsupported AgentEvent type: ${type}`);
+  const event = {
+    schema_version: 1,
+    type,
+    timestamp: options.timestamp || new Date().toISOString(),
+    ...(options.runId ? { run_id: String(options.runId) } : {}),
+    ...(Number.isInteger(options.sequence) && options.sequence >= 0 ? { sequence: options.sequence } : {}),
+    payload: payload && typeof payload === 'object' ? payload : { value: payload },
+  };
+  JSON.stringify(event);
+  return Object.freeze(event);
+}
+
+export function createUsageSnapshot(value = {}) {
+  const estimateKind = value.estimate_kind === 'provider' ? 'provider' : 'local';
+  return Object.freeze({
+    current_context: Object.freeze({
+      input_tokens: integer(value.current_context?.input_tokens ?? value.currentContextTokens, 'current_context.input_tokens'),
+      window_tokens: integer(value.current_context?.window_tokens ?? value.windowTokens, 'current_context.window_tokens'),
+    }),
+    cumulative: Object.freeze({
+      input_tokens: integer(value.cumulative?.input_tokens ?? value.inputTokens, 'cumulative.input_tokens'),
+      output_tokens: integer(value.cumulative?.output_tokens ?? value.outputTokens, 'cumulative.output_tokens'),
+      cached_input_tokens: integer(value.cumulative?.cached_input_tokens ?? value.cachedInputTokens, 'cumulative.cached_input_tokens'),
+      cache_write_tokens: integer(value.cumulative?.cache_write_tokens ?? value.cacheWriteTokens, 'cumulative.cache_write_tokens'),
+      reasoning_tokens: integer(value.cumulative?.reasoning_tokens ?? value.reasoningTokens, 'cumulative.reasoning_tokens'),
+    }),
+    estimate_kind: estimateKind,
+    provider_authoritative: estimateKind === 'provider',
+  });
+}

package/src/telemetry/index.js

@@ -0,0 +1,8 @@
+export { AGENT_EVENT_TYPES, createAgentEvent, createUsageSnapshot } from './events.js';
+export {
+  RUNTIME_RECEIPT_SCHEMA_VERSION,
+  createRunReceipt,
+  createUsageReceipt,
+  createApprovalReceipt,
+  createTerminalJobReceipt,
+} from './contracts.js';

package/src/tools/hydrate.js

@@ -0,0 +1,35 @@
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+export function hydrateToolSchemas(catalog = [], selected = [], options = {}) {
+  if (!Array.isArray(catalog)) throw new TypeError('catalog must be an array');
+  if (!Array.isArray(selected)) throw new TypeError('selected must be an array');
+  const maxTools = Number.isInteger(options.maxTools) && options.maxTools > 0 ? options.maxTools : 8;
+  const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : 40_000;
+  const wanted = [...new Set(selected.map(clean).filter(Boolean))].slice(0, maxTools);
+  const byName = new Map(catalog.map((tool) => [clean(tool.tool || tool.name), tool]).filter(([name]) => name));
+  const tools = [];
+  const missing = [];
+  const deferred = [];
+  let schemaChars = 0;
+
+  for (const name of wanted) {
+    const tool = byName.get(name);
+    if (!tool) { missing.push(name); continue; }
+    const size = JSON.stringify(tool).length;
+    if (schemaChars + size > maxChars) { deferred.push(name); continue; }
+    tools.push(Object.freeze({ ...tool }));
+    schemaChars += size;
+  }
+
+  return Object.freeze({
+    tools: Object.freeze(tools),
+    receipt: Object.freeze({
+      catalog_items: catalog.length,
+      requested_tools: wanted.length,
+      hydrated_tools: tools.length,
+      schema_chars: schemaChars,
+      missing_tools: Object.freeze(missing),
+      deferred_tools: Object.freeze(deferred),
+    }),
+  });
+}

package/src/tools/index.js

@@ -1 +1,2 @@
 export { searchToolCards, toToolCard } from './search.js';
+export { hydrateToolSchemas } from './hydrate.js';

package/src/ui/boot.js

@@ -5,7 +5,6 @@ const FRAMES = ['◔', '◑', '◕', '●'];
 const CLEAR_LINE = '\x1b[2K';
 const HIDE_CURSOR = '\x1b[?25l';
 const SHOW_CURSOR = '\x1b[?25h';
-
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 function compactHome(value) {
@@ -14,43 +13,42 @@ function compactHome(value) {
   return value;
 }
 
+function modelLine(preferences) {
+  const model = preferences.modelPreference && preferences.modelPreference !== 'auto' ? preferences.modelPreference : 'auto';
+  const reasoning = preferences.reasoningEffort && preferences.reasoningEffort !== 'auto' ? preferences.reasoningEffort : 'auto';
+  const tier = preferences.serviceTier || 'default';
+  return `${model} · ${reasoning} · ${tier}`;
+}
+
 export function renderBootSummary({ identity, preferences }) {
   const branch = identity.branch ? ` · ${pc.cyan(identity.branch)}` : '';
-  const model = preferences.modelPreference && preferences.modelPreference !== 'auto'
-    ? preferences.modelPreference
-    : 'auto';
   const runtime = preferences.runtime || 'local';
   const terminal = preferences.terminal || path.basename(process.env.SHELL || '') || 'shell';
   return [
     '',
     `  ${pc.bold('Agent Sam')}  ${pc.green('●')}`,
-    `  ${pc.cyan(identity.project)}${branch} · ${pc.white(model)}`,
+    `  ${pc.cyan(identity.project)}${branch}`,
+    `  ${pc.white(modelLine(preferences))}`,
     `  ${pc.dim(compactHome(identity.root))}`,
     `  ${pc.green('✓')} ${pc.dim(runtime)} · ${pc.dim(terminal)} · ready`,
+    `  ${pc.dim('Tip: /model changes model + reasoning + processing; / shows the command menu.')}`,
     '',
   ].join('\n');
 }
 
 export async function runBootScene({ identity, preferences, animate = true, write = process.stdout.write.bind(process.stdout) }) {
   const interactive = Boolean(animate && process.stdout.isTTY);
-  if (!interactive) {
-    write(renderBootSummary({ identity, preferences }));
-    return;
-  }
-
+  if (!interactive) { write(renderBootSummary({ identity, preferences })); return; }
   write(HIDE_CURSOR);
   try {
-    write(`\n  ${pc.bold('Agent Sam')}\n  ${pc.cyan(identity.project)}${identity.branch ? ` · ${pc.cyan(identity.branch)}` : ''}\n\n`);
-    const checks = ['project', 'runtime', 'model'];
-    for (const label of checks) {
+    write(`\n  ${pc.bold('Agent Sam')}\n  ${pc.cyan(identity.project)}${identity.branch ? ` · ${pc.cyan(identity.branch)}` : ''}\n  ${pc.white(modelLine(preferences))}\n\n`);
+    for (const label of ['directory trust', 'runtime', 'model policy']) {
       for (let i = 0; i < FRAMES.length; i += 1) {
         write(`\r${CLEAR_LINE}  ${pc.cyan(FRAMES[i])} ${pc.dim(`checking ${label}`)}`);
         await sleep(i === FRAMES.length - 1 ? 45 : 55);
       }
       write(`\r${CLEAR_LINE}  ${pc.green('✓')} ${pc.dim(label)}\n`);
     }
-    write(`\n  ${pc.green('●')} ${pc.bold('ready')}  ${pc.dim(compactHome(identity.root))}\n\n`);
-  } finally {
-    write(SHOW_CURSOR);
-  }
+    write(`\n  ${pc.green('●')} ${pc.bold('ready')}  ${pc.dim(compactHome(identity.root))}\n  ${pc.dim('Type / and press Enter for the scrollable command menu.')}\n\n`);
+  } finally { write(SHOW_CURSOR); }
 }

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(' · '));
+}