@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/commands/eval.js

@@ -0,0 +1,63 @@
+import { evaluateContextFixture, listContextEvalFixtures } from '../eval/index.js';
+
+function parse(argv) {
+  const out = { subcommand: argv[0] || '', fixture: '', strategy: 'all', model: 'gpt-6-astra', json: false, list: false };
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--fixture') out.fixture = argv[++i] || '';
+    else if (arg === '--strategy') out.strategy = argv[++i] || 'all';
+    else if (arg === '--model') out.model = argv[++i] || 'gpt-6-astra';
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--list') out.list = true;
+    else if (arg === '--help' || arg === '-h') out.help = true;
+    else throw new Error(`unknown eval option: ${arg}`);
+  }
+  return out;
+}
+
+function render(report) {
+  const rows = [
+    '',
+    '  AgentSam · Context Eval',
+    '',
+    `  fixture          ${report.fixture}`,
+    `  model            ${report.model}`,
+    `  provider call    no · deterministic/offline`,
+    '',
+  ];
+  for (const row of report.strategies) {
+    rows.push(`  ${row.strategy.toUpperCase()}`);
+    rows.push(`    result           ${row.result}`);
+    rows.push(`    evidence         ${row.required_found} / ${row.required_evidence} required · ${row.sources_selected} / ${row.sources_considered} selected`);
+    rows.push(`    active context   ~${row.active_context_tokens.toLocaleString('en-US')}`);
+    rows.push(`    window           ${row.window_tokens.toLocaleString('en-US')}`);
+    rows.push(`    price threshold  ${row.pricing_threshold_tokens.toLocaleString('en-US')}`);
+    rows.push(`    remaining        ${row.tokens_until_pricing_threshold.toLocaleString('en-US')}`);
+    rows.push(`    tool schemas     ${row.hydrated_tools} · ${row.tool_schema_chars.toLocaleString('en-US')} chars`);
+    rows.push(`    compacted        ${row.compacted_chars.toLocaleString('en-US')} chars`);
+    rows.push(`    rehydrated       ${row.rehydrated_refs.length ? row.rehydrated_refs.join(', ') : 'none'}`);
+    rows.push(`    est input cost   $${row.estimated_input_cost_usd.toFixed(4)}`);
+    rows.push('');
+  }
+  rows.push(`  winner           ${report.winner}`);
+  rows.push(`  scoring          ${report.scoring.join(' → ')}`);
+  rows.push('');
+  return rows.join('\n');
+}
+
+export async function runEval(argv = [], options = {}) {
+  const args = parse(argv);
+  const write = options.write || (text => process.stdout.write(text));
+  if (args.help || args.subcommand !== 'context') {
+    write('agentsam eval context --fixture <name> [--strategy bounded|discovery|compact|all] [--model gpt-6-astra] [--json]\n');
+    return null;
+  }
+  if (args.list) {
+    const value = { fixtures: listContextEvalFixtures() };
+    write(args.json ? `${JSON.stringify(value)}\n` : `${value.fixtures.join('\n')}\n`);
+    return value;
+  }
+  const report = await evaluateContextFixture({ fixture: args.fixture || 'exact-symbol-callers', strategy: args.strategy, model: args.model });
+  write(args.json ? `${JSON.stringify(report)}\n` : render(report));
+  return report;
+}

package/src/commands/interactive.js

@@ -0,0 +1,18 @@
+import { configureCliPreferences } from './preferences.js';
+import { runShell } from './shell.js';
+import { detectCliProject, readCliPreferences } from '../lib/cli-preferences.js';
+import { runBootScene } from '../ui/boot.js';
+
+export async function runInteractive(options = {}) {
+  let identity = detectCliProject(options.cwd || process.cwd());
+  let preferences = readCliPreferences(identity.root);
+
+  if (!preferences || preferences.trustedDirectory !== true) {
+    const configured = await configureCliPreferences({ cwd: identity.root, firstRun: true });
+    identity = configured.identity;
+    preferences = configured.preferences;
+  }
+
+  await runBootScene({ identity, preferences, animate: options.animate !== false });
+  await runShell([], { cwd: identity.root, intro: 'quiet' });
+}

