@inneranimalmedia/agentsam-sdk 2.4.0 → 2.5.0

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,107 @@
+import pc from 'picocolors';
+import { probeOllama, resolveOllamaConfig } from './ollama.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' },
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function configured(value) {
+  return Boolean(clean(value));
+}
+
+export async function collectModelsStatus(options = {}) {
+  const env = options.env || process.env;
+  const fetchImpl = options.fetchImpl || fetch;
+  const ollamaConfig = resolveOllamaConfig({}, env);
+  const ollama = await probeOllama(ollamaConfig, fetchImpl);
+
+  return {
+    schemaVersion: 'agentsam-model-inventory-v1',
+    providers: API_PROVIDERS.map((provider) => ({
+      ...provider,
+      configured: configured(env[provider.credential]),
+      source: 'environment',
+    })),
+    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('Detected from this terminal session. Secrets are never printed.')}`);
+  lines.push('');
+
+  for (const provider of status.providers) {
+    const state = provider.configured ? pc.green('configured') : pc.dim('not configured');
+    const detail = provider.configured ? 'credential available' : provider.credential;
+    lines.push(`  ${statusMark(provider.configured)}  ${pc.cyan(provider.label.padEnd(10))} ${state.padEnd(20)} ${pc.dim(detail)}`);
+  }
+
+  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('Provider model catalogs and model selection belong to the connected host/runtime;')}`);
+  lines.push(`  ${pc.dim('this command only reports what this local CLI can prove is configured or available.')}`);
+  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]\n\nShow model providers configured in this terminal session plus models reported by local Ollama.\n';
+    (options.write || process.stdout.write.bind(process.stdout))(text);
+    return;
+  }
+  const unknown = argv.filter((arg) => arg !== '--json');
+  if (unknown.length) throw new Error(`unknown models option: ${unknown[0]}`);
+
+  const status = await collectModelsStatus(options);
+  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;
+}

