@inneranimalmedia/agentsam-sdk 2.5.0 → 2.6.1

package/src/commands/shell.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { confirm, isCancel, select } from '@clack/prompts';
 import { SLASH_COMMANDS, SHELL_PHASES } from '../lib/slash-commands.js';
 import { runContext } from './context.js';
 import { runDb } from './db.js';
@@ -10,11 +11,28 @@ import { runDeploy } from './deploy.js';
 import { runStatus } from './status.js';
 import { runModels } from './models.js';
 import { configureCliPreferences } from './preferences.js';
-import { createRuntimeActivity } from '../ui/runtime-activity.js';
+import { runCloudflare } from './cloudflare.js';
+import { probeOllamaModel, resolveOllamaConfig } from './ollama.js';
+import { createInlineActivity } from '../ui/cli/activity.js';
+import { createCliRuntimePresenter } from '../ui/cli/runtime-events.js';
+import { renderCliFooter } from '../ui/cli/footer.js';
+import { diagnosticFromError, renderDiagnosticError } from '../errors/index.js';
+import { getModelRecord } from '../models/index.js';
+import { discoverProviderModels } from '../models/discovery.js';
+import { readCliPreferences, updateCliPreferences } from '../lib/cli-preferences.js';
+import { buildContextEconomicsReport, renderContextEconomics } from './context-economics.js';
+import { createProviderAdapter } from '../providers/index.js';
+import { createCapabilityAdapter, runResponsesAgent } from '../agent/index.js';
+import { resolveProviderCredential } from '../lib/provider-credentials.js';
+import { createLocalSession, saveLocalSession, sessionTitleFromInput, localSessionElapsedMs } from '../lib/local-sessions.js';
+import { grantExecutionApproval, isExecutionApproved, toolApprovalKey } from '../lib/execution-approvals.js';
+import { runWhoami } from './whoami.js';
+import { runLogin, runLogout } from './account-auth.js';
+import { runHelp } from '../ui/cli/help.js';
+import { readAccountSession } from '../lib/account-session.js';
+import { startRuntimeRun, finishRuntimeRun, recordRuntimeCompaction } from '../local/runtime-store.js';
 
