@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

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,48 @@
+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',
+  'task.updated',
+]);
+
+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

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

package/src/tools/search.js

@@ -0,0 +1,70 @@
+import { DEFAULT_RESULT_POLICY, normalizeResultPolicy } from '../context/result-policy.js';
+
+function text(value) { return value == null ? '' : String(value).trim(); }
+
+export function toToolCard(tool = {}) {
+  const required = Array.isArray(tool.required)
+    ? tool.required
+    : Array.isArray(tool.input_schema?.required)
+      ? tool.input_schema.required
+      : [];
+  return Object.freeze({
+    tool: text(tool.tool || tool.name),
+    summary: text(tool.summary || tool.description),
+    category: text(tool.category) || undefined,
+    risk: text(tool.risk) || 'read',
+    required: Object.freeze([...required]),
+    result_class: text(tool.result_class) || 'bounded_evidence',
+  });
+}
+
+function score(card, query) {
+  if (!query) return 1;
+  const q = query.toLowerCase();
+  const terms = q.split(/\s+/).filter(Boolean);
+  const haystack = `${card.tool} ${card.summary} ${card.category || ''}`.toLowerCase();
+  let total = 0;
+  if (card.tool.toLowerCase() === q) total += 100;
+  if (card.tool.toLowerCase().includes(q)) total += 30;
+  if (card.summary.toLowerCase().includes(q)) total += 15;
+  for (const term of terms) {
+    if (card.tool.toLowerCase().includes(term)) total += 8;
+    if (card.summary.toLowerCase().includes(term)) total += 4;
+    if ((card.category || '').toLowerCase().includes(term)) total += 2;
+  }
+  return total;
+}
+
+export function searchToolCards(catalog = [], query = '', options = {}) {
+  if (!Array.isArray(catalog)) throw new TypeError('catalog must be an array');
+  const policy = normalizeResultPolicy({
+    max_items: options.maxItems ?? DEFAULT_RESULT_POLICY.max_items,
+    max_chars: options.maxChars ?? DEFAULT_RESULT_POLICY.max_chars,
+    detail: 'card',
+  }, { ceiling: DEFAULT_RESULT_POLICY });
+  const cards = catalog.map(toToolCard)
+    .map((card, index) => ({ card, score: score(card, text(query)), index }))
+    .filter((row) => row.card.tool && row.score > 0)
+    .sort((a, b) => (b.score - a.score) || (a.index - b.index))
+    .slice(0, policy.max_items)
+    .map((row) => row.card);
+
+  let chars = 0;
+  const bounded = [];
+  for (const card of cards) {
+    const size = JSON.stringify(card).length;
+    if (chars + size > policy.max_chars) break;
+    bounded.push(card);
+    chars += size;
+  }
+  return Object.freeze({
+    query: text(query),
+    cards: Object.freeze(bounded),
+    receipt: Object.freeze({
+      catalog_items: catalog.length,
+      returned_items: bounded.length,
+      chars,
+      result_policy: policy,
+    }),
+  });
+}

package/src/ui/ansi.js

@@ -40,7 +40,7 @@ export function renderLocalStatus(status) {
     return lines.join('\n');
   }
 
