@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

package/src/commands/machine.js

@@ -0,0 +1,137 @@
+/**
+ * agentsam machine — graduate the native Machine engine to the product CLI.
+ *
+ * Graduation rule: capability is complete when reachable through
+ * `agentsam machine …`, emits bounded deterministic receipts, and preserves evidence.
+ *
+ * Asset perception rule: discovery is read-only and network-free by default.
+ */
+
+import path from 'node:path';
+import { resolveMachineBinary, spawnMachine } from './machine-binary.js';
+
+function usage() {
+  return `agentsam machine — deterministic local perception (native engine)
+
+Usage:
+  agentsam machine inspect <path> [--json] [--run-id <id>] [--include-generated]
+  agentsam machine doctor [--json]
+  agentsam machine --help
+
+Notes:
+  Default inspect is read-only and network-free.
+  Large detail is externalized under <target>/.agentsam/machine/runs/<run_id>/.
+  Generated/cache trees are summarized unless --include-generated is set.
+  Remote fetch/probe, optimization, storage, and reference rewriting are separate explicit actions.
+  Set AGENTSAM_MACHINE_BIN to force a specific agentsam-machine binary.`;
+}
+
+function parseArgs(argv = []) {
+  const out = {
+    help: false,
+    json: false,
+    includeGenerated: false,
+    runId: null,
+    subcommand: null,
+    target: null,
+    positionals: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') out.help = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--include-generated') out.includeGenerated = true;
+    else if (arg === '--run-id') {
+      const value = argv[++i];
+      if (value == null || value.startsWith('--')) {
+        throw new Error('--run-id requires a value');
+      }
+      out.runId = value;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`unknown machine option: ${arg}`);
+    } else {
+      out.positionals.push(arg);
+    }
+  }
+  out.subcommand = out.positionals[0] || null;
+  out.target = out.positionals[1] || null;
+  return out;
+}
+
+function printTextDoctor(resolution) {
+  if (resolution.kind === 'binary') {
+    console.log(`agentsam-machine available (${resolution.source}): ${resolution.path}`);
+    console.log('capability: machine.inspect');
+    return;
+  }
+  if (resolution.kind === 'cargo') {
+    console.log(`agentsam-machine via cargo run (${resolution.source}): ${resolution.manifest}`);
+    console.log('capability: machine.inspect (dev fallback)');
+    return;
+  }
+  console.log('agentsam-machine unavailable');
+  console.log(`tried: ${(resolution.tried || []).join(', ')}`);
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function runMachine(argv = []) {
+  const args = parseArgs(argv);
+  if (args.help || !args.subcommand) {
+    console.log(usage());
+    return 0;
+  }
+
+  const resolution = resolveMachineBinary();
+
+  if (args.subcommand === 'doctor') {
+    const payload = {
+      capability: 'machine.doctor',
+      available: resolution.kind !== 'missing',
+      resolution,
+    };
+    if (args.json) console.log(JSON.stringify(payload));
+    else printTextDoctor(resolution);
+    return resolution.kind === 'missing' ? 1 : 0;
+  }
+
+  if (args.subcommand === 'inspect') {
+    const target = args.target || process.cwd();
+    const abs = path.resolve(target);
+    const machineArgv = ['inspect', abs];
+    if (args.runId) machineArgv.push('--run-id', args.runId);
+    if (args.includeGenerated) machineArgv.push('--include-generated');
+    if (args.json) machineArgv.push('--json');
+
+    const result = spawnMachine(resolution, machineArgv, {
+      stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      // Large donors still emit bounded compact JSON; raise buffer for safety.
+      maxBuffer: 32 * 1024 * 1024,
+    });
+
+    if (result.error) throw result.error;
+    if (args.json) {
+      const stdout = String(result.stdout || '');
+      const stderr = String(result.stderr || '');
+      if (result.status && result.status !== 0) {
+        const err = new Error(stderr.trim() || `agentsam-machine exited with code ${result.status}`);
+        err.exitCode = result.status;
+        throw err;
+      }
+      try {
+        const parsed = JSON.parse(stdout);
+        console.log(JSON.stringify(parsed));
+      } catch {
+        process.stdout.write(stdout);
+      }
+      if (stderr.trim()) process.stderr.write(stderr);
+    }
+    return result.status ?? 0;
+  }
+
+  console.log(usage());
+  const err = new Error(`Unknown machine subcommand: ${args.subcommand}`);
+  err.exitCode = 1;
+  throw err;
+}

package/src/commands/security.js

@@ -1,5 +1,4 @@
 import fs from 'node:fs';
-import { scanProjectSecurity, reportExitCode, repairProject, formatSecurityReport } from '../security/index.js';
 import { runProcess } from '../security/process.js';
 import { diagnosticFromError, renderDiagnosticError } from '../errors/index.js';
 
@@ -19,6 +18,54 @@ const help = [
   'Exit: 0 clean/verified, 1 unresolved findings or command failure, 2 incomplete/error.',
   ''
 ].join('\n');
+
+async function loadSecurityModules() {
+  // Deferred until after any pre-install child command (e.g. npm ci) so the
+  // Merkle/TypeScript trust-boundary stack is not required before dependencies exist.
+  return import('../security/index.js');
+}
+
+/** Bootstrap-safe receipt when the child install/build command fails — never import the heavy scan stack. */
+function bootstrapSafeCommandFailureReceipt(result, childArgs) {
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  return {
+    schema_version: 1,
+    ok: false,
+    complete: true,
+    status: 'command-failed',
+    command: childArgs,
+    command_exit_code: result.code,
+    signal: result.signal || null,
+    stdout,
+    stderr,
+    log: stdout + (stdout && stderr ? '\n' : '') + stderr,
+    issues: [`Child command exited with code ${result.code}`],
+    findings: [],
+    results: [],
+    dependency_count: 0,
+    checked_count: 0,
+    dependency_complete: false,
+  };
+}
+
+function formatCommandFailureReport(report) {
+  const lines = [
+    'Agent Sam · security · COMMAND-FAILED',
+    '',
+    'Command: ' + (Array.isArray(report.command) ? report.command.join(' ') : String(report.command || '')),
+    'Exit code: ' + String(report.command_exit_code),
+  ];
+  if (report.signal) lines.push('Signal: ' + report.signal);
+  for (const issue of report.issues || []) lines.push('  ! ' + issue);
+  if (report.stderr) {
+    lines.push('', 'stderr:', report.stderr.trimEnd());
+  } else if (report.stdout) {
+    lines.push('', 'stdout:', report.stdout.trimEnd());
+  }
+  return lines.join('\n') + '\n';
+}
+
 export async function runSecurity(argv) {
   const ownArgs = argv.slice(0, argv.indexOf('--') < 0 ? argv.length : argv.indexOf('--'));
   if (ownArgs.includes('--help') || ownArgs.includes('-h') || !argv.length) { process.stdout.write(help); return; }
@@ -52,13 +99,29 @@ export async function runSecurity(argv) {
     const abort = () => controller.abort();
     process.once('SIGINT', abort); process.once('SIGTERM', abort);
     let report;
+    let reportExitCode;
+    let formatSecurityReport;
     try {
       if (command === 'run') {
         const result = await runProcess(childArgs[0], childArgs.slice(1), { cwd: options.projectRoot || process.cwd(), signal: options.signal });
-        report = await scanProjectSecurity({ ...options, log: result.stdout + '\n' + result.stderr });
+        // Child failure must surface as command-failed without importing Merkle/TypeScript.
+        if (result.code !== 0) {
+          report = bootstrapSafeCommandFailureReceipt(result, childArgs);
+          process.stdout.write(options.json ? JSON.stringify(report, null, 2) + '\n' : formatCommandFailureReport(report));
+          process.exitCode = 1;
+          return;
+        }
+        const security = await loadSecurityModules();
+        reportExitCode = security.reportExitCode;
+        formatSecurityReport = security.formatSecurityReport;
+        report = await security.scanProjectSecurity({ ...options, log: result.stdout + '\n' + result.stderr });
         report.command_exit_code = result.code;
-        if (result.code) { report.ok = false; report.status = 'command-failed'; }
-      } else report = command === 'repair' ? await repairProject(options) : await scanProjectSecurity(options);
+      } else {
+        const security = await loadSecurityModules();
+        reportExitCode = security.reportExitCode;
+        formatSecurityReport = security.formatSecurityReport;
+        report = command === 'repair' ? await security.repairProject(options) : await security.scanProjectSecurity(options);
+      }
     } finally {
       process.removeListener('SIGINT', abort); process.removeListener('SIGTERM', abort);
     }

package/src/commands/setup.js

@@ -18,11 +18,39 @@ import {
   RUNTIME_PROFILES,
 } from '../lib/setup/runtime.js';
 import { runRuntime } from './runtime.js';
+import { getCliCommand } from '../cli/command-catalog.js';
 
 function writeLine(write, value = '') {
   write(`${value}\n`);
 }
 
+function catalogCommand(id, args = '') {
+  const entry = getCliCommand(id);
+  if (!entry) throw new Error(`setup_next_command_not_catalogued: ${id}`);
+  return `agentsam ${entry.id}${args ? ` ${args}` : ''}`;
+}
+
+export function setupNextCommands(capabilityIds = []) {
+  const commands = [
+    catalogCommand('status'),
+    catalogCommand('capabilities'),
+    catalogCommand('google-cloud', 'doctor'),
+  ];
+  if (capabilityIds.includes('google.cloud')) {
+    commands.push(catalogCommand('setup', 'google.cloud --inventory'));
+  }
+  if (capabilityIds.includes('image.vectorize')) {
+    commands.push(catalogCommand('capabilities', 'image.vectorize'));
+  }
+  return [...new Set(commands)];
+}
+
+function writeSetupNext(write, capabilityIds = []) {
+  writeLine(write, '  Next');
+  for (const command of setupNextCommands(capabilityIds)) writeLine(write, `    ${command}`);
+  writeLine(write, '');
+}
+
 function printHelp(write) {
   writeLine(write, '');
   writeLine(write, '  Agent Sam · setup');
@@ -220,9 +248,9 @@ export async function runSetup(argv = [], options = {}) {
       }
       writeLine(write, '');
       writeLine(write, '  Next');
-      writeLine(write, '    agentsam gcloud auth login');
-      writeLine(write, '    agentsam google-cloud connection set --identity EMAIL --project PROJECT');
-      writeLine(write, '    agentsam google-cloud doctor');
+      writeLine(write, `    ${catalogCommand('google-cloud', 'auth login')}`);
+      writeLine(write, `    ${catalogCommand('google-cloud', 'connection set --identity EMAIL --project PROJECT')}`);
+      writeLine(write, `    ${catalogCommand('google-cloud', 'doctor')}`);
       writeLine(write, '');
     }
     return inv.errors?.length ? 2 : 0;
@@ -243,8 +271,7 @@ export async function runSetup(argv = [], options = {}) {
   if (dryRun || !plan.would_install.length) {
     if (!plan.would_install.length) {
       writeLine(write, '  ✓ setup complete — requested capabilities already satisfied');
-      writeLine(write, '  Next: agentsam doctor · agentsam capabilities · agentsam google-cloud doctor');
-      writeLine(write, '');
+      writeSetupNext(write, capabilityIds);
     }
     if (json) write(JSON.stringify({ environment, plan, executed: false }, null, 2) + '\n');
     return 0;
@@ -262,17 +289,7 @@ export async function runSetup(argv = [], options = {}) {
   writeLine(write, receipt.ok ? '  ✓ Agent Sam setup complete' : '  ✕ Setup finished with failures');
   writeLine(write, `  Receipt  ${receipt.path}`);
   writeLine(write, '');
-  writeLine(write, '  Next');
-  writeLine(write, '    agentsam doctor');
-  writeLine(write, '    agentsam capabilities');
-  if (capabilityIds.includes('google.cloud')) {
-    writeLine(write, '    agentsam setup google.cloud --inventory');
-    writeLine(write, '    agentsam gcloud auth login');
-  }
-  if (capabilityIds.includes('image.vectorize')) {
-    writeLine(write, '    agentsam image optimize ./logo.png   # when image command ships');
-  }
-  writeLine(write, '');
+  writeSetupNext(write, capabilityIds);
 
   if (json) write(JSON.stringify({ environment, plan, receipt }, null, 2) + '\n');
   return receipt.ok ? 0 : 2;

package/src/commands/status.js

@@ -4,6 +4,7 @@ import { buildStatusActionPlan } from '../status/actions.js';
 import { openExternalUrl } from '../lib/open-url.js';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
+import { renderCommandHelp } from '../ui/cli/help.js';
 
 function parseStatusArgs(argv = []) {
   const opts = {
@@ -11,12 +12,14 @@ function parseStatusArgs(argv = []) {
     offline: false,
     discoverModels: true,
     interactive: false,
+    help: false,
   };
   for (const arg of argv) {
     if (arg === '--json') opts.json = true;
     else if (arg === '--offline') opts.offline = true;
     else if (arg === '--no-discover') opts.discoverModels = false;
     else if (arg === '--interactive' || arg === '-i') opts.interactive = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
     else throw new Error(`unknown status option: ${arg}`);
   }
   return opts;
@@ -68,13 +71,17 @@ async function runInteractiveMenu(status, write) {
 
 export async function runStatus(argv = [], opts = {}) {
   const parsed = parseStatusArgs(argv);
+  const write = opts.write || ((value) => process.stdout.write(value));
+  if (parsed.help) {
+    write(renderCommandHelp('status'));
+    return null;
+  }
   const status = await (opts.collectRuntime || collectRuntimeStatus)({
     ...opts,
     cwd: opts.cwd || process.cwd(),
     offline: parsed.offline,
     discoverModels: parsed.discoverModels,
   });
-  const write = opts.write || ((value) => process.stdout.write(value));
   if (parsed.json) {
     const plan = buildStatusActionPlan(status);
     write(`${JSON.stringify({ ...status, next: plan }, null, 2)}\n`);

package/src/features/resolve.js

@@ -39,6 +39,7 @@ export function normalizeProviderTemplateId(id) {
   if (!key) return '';
   if (key === 'iam') return 'inneranimalmedia';
   if (key === 'google-desktop') return 'google_desktop';
+  if (key === 'openai' || key === 'chatgpt-hosted' || key === 'chatgpt_hosted') return 'chatgpt';
   return key;
 }
 

package/src/knowledge/engine.js

@@ -59,7 +59,7 @@ export async function planIndex({ root, config: input, store, embed = false, lim
       limits: Number.isFinite(maxFiles) || Number.isFinite(maxChunks) ? { max_files: maxFiles, max_chunks: maxChunks } : null } };
 }
 
-export async function runIndex({ root, config, store, embedder, embed = false, maxInputs = 100, maxCharacters = 200000, limits = null }) {
+export async function runIndex({ root, config, store, embedder, embed = false, vectorBackend = null, vectorContext = {}, maxInputs = 100, maxCharacters = 200000, limits = null }) {
   if (!store) throw new Error('A writable knowledge store is required.');
   if (!Number.isInteger(maxInputs) || maxInputs < 0 || !Number.isInteger(maxCharacters) || maxCharacters < 0) throw new Error('Embedding budgets must be nonnegative integers.');
   const plan = await planIndex({ root, config, store, embed, limits });
@@ -76,6 +76,25 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
     // Completed work remains reusable even if a later request or publication fails.
     await store.cachePut(key, vector);
   }
+  let vectorUpsert = null;
+  if (embed && plan.config.lane?.backend === 'cloudflare_vectorize') {
+    if (!vectorBackend?.upsert) throw new Error('cloudflare_vectorize_backend_required');
+    const records = [];
+    for (const chunk of plan.chunks) {
+      const vector = validateVector(await store.cacheGet(chunk.embedding_key), plan.config.embedding.dimensions);
+      records.push({
+        id: chunk.id,
+        vector,
+        metadata: { path: chunk.path, ordinal: chunk.ordinal, content_hash: chunk.content_hash },
+      });
+    }
+    vectorUpsert = await vectorBackend.upsert(records, {
+      ...vectorContext,
+      binding: plan.config.lane.binding,
+      index: plan.config.lane.index,
+      profile: { ...plan.config.lane, dimensions: plan.config.embedding.dimensions },
+    });
+  }
   // A generation describes one coherent source snapshot. Never publish after a mid-run edit.
   const check = [];
   const checkFiles = inventory(root, plan.config.scope).slice(0, limits?.maxFiles == null ? Infinity : limits.maxFiles);
@@ -85,7 +104,7 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
     source_hash: receipt.source_hash, config_hash: receipt.config_hash, config: plan.config, profile_id: receipt.profile_id,
     git: gitEvidence(root), files: plan.files, chunks: plan.chunks, symbols: plan.symbols, edges: plan.edges, receipt };
   await store.publish(generation, plan.previous?.id || null);
-  return { ...receipt, generation_id: generation.id, published: true };
+  return { ...receipt, generation_id: generation.id, published: true, vector_upsert: vectorUpsert };
 }
 
 export async function retrieve({ store, config: input, text, semantic = false, embedder, topK = 8, tokenBudget = 6000, generationId, resultPolicy: requestedResultPolicy }) {

package/src/knowledge/runtime-discovery.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readCloudflareDeploymentContract } from '../cloudflare/runtime-status.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
+import { resolveProviderCredential } from '../lib/provider-credentials.js';
+import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
+
+export const PROJECT_CONTEXT_SCHEMA = 'agentsam.project-context.v1';
+const clean = value => value == null ? '' : String(value).trim();
+const localIndexPath = root => path.join(root, '.agentsam', 'knowledge', 'index.sqlite');
+function readJson(filename) { try { return JSON.parse(fs.readFileSync(filename, 'utf8')); } catch { return null; } }
+function executionState({ observed = false, selected = false, local = false, remote = false, conflicting = false, source = null, reason = null } = {}) {
+  return { observed: Boolean(observed), explicitly_selected: Boolean(selected), locally_executable: Boolean(local), remotely_executable: Boolean(remote), missing: !observed, conflicting: Boolean(conflicting), source: source || null, reason: reason || null };
+}
+function cloudflareCredentialState(env) {
+  try {
+    const credential = resolveProviderCredential('cloudflare', { env });
+    const configured = Boolean(credential?.configured);
+    const accountResolved = Boolean(clean(credential?.account_id));
+    return { configured, account_resolved: accountResolved, executable: configured && accountResolved, source: credential?.source || null, error: credential?.error || (!configured ? 'cloudflare_authorization_required' : !accountResolved ? 'cloudflare_account_id_required' : null) };
+  } catch (error) {
+    return { configured: false, account_resolved: false, executable: false, source: null, error: error?.message || String(error) };
+  }
+}
+function policyConflict(policy, vectorize) {
+  if (policy?.lane?.backend !== 'cloudflare_vectorize') return [];
+  const binding = clean(policy.lane.binding), index = clean(policy.lane.index);
+  if (vectorize.some(row => row.binding === binding && row.index === index)) return [];
+  return [{ kind: 'knowledge_deployment_drift', backend: 'cloudflare_vectorize', policy: { binding: binding || null, index: index || null }, observed: vectorize.map(row => ({ binding: row.binding, index: row.index })), detail: 'Knowledge policy selects a Vectorize binding/index that is not declared by the active Wrangler deployment contract.' }];
+}
+
+export function discoverProjectContext(root = process.cwd(), options = {}) {
+  const resolvedRoot = fs.realpathSync(path.resolve(root));
+  const env = options.env || process.env;
+  const policy = options.knowledgeConfig || null;
+  const projectConfig = options.projectConfig || tryReadProjectConfig(resolvedRoot);
+  const git = tryResolveGitContext({ cwd: resolvedRoot });
+  const repositoryId = getRepositoryId(projectConfig) || portableRepositoryIdFromGit(resolvedRoot) || `local:${path.basename(resolvedRoot)}`;
+  const hostInstallPath = path.join(resolvedRoot, '.agentsam', 'app.json');
+  const hostInstall = fs.existsSync(hostInstallPath) ? readJson(hostInstallPath) : null;
+  const productManifestPath = path.join(resolvedRoot, 'agentsam.app.json');
+  const productManifest = fs.existsSync(productManifestPath) ? readJson(productManifestPath) : null;
+  let contract = null, contractError = null;
+  try { contract = readCloudflareDeploymentContract(resolvedRoot, projectConfig || {}); } catch (error) { contractError = error?.message || String(error); }
+  const bindings = contract?.bindings || [];
+  const ai = bindings.find(row => row.type === 'ai') || null;
+  const vectorize = bindings.filter(row => row.type === 'vectorize').map(row => ({ binding: row.name, index: row.index_name || null, source: row.source || 'wrangler_config' }));
+  const d1 = bindings.filter(row => row.type === 'd1');
+  const r2 = bindings.filter(row => row.type === 'r2_bucket');
+  const credential = cloudflareCredentialState(env);
+  const remoteConfigured = Boolean(contract?.configured);
+  const conflicts = policyConflict(policy, vectorize);
+  const indexPath = localIndexPath(resolvedRoot);
+  const localIndex = { exists: fs.existsSync(indexPath), path: path.relative(resolvedRoot, indexPath) };
+  const policyBinding = clean(policy?.lane?.binding), policyIndex = clean(policy?.lane?.index);
+  const vectorizeResources = vectorize.map(row => {
+    const selected = policy?.lane?.backend === 'cloudflare_vectorize' && row.binding === policyBinding && row.index === policyIndex;
+    return {
+      ...row,
+      configured: Boolean(row.binding && row.index),
+      ...executionState({
+        observed: Boolean(row.binding && row.index), selected,
+        local: Boolean(row.binding && row.index && credential.executable),
+        remote: Boolean(row.binding && row.index && remoteConfigured),
+        conflicting: conflicts.length > 0 && !selected,
+        source: row.source,
+        reason: credential.executable ? null : 'Local CLI/Desktop Vectorize execution requires the current user Cloudflare authorization and account id.',
+      }),
+    };
+  });
+  const workersAi = ai ? {
+    binding: ai.name, configured: true, credential_state: credential,
+    ...executionState({ observed: true, selected: policy?.embedding?.provider === 'workers-ai', local: false, remote: remoteConfigured, source: ai.source || 'wrangler_config', reason: 'Workers AI binding is executable in the configured Worker runtime; a local Node process does not possess env.<AI_BINDING>.' }),
+  } : {
+    binding: null, configured: false, credential_state: credential,
+    ...executionState({ observed: false, source: contract?.config || null, reason: 'No Workers AI binding declared.' }),
+  };
+  const mapBoundResource = row => ({
+    binding: row.name,
+    name: row.database_name || row.bucket_name || null,
+    id: row.database_id || null,
+    ...executionState({ observed: true, local: false, remote: remoteConfigured, source: row.source || 'wrangler_config', reason: 'This receipt describes runtime binding execution; local provider API execution is a separate authorized transport.' }),
+  });
+  const lanes = [];
+  if (localIndex.exists) lanes.push({ id: 'local-index', backend: 'local_exact', source: 'local_index', configured: true, locally_executable: true, remotely_executable: false });
+  for (const row of vectorizeResources) lanes.push({ id: `cloudflare-vectorize:${row.binding}`, backend: 'cloudflare_vectorize', binding: row.binding, index: row.index, source: row.source, configured: row.configured, locally_executable: row.locally_executable, remotely_executable: row.remotely_executable, explicitly_selected: row.explicitly_selected, conflicting: row.conflicting });
+
+  return {
+    schema: PROJECT_CONTEXT_SCHEMA,
+    version: 1,
+    repository: { root: resolvedRoot, identity: repositoryId, branch: git?.branch || null, revision: git?.revisionSha || null, dirty: git?.dirty ?? null, source: git ? 'git' : projectConfig ? '.agentsam/config.json' : 'filesystem' },
+    project: {
+      config_present: Boolean(projectConfig), config_source: projectConfig ? '.agentsam/config.json' : null,
+      product_manifest: productManifest ? { id: clean(productManifest.id) || null, source: 'agentsam.app.json' } : null,
+      host_install: hostInstall ? { app_id: clean(hostInstall.app_id || hostInstall.id) || null, name: clean(hostInstall.name) || null, role: clean(hostInstall.role) || null, mounts: hostInstall.mounts || null, schema: clean(hostInstall.schema) || null, source: '.agentsam/app.json' } : null,
+    },
+    deployment: { configured: remoteConfigured, worker_name: contract?.worker_name || null, config: contract?.config || null, error: contractError },
+    knowledge: {
+      policy_configured: Boolean(policy), policy_source: policy ? '.agentsam/knowledge.json' : null,
+      selected_backend: policy?.lane?.backend || null,
+      suggested_backend: !policy && vectorizeResources.length === 1 ? 'cloudflare_vectorize' : (!policy ? 'local_exact' : null),
+      local_index: { ...localIndex, ...executionState({ observed: localIndex.exists, selected: policy?.lane?.backend === 'local_exact', local: localIndex.exists, remote: false, source: localIndex.exists ? localIndex.path : null, reason: localIndex.exists ? null : 'No local knowledge SQLite index exists.' }) },
+    },
+    authorization: { cloudflare: credential },
+    resources: {
+      workers_ai: workersAi,
+      vectorize: vectorizeResources,
+      d1: d1.map(mapBoundResource),
+      r2: r2.map(mapBoundResource),
+    },
+    conflicts,
+    local_index: localIndex,
+    cloudflare: {
+      configured: remoteConfigured,
+      worker_name: contract?.worker_name || null,
+      config: contract?.config || null,
+      ai_binding: ai?.name || null,
+      vectorize: vectorizeResources.map(row => ({ binding: row.binding, index: row.index, source: row.source })),
+      error: contractError,
+    },
+    lanes,
+  };
+}
+
+export function discoverKnowledgeRuntime(root = process.cwd(), options = {}) {
+  return discoverProjectContext(root, options);
+}