-function writeLine(write, value = '') {
-  write(`${value}\n`);
-}
+function writeLine(write, value = '') { write(`${value}\n`); }
 
 export function compactCwd(value, home = process.env.HOME || process.env.USERPROFILE || '') {
   const cwd = path.resolve(value);
@@ -41,34 +59,22 @@ export function tokenizeShellLine(input = '') {
   let token = '';
   let quote = '';
   let started = false;
-
   const flush = () => {
     if (!started) return;
     tokens.push(token);
     token = '';
     started = false;
   };
-
   for (let i = 0; i < source.length; i += 1) {
     const ch = source[i];
     if (quote) {
-      if (ch === quote) {
-        quote = '';
-      } else {
-        token += ch;
-      }
-      started = true;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
+      if (ch === quote) quote = '';
+      else token += ch;
       started = true;
       continue;
     }
-    if (/\s/.test(ch)) {
-      flush();
-      continue;
-    }
+    if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
+    if (/\s/.test(ch)) { flush(); continue; }
     token += ch;
     started = true;
   }
@@ -78,21 +84,20 @@ export function tokenizeShellLine(input = '') {
 
 export function renderShellCatalog() {
   const next = SHELL_PHASES.find((phase) => phase.status === 'next' || phase.status === 'current');
-  const rows = SLASH_COMMANDS.map((row) => `    ${row.cmd.padEnd(14)} ${row.description}`).join('\n');
-  return `
-  ╔════════════════════════════════╗
-  ║        Agent Sam Terminal      ║
-  ╚════════════════════════════════╝
-
-  Local PTY   agentsam start-local     ws://127.0.0.1:3099
-  Models      agentsam models          providers + local model inventory
-  DB          agentsam db status       local SQLite
-
-  Current milestone: ${next?.label ?? 'local terminal experience'}
-
-  Slash commands (${SLASH_COMMANDS.length} registered):
-${rows}
-`;
+  return [
+    '',
+    '  Agent Sam',
+    '  Type normally to work with the selected model.',
+    '',
+    '    /        command picker',
+    '    /model   model · reasoning · processing',
+    '    /usage   tokens · cost · resume receipt',
+    '    /help    focused help',
+    '    /exit    return to host shell',
+    '',
+    `  ${next?.label ?? 'interactive runtime'} · ${SLASH_COMMANDS.length} commands available through /`,
+    '',
+  ].join('\n');
 }
 
 function parseDeployOptions(args, cwd) {
@@ -106,6 +111,105 @@ function parseDeployOptions(args, cwd) {
   return opts;
 }
 
+function spawnGit(cwd, args) {
+  const result = spawnSync('git', args, { cwd, stdio: 'inherit', shell: false });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`git exited ${result.status}`);
+}
+
+function selectedModel(cwd) {
+  const preferences = readCliPreferences(cwd) || {};
+  const snapshot = preferences.modelSnapshot?.model_key === preferences.modelPreference
+    ? preferences.modelSnapshot
+    : null;
+  const model = snapshot || getModelRecord(preferences.modelPreference);
+  if (!model) throw new Error('Select an exact provider-verified model with /model first so Agent Sam can verify supported runtime controls.');
+  return { preferences, model };
+}
+
+async function resolveModelForTurn(cwd, state) {
+  const selected = selectedModel(cwd);
+  const { preferences } = selected;
+  let model = selected.model;
+
+  if (model.provider === 'ollama') {
+    const config = resolveOllamaConfig({}, process.env);
+    const probe = await probeOllamaModel(model.provider_model_id, config, state.providerFetchImpl || fetch);
+    if (!probe.ok) throw new Error(`ollama_model_probe_failed:${model.provider_model_id}:${probe.error || 'unknown'}`);
+    model = {
+      ...model,
+      context_window: probe.context_window,
+      context_window_source: probe.context_window_source || 'unknown',
+      capabilities: { ...(model.capabilities || {}), local_runtime: true, ...(Object.fromEntries((probe.capabilities || []).map((name) => [name, true]))) },
+    };
+    updateCliPreferences(cwd, { modelPreference: model.model_key, modelSnapshot: model });
+    return { preferences: readCliPreferences(cwd) || preferences, model, credential: null, verification: 'local_runtime' };
+  }
+
+  const credential = resolveProviderCredential(model.provider, { home: state.home });
+  if (!credential.configured) {
+    throw new Error(`provider_credential_unavailable:${model.provider}:${credential.error || credential.env || 'not_configured'}`);
+  }
+
+  const discovery = await discoverProviderModels(model.provider, credential, { fetchImpl: state.providerFetchImpl || fetch });
+  if (discovery.ok) {
+    const live = discovery.models.find((row) => row.provider_model_id === model.provider_model_id || row.model_key === model.model_key);
+    if (!live) throw new Error(`selected_model_not_available_for_credential:${model.provider}:${model.provider_model_id}`);
+    model = live;
+    updateCliPreferences(cwd, { modelPreference: live.model_key, modelSnapshot: live });
+    return { preferences: readCliPreferences(cwd) || preferences, model, credential, verification: 'provider_api' };
+  }
+
+  if (preferences.modelSnapshot?.availability === 'available') {
+    return { preferences, model, credential, verification: 'cached_provider_snapshot', discoveryError: discovery.error || null };
+  }
+  throw new Error(`provider_model_discovery_failed:${model.provider}:${discovery.error || 'unknown'}`);
+}
+
+async function chooseReasoning(cwd, args, state) {
+  const { preferences, model } = selectedModel(cwd);
+  let effort = String(args[0] || '').trim().toLowerCase();
+  if (!effort) {
+    if (!state.interactive) {
+      writeLine(state.write, `  ${model.provider_model_id} reasoning: ${model.reasoning_efforts.join(' | ')}`);
+      writeLine(state.write, `  current: ${preferences.reasoningEffort || 'auto'}`);
+      return;
+    }
+    const choice = await select({
+      message: `Reasoning level · ${model.provider_model_id}`,
+      initialValue: model.reasoning_efforts.includes(preferences.reasoningEffort) ? preferences.reasoningEffort : model.reasoning_efforts[0],
+      options: model.reasoning_efforts.map((value) => ({ value, label: value === 'xhigh' ? 'Extra high' : value === 'max' ? 'Max' : value[0].toUpperCase() + value.slice(1) })),
+    });
+    if (isCancel(choice)) return;
+    effort = choice;
+  }
+  if (!model.reasoning_efforts.includes(effort)) throw new Error(`unsupported reasoning level for ${model.provider_model_id}: ${effort}`);
+  updateCliPreferences(cwd, { reasoningEffort: effort });
+  writeLine(state.write, `  reasoning → ${effort}`);
+}
+
+function setServiceTier(cwd, tier, write) {
+  const { model } = selectedModel(cwd);
+  if (!model.service_tiers.includes(tier)) throw new Error(`${model.provider_model_id} does not declare ${tier} processing support`);
+  updateCliPreferences(cwd, { serviceTier: tier });
+  const label = tier === 'default' ? 'standard' : tier;
+  writeLine(write, `  processing → ${label}`);
+  if (tier === 'fast') writeLine(write, '  Fast is a paid latency choice; Agent Sam will account for its model-specific pricing multiplier.');
+  if (tier === 'flex') writeLine(write, '  Flex trades latency/capacity availability for lower cost; it is not Batch.');
+}
+
+async function showCommandPicker(state) {
+  if (!state.interactive) {
+    state.write(renderShellCatalog());
+    return;
+  }
+  const choice = await select({
+    message: 'Agent Sam commands',
+    options: SLASH_COMMANDS.map((row) => ({ value: row.cmd, label: row.cmd, hint: row.description })),
+  });
+  if (isCancel(choice)) return;
+  await dispatchShellLine(choice, state);
+}
 
 export async function runLocalAgent(goal, write, options = {}) {
   if (!goal) {
@@ -115,90 +219,404 @@ export async function runLocalAgent(goal, write, options = {}) {
   }
   const base = String(process.env.AGENTSAM_LOCAL_URL || 'http://127.0.0.1:8787').replace(/\/$/, '');
   const fetchImpl = options.fetchImpl || fetch;
-  const activity = options.activity || createRuntimeActivity({
-    write,
-    phase: 'thinking',
-    interactive: options.interactive,
-  });
+  const activity = options.activity || createInlineActivity({ write, label: 'Thinking', interactive: options.interactive });
   let response;
   activity.start('thinking');
   try {
     response = await fetchImpl(`${base}/api/agentsam/message`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ message: goal }),
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ message: goal }),
     });
   } catch (error) {
     activity.fail('unavailable');
     throw new Error(`local Agent Sam unavailable at ${base} — run \`npm run dev\` first (${error?.message || error})`);
   }
   let text;