-  lines.push(row('lane', `${status.lane} · ${status.agent}`, width));
+  lines.push(row('profile', `${status.lane || 'custom'} · ${status.agent || 'default'}`, width));
   lines.push(
     row(
       'git',

package/src/ui/boot.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import pc from 'picocolors';
+
+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) {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (home && value.startsWith(home)) return `~${value.slice(home.length)}`;
+  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 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(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; }
+  write(HIDE_CURSOR);
+  try {
+    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  ${pc.dim('Type / and press Enter for the scrollable command menu.')}\n\n`);
+  } finally { write(SHOW_CURSOR); }
+}

package/src/ui/merkle/render.js

@@ -79,6 +79,7 @@ export function renderSummary(result, { inspect = false, color = false } = {}) {
   const { tree, diff } = result;
   const lines = [paint(`Agent Sam · ${safeText(result.title)}`, '1;36', color), `  path:  ${safeText(tree.rootPath)}`,
     `  files: ${tree.stats.files}  links: ${tree.stats.symlinks}  bytes: ${tree.stats.bytes}`, `  root:  ${tree.rootHash}`];
+  if (tree.semantic) lines.push(`  meta:  ${tree.semantic.rootHash}  (${tree.semantic.classifier.format}/v${tree.semantic.classifier.version})`);
   if (result.output) lines.push(`  saved: ${safeText(result.output)}`);
   if (diff) {
     lines.push(`  ${diff.equal ? 'MATCH' : 'CHANGED'}  ` + Object.entries(diff.stats).map(([key, value]) => `${value} ${key}`).join(' · '));

package/src/ui/runtime-activity.js

@@ -0,0 +1,192 @@
+import pc from 'picocolors';
+
+const CLEAR_LINE = '\x1b[2K';
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const SPINNER = ['◔', '◑', '◕', '●'];
+const PANEL_WIDTH = 34;
+const PANEL_INNER = PANEL_WIDTH - 2;
+const PANEL_LINES = 5;
+
+const THINK_FRAMES = [
+  ['  ·     ·', '     ○', '  ·     ·'],
+  ['  ✦     ·', '    (○)', '  ·     ✦'],
+  ['  ·     ✦', '    (●)', '  ✦     ·'],
+  ['    ✦', '   ( ◯ )', '    ✦'],
+  ['  ✦     ✦', '    (●)', '  ✦     ✦'],
+  ['  ·     ✦', '    (○)', '  ✦     ·'],
+];
+
+function elapsedLabel(ms) {
+  if (ms < 1000) return `${Math.max(0, Math.round(ms))}ms`;
+  return `${(ms / 1000).toFixed(ms < 10000 ? 1 : 0)}s`;
+}
+
+function truncate(value, max) {
+  const text = String(value || '');
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+
+function center(value, width) {
+  const text = truncate(value, width);
+  const left = Math.max(0, Math.floor((width - text.length) / 2));
+  const right = Math.max(0, width - text.length - left);
+  return `${' '.repeat(left)}${text}${' '.repeat(right)}`;
+}
+
+function titledBorder(title, width, left, right) {
+  const label = ` ${title} `;
+  const fill = Math.max(0, width - left.length - right.length - label.length);
+  return `${left}${label}${'─'.repeat(fill)}${right}`;
+}
+
+function subtitledBorder(subtitle, width, left, right) {
+  const label = ` ${truncate(subtitle, width - 4)} `;
+  const fill = Math.max(0, width - left.length - right.length - label.length);
+  return `${left}${label}${'─'.repeat(fill)}${right}`;
+}
+
+export function canAnimateTerminal({ stdout = process.stdout, env = process.env } = {}) {
+  if (!stdout?.isTTY) return false;
+  if (String(env.TERM || '').toLowerCase() === 'dumb') return false;
+  if (String(env.CI || '').trim()) return false;
+  return true;
+}
+
+export function renderRuntimeActivityFrame({
+  label = 'Agent Sam',
+  phase = 'thinking',
+  tick = 0,
+  elapsedMs = 0,
+} = {}) {
+  const frame = SPINNER[Math.abs(Number(tick) || 0) % SPINNER.length];
+  return `  ${pc.cyan(frame)} ${pc.bold(label)} ${pc.dim(`· ${phase}`)} ${pc.dim(`· ${elapsedLabel(elapsedMs)}`)}`;
+}
+
+export function renderRuntimeActivityPanel({
+  label = 'Agent Sam',
+  phase = 'thinking',
+  tick = 0,
+  elapsedMs = 0,
+  status = 'active',
+  locality = 'working locally',
+} = {}) {
+  const frame = THINK_FRAMES[Math.abs(Number(tick) || 0) % THINK_FRAMES.length];
+  const border = status === 'success' ? pc.green : status === 'error' ? pc.red : pc.cyan;
+  const body = status === 'error' ? pc.red : pc.cyan;
+  const title = titledBorder(label, PANEL_WIDTH, '╭─', '╮');
+  const subtitle = status === 'active'
+    ? `${phase} · ${locality}`
+    : `${phase} · ${elapsedLabel(elapsedMs)}`;
+  return [
+    border(title),
+    `${border('│')}${body(center(frame[0], PANEL_INNER))}${border('│')}`,
+    `${border('│')}${body(center(frame[1], PANEL_INNER))}${border('│')}`,
+    `${border('│')}${body(center(frame[2], PANEL_INNER))}${border('│')}`,
+    border(subtitledBorder(subtitle, PANEL_WIDTH, '╰─', '╯')),
+  ].join('\n');
+}
+
+export function renderRuntimeActivityResult({
+  label = 'Agent Sam',
+  status = 'success',
+  phase = status === 'success' ? 'done' : 'failed',
+  elapsedMs = 0,
+} = {}) {
+  const ok = status === 'success';
+  const symbol = ok ? pc.green('✓') : pc.red('✗');
+  return `  ${symbol} ${pc.bold(label)} ${pc.dim(`· ${phase}`)} ${pc.dim(`· ${elapsedLabel(elapsedMs)}`)}`;
+}
+
+/**
+ * Live terminal activity for product runtime operations.
+ *
+ * This is shipped product UI, not a preview renderer. It remains quiet in pipes/CI,
+ * and only uses cursor redraw when stdout is an interactive terminal.
+ */
+export function createRuntimeActivity(options = {}) {
+  const write = options.write || process.stdout.write.bind(process.stdout);
+  const now = options.now || (() => Date.now());
+  const setTimer = options.setInterval || globalThis.setInterval;
+  const clearTimer = options.clearInterval || globalThis.clearInterval;
+  const interactive = options.interactive ?? canAnimateTerminal(options);
+  const intervalMs = Math.max(40, Number(options.intervalMs) || 90);
+  const label = String(options.label || 'Agent Sam');
+  const locality = String(options.locality || 'working locally');
+
+  let phase = String(options.phase || 'thinking');
+  let startedAt = 0;
+  let tick = 0;
+  let timer = null;
+  let started = false;
+  let finished = false;
+  let drawn = false;
+
+  const writePanel = (status = 'active') => {
+    if (!interactive || !started) return;
+    const elapsedMs = Math.max(0, now() - startedAt);
+    if (drawn) write(`\x1b[${PANEL_LINES}A`);
+    const panel = renderRuntimeActivityPanel({ label, phase, tick, elapsedMs, status, locality });
+    for (const line of panel.split('\n')) write(`\r${CLEAR_LINE}${line}\n`);
+    drawn = true;
+    tick += 1;
+  };
+
+  const draw = () => {
+    if (finished) return;
+    writePanel('active');
+  };
+
+  const start = (nextPhase = phase) => {
+    if (started || finished) return;
+    phase = String(nextPhase || phase);
+    started = true;
+    startedAt = now();
+    if (!interactive) return;
+    write(HIDE_CURSOR);
+    draw();
+    timer = setTimer(draw, intervalMs);
+  };
+
+  const update = (nextPhase) => {
+    if (nextPhase) phase = String(nextPhase);
+    if (!started) start(phase);
+    draw();
+  };
+
+  const finish = ({ status = 'success', resultPhase } = {}) => {
+    if (finished) return;
+    if (timer) clearTimer(timer);
+    timer = null;
+    phase = resultPhase || (status === 'success' ? 'done' : 'failed');
+    if (interactive && started) {
+      writePanel(status === 'success' ? 'success' : 'error');
+      write(SHOW_CURSOR);
+    }
+    finished = true;
+  };
+
+  return {
+    get interactive() { return interactive; },
+    start,
+    update,
+    succeed(phaseName = 'done') { finish({ status: 'success', resultPhase: phaseName }); },
+    fail(phaseName = 'failed') { finish({ status: 'error', resultPhase: phaseName }); },
+    stop() { finish({ status: 'success', resultPhase: 'done' }); },
+  };
+}
+
+/**
+ * Maps portable runtime events onto the customer terminal without making the renderer
+ * the authority for execution. Hosts may feed richer telemetry into the same seam.
+ */
+export function phaseForRuntimeEvent(event = {}) {
+  const type = String(event.type || '');
+  if (type === 'model.started' || type === 'model.delta') return 'thinking';
+  if (type === 'tool.started') return event.tool ? `using ${event.tool}` : 'using tool';
+  if (type === 'context.compaction.started') return 'tidying context';
+  if (type === 'context.compaction.completed') return 'context ready';
+  if (type === 'run.started') return 'working';
+  return null;
+}