package/src/commands/ollama.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { readProjectConfig, setLocalModelCapability, writeProjectConfig } from '../lib/project-config.js';
+
+export const OLLAMA_DEFAULTS = Object.freeze({
+  baseUrl: 'http://127.0.0.1:11434',
+  model: 'qwen2.5-coder',
+  embedModel: 'mxbai-embed-large',
+});
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function boolFlag(argv, name) {
+  return argv.includes(name);
+}
+
+export function parseOllamaArgs(argv = []) {
+  const first = argv[0] && !String(argv[0]).startsWith('-') ? String(argv[0]) : 'status';
+  const opts = {
+    command: first,
+    cwd: process.cwd(),
+    envFile: '',
+    baseUrl: '',
+    model: '',
+    embedModel: '',
+    install: boolFlag(argv, '--install'),
+    start: boolFlag(argv, '--start'),
+    pull: boolFlag(argv, '--pull'),
+    json: boolFlag(argv, '--json'),
+  };
+
+  for (let i = first === argv[0] ? 1 : 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (['--install', '--start', '--pull', '--json'].includes(arg)) continue;
+    if (arg === '--cwd') opts.cwd = argv[++i] || opts.cwd;
+    else if (arg === '--env-file') opts.envFile = argv[++i] || '';
+    else if (arg === '--base-url') opts.baseUrl = argv[++i] || '';
+    else if (arg === '--model') opts.model = argv[++i] || '';
+    else if (arg === '--embed-model') opts.embedModel = argv[++i] || '';
+    else if (!String(arg).startsWith('-') && opts.command === 'pull') {
+      opts.model = opts.model || arg;
+    } else if (arg === '--help' || arg === '-h') opts.command = 'help';
+    else throw new Error(`unknown ollama option: ${arg}`);
+  }
+  return opts;
+}
+
+export function resolveOllamaConfig(opts = {}, env = process.env) {
+  return {
+    baseUrl: clean(opts.baseUrl || env.OLLAMA_BASE_URL || OLLAMA_DEFAULTS.baseUrl).replace(/\/+$/, ''),
+    model: clean(opts.model || env.OLLAMA_MODEL || OLLAMA_DEFAULTS.model),
+    embedModel: clean(opts.embedModel || env.OLLAMA_EMBED_MODEL || OLLAMA_DEFAULTS.embedModel),
+  };
+}
+
+function replaceEnvLine(text, key, value) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const line = `${key}=${value}`;
+  const re = new RegExp(`^${escaped}=.*$`, 'm');
+  if (re.test(text)) return text.replace(re, line);
+  const prefix = text && !text.endsWith('\n') ? `${text}\n` : text;
+  return `${prefix}${line}\n`;
+}
+
+export function upsertOllamaEnvFile(filename, config) {
+  const target = path.resolve(filename);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  let text = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+  text = replaceEnvLine(text, 'OLLAMA_BASE_URL', config.baseUrl);
+  text = replaceEnvLine(text, 'OLLAMA_MODEL', config.model);
+  text = replaceEnvLine(text, 'OLLAMA_EMBED_MODEL', config.embedModel);
+  fs.writeFileSync(target, text, 'utf8');
+  return target;
+}
+
+export function updateProjectOllamaConfig(cwd, config) {
+  const root = path.resolve(cwd);
+  const filename = path.join(root, '.agentsam', 'config.json');
+  if (!fs.existsSync(filename)) return null;
+  const project = readProjectConfig(root);
+  setLocalModelCapability(project, 'ollama');
+  writeProjectConfig(root, project);
+  return filename;
+}
+
+function commandResult(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: options.inherit ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+    timeout: options.timeout || 15_000,
+    ...options,
+  });
+}
+
+export function commandAvailable(command, spawnSyncImpl = spawnSync) {
+  const finder = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSyncImpl(finder, [command], { encoding: 'utf8', stdio: 'ignore' });
+  return result.status === 0;
+}
+
+export function ollamaInstallPlan(platform = process.platform, available = {}) {
+  if ((platform === 'darwin' || platform === 'linux') && available.brew) {
+    return { command: 'brew', args: ['install', 'ollama'], manager: 'homebrew' };
+  }
+  if (platform === 'win32' && available.winget) {
+    return {
+      command: 'winget',
+      args: ['install', '--id', 'Ollama.Ollama', '--exact', '--accept-source-agreements', '--accept-package-agreements'],
+      manager: 'winget',
+    };
+  }
+  return null;
+}
+
+function installOllama() {
+  const available = {
+    brew: commandAvailable('brew'),
+    winget: commandAvailable('winget'),
+  };
+  const plan = ollamaInstallPlan(process.platform, available);
+  if (!plan) {
+    throw new Error('automatic Ollama install is unavailable on this host; install Ollama with your platform package manager, then rerun `agentsam ollama setup`');
+  }
+  const result = commandResult(plan.command, plan.args, { inherit: true, timeout: 20 * 60_000 });
+  if (result.status !== 0) throw new Error(`Ollama install failed via ${plan.manager}`);
+  return plan.manager;
+}
+
+function startOllama() {
+  if (process.platform === 'darwin' && commandAvailable('brew')) {
+    const result = commandResult('brew', ['services', 'start', 'ollama'], { inherit: true, timeout: 60_000 });
+    if (result.status === 0) return 'homebrew-service';
+  }
+  const child = spawn('ollama', ['serve'], { detached: true, stdio: 'ignore' });
+  child.unref();
+  return 'ollama-serve';
+}
+
+function normalizeModelName(value) {
+  return clean(value).toLowerCase().replace(/:latest$/, '');
+}
+
+function hasModel(models, desired) {
+  const want = normalizeModelName(desired);
+  return models.some((row) => normalizeModelName(row.name || row.model) === want);
+}
+
+export async function probeOllama(config, fetchImpl = fetch) {
+  const endpoint = `${config.baseUrl}/api/tags`;
+  try {
+    const response = await fetchImpl(endpoint, { signal: AbortSignal.timeout(2000) });
+    if (!response.ok) return { online: false, status: response.status, endpoint, models: [] };
+    const body = await response.json();
+    const models = Array.isArray(body?.models) ? body.models.map((row) => ({ name: row.name || row.model || '' })).filter((row) => row.name) : [];
+    return {
+      online: true,
+      status: response.status,
+      endpoint,
+      models,
+      chat_ready: hasModel(models, config.model),
+      embed_ready: hasModel(models, config.embedModel),
+    };
+  } catch (error) {
+    return { online: false, status: null, endpoint, models: [], error: error?.message || String(error) };
+  }
+}
+
+function binaryInfo() {
+  if (!commandAvailable('ollama')) return { installed: false, version: null };
+  const result = commandResult('ollama', ['--version']);
+  return {
+    installed: result.status === 0,
+    version: result.status === 0 ? clean(result.stdout || result.stderr) : null,
+  };
+}
+
+function pullModel(model) {
+  const result = commandResult('ollama', ['pull', model], { inherit: true, timeout: 60 * 60_000 });
+  if (result.status !== 0) throw new Error(`ollama pull failed for ${model}`);
+}
+
+function help() {
+  return `agentsam ollama <setup|status|list|pull> [options]\n\nLocal-only Ollama development kit. Nothing here configures an edge model.\n\n  setup                 Write OLLAMA_* values into the local project .env\n    --install           Explicitly install Ollama with a supported package manager\n    --start             Start the local Ollama service\n    --pull              Pull both configured chat + embedding models\n  status                Probe the local Ollama API and configured models\n  list                  Alias for status with model inventory\n  pull [model]          Pull one model, or both configured defaults when omitted\n\n  --base-url <url>      Default http://127.0.0.1:11434\n  --model <name>        Default qwen2.5-coder\n  --embed-model <name>  Default mxbai-embed-large\n  --cwd <path>          Project root (default current directory)\n  --env-file <path>     Env file to update (default <cwd>/.env)\n  --json                Machine-readable output\n\nRemote AgentSam sessions should use the existing user-hosted terminal tunnel to execute this CLI on the local machine; the Worker should not try to reach 127.0.0.1.\n`;
+}
+
+function printResult(result, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  console.log(`Ollama local development`);
+  console.log(`  base URL     ${result.config.baseUrl}`);
+  console.log(`  chat model   ${result.config.model}`);
+  console.log(`  embed model  ${result.config.embedModel}`);
+  console.log(`  binary       ${result.binary.installed ? result.binary.version || 'installed' : 'not installed'}`);
+  console.log(`  API          ${result.api.online ? 'online' : 'offline'}`);
+  if (result.env_file) console.log(`  env          ${result.env_file}`);
+  if (result.project_config) console.log(`  project      ${result.project_config}`);
+  if (result.api.online) {
+    console.log(`  chat ready   ${result.api.chat_ready ? 'yes' : 'no'}`);
+    console.log(`  embed ready  ${result.api.embed_ready ? 'yes' : 'no'}`);
+  }
+  if (!result.binary.installed) console.log(`  next         agentsam ollama setup --install --start --pull`);
+  else if (!result.api.online) console.log(`  next         agentsam ollama setup --start`);
+  else if (!result.api.chat_ready || !result.api.embed_ready) console.log(`  next         agentsam ollama pull`);
+}
+
+export async function runOllama(argv = []) {
+  const opts = parseOllamaArgs(argv);
+  if (opts.command === 'help') {
+    process.stdout.write(help());
+    return;
+  }
+  if (!['setup', 'status', 'list', 'pull'].includes(opts.command)) {
+    throw new Error(`unknown ollama command: ${opts.command}`);
+  }
+
+  const root = path.resolve(opts.cwd || process.cwd());
+  const config = resolveOllamaConfig(opts);
+  let envFile = null;
+  let projectConfig = null;
+  let installedBy = null;
+  let startedBy = null;
+
+  if (opts.command === 'setup') {
+    envFile = upsertOllamaEnvFile(opts.envFile || path.join(root, '.env'), config);
+    projectConfig = updateProjectOllamaConfig(root, config);
+    if (!commandAvailable('ollama') && opts.install) installedBy = installOllama();
+    if (commandAvailable('ollama') && opts.start) startedBy = startOllama();
+  }
+
+  if (opts.command === 'pull') {
+    if (!commandAvailable('ollama')) throw new Error('Ollama is not installed; run `agentsam ollama setup --install` first');
+    const requested = opts.model && opts.model !== OLLAMA_DEFAULTS.model ? [opts.model] : [config.model, config.embedModel];
+    for (const model of [...new Set(requested.filter(Boolean))]) pullModel(model);
+  } else if (opts.command === 'setup' && opts.pull) {
+    if (!commandAvailable('ollama')) throw new Error('Ollama is not installed; rerun setup with --install before --pull');
+    for (const model of [...new Set([config.model, config.embedModel])]) pullModel(model);
+  }
+
+  if (startedBy) await new Promise((resolve) => setTimeout(resolve, 600));
+  const result = {
+    schemaVersion: 'agentsam-ollama-local-v1',
+    local_only: true,
+    edge_model: false,
+    config,
+    env_file: envFile,
+    project_config: projectConfig,
+    installed_by: installedBy,
+    started_by: startedBy,
+    binary: binaryInfo(),
+    api: await probeOllama(config),
+  };
+  printResult(result, opts.json);
+  return result;
+}