-  try {
-    text = await response.text();
-  } catch (error) {
-    activity.fail('response error');
-    throw new Error(`local Agent Sam response could not be read: ${error?.message || error}`);
-  }
-  if (!response.ok) {
-    activity.fail(`HTTP ${response.status}`);
-    throw new Error(`local Agent Sam returned HTTP ${response.status}: ${text.slice(0, 400)}`);
-  }
+  try { text = await response.text(); }
+  catch (error) { activity.fail('response error'); throw new Error(`local Agent Sam response could not be read: ${error?.message || error}`); }
+  if (!response.ok) { activity.fail(`HTTP ${response.status}`); throw new Error(`local Agent Sam returned HTTP ${response.status}: ${text.slice(0, 400)}`); }
   activity.succeed('done');
-  try {
-    writeLine(write, JSON.stringify(JSON.parse(text), null, 2));
-  } catch {
-    writeLine(write, text);
-  }
+  try { writeLine(write, JSON.stringify(JSON.parse(text), null, 2)); }
+  catch { writeLine(write, text); }
 }
 
 async function showLocalLogs(cwd, write) {
   const dbPath = path.join(cwd, '.agentsam', 'data', 'agentsam.sqlite');
-  if (!fs.existsSync(dbPath)) {
-    writeLine(write, '  No local Agent Sam DB found. Run `agentsam init . --yes` first.');
-    return;
-  }
+  if (!fs.existsSync(dbPath)) { writeLine(write, '  No local Agent Sam DB found. Run `agentsam init . --yes` first.'); return; }
   const { createLocalSqliteDatabase } = await import('../local/sqlite.js');
   const db = await createLocalSqliteDatabase(dbPath);
   try {
-    const calls = await db
-      .prepare('SELECT id, session_id, tool_name, status, created_at, completed_at FROM agent_tool_calls ORDER BY created_at DESC LIMIT 20')
-      .all();
-    if (!calls.results.length) {
-      writeLine(write, '  No local Agent Sam tool-call events yet.');
-      return;
-    }
+    const calls = await db.prepare('SELECT id, session_id, tool_name, status, created_at, completed_at FROM agent_tool_calls ORDER BY created_at DESC LIMIT 20').all();
+    if (!calls.results.length) { writeLine(write, '  No local Agent Sam tool-call events yet.'); return; }
+    writeLine(write, '\n  Recent Agent Sam tool calls');
+    for (const row of calls.results) writeLine(write, `  ${String(row.created_at || '').padEnd(20)} ${String(row.status || '').padEnd(10)} ${row.tool_name}`);
     writeLine(write, '');
-    writeLine(write, '  Recent Agent Sam tool calls');
-    for (const row of calls.results) {
-      writeLine(write, `  ${String(row.created_at || '').padEnd(20)} ${String(row.status || '').padEnd(10)} ${row.tool_name}`);
+  } finally { db.close(); }
+}
+
+function formatCount(value) {
+  return Math.max(0, Number(value || 0)).toLocaleString('en-US');
+}
+
+function formatUsd(value) {
+  const amount = Number(value || 0);
+  if (!Number.isFinite(amount)) return 'unavailable';
+  const currency = String.fromCharCode(36);
+  if (amount === 0) return currency + '0.000000';
+  return currency + (amount < 0.01 ? amount.toFixed(6) : amount.toFixed(4));
+}
+
+function formatElapsed(ms) {
+  const totalSeconds = Math.max(0, Math.round(Number(ms || 0) / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours) return `${hours}h ${minutes}m ${seconds}s`;
+  if (minutes) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+export function renderSessionReceipt(session) {
+  if (!session) return '';
+  const usage = session.cumulative_usage || {};
+  const input = Number(usage.input_tokens || 0);
+  const output = Number(usage.output_tokens || 0);
+  const cached = Number(usage.cached_input_tokens || 0);
+  const cacheWrite = Number(usage.cache_write_tokens || 0);
+  const reasoning = Number(usage.reasoning_tokens || 0);
+  const total = input + output;
+  const active = Number(session.usage_snapshot?.current_context?.input_tokens || 0);
+  const model = session.provider_model_id || session.model_key || 'model unavailable';
+  const breakdown = session.cost_breakdown_usd || {};
+  const componentTotal = ['input', 'cached_input', 'cache_write', 'output'].reduce((sum, key) => sum + Number(breakdown[key] || 0), 0);
+  const elapsed = localSessionElapsedMs(session);
+  const lines = [
+    '',
+    'Session summary',
+    `Token usage: total=${formatCount(total)} input=${formatCount(input)}${cached ? ` (+ ${formatCount(cached)} cached)` : ''}${cacheWrite ? ` (+ ${formatCount(cacheWrite)} cache write)` : ''} output=${formatCount(output)}${reasoning ? ` reasoning=${formatCount(reasoning)}` : ''}`,
+    `Spent: ${formatUsd(session.total_cost_usd)} · ${model}${session.actual_service_tier ? ` · ${session.actual_service_tier}` : ''}`,
+    `Elapsed: ${formatElapsed(elapsed)}`,
+  ];
+  if (componentTotal > 0) {
+    lines.push(`Cost breakdown: input ${formatUsd(breakdown.input)} · cached ${formatUsd(breakdown.cached_input)} · cache write ${formatUsd(breakdown.cache_write)} · output ${formatUsd(breakdown.output)}`);
+  }
+  if (active) lines.push(`Active context: ${formatCount(active)} tokens`);
+  lines.push('', 'To continue this session, run:', `  agentsam resume ${session.id}`, '', 'Or run:', '  agentsam resume', '', 'and select:', `  ${session.title || 'this session'}`, '');
+  return lines.join('\n');
+}
+
+function persistSession(state, patch = {}) {
+  if (!state.session) return null;
+  state.session = saveLocalSession({ ...state.session, ...patch }, { home: state.home });
+  return state.session;
+}
+
+function recordSessionInput(state, input) {
+  const value = String(input || '').trim();
+  if (!state.session || !value) return;
+  const housekeeping = new Set(['/exit', '/quit', '/session', '/help', '/', '/menu', '/clear']);
+  if (housekeeping.has(value.toLowerCase())) return;
+  persistSession(state, {
+    status: 'active',
+    last_input: value,
+    title: sessionTitleFromInput(value),
+  });
+}
+
+function safeToolInput(value, depth = 0) {
+  if (depth > 3) return '[nested]';
+  if (Array.isArray(value)) return value.slice(0, 12).map((row) => safeToolInput(row, depth + 1));
+  if (!value || typeof value !== 'object') return value;
+  const output = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (/token|secret|password|api[_-]?key|authorization/i.test(key)) output[key] = '[REDACTED]';
+    else output[key] = safeToolInput(item, depth + 1);
+  }
+  return output;
+}
+
+async function approveModelRequest(preflight, state) {
+  const projected = Number(preflight.projected_max_call_cost_usd);
+  const threshold = Number(process.env.AGENTSAM_CONFIRM_CALL_COST_USD || 0);
+  if (!(Number.isFinite(projected) && projected >= 0)) return true;
+  if (!(Number.isFinite(threshold) && threshold > 0) || projected <= threshold) return true;
+
+  const approvedCeiling = Number(state.session?.approved_projected_call_cost_usd || 0);
+  if (approvedCeiling > 0 && projected <= approvedCeiling) return true;
+  if (!state.interactive) return false;
+
+  state.activity?.clear?.();
+  writeLine(state.write, '');
+  writeLine(state.write, '  ◆ Model cost approval');
+  writeLine(state.write, `    model       ${preflight.model}`);
+  writeLine(state.write, `    reasoning   ${preflight.reasoning_effort}`);
+  writeLine(state.write, `    processing  ${preflight.service_tier}`);
+  writeLine(state.write, `    context     ~${formatCount(preflight.estimated_input_tokens)} input tokens`);
+  writeLine(state.write, `    max call    ${formatUsd(projected)} conservative ceiling`);
+  if (Number.isFinite(preflight.tokens_until_pricing_threshold)) writeLine(state.write, `    headroom    ${formatCount(preflight.tokens_until_pricing_threshold)} tokens`);
+  const approved = await confirm({ message: 'Allow this call?', initialValue: false });
+  if (isCancel(approved) || approved !== true) return false;
+  persistSession(state, { approved_projected_call_cost_usd: Math.max(approvedCeiling, projected) });
+  state.activity?.start?.('Working');
+  return true;
+}
+
+async function approveToolExecution(request, state) {
+  const sideEffects = request?.descriptor?.side_effects || 'none';
+  if (sideEffects === 'none') return true;
+  const key = toolApprovalKey(request.capability_id, request.input);
+  if (isExecutionApproved({ cwd: state.cwd, key }, { home: state.home })) return true;
+  if (!state.interactive) return false;
+
+  const summary = JSON.stringify(safeToolInput(request.input || {}));
+  state.activity?.clear?.();
+  writeLine(state.write, '');
+  writeLine(state.write, '  Agent Sam needs execution permission');
+  writeLine(state.write, `  action  ${key}`);
+  writeLine(state.write, `  target  local runtime · ${compactCwd(state.cwd)}`);
+  writeLine(state.write, `  effect  ${sideEffects}`);
+  if (summary && summary !== '{}') writeLine(state.write, `  input   ${summary.length > 500 ? `${summary.slice(0, 497)}...` : summary}`);
+  writeLine(state.write, '  secrets remain runtime-owned and are not included in the model-visible result.');
+
+  const choice = await select({
+    message: `Allow ${key}?`,
+    options: [
+      { value: 'once', label: 'Allow once' },
+      { value: 'always', label: `Always allow ${key} in this project` },
+      { value: 'deny', label: 'Deny' },
+    ],
+  });
+  if (isCancel(choice) || choice === 'deny') return false;
+  if (choice === 'always') grantExecutionApproval({ cwd: state.cwd, key, label: key }, { home: state.home });
+  state.activity?.start?.(`Working · ${request.capability_id}`);
+  return true;
+}
+
+async function runInteractiveModelTurn(prompt, state) {
+  const resolved = await resolveModelForTurn(state.cwd, state);
+  const { preferences, model, credential } = resolved;
+  const provider = createProviderAdapter({
+    modelRecord: model,
+    credential,
+    endpoint: model.provider === 'ollama' ? process.env.OLLAMA_BASE_URL : undefined,
+    fetchImpl: state.providerFetchImpl,
+  });
+  const capabilityAdapter = createCapabilityAdapter();
+
+  const samePolicy = state.session
+    && state.session.model_key === model.model_key
+    && state.session.reasoning_effort === preferences.reasoningEffort
+    && state.session.requested_service_tier === preferences.serviceTier;
+  const previousProviderState = samePolicy ? state.session?.provider_state : null;
+  const previousUsageSnapshot = samePolicy ? state.session?.usage_snapshot : null;
+  const accountId = readAccountSession({ home: state.home })?.account_id || null;
+  let runtimeRunId = null;
+  try {
+    runtimeRunId = await startRuntimeRun({
+      cwd: state.cwd,
+      account_id: accountId,
+      mode: 'agent',
+      model_key: model.model_key,
+      reasoning_effort: preferences.reasoningEffort,
+      service_tier: preferences.serviceTier,
+    });
+  } catch {
+    runtimeRunId = null;
+  }
+
+  const activity = createInlineActivity({
+    write: state.write,
+    interactive: state.interactive,
+    label: `Thinking · ${model.provider_model_id}`,
+  });
+  state.activity = activity;
+  const presenter = createCliRuntimePresenter({ activity, write: state.write, state });
+  const startedAt = Date.now();
+  activity.start(`Thinking · ${model.provider_model_id}`);
+
+  let result;
+  try {
+    result = await runResponsesAgent({
+      provider,
+      capabilityAdapter,
+      cwd: state.cwd,
+      prompt,
+      model: model.model_key,
+      modelRecord: model,
+      reasoningEffort: preferences.reasoningEffort,
+      serviceTier: preferences.serviceTier,
+      previousProviderState,
+      previousUsageSnapshot,
+      cumulativeUsage: state.session?.cumulative_usage || null,
+      promptCacheKey: state.session?.id || undefined,
+      runId: runtimeRunId || state.session?.id || undefined,
+      beforeRequest: (preflight) => approveModelRequest(preflight, state),
+      beforeTool: (request) => approveToolExecution(request, state),
+      emit(event) {
+        presenter.handle(event);
+        if (event?.type === 'usage.snapshot') state.usageSnapshot = event.payload;
+      },
+    });
+  } catch (error) {
+    activity.fail('Failed');
+    state.activity = null;
+    if (runtimeRunId) {
+      try {
+        await finishRuntimeRun({
+          cwd: state.cwd,
+          id: runtimeRunId,
+          status: 'failed',
+          error_code: error?.code || 'interactive_error',
+          error_message: error?.message || String(error),
+          latency_ms: Date.now() - startedAt,
+        });
+      } catch { /* execution result remains primary */ }
     }
-    writeLine(write, '');
-  } finally {
-    db.close();
+    throw error;
   }
+
+  activity.succeed(result.tool_receipts?.length ? `Done · ${result.tool_receipts.length} tool call${result.tool_receipts.length === 1 ? '' : 's'}` : 'Done');
+  state.activity = null;
+
+  const compacted = presenter.compactionReceipt();
+  if (compacted) writeLine(state.write, compacted);
+
+  if (result.output_text) {
+    writeLine(state.write, '');
+    writeLine(state.write, result.output_text);
+    writeLine(state.write, '');
+  }
+
+  state.usageSnapshot = result.usage_snapshot;
+  if (runtimeRunId) {
+    try {
+      await finishRuntimeRun({
+        cwd: state.cwd,
+        id: runtimeRunId,
+        status: 'completed',
+        actual_service_tier: result.actual_service_tier,
+        usage: result.cumulative_usage || result.usage_snapshot?.cumulative || {},
+        cost_usd: result.total_cost_usd || 0,
+        latency_ms: Date.now() - startedAt,
+      });
+      if (presenter.state.lastCompaction) {
+        await recordRuntimeCompaction({
+          cwd: state.cwd,
+          account_id: accountId,
+          agent_run_id: runtimeRunId,
+          session_id: state.session?.id,
+          provider: model.provider,
+          model_key: model.model_key,
+          tokens_before: presenter.state.lastCompaction.tokens_before,
+          tokens_after: presenter.state.lastCompaction.tokens_after,
+          summary_text: presenter.state.lastCompaction.summary_text || '',
+          source_kind: model.provider === 'ollama' ? 'filesystem' : 'api',
+          metadata: { verification: resolved.verification, compaction_id: presenter.state.lastCompaction.compaction_id || null },
+        });
+      }
+    } catch { /* local telemetry persistence is best-effort */ }
+  }
+  if (state.session) {
+    persistSession(state, {
+      status: 'active',
+      model_key: model.model_key,
+      provider_model_id: result.model,
+      reasoning_effort: result.reasoning_effort,
+      requested_service_tier: result.requested_service_tier,
+      actual_service_tier: result.actual_service_tier,
+      provider_state: { provider: model.provider, ...(result.provider_state || {}) },
+      usage_snapshot: result.usage_snapshot,
+      cumulative_usage: result.cumulative_usage,
+      total_cost_usd: Number(state.session.total_cost_usd || 0) + Number(result.total_cost_usd || 0),
+      cost_breakdown_usd: Object.fromEntries(['input', 'cached_input', 'cache_write', 'output'].map((key) => [
+        key, Number(state.session.cost_breakdown_usd?.[key] || 0) + Number(result.cost_breakdown_usd?.[key] || 0),
+      ])),
+      last_error: null,
+    });
+  }
+
+  writeLine(state.write, renderCliFooter({
+    model: result.model || model.provider_model_id,
+    usageSnapshot: result.usage_snapshot,
+    tier: result.actual_service_tier,
+    elapsedMs: Date.now() - startedAt,
+  }));
+  writeLine(state.write, '');
+  return result;
 }
 
 export async function dispatchShellLine(line, state = {}) {
   const tokens = tokenizeShellLine(line);
   const write = state.write || ((text) => process.stdout.write(text));
+  state.write = write;
   state.cwd = path.resolve(state.cwd || process.cwd());
   if (!tokens.length) return { handled: true, exit: false, cwd: state.cwd };
-
   const [command, ...args] = tokens;
   try {
     switch (command.toLowerCase()) {
+      case '/':
+      case '/menu':
+        await showCommandPicker(state);
+        break;
       case '/help':
-        write(renderShellCatalog());
-        return { handled: true, exit: false, cwd: state.cwd };
+        await runHelp(args, { write, interactive: state.interactive });
+        break;
       case '/exit':
       case '/quit':
         return { handled: true, exit: true, cwd: state.cwd };
+      case '/model': {
+        const configured = await configureCliPreferences({ cwd: state.cwd, firstRun: false, section: 'model', home: state.home });
+        state.cwd = configured.identity.root;
+        break;
+      }
+      case '/reasoning':
+        await chooseReasoning(state.cwd, args, state);
+        break;
+      case '/fast':
+        setServiceTier(state.cwd, 'fast', write);
+        break;
+      case '/flex':
+        setServiceTier(state.cwd, 'flex', write);
+        break;
+      case '/standard':
+        setServiceTier(state.cwd, 'default', write);
+        break;
+      case '/context':
+        if (args[0] === 'repo' || args[0] === 'git') await runContext(['--cwd', state.cwd, ...args.slice(1)]);
+        else write(renderContextEconomics(buildContextEconomicsReport(state.cwd, {
+          activeInputTokens: state.usageSnapshot?.current_context?.input_tokens,
+          estimateKind: state.usageSnapshot?.estimate_kind,
+        })));
+        break;
       case '/status':
         await runStatus(args, { cwd: state.cwd });
         break;
-      case '/context':
-        await runContext(['--cwd', state.cwd, ...args]);
+      case '/models':
+        await runModels(args, { cwd: state.cwd, write, home: state.home });
         break;
+      case '/login':
+        await runLogin(args, { write, home: state.home });
+        break;
+      case '/logout':
+        runLogout(args, { write, home: state.home });
+        if (state.session) write(renderSessionReceipt(state.session));
+        break;
+      case '/whoami':
+        await runWhoami(args, { write, home: state.home });
+        break;
+      case '/session':
+      case '/usage':
+        if (state.session) write(renderSessionReceipt(state.session));
+        else writeLine(write, '  No persistent session is active in this shell invocation.');
+        break;
+      case '/cf':
+      case '/cloudflare':
+        await runCloudflare(args.length ? args : ['commands'], { cwd: state.cwd, write });
+        break;
+      case '/settings': {
+        const configured = await configureCliPreferences({ cwd: state.cwd, firstRun: false, home: state.home });
+        state.cwd = configured.identity.root;
+        break;
+      }
       case '/pwd':
         writeLine(write, state.cwd);
         break;
@@ -210,54 +628,60 @@ export async function dispatchShellLine(line, state = {}) {
         writeLine(write, state.cwd);
         break;
       }
-      case '/git': {
-        const gitArgs = args.length ? args : ['status', '--short', '--branch'];
-        const result = spawnSync('git', gitArgs, { cwd: state.cwd, stdio: 'inherit', shell: false });
-        if (result.error) throw result.error;
-        if (result.status !== 0) throw new Error(`git exited ${result.status}`);
+      case '/git':
+        spawnGit(state.cwd, args.length ? args : ['status', '--short', '--branch']);
+        break;
+      case '/diff':
+        spawnGit(state.cwd, ['diff', ...args]);
         break;
-      }
       case '/db':
         await runDb(args.length ? args : ['status'], { cwd: state.cwd });
         break;
       case '/agent':
         await runLocalAgent(args.join(' '), write, { interactive: state.interactive });
         break;
-      case '/models':
-        await runModels(args, { cwd: state.cwd, write });
-        break;
-      case '/settings': {
-        const configured = await configureCliPreferences({ cwd: state.cwd, firstRun: false });
-        state.cwd = configured.identity.root;
-        break;
-      }
       case '/logs':
         await showLocalLogs(state.cwd, write);
         break;
       case '/deploy':
         await runDeploy(parseDeployOptions(args, state.cwd));
         break;
+      case '/clear':
+        write('\x1b[2J\x1b[H');
+        break;
       default:
+        if (!command.startsWith('/')) {
+          await runInteractiveModelTurn(line, state);
+          break;
+        }
         writeLine(write, `  Unknown Agent Sam command: ${command}`);
-        writeLine(write, '  Type /help for available commands.');
+        writeLine(write, '  Type / or /help for available commands.');
         return { handled: false, exit: false, cwd: state.cwd };
     }
   } catch (error) {
-    writeLine(write, `  ✗ ${error?.message || error}`);
+    if (state.session) {
+      persistSession(state, { last_error: diagnosticFromError(error, { source: 'shell', kind: 'interactive_error' }) });
+    }
+    if (!error?.reported) {
+      for (const line of renderDiagnosticError(error).split('\n')) writeLine(write, `  ${line}`);
+    }
   }
-
   return { handled: true, exit: false, cwd: state.cwd };
 }
 
 export async function runShell(argv = [], options = {}) {
   const write = options.write || ((text) => process.stdout.write(text));
-  const state = { cwd: path.resolve(options.cwd || process.cwd()), write, interactive: options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY) };
+  const state = {
+    cwd: path.resolve(options.cwd || process.cwd()),
+    write,
+    interactive: options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    usageSnapshot: options.usageSnapshot || options.session?.usage_snapshot || null,
+    session: options.session || null,
+    home: options.home,
+    providerFetchImpl: options.providerFetchImpl,
+  };
   const sub = argv[0] || '';
-
-  if (sub === 'list' || sub === 'status') {
-    write(renderShellCatalog());
-    return;
-  }
+  if (sub === 'list' || sub === 'status') { write(renderShellCatalog()); return; }
   if (sub === '--command' || sub === '--once') {
     const line = argv.slice(1).join(' ');
     if (!line) throw new Error(`${sub} requires a slash command`);
@@ -266,32 +690,57 @@ export async function runShell(argv = [], options = {}) {
   }
   if (sub) throw new Error(`unknown shell option: ${sub}`);
 
+  if (state.session) {
+    state.cwd = path.resolve(state.session.cwd || state.cwd);
+    state.session = saveLocalSession({
+      ...state.session,
+      status: 'active',
+      cwd: state.cwd,
+      active_started_at: new Date().toISOString(),
+    }, { home: state.home });
+    state.usageSnapshot = state.session.usage_snapshot || state.usageSnapshot;
+  } else {
+    const preferences = readCliPreferences(state.cwd) || {};
+    state.session = createLocalSession({
+      cwd: state.cwd,
+      status: 'active',
+      model_key: preferences.modelPreference !== 'auto' ? preferences.modelPreference : null,
+      reasoning_effort: preferences.reasoningEffort !== 'auto' ? preferences.reasoningEffort : null,
+      requested_service_tier: preferences.serviceTier || 'default',
+    }, { home: state.home });
+  }
+
   if (options.intro !== 'quiet') {
     write(renderShellCatalog());
-    writeLine(write, '  Interactive shell ready. Type /help for commands; /exit to return to your host shell.');
-    writeLine(write, '');
+    writeLine(write, '  Interactive shell ready. Type / for the command picker; /exit to return to your host shell.\n');
   }
-
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+  let interrupted = false;
+  rl.on('SIGINT', () => {
+    interrupted = true;
+    rl.close();
+  });
   const promptText = () => {
     if (typeof options.prompt === 'function') return options.prompt(state);
     if (typeof options.prompt === 'string' && options.prompt) return options.prompt;
     return renderShellPrompt(state.cwd);
   };
-  if (rl.terminal) {
-    rl.setPrompt(promptText());
-    rl.prompt();
-  }
-
+  if (rl.terminal) { rl.setPrompt(promptText()); rl.prompt(); }
   for await (const line of rl) {
+    recordSessionInput(state, line);
     const result = await dispatchShellLine(line, state);
-    if (result.exit) {
-      rl.close();
-      break;
-    }
-    if (rl.terminal) {
-      rl.setPrompt(promptText());
-      rl.prompt();
-    }
+    if (result.exit) { rl.close(); break; }
+    if (rl.terminal) { rl.setPrompt(promptText()); rl.prompt(); }
+  }
+  if (state.session) {
+    const activeElapsedMs = localSessionElapsedMs(state.session);
+    persistSession(state, {
+      status: interrupted ? 'interrupted' : 'paused',
+      cwd: state.cwd,
+      active_elapsed_ms: activeElapsedMs,
+      active_started_at: null,
+    });
+    if (options.receipt !== false) write(renderSessionReceipt(state.session));
   }
+  return state.session;
 }