@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/src/cloudflare/runtime-status.js

@@ -0,0 +1,393 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runWranglerNative } from './wrangler.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+
+function parseJsonc(source) {
+  let output = '';
+  let string = false;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (lineComment) {
+      if (char === '\n') { lineComment = false; output += char; }
+      continue;
+    }
+    if (blockComment) {
+      if (char === '*' && next === '/') { blockComment = false; index += 1; }
+      continue;
+    }
+    if (string) {
+      output += char;
+      if (escaped) escaped = false;
+      else if (char === '\\') escaped = true;
+      else if (char === '"') string = false;
+      continue;
+    }
+    if (char === '"') { string = true; output += char; continue; }
+    if (char === '/' && next === '/') { lineComment = true; index += 1; continue; }
+    if (char === '/' && next === '*') { blockComment = true; index += 1; continue; }
+    output += char;
+  }
+  return JSON.parse(output.replace(/,\s*([}\]])/g, '$1'));
+}
+
+export function parseWranglerToml(source = '') {
+  const result = { vars: {}, d1_databases: [], r2_buckets: [], hyperdrive: [], kv_namespaces: [], services: [] };
+  const lines = source.split(/\r?\n/);
+  let currentSection = '';
+  let currentBlock = null;
+
+  for (let line of lines) {
+    line = line.replace(/#.*$/, '').trim();
+    if (!line) continue;
+
+    const arrMatch = line.match(/^\[\[([a-zA-Z0-9_.]+)\]\]$/);
+    if (arrMatch) {
+      currentSection = arrMatch[1];
+      currentBlock = {};
+      if (currentSection === 'd1_databases') result.d1_databases.push(currentBlock);
+      else if (currentSection === 'r2_buckets') result.r2_buckets.push(currentBlock);
+      else if (currentSection === 'hyperdrive') result.hyperdrive.push(currentBlock);
+      else if (currentSection === 'kv_namespaces') result.kv_namespaces.push(currentBlock);
+      else if (currentSection === 'services') result.services.push(currentBlock);
+      continue;
+    }
+
+    const tableMatch = line.match(/^\[([a-zA-Z0-9_.]+)\]$/);
+    if (tableMatch) {
+      currentSection = tableMatch[1];
+      currentBlock = null;
+      if (currentSection === 'ai' && !result.ai) result.ai = {};
+      if (currentSection === 'assets' && !result.assets) result.assets = {};
+      continue;
+    }
+
+    const kvMatch = line.match(/^([a-zA-Z0-9_.-]+)\s*=\s*(.*)$/);
+    if (kvMatch) {
+      const key = kvMatch[1].trim();
+      let rawVal = kvMatch[2].trim();
+      let val = rawVal;
+      if ((rawVal.startsWith('"') && rawVal.endsWith('"')) || (rawVal.startsWith("'") && rawVal.endsWith("'"))) {
+        val = rawVal.slice(1, -1);
+      } else if (rawVal === 'true') {
+        val = true;
+      } else if (rawVal === 'false') {
+        val = false;
+      } else if (/^\d+$/.test(rawVal)) {
+        val = parseInt(rawVal, 10);
+      }
+
+      if (currentBlock) {
+        currentBlock[key] = val;
+      } else if (currentSection === 'vars') {
+        result.vars[key] = val;
+      } else if (currentSection === 'ai') {
+        result.ai[key] = val;
+      } else if (currentSection === 'assets') {
+        result.assets[key] = val;
+      } else if (!currentSection) {
+        result[key] = val;
+      }
+    }
+  }
+  return result;
+}
+
+function declaredBindings(config = {}) {
+  const rows = [];
+  const add = (row = {}) => {
+    const name = clean(row.name);
+    if (name) rows.push({ ...row, name });
+  };
+
+  for (const [name, value] of Object.entries(config.vars || {})) {
+    add({
+      name,
+      type: typeof value === 'object' && value !== null ? 'json' : 'plain_text',
+      value: typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value),
+      source: 'wrangler_config',
+    });
+  }
+
+  for (const name of config.secrets?.required || []) {
+    add({ name, type: 'secret_text', encrypted: true, source: 'wrangler_required_secret' });
+  }
+
+  for (const row of config.d1_databases || []) add({
+    name: row?.binding,
+    type: 'd1',
+    database_name: clean(row?.database_name) || null,
+    database_id: clean(row?.database_id) || null,
+    source: 'wrangler_config',
+  });
+  for (const row of config.hyperdrive || []) add({
+    name: row?.binding,
+    type: 'hyperdrive',
+    id: clean(row?.id) || null,
+    source: 'wrangler_config',
+  });
+  for (const row of config.r2_buckets || []) add({
+    name: row?.binding,
+    type: 'r2_bucket',
+    bucket_name: clean(row?.bucket_name) || null,
+    source: 'wrangler_config',
+  });
+  for (const row of config.services || []) add({
+    name: row?.binding,
+    type: 'service',
+    service: clean(row?.service) || null,
+    environment: clean(row?.environment) || null,
+    entrypoint: clean(row?.entrypoint) || null,
+    source: 'wrangler_config',
+  });
+  for (const row of config.vpc_services || []) add({
+    name: row?.binding,
+    type: 'vpc_service',
+    service_id: clean(row?.service_id) || null,
+    source: 'wrangler_config',
+  });
+  if (config.ai?.binding) add({ name: config.ai.binding, type: 'ai', source: 'wrangler_config' });
+  if (config.assets?.binding) add({
+    name: config.assets.binding,
+    type: 'assets',
+    directory: clean(config.assets?.directory) || null,
+    source: 'wrangler_config',
+  });
+  for (const row of config.kv_namespaces || []) add({
+    name: row?.binding,
+    type: 'kv_namespace',
+    id: clean(row?.id) || null,
+    source: 'wrangler_config',
+  });
+  for (const row of config.vectorize || []) add({
+    name: row?.binding,
+    type: 'vectorize',
+    index_name: clean(row?.index_name) || null,
+    source: 'wrangler_config',
+  });
+  const queueProducers = Array.isArray(config.queues?.producers) ? config.queues.producers : [];
+  for (const row of queueProducers) add({
+    name: row?.binding,
+    type: 'queue',
+    queue_name: clean(row?.queue) || null,
+    source: 'wrangler_config',
+  });
+
+  return rows.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function safeLiveBinding(row = {}) {
+  const name = clean(row?.name);
+  const type = clean(row?.type);
+  if (!name) return null;
+
+  const output = { name, type: type || 'unknown', source: 'cloudflare_live_version' };
+  if (type === 'secret_text' || type === 'secret_key') {
+    output.encrypted = true;
+    return output;
+  }
+
+  if (type === 'plain_text') {
+    const value = row?.text ?? row?.value;
+    if (value != null) output.value = String(value);
+  } else if (type === 'json') {
+    const value = row?.json ?? row?.value;
+    if (value != null) output.value = typeof value === 'string' ? value : JSON.stringify(value);
+  }
+
+  for (const key of [
+    'id',
+    'database_id',
+    'database_name',
+    'bucket_name',
+    'service',
+    'environment',
+    'entrypoint',
+    'service_id',
+    'index_name',
+    'namespace',
+    'class_name',
+    'script_name',
+    'store_id',
+    'secret_name',
+  ]) {
+    const value = row?.[key];
+    if (value != null && clean(value)) output[key] = clean(value);
+  }
+
+  return output;
+}
+
+function bindingCategory(row = {}) {
+  const type = clean(row?.type);
+  if (type === 'secret_text' || type === 'secret_key') return 'secret';
+  if (type === 'plain_text' || type === 'json') return 'variable';
+  return 'resource';
+}
+
+export function readCloudflareDeploymentContract(root, projectConfig = {}) {
+  const deployment = projectConfig?.deployment?.cloudflare || {};
+  let workerName = clean(deployment.worker_name);
+  let relativeConfig = clean(deployment.config);
+  let configPath = relativeConfig ? path.resolve(root, relativeConfig) : null;
+
+  // Auto-discover candidate wrangler config when not explicitly specified
+  if (!workerName && !configPath) {
+    const candidates = [
+      'wrangler.jsonc',
+      'wrangler.json',
+      'wrangler.toml',
+      'backend/wrangler.jsonc',
+      'backend/wrangler.json',
+      'backend/wrangler.toml',
+      'worker/wrangler.jsonc',
+      'worker/wrangler.json',
+      'worker/wrangler.toml',
+      'apps/local-studio/backend/wrangler.jsonc',
+    ];
+    for (const rel of candidates) {
+      const candidatePath = path.resolve(root, rel);
+      if (fs.existsSync(candidatePath)) {
+        try {
+          const raw = fs.readFileSync(candidatePath, 'utf8');
+          const parsed = rel.endsWith('.toml') ? parseWranglerToml(raw) : parseJsonc(raw);
+          if (clean(parsed?.name)) {
+            workerName = clean(parsed.name);
+            relativeConfig = rel;
+            configPath = candidatePath;
+            break;
+          }
+        } catch {
+          // ignore candidate error
+        }
+      }
+    }
+  }
+
+  if (!workerName && !configPath) return { configured: false, worker_name: null, config: null, bindings: [], routes: [], health_url: null };
+  if (!workerName || !configPath) throw new Error('cloudflare_deployment_contract_incomplete');
+  if (configPath !== path.resolve(root) && !configPath.startsWith(`${path.resolve(root)}${path.sep}`)) throw new Error('cloudflare_deployment_config_outside_project');
+  const rawSource = fs.readFileSync(configPath, 'utf8');
+  const parsed = configPath.endsWith('.toml') ? parseWranglerToml(rawSource) : parseJsonc(rawSource);
+  if (clean(parsed.name) !== workerName) throw new Error(`cloudflare_worker_name_mismatch:${workerName}:${clean(parsed.name) || 'missing'}`);
+  const routes = (parsed.routes || []).map((row) => typeof row === 'string' ? row : clean(row?.pattern)).filter(Boolean);
+  const customDomain = routes.find((value) => !value.includes('*')) || '';
+  return {
+    configured: true,
+    worker_name: workerName,
+    config: relativeConfig,
+    config_path: configPath,
+    bindings: declaredBindings(parsed),
+    routes,
+    health_url: clean(deployment.health_url) || (customDomain ? `https://${customDomain}/health` : null),
+  };
+}
+
+export function resolveProjectD1Database(root = process.cwd()) {
+  try {
+    const contract = readCloudflareDeploymentContract(root);
+    if (contract?.bindings) {
+      const dbBinding = contract.bindings.find((b) => b.name === 'DB' && b.type === 'd1')
+        || contract.bindings.find((b) => b.type === 'd1');
+      if (dbBinding) {
+        return clean(dbBinding.database_name) || clean(dbBinding.name) || '';
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return clean(process.env.DB) || '';
+}
+
+function newest(rows = [], dateAt) {
+  return [...rows].sort((left, right) => Date.parse(dateAt(right) || 0) - Date.parse(dateAt(left) || 0))[0] || null;
+}
+
+async function probeHealth(url, fetchImpl) {
+  if (!url) return { configured: false, ok: null, status: null, url: null, data: null, error: null };
+  try {
+    const response = await fetchImpl(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(8_000) });
+    const data = await response.json().catch(() => null);
+    return { configured: true, ok: response.ok && data?.ok !== false, status: response.status, url, data, error: null };
+  } catch (error) {
+    return { configured: true, ok: false, status: null, url, data: null, error: error?.message || String(error) };
+  }
+}
+
+export async function collectCloudflareDeploymentStatus(options = {}) {
+  const root = path.resolve(options.root || options.cwd || process.cwd());
+  let contract;
+  try {
+    contract = readCloudflareDeploymentContract(root, options.projectConfig || {});
+  } catch (error) {
+    return { configured: true, connected: false, contract_error: error?.message || String(error), worker_name: null, bindings: null, health: null, error: 'deployment_contract_invalid' };
+  }
+  if (!contract.configured) return { ...contract, connected: false, offline: options.offline === true, bindings: null, health: null, error: null };
+  if (options.offline === true) return { ...contract, connected: false, offline: true, bindings: null, health: null, error: null };
+
+  const runner = options.runWrangler || runWranglerNative;
+  const base = { cwd: root, config: contract.config, name: contract.worker_name };
+  try {
+    const [identity, deployments, versions, health] = await Promise.all([
+      runner('whoami', base),
+      runner('deployments.list', base),
+      runner('versions.list', base),
+      probeHealth(contract.health_url, options.fetchImpl || fetch),
+    ]);
+    const deploymentRows = Array.isArray(deployments?.data) ? deployments.data : [];
+    const versionRows = Array.isArray(versions?.data) ? versions.data : [];
+    const activeDeployment = newest(deploymentRows, row => row?.created_on);
+    const activeVersionId = clean(activeDeployment?.versions?.find((row) => Number(row?.percentage) === 100)?.version_id)
+      || clean(newest(versionRows, row => row?.metadata?.created_on)?.id);
+    const version = activeVersionId ? await runner('versions.view', { ...base, version_id: activeVersionId }) : null;
+    const rawLiveBindings = Array.isArray(version?.data?.resources?.bindings)
+      ? version.data.resources.bindings
+      : Array.isArray(version?.data?.bindings)
+        ? version.data.bindings
+        : [];
+    const liveBindings = rawLiveBindings.map(safeLiveBinding).filter(Boolean);
+    const liveByName = new Map(liveBindings.map((row) => [row.name, row]));
+    const missing = contract.bindings.filter((row) => !liveByName.has(row.name));
+    const typeMismatches = contract.bindings.filter((row) => liveByName.has(row.name) && liveByName.get(row.name).type !== row.type)
+      .map((row) => ({ name: row.name, declared: row.type, live: liveByName.get(row.name).type }));
+    const runtimeVariables = liveBindings.filter((row) => bindingCategory(row) === 'variable');
+    const runtimeSecrets = liveBindings.filter((row) => bindingCategory(row) === 'secret');
+    const resourceBindings = liveBindings.filter((row) => bindingCategory(row) === 'resource');
+    return {
+      ...contract,
+      connected: true,
+      offline: false,
+      identity: identity?.data ? {
+        logged_in: identity.data.loggedIn === true,
+        auth_type: identity.data.authType || null,
+        accounts: (identity.data.accounts || []).map((row) => ({ id: row?.id || null, name: row?.name || null, type: row?.type || null })),
+      } : null,
+      deployment: activeDeployment,
+      version: version?.data ? {
+        id: version.data.id || activeVersionId,
+        number: version.data.number ?? null,
+        created_on: version.data.metadata?.created_on || null,
+        source: version.data.metadata?.source || null,
+      } : null,
+      bindings: {
+        declared: contract.bindings,
+        live: liveBindings,
+        runtime_variables: runtimeVariables,
+        runtime_secrets: runtimeSecrets,
+        resources: resourceBindings,
+        missing,
+        type_mismatches: typeMismatches,
+        match: missing.length === 0 && typeMismatches.length === 0,
+      },
+      health,
+      error: null,
+    };
+  } catch (error) {
+    return { ...contract, connected: false, offline: false, bindings: null, health: await probeHealth(contract.health_url, options.fetchImpl || fetch), error: error?.message || String(error) };
+  }
+}

package/src/cloudflare/wrangler.js

@@ -10,8 +10,11 @@ export const WRANGLER_NATIVE_COMMANDS = Object.freeze([
   Object.freeze({ id: 'whoami', argv: ['whoami', '--json'], risk: 'read', output: 'json', description: 'Read authenticated Cloudflare user/account membership without exposing the auth token.' }),
   Object.freeze({ id: 'deployments.list', argv: ['deployments', 'list', '--json'], risk: 'read', output: 'json', description: 'List recent Worker deployments.' }),
   Object.freeze({ id: 'versions.list', argv: ['versions', 'list', '--json'], risk: 'read', output: 'json', description: 'List recent Worker versions.' }),
+  Object.freeze({ id: 'versions.view', argv: ['versions', 'view'], risk: 'read', output: 'json', description: 'Read one exact Worker version, including its binding names and types but never secret values.' }),
   Object.freeze({ id: 'types.check', argv: ['types', '--check'], risk: 'read', output: 'text', description: 'Check generated Worker binding/runtime types without rewriting them.' }),
   Object.freeze({ id: 'queues.list', argv: ['queues', 'list'], risk: 'read', output: 'text', description: 'List Workers Queues visible to the active Cloudflare identity.' }),
+  Object.freeze({ id: 'tunnel.list', argv: ['tunnel', 'list'], risk: 'read', output: 'text', description: 'List real Cloudflare Tunnels visible to the active Wrangler identity.' }),
+  Object.freeze({ id: 'tunnel.info', argv: ['tunnel', 'info'], risk: 'read', output: 'text', description: 'Read connector/status details for one real Cloudflare Tunnel.' }),
 ]);
 
 export const WRANGLER_OPERATION_FAMILIES = Object.freeze([
@@ -51,8 +54,19 @@ export function buildWranglerInvocation(id, input = {}) {
   const args = [...row.argv];
   if (id === 'whoami' && clean(input.account)) args.push('--account', clean(input.account));
   if ((id === 'deployments.list' || id === 'versions.list') && clean(input.name)) args.push('--name', clean(input.name));
+  if (id === 'versions.view') {
+    const versionId = clean(input.version_id);
+    if (!versionId) throw new Error('cloudflare_version_id_required');
+    args.push(versionId, '--json');
+    if (clean(input.name)) args.push('--name', clean(input.name));
+  }
   if (id === 'types.check' && clean(input.path)) args.splice(1, 0, clean(input.path));
   if (id === 'queues.list' && input.page != null) args.push('--page', String(positiveInteger(input.page, 1)));
+  if (id === 'tunnel.info') {
+    const tunnel = clean(input.tunnel);
+    if (!tunnel) throw new Error('cloudflare_tunnel_required');
+    args.push(tunnel);
+  }
   const config = resolveConfig(cwd, input.config);
   if (config) args.push('--config', config);
   if (clean(input.env)) args.push('--env', clean(input.env));
@@ -91,11 +105,13 @@ export async function runWranglerNative(id, input = {}, options = {}) {
   const plan = buildWranglerInvocation(id, input);
   const runner = options.run || runProcess;
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 30_000;
-  const result = await runner(options.bin || 'npx', ['--yes', 'wrangler', ...plan.args], {
+  const defaultBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  const result = await runner(options.bin || defaultBin, ['--yes', 'wrangler', ...plan.args], {
     cwd: plan.cwd,
     timeoutMs,
     signal: options.signal,
     maxBytes: options.maxBytes || 2 * 1024 * 1024,
+    shell: process.platform === 'win32',
   });
   if (result.code !== 0) {
     const evidence = parseWranglerErrorEvidence(result.stderr, result.stdout);

package/src/commands/account-auth.js

@@ -11,7 +11,7 @@ export async function runLogin(argv = [], options = {}) {
   const write = options.write || ((text) => process.stdout.write(text));
   const authenticate = options.authenticateImpl || authenticateViaBrowser;
   const session = await authenticate();
-  if (!String(session?.access_token || '').trim().startsWith('sdk_')) throw new Error('Agent Sam login did not return a valid SDK session');
+  if (!String(session?.access_token || '').trim()) throw new Error('Agent Sam login did not return a browser session credential');
   // authenticateViaBrowser persists by default. Keep injected transports/test flows equivalent.
   if (!readAccountSession({ home: options.home })) saveAccountSession(session, { home: options.home });
   const status = await collectWhoami({ home: options.home, env: options.env || process.env, contextLoader: options.contextLoader });

package/src/commands/app.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+export function listAppManifests(root = REPO_ROOT) {
+  const appsRoot = path.join(root, 'apps');
+  if (!fs.existsSync(appsRoot)) return [];
+  return fs.readdirSync(appsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dir = path.join(appsRoot, entry.name);
+      const manifestPath = path.join(dir, 'agentsam.app.json');
+      if (!fs.existsSync(manifestPath)) return null;
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        return {
+          id: manifest.id || entry.name,
+          name: manifest.name || entry.name,
+          dir,
+          manifestPath,
+          bin: manifest.bin || null,
+          commands: manifest.commands || {},
+          manifest,
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function resolveApp(id, root = REPO_ROOT) {
+  const apps = listAppManifests(root);
+  const hit = apps.find((row) => row.id === id || path.basename(row.dir) === id);
+  if (!hit) throw new Error(`unknown AgentSam app: ${id}`);
+  return hit;
+}
+
+function runAppBin(app, args, options = {}) {
+  if (!app.bin) throw new Error(`app ${app.id} has no bin entry`);
+  const binPath = path.resolve(app.dir, app.bin);
+  if (!fs.existsSync(binPath)) throw new Error(`app bin missing: ${binPath}`);
+  const result = spawnSync(process.execPath, [binPath, ...args], {
+    cwd: options.cwd || process.cwd(),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+}
+
+export async function runApp(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const [command = 'list', appId, ...rest] = argv;
+  if (command === '--help' || command === '-h' || command === 'help') {
+    write([
+      'agentsam app list',
+      'agentsam app info <id>',
+      'agentsam app doctor <id>',
+      'agentsam app preview <id>',
+      'agentsam app scaffold <id> <dir>',
+      '',
+    ].join('\n'));
+    return;
+  }
+
+  if (command === 'list') {
+    const apps = listAppManifests(options.root || REPO_ROOT);
+    write('\n  AgentSam apps\n\n');
+    for (const app of apps) {
+      write(`  • ${app.id.padEnd(20)} ${app.name}\n`);
+    }
+    write('\n');
+    return apps;
+  }
+
+  if (!appId) throw new Error('agentsam app requires an app id');
+  const app = resolveApp(appId, options.root || REPO_ROOT);
+
+  if (command === 'info') {
+    write(`${JSON.stringify(app.manifest, null, 2)}\n`);
+    return app.manifest;
+  }
+  if (command === 'doctor' || command === 'preview') {
+    runAppBin(app, [command, ...rest], options);
+    return;
+  }
+  if (command === 'scaffold') {
+    runAppBin(app, ['scaffold', ...rest], options);
+    return;
+  }
+  throw new Error(`unknown agentsam app command: ${command}`);
+}
+
+export function appCommandHelp() {
+  return 'agentsam app list|info|doctor|preview|scaffold';
+}
+
+export { clean };

package/src/commands/autorag.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { repositoryRoot, readConfig, validateConfig, CONFIG_PATH } 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 { discoverAutoRag, recommendAutoRag, safeAutoRagConfig, runAutoRagProbe, createProviderRegistry, createBackendRegistry } from '../../packages/agentsam-knowledge/src/index.js';
+
+const show = value => console.log(JSON.stringify(value, null, 2));
+const split = value => String(value || '').split(',').map(item => item.trim()).filter(Boolean);
+const localPath = root => path.join(root, '.agentsam', 'knowledge', 'index.sqlite');
+const parse = argv => parseArgs({ args: argv, allowPositionals: true, options: {
+  cwd: { type: 'string' }, json: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, help: { type: 'boolean', short: 'h' },
+  kind: { type: 'string' }, scope: { type: 'string' }, provider: { type: 'string' }, backend: { type: 'string' }, model: { type: 'string' }, dimensions: { type: 'string' }, semantic: { type: 'boolean' }, 'allow-paid': { type: 'boolean' }, query: { type: 'string' },
+} });
+function readExisting(root) { try { return readConfig(root); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } }
+function writeConfig(root, config) {
+  const filename = path.join(root, CONFIG_PATH); fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const safe = JSON.stringify(validateConfig(config), null, 2) + '\n';
+  if (/api[_-]?key|secret|token|password/i.test(safe)) throw new Error('autorag_config_must_not_contain_credentials');
+  fs.writeFileSync(filename, safe, { mode: 0o600 });
+}
+function adapterFor(config) {
+  if (config.embedding.provider === 'none') return null;
+  const adapter = createProviderRegistry().get(config.embedding.provider);
+  return { validate: profile => adapter.validate(profile), async embed(text, profile, context) { return context?.kind === 'query' ? adapter.embedQuery(text, profile, context) : (await adapter.embedDocuments([text], profile, context))[0]; } };
+}
+async function storeFor(root, config, readOnly = false) { return config.storage.driver === 'sqlite' ? openSqliteStore(localPath(root), { readOnly }) : openPostgresStore(process.env[config.storage.connection_env]); }
+function defaults(discovery, opts, existing) {
+  const purpose = opts.kind || existing?.scope?.name || 'code';
+  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend: opts.backend || existing?.lane?.backend || 'local_exact', semantic: Boolean(opts.semantic) });
+  const config = safeAutoRagConfig({ existing: existing || {}, recommendation, repositoryId: existing?.repository_id || discovery.repository.identity, projectKey: existing?.project_key || discovery.repository.identity });
+  if (opts.provider) {
+    const models = { fixture: 'deterministic', gemini: 'gemini-embedding-2', openai: 'text-embedding-3-small', 'workers-ai': '@cf/baai/bge-base-en-v1.5', ollama: 'nomic-embed-text' };
+    config.embedding = opts.provider === 'none' ? { provider: 'none', model: 'none', revision: '1', dimensions: 0, parameters: {} } : { provider: opts.provider, model: opts.model || models[opts.provider] || '', revision: '1', dimensions: Number(opts.dimensions || (opts.provider === 'fixture' ? 3 : 768)), parameters: { task: 'code retrieval' } };
+  }
+  if (opts.backend) config.lane.backend = opts.backend;
+  return { recommendation, config };
+}
+async function interactiveOptions(discovery, opts) {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const kind = opts.kind || await prompt.question('What kind of knowledge? code, documents, schema, media, memory, mixed [code]: ') || 'code';
+    const suggested = kind === 'code' ? discovery.scopes.filter(scope => ['packages', 'src'].includes(scope)).join(',') : discovery.scopes.filter(scope => /docs|README|schema|migrations/.test(scope)).join(',');
+    const scope = opts.scope || await prompt.question(`Sources (literal paths, comma separated) [${suggested || '.'}]: `) || suggested || '.';
+    const semantic = opts.semantic || (await prompt.question('Enable semantic embeddings for this setup? [no]: ')).toLowerCase() === 'yes';
+    const provider = opts.provider || (semantic ? await prompt.question('Provider: fixture, gemini, openai, workers-ai, ollama [fixture]: ') || 'fixture' : 'none');
+    return { ...opts, kind, scope, semantic, provider };
+  } finally { prompt.close(); }
+}
+export async function runAutoRag(argv) {
+  const { values: opts, positionals } = parse(argv); const command = positionals[0] || 'status';
+  if (opts.help || !['setup', 'status', 'doctor', 'lanes', 'configure', 'probe', 'providers', 'backends', 'scope'].includes(command)) {
+    console.log('agentsam autorag setup|status|doctor|lanes|configure|probe|providers|backends|scope [--cwd PATH] [--yes] [--kind code|documents|schema|media|memory|mixed] [--scope a,b] [--provider none|fixture|gemini|openai|workers-ai|ollama] [--backend local_exact|postgres_pgvector|supabase_pgvector|cloudflare_vectorize] [--semantic]'); return;
+  }
+  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root);
+  if (command === 'providers') return show(await createProviderRegistry().capabilities());
+  if (command === 'backends') return show(createBackendRegistry().capabilities());
+  if (command === 'status') return show({ discovery, config: existing || null, generation: existing ? await (async () => { const store = await storeFor(root, existing, true); try { return await store?.active((await import('../knowledge/config.js')).scopeKey(existing)); } finally { await store?.close(); } })() : null });
+  if (command === 'doctor') {
+    const checks = [{ check: 'knowledge_config', ok: Boolean(existing), detail: existing ? CONFIG_PATH : 'Run agentsam autorag setup.' }, { check: 'local_sqlite', ok: true }, { check: 'git_merkle', ok: discovery.capabilities.git }];
+    if (existing?.embedding?.provider !== 'none') { try { adapterFor(existing).validate(existing.embedding); checks.push({ check: `provider:${existing.embedding.provider}`, ok: true }); } catch (error) { checks.push({ check: `provider:${existing.embedding.provider}`, ok: false, detail: error.message }); } }
+    return show({ ok: checks.every(check => check.ok), checks });
+  }
+  if (command === 'lanes') return show(existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector' }] : []);
+  if (command === 'setup' || command === 'configure' || command === 'scope') {
+    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing);
+    writeConfig(root, config); return show({ action: command, config: CONFIG_PATH, recommendation, config, next: ['agentsam autorag probe', 'agentsam index plan', 'agentsam index run', 'agentsam search "symbol or phrase"'] });
+  }
+  if (!existing) throw new Error('AutoRAG is not configured. Run agentsam autorag setup first.');
+  const semantic = Boolean(opts.semantic); if (semantic && !opts['allow-paid'] && !['fixture', 'ollama'].includes(existing.embedding.provider)) throw new Error('Paid embedding probes are disabled. Use --allow-paid only after reviewing the provider/profile.');
+  const store = await storeFor(root, existing, false);
+  try { return show(await runAutoRagProbe({ root, config: existing, store, semantic, embedder: semantic ? adapterFor(existing) : null, query: opts.query || 'repository overview', engine: { planIndex, runIndex, retrieve } })); }
+  finally { await store.close(); }
+}