package/src/commands/knowledge.js

@@ -6,12 +6,15 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
+import pkg from '../../package.json' with { type: 'json' };
 import { CONFIG_PATH, repositoryRoot, initRepository, readConfig, scopeKey, cacheNamespace } from '../knowledge/config.js';
 import { openSqliteStore } from '../knowledge/stores/sqlite.js';
 import { openPostgresStore } from '../knowledge/stores/postgres.js';
 import { planIndex, runIndex, retrieve } from '../knowledge/engine.js';
 import { createGeminiEmbedder } from '../knowledge/providers/gemini.js';
 import { compareObservations } from '../knowledge/evolution.js';
+import { ensureProjectManifest, getProjectName, getRepositoryId } from '../lib/project-config.js';
+import { ensureProjectRules } from '../lib/project-rules.js';
 
 const execute = promisify(execFile);
 const split = text => text.split(',').map(s => s.trim()).filter(Boolean);
@@ -28,7 +31,20 @@ export async function runRepositoryInit(argv) {
   if (opts.help) { console.log('agentsam init [.] [--cwd PATH] [--yes] [--include src,docs] [--exclude src/generated] [--scope NAME] [--target local|production] [--dimensions 768]'); return; }
   if (positionals.length > 1 || (positionals[0] && positionals[0] !== '.')) throw new Error('Use init . --cwd PATH to adopt an existing repository, or init --name NAME to scaffold.');
   const root = repositoryRoot(opts.cwd);
-  if (fs.existsSync(path.join(root, CONFIG_PATH))) throw new Error(`${CONFIG_PATH} already exists; edit it to change scope/profile. Existing configuration was preserved.`);
+  const knowledgePath = path.join(root, CONFIG_PATH);
+  const existingKnowledge = fs.existsSync(knowledgePath) ? readConfig(root) : null;
+  const projectManifest = ensureProjectManifest(root, {
+    repositoryId: existingKnowledge?.repository_id || undefined,
+    sdkVersion: pkg.version,
+  });
+  ensureProjectRules(root, getProjectName(projectManifest));
+  const projectRepositoryId = getRepositoryId(projectManifest);
+  if (existingKnowledge) {
+    if (projectRepositoryId && existingKnowledge.repository_id !== projectRepositoryId) {
+      throw new Error(`repository_identity_mismatch: project=${projectRepositoryId} knowledge=${existingKnowledge.repository_id}`);
+    }
+    throw new Error(`${CONFIG_PATH} already exists; edit it to change scope/profile. Existing configuration was preserved.`);
+  }
   let include = opts.include, exclude = opts.exclude, target = opts.target, dimensions = opts.dimensions;
   if (!opts.yes) {
     if (!process.stdin.isTTY) throw new Error('Existing-repository setup needs a terminal or --yes with explicit options.');
@@ -41,7 +57,14 @@ export async function runRepositoryInit(argv) {
       dimensions ??= await prompt.question('4) Gemini Embedding 2 dimensions [768]: ') || '768';
     } finally { prompt.close(); }
   }
-  const config = initRepository(root, { include: split(include || '.'), exclude: split(exclude || ''), scope: opts.scope || 'default', target: target || 'local', dimensions: Number(dimensions || 768) });
+  const config = initRepository(root, {
+    include: split(include || '.'),
+    exclude: split(exclude || ''),
+    scope: opts.scope || 'default',
+    target: target || 'local',
+    dimensions: Number(dimensions || 768),
+    repositoryId: projectRepositoryId,
+  });
   show({ root, config: CONFIG_PATH, storage: config.storage.driver, next: config.storage.driver === 'postgres' ? ['agentsam index setup-store', 'agentsam index plan', 'agentsam index run'] : ['agentsam index plan', 'agentsam index run', 'agentsam search "your symbol"'], note: 'No indexing, credentials, network calls, or source-file changes during setup.' });
 }
 
