@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/src/commands/app.js

@@ -4,14 +4,34 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const FORBIDDEN_STRING_APP = /\bconst\s+APP\s*=\s*["'`][^"'`]+["'`]/;
+const HOST_PRODUCT_FIELDS = new Set([
+  'id',
+  'name',
+  'package',
+  'bin',
+  'commands',
+  'routes',
+  'surfaces',
+  'capabilities',
+  'entrypoints',
+  'version',
+  'kind',
+  'product_id',
+]);
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
 }
 
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
 function readManifest(manifestPath, fallbackId) {
   try {
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const manifest = readJson(manifestPath);
     return {
       id: manifest.id || fallbackId,
       name: manifest.name || fallbackId,
@@ -74,6 +94,264 @@ function runAppBin(app, args, options = {}) {
   if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
 }
 
+function walkFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.output' || entry.name === 'target') {
+      continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkFiles(full, out);
+    else if (/\.(js|mjs|cjs|ts|tsx)$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+function walkPackageJsonFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (['node_modules', 'dist', '.output', 'target', '.git'].includes(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkPackageJsonFiles(full, out);
+    else if (entry.name === 'package.json') out.push(full);
+  }
+  return out;
+}
+
+function npmDistributionWarnings(app) {
+  const warnings = [];
+  const installCommand = clean(app.manifest?.install?.command);
+  const declaresNpmInstall = /^npm\s+(?:i|install)\b/.test(installCommand);
+  if (!declaresNpmInstall) return warnings;
+
+  const rootPackagePath = path.join(app.dir, 'package.json');
+  if (!fs.existsSync(rootPackagePath)) {
+    return [`${app.id}: distribution: install.command advertises npm but package.json is missing`];
+  }
+
+  let rootPackage;
+  try {
+    rootPackage = readJson(rootPackagePath);
+  } catch (error) {
+    return [`${app.id}: distribution: package.json is invalid JSON: ${error.message}`];
+  }
+
+  if (app.manifest.package && rootPackage.name !== app.manifest.package) {
+    warnings.push(`${app.id}: distribution: manifest package ${app.manifest.package} does not match package.json name ${rootPackage.name || '(missing)'}`);
+  }
+  if (rootPackage.private === true) {
+    warnings.push(`${app.id}: distribution: package.json private=true but install.command advertises npm installation`);
+  }
+
+  const expectedBin = clean(app.manifest.bin || app.manifest?.entrypoints?.cli);
+  const packageBins = typeof rootPackage.bin === 'string'
+    ? [rootPackage.bin]
+    : Object.values(rootPackage.bin || {}).map(clean).filter(Boolean);
+  if (expectedBin && !packageBins.includes(expectedBin)) {
+    warnings.push(`${app.id}: distribution: package.json does not expose manifest CLI bin ${expectedBin}`);
+  }
+  if (!Array.isArray(rootPackage.files) || rootPackage.files.length === 0) {
+    warnings.push(`${app.id}: distribution: package.json has no explicit files allowlist`);
+  }
+
+  const escaping = [];
+  for (const packageFile of walkPackageJsonFiles(app.dir)) {
+    let nested;
+    try { nested = readJson(packageFile); } catch { continue; }
+    for (const group of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+      for (const [name, spec] of Object.entries(nested[group] || {})) {
+        if (typeof spec !== 'string' || !spec.startsWith('file:')) continue;
+        const target = path.resolve(path.dirname(packageFile), spec.slice(5));
+        const insideApp = target === app.dir || target.startsWith(`${app.dir}${path.sep}`);
+        if (!insideApp) {
+          escaping.push(`${path.relative(app.dir, packageFile)}:${group}:${name}=${spec}`);
+        }
+      }
+    }
+  }
+  if (escaping.length) {
+    warnings.push(`${app.id}: distribution: ${escaping.length} repo-local file: dependencies escape the app package (${escaping.join(', ')})`);
+  }
+
+  return warnings;
+}
+
+function validateOneApp(app, knownIds, root) {
+  const errors = [];
+  const warnings = [];
+  const m = app.manifest;
+
+  if (m.schema !== 'agentsam.app.v1') {
+    errors.push(`${app.id}: schema must be "agentsam.app.v1"`);
+  }
+  if (!KEBAB.test(app.id)) {
+    errors.push(`${app.id}: id must be kebab-case (^[a-z][a-z0-9]*(-[a-z0-9]+)*$)`);
+  }
+  const dirId = path.basename(app.dir);
+  if (dirId !== app.id && !m.directory_id_exception) {
+    errors.push(`${app.id}: directory basename "${dirId}" must equal id (set directory_id_exception if intentional)`);
+  }
+  if (m.kind !== 'app') {
+    errors.push(`${app.id}: kind must be "app"`);
+  }
+  if (m.product_id != null && !KEBAB.test(m.product_id)) {
+    errors.push(`${app.id}: product_id must be kebab-case`);
+  }
+  if (m.package && m.package === app.id) {
+    errors.push(`${app.id}: package must not equal APP.id (PACKAGE namespace is separate)`);
+  }
+  if (typeof m.package === 'string' && m.package.startsWith('@') === false && m.package.includes('/')) {
+    warnings.push(`${app.id}: package looks unusual: ${m.package}`);
+  }
+
+  const caps = m.capabilities;
+  if (caps == null) {
+    warnings.push(`${app.id}: capabilities not declared`);
+  } else if (!Array.isArray(caps) && (typeof caps !== 'object' || caps === null)) {
+    errors.push(`${app.id}: capabilities must be an array or boolean map`);
+  }
+
+  if (!m.entrypoints && !m.bin) {
+    warnings.push(`${app.id}: neither entrypoints nor bin declared`);
+  }
+
+  warnings.push(...npmDistributionWarnings(app));
+
+  const hostPath = path.join(app.dir, '.agentsam', 'app.json');
+  if (fs.existsSync(hostPath)) {
+    let host;
+    try {
+      host = readJson(hostPath);
+    } catch (err) {
+      errors.push(`${app.id}: .agentsam/app.json invalid JSON: ${err.message}`);
+      host = null;
+    }
+    if (host) {
+      if (host.schema === 'agentsam.app.v1' || host.id) {
+        errors.push(
+          `${app.id}: .agentsam/app.json must be host/install state (agentsam.host-install.v1 with app_id), not a second product definition`,
+        );
+      }
+      if (host.schema !== 'agentsam.host-install.v1') {
+        errors.push(`${app.id}: .agentsam/app.json schema must be "agentsam.host-install.v1"`);
+      }
+      if (!host.app_id) {
+        errors.push(`${app.id}: .agentsam/app.json missing app_id`);
+      } else if (!knownIds.has(host.app_id)) {
+        errors.push(`${app.id}: .agentsam/app.json app_id "${host.app_id}" does not resolve to a known APP`);
+      } else if (host.app_id !== app.id) {
+        errors.push(`${app.id}: .agentsam/app.json app_id "${host.app_id}" must match this APP.id`);
+      }
+      for (const field of HOST_PRODUCT_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(host, field)) {
+          errors.push(`${app.id}: .agentsam/app.json must not redefine product field "${field}"`);
+        }
+      }
+    }
+  }
+
+  for (const file of walkFiles(path.join(app.dir, 'backend'))) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (FORBIDDEN_STRING_APP.test(text)) {
+      const rel = path.relative(root, file);
+      errors.push(`${app.id}: forbidden string APP identity in ${rel} — import agentsam.app.json instead`);
+    }
+  }
+
+  return { id: app.id, errors, warnings };
+}
+
+function validateDesktopManifests(root, knownIds) {
+  const errors = [];
+  const warnings = [];
+  const dir = path.join(root, 'packages/agentsam-desktop-shell/manifests');
+  if (!fs.existsSync(dir)) return { errors, warnings };
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json') || name === 'schema.json' || name === 'example.json') continue;
+    const file = path.join(dir, name);
+    let manifest;
+    try {
+      manifest = readJson(file);
+    } catch (err) {
+      errors.push(`desktop ${name}: invalid JSON: ${err.message}`);
+      continue;
+    }
+    const appId = manifest.app_id;
+    if (!appId) {
+      errors.push(`desktop ${name}: missing app_id`);
+      continue;
+    }
+    if (!KEBAB.test(appId)) {
+      errors.push(`desktop ${name}: app_id must be kebab-case`);
+    }
+    // Brand shells (meauxbility, etc.) may not be APP products — only fail when
+    // the filename suggests a product APP or when app_id is a known near-miss.
+    const productish = ['cad-creator', 'client-cms-editor', 'local-studio', 'cms-editor'].includes(appId)
+      || ['cad-creator', 'client-cms-editor', 'cms-editor', 'local-studio'].some((n) => name.startsWith(n));
+    if (productish && !knownIds.has(appId)) {
+      errors.push(`desktop ${name}: app_id "${appId}" does not resolve to a known APP manifest`);
+    }
+    const included = Array.isArray(manifest.included_apps) ? manifest.included_apps : [];
+    for (const bundledId of included) {
+      if (!KEBAB.test(bundledId)) {
+        errors.push(`desktop ${name}: included_apps entry "${bundledId}" must be kebab-case`);
+        continue;
+      }
+      if (!knownIds.has(bundledId)) {
+        errors.push(
+          `desktop ${name}: included_apps entry "${bundledId}" does not resolve to a known APP manifest`,
+        );
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+export function validateApps(options = {}) {
+  const root = options.root || REPO_ROOT;
+  const filterId = options.appId || null;
+  const apps = listAppManifests(root);
+  const knownIds = new Set(apps.map((a) => a.id));
+  const selected = filterId ? apps.filter((a) => a.id === filterId || path.basename(a.dir) === filterId) : apps;
+
+  if (filterId && selected.length === 0) {
+    throw new Error(`unknown AgentSam app: ${filterId}`);
+  }
+
+  const idCounts = new Map();
+  for (const app of apps) {
+    idCounts.set(app.id, (idCounts.get(app.id) || 0) + 1);
+  }
+
+  const results = [];
+  const allErrors = [];
+  const allWarnings = [];
+
+  for (const [id, count] of idCounts) {
+    if (count > 1) allErrors.push(`duplicate APP.id across manifests: ${id}`);
+  }
+
+  for (const app of selected) {
+    const result = validateOneApp(app, knownIds, root);
+    results.push(result);
+    allErrors.push(...result.errors);
+    allWarnings.push(...result.warnings);
+  }
+
+  if (!filterId) {
+    const desktop = validateDesktopManifests(root, knownIds);
+    allErrors.push(...desktop.errors);
+    allWarnings.push(...desktop.warnings);
+  }
+
+  return {
+    ok: allErrors.length === 0,
+    apps: results,
+    errors: allErrors,
+    warnings: allWarnings,
+  };
+}
+
 export async function runApp(argv = [], options = {}) {
   const write = options.write || ((text) => process.stdout.write(text));
   const [command = 'list', appId, ...rest] = argv;
@@ -81,6 +359,8 @@ export async function runApp(argv = [], options = {}) {
     write([
       'agentsam app list',
       'agentsam app info <id>',
+      'agentsam app inspect <id>',
+      'agentsam app validate [--all|<id>]',
       'agentsam app install <id>',
       'agentsam app doctor <id>',
       'agentsam app preview <id>',
@@ -100,10 +380,34 @@ export async function runApp(argv = [], options = {}) {
     return apps;
   }
 
+  if (command === 'validate') {
+    const target = appId === '--all' || appId == null ? null : appId;
+    const report = validateApps({ root: options.root || REPO_ROOT, appId: target });
+    if (report.warnings.length) {
+      write('\n  Warnings\n');
+      for (const w of report.warnings) write(`  • ${w}\n`);
+    }
+    if (report.errors.length) {
+      write('\n  Errors\n');
+      for (const e of report.errors) write(`  ✗ ${e}\n`);
+      write('\n');
+      if (!options.noExit) process.exitCode = 1;
+      return report;
+    }
+    write(`\n  ✓ agentsam app validate${target ? ` ${target}` : ' --all'} (${report.apps.length} app(s))\n\n`);
+    return report;
+  }
+
   if (!appId) throw new Error('agentsam app requires an app id');
   const app = resolveApp(appId, options.root || REPO_ROOT);
 
-  if (command === 'info') {
+  if (command === 'info' || command === 'inspect') {
+    if (command === 'inspect') {
+      const report = validateApps({ root: options.root || REPO_ROOT, appId: app.id });
+      write(`${JSON.stringify({ manifest: app.manifest, validation: report }, null, 2)}\n`);
+      if (!report.ok && !options.noExit) process.exitCode = 1;
+      return { manifest: app.manifest, validation: report };
+    }
     write(`${JSON.stringify(app.manifest, null, 2)}\n`);
     return app.manifest;
   }
@@ -132,7 +436,7 @@ export async function runApp(argv = [], options = {}) {
 }
 
 export function appCommandHelp() {
-  return 'agentsam app list|info|install|doctor|preview|scaffold';
+  return 'agentsam app list|info|inspect|validate|install|doctor|preview|scaffold';
 }
 
 export { clean };

package/src/commands/autorag.js

@@ -2,10 +2,12 @@ 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 { repositoryRoot, readConfig, validateConfig, defaultConfig, scopeKey, 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 { discoverKnowledgeRuntime } from '../knowledge/runtime-discovery.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.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));
@@ -16,6 +18,12 @@ const parse = argv => parseArgs({ args: argv, allowPositionals: true, options: {
   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 generationConfig(root, existing) {
+  if (existing) return existing;
+  const project = tryReadProjectConfig(root);
+  const repositoryId = getRepositoryId(project) || portableRepositoryIdFromGit(root);
+  return repositoryId ? defaultConfig({ repositoryId }) : null;
+}
 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';
@@ -28,10 +36,20 @@ function adapterFor(config) {
   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) {
+function defaults(discovery, opts, existing, runtime) {
   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 declaredVectorize = (runtime?.cloudflare?.vectorize || []).filter(row => row.binding && row.index);
+  const adoptVectorize = !opts.backend && !existing?.lane?.backend && declaredVectorize.length === 1;
+  const backend = opts.backend || existing?.lane?.backend || (adoptVectorize ? 'cloudflare_vectorize' : 'local_exact');
+  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend, 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 (adoptVectorize) {
+    const resource = declaredVectorize[0];
+    config.lane.id = `${purpose}-cloudflare-vectorize`;
+    config.lane.backend = 'cloudflare_vectorize';
+    config.lane.binding = resource.binding;
+    config.lane.index = resource.index;
+  }
   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' } };
@@ -43,7 +61,7 @@ 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 suggested = recommendAutoRag({ discovery, purpose: kind }).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');
@@ -55,18 +73,54 @@ export async function runAutoRag(argv) {
   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 });
+  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root); const runtime = discoverKnowledgeRuntime(root, { knowledgeConfig: existing });
+  if (command === 'providers') {
+    const providers = await createProviderRegistry().capabilities();
+    const workersAi = runtime.resources.workers_ai;
+    return show(providers.map(item => item.id === 'workers-ai'
+      ? { ...item, runtime_configured: workersAi.configured, runtime_binding: workersAi.binding, locally_executable: workersAi.locally_executable, remotely_executable: workersAi.remotely_executable, credential_state: workersAi.credential_state }
+      : item));
+  }
+  if (command === 'backends') {
+    const backends = createBackendRegistry().capabilities();
+    const vectorize = runtime.resources.vectorize;
+    return show(backends.map(item => item.id === 'cloudflare_vectorize'
+      ? { ...item, declared_resources: vectorize, locally_executable: vectorize.some(row => row.locally_executable), remotely_executable: vectorize.some(row => row.remotely_executable), conflicts: runtime.conflicts }
+      : item));
+  }
+  if (command === 'status') {
+    const generationProfile = runtime.local_index.exists ? generationConfig(root, existing) : null;
+    const generation = generationProfile ? await (async () => {
+      const store = await storeFor(root, generationProfile, true);
+      try { return await store?.active(scopeKey(generationProfile)); }
+      finally { await store?.close(); }
+    })() : null;
+    return show({ discovery, config: existing || null, project_context: runtime, runtime, generation });
+  }
   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 });
+    const hasRuntimeLane = runtime.lanes.some(lane => lane.configured);
+    const checks = [
+      { check: 'knowledge_authority', ok: Boolean(existing) || hasRuntimeLane, detail: existing ? CONFIG_PATH : hasRuntimeLane ? 'Detected repository knowledge runtime.' : 'No local config or declared runtime lane found.' },
+      { check: 'local_sqlite', ok: runtime.local_index.exists, blocking: false, detail: runtime.local_index.exists ? runtime.local_index.path : 'Not indexed yet; run agentsam index run or agentsam autorag probe.' },
+      { check: 'git_merkle', ok: discovery.repository.merkle, blocking: false, detail: discovery.repository.merkle ? '.agentsam/merkle.json' : 'No Merkle snapshot yet; run agentsam merkle root . --json when snapshot evidence is needed.' },
+    ];
+    if (existing?.embedding && 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 }); }
+    }
+    if (runtime.resources.vectorize.length) checks.push({ check: 'cloudflare_vectorize', ok: runtime.conflicts.length === 0 && runtime.resources.vectorize.every(row => row.configured && (row.locally_executable || row.remotely_executable)), detail: runtime.resources.vectorize });
+    if (runtime.resources.workers_ai.observed) checks.push({ check: 'workers_ai_runtime', ok: runtime.resources.workers_ai.remotely_executable || runtime.resources.workers_ai.locally_executable, detail: runtime.resources.workers_ai });
+    if (runtime.conflicts.length) checks.push({ check: 'project_context_conflicts', ok: false, detail: runtime.conflicts });
+    return show({ ok: checks.filter(check => check.blocking !== false).every(check => check.ok), checks, project_context: runtime, runtime });
+  }
+  if (command === 'lanes') {
+    const configured = existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector', source: CONFIG_PATH }] : [];
+    const laneKey = lane => [lane.backend, lane.binding || '', lane.index || ''].join(':');
+    const seen = new Set(configured.map(laneKey));
+    return show([...configured, ...runtime.lanes.filter(lane => !seen.has(laneKey(lane)))]);
   }
-  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);
+    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing, runtime);
     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.');

package/src/commands/billing.js

@@ -0,0 +1,127 @@
+/**
+ * Billing relationships — not --billing-project (quota attribution).
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+async function runGcloud(args, env) {
+  try {
+    const { stdout, stderr } = await execFileAsync('gcloud', args, {
+      timeout: 30000,
+      env,
+      maxBuffer: 1024 * 1024,
+    });
+    return { ok: true, stdout: String(stdout || ''), stderr: String(stderr || '') };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: String(error?.stdout || ''),
+      stderr: String(error?.stderr || error?.message || ''),
+    };
+  }
+}
+
+function printHelp(write) {
+  writeLine(write, '');
+  writeLine(write, '  agentsam billing');
+  writeLine(write, '  agentsam billing accounts');
+  writeLine(write, '  agentsam billing project [PROJECT_ID]');
+  writeLine(write, '  agentsam billing budgets --account XXXXXX-XXXXXX-XXXXXX');
+  writeLine(write, '');
+  writeLine(write, '  Note: gcloud --billing-project only attributes quota for one CLI call.');
+  writeLine(write, '  It does not show historical spend. Use Cloud Billing reports / BigQuery export for costs.');
+  writeLine(write, '  Future: agentsam costs gcp|cloudflare|models');
+  writeLine(write, '');
+}
+
+export async function runBilling(argv = [], options = {}) {
+  const write = options.write || ((s) => process.stdout.write(s));
+  const env = options.env || process.env;
+  const json = argv.includes('--json');
+  const args = argv.filter((a) => a !== '--json');
+
+  if (!args.length || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+    printHelp(write);
+    if (!args.length) {
+      // Default: accounts list
+      args.push('accounts');
+    } else {
+      return 0;
+    }
+  }
+
+  if (args[0] === 'accounts') {
+    const result = await runGcloud(['billing', 'accounts', 'list', '--format=table(name,displayName,open)'], env);
+    if (!result.ok) {
+      write(result.stderr || result.stdout);
+      return 1;
+    }
+    if (json) write(JSON.stringify({ ok: true, stdout: result.stdout }, null, 2) + '\n');
+    else {
+      writeLine(write, '');
+      writeLine(write, '  Agent Sam · billing accounts');
+      writeLine(write, '  (relationship inventory — not a spend dashboard)');
+      writeLine(write, '');
+      write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    }
+    return 0;
+  }
+
+  if (args[0] === 'project') {
+    let project = args[1] || '';
+    if (!project) {
+      const cfg = await runGcloud(['config', 'get-value', 'project'], env);
+      project = cfg.stdout.trim();
+    }
+    if (!project || project === '(unset)') {
+      writeLine(write, '  ✕ Pass a project id or set gcloud config project.');
+      return 1;
+    }
+    const result = await runGcloud(['billing', 'projects', 'describe', project, '--format=yaml(billingAccountName,billingEnabled,projectId)'], env);
+    if (!result.ok) {
+      write(result.stderr || result.stdout);
+      return 1;
+    }
+    write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    return 0;
+  }
+
+  if (args[0] === 'budgets') {
+    let account = '';
+    for (let i = 1; i < args.length; i += 1) {
+      if (args[i] === '--account') account = args[++i] || '';
+      else if (args[i].startsWith('--account=')) account = args[i].slice('--account='.length);
+      else if (!args[i].startsWith('-') && !account) account = args[i];
+    }
+    if (!account || account.includes('XXXX')) {
+      writeLine(write, '  ✕ Pass a real billing account id from: agentsam billing accounts');
+      writeLine(write, '    Example: agentsam billing budgets --account 017E01-4426EF-21356F');
+      return 1;
+    }
+    const name = account.startsWith('billingAccounts/') ? account : `billingAccounts/${account}`;
+    const result = await runGcloud(['billing', 'budgets', 'list', '--billing-account', name.replace(/^billingAccounts\//, ''), '--format=table(displayName,amount,budgetFilter)'], env);
+    // gcloud wants the id without prefix sometimes; try both on failure
+    if (!result.ok) {
+      const retry = await runGcloud(['billing', 'budgets', 'list', `--billing-account=${account.replace(/^billingAccounts\//, '')}`], env);
+      if (!retry.ok) {
+        write(retry.stderr || result.stderr || retry.stdout);
+        writeLine(write, '');
+        writeLine(write, '  Tip: copy ACCOUNT_ID from `agentsam billing accounts` — not the placeholder XXXXXX-XXXXXX-XXXXXX.');
+        return 1;
+      }
+      write(retry.stdout.endsWith('\n') ? retry.stdout : `${retry.stdout}\n`);
+      return 0;
+    }
+    write(result.stdout.endsWith('\n') ? result.stdout : `${result.stdout}\n`);
+    return 0;
+  }
+
+  printHelp(write);
+  return 1;
+}