@@ -73,9 +96,9 @@ export async function runKnowledge(argv) {
 
 export async function runSearch(argv) {
   const { values: opts, positionals } = flags(argv, { semantic: { type: 'boolean' }, 'top-k': { type: 'string' }, 'token-budget': { type: 'string' }, generation: { type: 'string' } });
-  if (opts.help) { console.log('agentsam search "query" [--cwd PATH] [--semantic] [--top-k 8] [--token-budget 8000] [--generation ID]'); return; }
+  if (opts.help) { console.log('agentsam search "query" [--cwd PATH] [--semantic] [--top-k 8] [--token-budget 6000] [--generation ID]'); return; }
   const root = repositoryRoot(opts.cwd), config = readConfig(root), store = await openStore(root, config, true);
-  try { show(await retrieve({ store, config, text: positionals.join(' '), semantic: opts.semantic, embedder: opts.semantic ? provider() : null, topK: Number(opts['top-k'] || 8), tokenBudget: Number(opts['token-budget'] || 8000), generationId: opts.generation })); }
+  try { show(await retrieve({ store, config, text: positionals.join(' '), semantic: opts.semantic, embedder: opts.semantic ? provider() : null, topK: Number(opts['top-k'] || 8), tokenBudget: Number(opts['token-budget'] || 6000), generationId: opts.generation })); }
   finally { await store?.close(); }
 }
 

package/src/commands/merkle-persist.js

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import { readSnapshot } from '../lib/merkle/snapshot.js';
+import {
+  buildMerklePersistencePlan,
+  persistMerkleSnapshotCloudflare,
+  resolveWranglerMerklePersistence,
+} from '../lib/merkle/cloudflare-persistence.js';
+
+function value(args, index, flag) {
+  const next = args[index + 1];
+  if (!next || next.startsWith('--')) throw new Error(`Missing value for ${flag}`);
+  return next;
+}
+
+export function printMerklePersistHelp() {
+  console.log(`
+  agentsam merkle persist <snapshot.json> — publish a saved Merkle snapshot through host bindings
+
+  --wrangler-config <file>    Worker config containing WEBSITE_ASSETS and optionally DB
+  --owner-user-id <id>        Snapshot owner authority (or AGENTSAM_OWNER_USER_ID)
+  --repo-id <id>              Canonical repo id; inferred for GitHub/GitLab/Bitbucket when possible
+  --capture-kind <kind>       deploy|manual|agent|index (default manual)
+  --connection-id <id>        Execution provenance for non-deploy captures
+  --runtime-lease-id <id>     Alternative execution provenance for non-deploy captures
+  --deployment-id <id>        Optional deployment linkage
+  --worker-version <id>       Optional provider worker version linkage
+  --reference-label <label>   Optional human/audit label
+  --source <source>           github|gitlab|bitbucket|local|upload (default local)
+  --prefix <prefix>           Object prefix (default agentsam_fs_merkle_snapshots)
+  --r2-binding <name>         Logical R2 role (default WEBSITE_ASSETS)
+  --d1-binding <name>         Logical D1 role (default DB)
+  --environment <name>        Wrangler environment
+  --wrangler-bin <path>       Wrangler executable (default WRANGLER_BIN or wrangler)
+  --r2-only                   Upload object without indexing in D1
+  --dry-run                   Resolve bindings and emit the exact storage/index plan without writes
+  --json                      Machine-readable output
+
+  The SDK never infers owner identity. Hosts should pass authenticated owner_user_id.
+  Physical bucket/database names come from Wrangler bindings, so customer installs keep
+  WEBSITE_ASSETS/DB while selecting their own storage resources.
+`);
+}
+
+function parse(args) {
+  if (!args.length || args.includes('--help') || args.includes('-h')) return { help: true };
+  const opts = {
+    snapshotPath: '', json: false, dryRun: false, r2Only: false,
+    captureKind: 'manual', source: 'local', r2Binding: 'WEBSITE_ASSETS', d1Binding: 'DB',
+    storagePrefix: 'agentsam_fs_merkle_snapshots',
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('-') && !opts.snapshotPath) { opts.snapshotPath = arg; continue; }
+    if (arg === '--json') { opts.json = true; continue; }
+    if (arg === '--dry-run') { opts.dryRun = true; continue; }
+    if (arg === '--r2-only') { opts.r2Only = true; continue; }
+    const map = {
+      '--wrangler-config': 'wranglerConfig', '--owner-user-id': 'ownerUserId', '--repo-id': 'repoId',
+      '--capture-kind': 'captureKind', '--connection-id': 'connectionId', '--runtime-lease-id': 'runtimeLeaseId',
+      '--deployment-id': 'deploymentId', '--worker-version': 'workerVersionId', '--reference-label': 'referenceLabel',
+      '--source': 'source', '--prefix': 'storagePrefix', '--r2-binding': 'r2Binding', '--d1-binding': 'd1Binding',
+      '--environment': 'environment', '--wrangler-bin': 'wranglerBin', '--root': 'root',
+    };
+    if (map[arg]) { opts[map[arg]] = value(args, i, arg); i += 1; continue; }
+    throw new Error(`Unknown merkle persist option: ${arg}`);
+  }
+  if (!opts.snapshotPath) throw new Error('snapshot_file_required');
+  opts.ownerUserId ||= process.env.AGENTSAM_OWNER_USER_ID || '';
+  opts.wranglerConfig ||= process.env.AGENTSAM_WRANGLER_CONFIG || '';
+  opts.connectionId ||= process.env.AGENTSAM_CONNECTION_ID || '';
+  opts.runtimeLeaseId ||= process.env.AGENTSAM_RUNTIME_LEASE_ID || '';
+  return opts;
+}
+
+export async function runMerklePersist(args = []) {
+  const opts = parse(args);
+  if (opts.help) { printMerklePersistHelp(); return null; }
+  const snapshotPath = path.resolve(opts.snapshotPath);
+  const snapshot = await readSnapshot(snapshotPath);
+  const root = path.resolve(opts.root || snapshot.rootPath || process.cwd());
+  const wrangler = resolveWranglerMerklePersistence({
+    configPath: opts.wranglerConfig,
+    environment: opts.environment || null,
+    r2Binding: opts.r2Binding,
+    d1Binding: opts.d1Binding,
+    r2Only: opts.r2Only,
+  });
+  const plan = buildMerklePersistencePlan({
+    snapshot,
+    root,
+    ownerUserId: opts.ownerUserId,
+    repoId: opts.repoId,
+    source: opts.source,
+    captureKind: opts.captureKind,
+    connectionId: opts.connectionId,
+    runtimeLeaseId: opts.runtimeLeaseId,
+    deploymentId: opts.deploymentId,
+    workerVersionId: opts.workerVersionId,
+    referenceLabel: opts.referenceLabel,
+    storagePrefix: opts.storagePrefix,
+    wrangler,
+  });
+  const result = persistMerkleSnapshotCloudflare({
+    snapshotPath,
+    snapshot,
+    plan,
+    wranglerBin: opts.wranglerBin,
+    r2Only: opts.r2Only,
+    dryRun: opts.dryRun,
+  });
+  if (opts.json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else {
+    console.log(`Persisted ${result.snapshot_id}${result.dry_run ? ' (dry run)' : ''}`);
+    console.log(`  R2   ${result.binding} -> ${result.storage_bucket}/${result.storage_key}`);
+    if (result.table) console.log(`  D1   ${result.database_binding} -> ${result.database_name}.${result.table}`);
+  }
+  return result;
+}

package/src/commands/merkle.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { buildMerkleTree, saveSnapshot, readSnapshot, diffTrees, normalizePolicy } from '../lib/merkle/index.js';
 import { renderSummary, safeText } from '../ui/merkle/render.js';
 import { runMerkleExplorer } from '../ui/merkle/explorer.js';
+import { runMerklePersist } from './merkle-persist.js';
 
 export function printMerkleHelp() {
   console.log(`
@@ -13,24 +14,26 @@ export function printMerkleHelp() {
   verify <snapshot>           Check current files against a saved manifest
   diff <a> <b>                Compare two directories or snapshot files
   inspect [path]              Show every path and hash (also accepts a snapshot)
-  tui [path]                  Open the interactive tree explorer
+  persist <snapshot>          Publish a saved snapshot through WEBSITE_ASSETS/DB bindings
+  explore [path]              Open the interactive tree explorer
 
   --out <file>                Snapshot destination
   --force                     Replace an existing snapshot file
+  --semantic                  Add agentsam-filemeta classification + AST metadata
   --root <path>               Verify a snapshot against a different directory
   --include <default-rule>    Include an ignored category, e.g. --include dist
   --exclude <path-or-name>    Ignore an additional name or relative subtree
-  --tui                       Explore root/inspect/verify/diff interactively
-  --json                      Machine-readable output; never opens a TUI
+  --interactive               Explore root/inspect/verify/diff interactively
+  --json                      Machine-readable output; never opens the interactive explorer
 
   Examples:
     agentsam merkle root .
-    agentsam merkle snapshot . --out .agentsam/merkle.json
-    agentsam merkle verify .agentsam/merkle.json --tui
-    agentsam merkle diff ./mac-copy ./vm-copy --tui
-    agentsam tui merkle .
+    agentsam merkle snapshot . --semantic --out .agentsam/merkle.json
+    agentsam merkle verify .agentsam/merkle.json --interactive
+    agentsam merkle diff ./mac-copy ./vm-copy --interactive
+    agentsam merkle explore .
 
-  TUI: arrows or j/k to move; Enter/right to expand; left to collapse;
+  Explorer: arrows or j/k to move; Enter/right to expand; left to collapse;
        c to filter changes; r to rescan; q/Esc/Ctrl+C to close.
   Exit codes: 0 success/match, 1 differences, 2 error, 130 interrupted scan.
   Includes/excludes are literal rules, not globs or .gitignore syntax.
@@ -39,14 +42,16 @@ export function printMerkleHelp() {
 
 function parse(argv) {
   const [command, ...args] = argv;
-  if (!['root', 'snapshot', 'verify', 'diff', 'inspect', 'tui'].includes(command)) throw new Error(`Unknown Merkle command: ${command}`);
-  const opts = { command, paths: [], include: [], exclude: [], tui: command === 'tui', json: false, force: false };
+  if (!['root', 'snapshot', 'verify', 'diff', 'inspect', 'explore', 'tui'].includes(command)) throw new Error(`Unknown Merkle command: ${command}`);
+  const publicCommand = command === 'tui' ? 'explore' : command;
+  const opts = { command: publicCommand, paths: [], include: [], exclude: [], tui: publicCommand === 'explore', json: false, force: false, semantic: false };
   let positionalOnly = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--' && !positionalOnly) { positionalOnly = true; continue; }
     if (positionalOnly || !arg.startsWith('-')) opts.paths.push(arg);
-    else if (['--tui', '--json', '--force'].includes(arg)) opts[arg.slice(2)] = true;
+    else if (arg === '--interactive' || arg === '--tui') opts.tui = true;
+    else if (['--json', '--force', '--semantic'].includes(arg)) opts[arg.slice(2)] = true;
     else if (['--out', '--root', '--include', '--exclude'].includes(arg)) {
       const value = args[++i];
       if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
@@ -59,7 +64,8 @@ function parse(argv) {
   if (!count && !opts.paths.length) opts.paths.push('.');
   if ((opts.out || opts.force) && command !== 'snapshot') throw new Error('--out and --force apply only to snapshot.');
   if (opts.root && command !== 'verify') throw new Error('--root applies only to verify.');
-  if (command === 'snapshot' && opts.tui) throw new Error('Use inspect --tui after saving a snapshot.');
+  if (command === 'snapshot' && opts.tui) throw new Error('Use inspect --interactive after saving a snapshot.');
+  if (opts.semantic && !['root', 'snapshot', 'inspect'].includes(command)) throw new Error('--semantic applies only to root, snapshot, or inspect.');
   if (command === 'verify' && (opts.include.length || opts.exclude.length)) throw new Error('Verification uses the snapshot\'s saved ignore rules.');
   opts.policy = normalizePolicy(opts);
   return opts;
@@ -78,6 +84,14 @@ async function comparison(opts, progress) {
 }
 
 export async function runMerkle(argv = []) {
+  if (argv[0] === 'persist') {
+    try { return await runMerklePersist(argv.slice(1)); }
+    catch (error) {
+      process.exitCode = 2;
+      process.stderr.write(argv.includes('--json') ? JSON.stringify({ error: error.message }) + '\n' : `Merkle persist: ${safeText(error.message)}\n`);
+      return null;
+    }
+  }
   if (!argv.length || argv.includes('--help') || argv.includes('-h')) { printMerkleHelp(); return; }
   let opts;
   try {
@@ -91,12 +105,12 @@ export async function runMerkle(argv = []) {
       }
       if (opts.command === 'diff') return comparison(opts, progress);
       if (opts.command === 'snapshot') {
-        const { snapshot: tree, output } = await saveSnapshot(target, { ...progress, policy: opts.policy, out: opts.out, force: opts.force });
+        const { snapshot: tree, output } = await saveSnapshot(target, { ...progress, policy: opts.policy, out: opts.out, force: opts.force, semantic: opts.semantic });
         return { title: 'Merkle snapshot', tree, output };
       }
-      const isSnapshot = ['inspect', 'tui'].includes(opts.command) && !(await fs.stat(target)).isDirectory();
+      const isSnapshot = ['inspect', 'explore'].includes(opts.command) && !(await fs.stat(target)).isDirectory();
       if (isSnapshot && (opts.include.length || opts.exclude.length)) throw new Error('Snapshot inspection uses saved ignore rules.');
-      const tree = isSnapshot ? await readSnapshot(target) : await buildMerkleTree(target, { ...progress, policy: opts.policy });
+      const tree = isSnapshot ? await readSnapshot(target) : await buildMerkleTree(target, { ...progress, policy: opts.policy, semantic: opts.semantic });
       return { title: isSnapshot ? 'Saved Merkle tree' : 'Merkle root', tree };
     };
     let result;
@@ -108,9 +122,10 @@ export async function runMerkle(argv = []) {
       try { result = await load({ signal: controller.signal }); }
       finally { process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop); }
       if (opts.json) {
-        const { rootPath, rootHash, stats, policy } = result.tree;
+        const { rootPath, rootHash, stats, policy, policyHash, semantic } = result.tree;
+        const semanticSummary = semantic ? { metadataRoot: semantic.rootHash, classifier: semantic.classifier, semanticStats: semantic.stats } : {};
         const value = result.diff ? { ...result.diff, rootPath, policy } : opts.command === 'snapshot' ? { ...result.tree, output: result.output }
-          : opts.command === 'root' ? { rootPath, rootHash, stats, policy } : result.tree;
+          : opts.command === 'root' ? { rootPath, rootHash, stats, policy, policyHash, ...semanticSummary } : result.tree;
         process.stdout.write(JSON.stringify(value, null, 2) + '\n');
       } else process.stdout.write(renderSummary(result, { inspect: opts.command === 'inspect', color: process.stdout.isTTY && !Object.hasOwn(process.env, 'NO_COLOR') }));
     }

package/src/commands/models.js

@@ -0,0 +1,152 @@
+import pc from 'picocolors';
+import { probeOllama, resolveOllamaConfig } from './ollama.js';
+import { listModelCatalog } from '../models/index.js';
+import { resolveProviderCredential } from '../lib/provider-credentials.js';
+
+const API_PROVIDERS = Object.freeze([
+  { id: 'openai', label: 'OpenAI', credential: 'OPENAI_API_KEY' },
+  { id: 'gemini', label: 'Gemini', credential: 'GEMINI_API_KEY' },
+  { id: 'grok', label: 'Grok', credential: 'XAI_API_KEY' },
+  { id: 'anthropic', label: 'Anthropic', credential: 'ANTHROPIC_API_KEY' },
+]);
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function configured(value) { return Boolean(clean(value)); }
+
+async function discoverOpenAIModels(apiKey, fetchImpl) {
+  if (!apiKey) return { attempted: false, ok: false, models: [], error: null };
+  try {
+    const response = await fetchImpl('https://api.openai.com/v1/models', {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal: typeof AbortSignal?.timeout === 'function' ? AbortSignal.timeout(8_000) : undefined,
+    });
+    if (!response.ok) return { attempted: true, ok: false, models: [], error: `HTTP ${response.status}` };
+    const body = await response.json();
+    const models = Array.isArray(body?.data) ? body.data.map((row) => clean(row?.id)).filter(Boolean) : [];
+    return { attempted: true, ok: true, models, error: null };
+  } catch (error) {
+    return { attempted: true, ok: false, models: [], error: error?.message || String(error) };
+  }
+}
+
+export async function collectModelsStatus(options = {}) {
+  const env = options.env || process.env;
+  const ollamaFetchImpl = options.fetchImpl || fetch;
+  const providerFetchImpl = options.providerFetchImpl || fetch;
+  const ollamaConfig = resolveOllamaConfig({}, env);
+  const ollama = await probeOllama(ollamaConfig, ollamaFetchImpl);
+  const credentials = new Map(API_PROVIDERS.map((provider) => [provider.id, resolveProviderCredential(provider.id, { env, home: options.home })]));
+  const providers = API_PROVIDERS.map((provider) => {
+    const credential = credentials.get(provider.id);
+    return {
+      ...provider,
+      configured: credential?.configured === true,
+      source: credential?.source || null,
+      credentialError: credential?.error || null,
+    };
+  });
+
+  const openaiCredential = credentials.get('openai');
+  const shouldDiscover = options.discoverRemote !== false && Boolean(openaiCredential?.configured);
+  const openai = shouldDiscover
+    ? await discoverOpenAIModels(clean(openaiCredential?.value), providerFetchImpl)
+    : { attempted: false, ok: false, models: [], error: null };
+  const availableIds = new Set(openai.models);
+  const catalogModels = listModelCatalog().map((record) => ({
+    model_key: record.model_key,
+    provider: record.provider,
+    provider_model_id: record.provider_model_id,
+    label: record.label,
+    availability: record.provider === 'openai' && openai.ok
+      ? (availableIds.has(record.provider_model_id) ? 'available' : 'unavailable')
+      : 'unverified',
+    source: record.source,
+  }));
+
+  return {
+    schemaVersion: 'agentsam-model-inventory-v2',
+    providers,
+    discovery: {
+      openai: {
+        attempted: openai.attempted,
+        ok: openai.ok,
+        error: openai.error,
+        returnedModelCount: openai.models.length,
+      },
+    },
+    catalogModels,
+    availableModels: catalogModels.filter((row) => row.availability === 'available'),
+    local: {
+      provider: 'ollama',
+      configured: ollama.online,
+      online: ollama.online,
+      endpoint: ollama.endpoint,
+      chatModel: ollamaConfig.model,
+      embedModel: ollamaConfig.embedModel,
+      models: ollama.models || [],
+      error: ollama.error || null,
+    },
+  };
+}
+
+function statusMark(ok) { return ok ? pc.green('●') : pc.dim('○'); }
+function writeLine(write, value = '') { write(`${value}\n`); }
+
+export function renderModelsStatus(status) {
+  const lines = [];
+  lines.push('');
+  lines.push(`  ${pc.bold('Agent Sam · models')}`);
+  lines.push(`  ${pc.dim('Credential presence is local evidence; exact hosted-model availability is provider-verified when discovery succeeds.')}`);
+  lines.push('');
+
+  for (const provider of status.providers) {
+    const state = provider.configured ? pc.green('configured') : pc.dim(provider.credentialError ? 'blocked' : 'not configured');
+    const detail = provider.configured ? `credential available · ${provider.source || 'runtime'}` : provider.credentialError ? `${provider.credential} · ${provider.credentialError}` : provider.credential;
+    lines.push(`  ${statusMark(provider.configured)}  ${pc.cyan(provider.label.padEnd(10))} ${state.padEnd(20)} ${pc.dim(detail)}`);
+  }
+
+  const exact = status.availableModels || [];
+  if (exact.length) {
+    lines.push('');
+    lines.push(`  ${pc.dim('provider-verified selectable models')}`);
+    for (const model of exact) lines.push(`    ${pc.green('•')} ${model.provider_model_id}`);
+  } else if (status.discovery?.openai?.attempted) {
+    lines.push('');
+    lines.push(`  ${pc.dim(`OpenAI discovery ${status.discovery.openai.ok ? 'completed; no catalog models matched' : `failed: ${status.discovery.openai.error || 'unknown error'}`}`)}`);
+  }
+
+  const local = status.local;
+  const localState = local.online ? pc.green('online') : pc.dim('offline');
+  lines.push(`  ${statusMark(local.online)}  ${pc.cyan('Ollama'.padEnd(10))} ${localState.padEnd(20)} ${pc.dim('local only')}`);
+  if (local.online) {
+    const names = local.models.map((row) => row.name).filter(Boolean);
+    lines.push('');
+    lines.push(`  ${pc.dim('local models')}`);
+    if (names.length) for (const name of names) lines.push(`    ${pc.green('•')} ${name}`);
+    else lines.push(`    ${pc.dim('no models reported')}`);
+    lines.push('');
+    lines.push(`  ${pc.dim('chat default')}   ${local.chatModel}`);
+    lines.push(`  ${pc.dim('embed default')}  ${local.embedModel}`);
+  }
+  lines.push('');
+  lines.push(`  ${pc.dim('Use /model inside Agent Sam to choose an exact verified model, reasoning effort, and processing tier.')}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+export async function runModels(argv = [], options = {}) {
+  if (argv.some((arg) => arg === '--help' || arg === '-h')) {
+    const text = 'agentsam models [--json] [--no-discover]\n\nShow configured providers, provider-verified known models when available, and local Ollama inventory.\n';
+    (options.write || process.stdout.write.bind(process.stdout))(text);
+    return;
+  }
+  const allowed = new Set(['--json', '--no-discover']);
+  const unknown = argv.filter((arg) => !allowed.has(arg));
+  if (unknown.length) throw new Error(`unknown models option: ${unknown[0]}`);
+
+  const status = await collectModelsStatus({ ...options, discoverRemote: !argv.includes('--no-discover') });
+  const write = options.write || ((text) => process.stdout.write(text));
+  if (argv.includes('--json')) writeLine(write, JSON.stringify(status, null, 2));
+  else write(renderModelsStatus(status));
+  return status;
+}