@inneranimalmedia/agentsam-sdk 2.0.0 → 2.2.0

package/src/commands/deploy-receipt.js

@@ -0,0 +1,129 @@
+import { captureDeployReceipt, finalizeDeployReceipt, showLatestDeployReceipt } from '../lib/deploy-receipt/index.js';
+
+export function printDeployReceiptHelp() {
+  console.log(`
+  agentsam deploy-receipt — reusable Merkle deployment/checkpoint lifecycle
+
+  capture [path]              Capture the current tree and compare to the last promoted baseline
+  success [path]              Finalize a successful run and promote its snapshot to latest
+  failure [path]              Finalize a failed run without advancing the baseline
+  show [path]                 Print the latest promoted receipt
+
+  --project <id>              Logical project identifier (defaults to directory name)
+  --state-dir <path>          Runtime state directory (default: .agentsam/deploy-merkle)
+  --baseline <snapshot>       Explicit baseline snapshot for capture (e.g. restored from R2)
+  --baseline-source <label>   Baseline provenance label (e.g. r2, local-cache)
+  --include <default-rule>    Include one AgentSam default-ignored category
+  --exclude <path-or-name>    Additional literal exclusion (repeatable)
+  --max-changed-files <n>     Receipt path cap (default 100)
+  --deployment-id <id>        Deployment/ledger identity for success/failure
+  --worker-version <id>       Provider version identity for success/failure
+  --metadata-json <json>      Extra compact receipt metadata object
+  --json                      Machine-readable output
+
+  Runtime state is intentionally not source. The state directory is excluded from the
+  captured Merkle tree, successful finalize advances latest.*, and failure never does.
+
+  Examples:
+    agentsam deploy-receipt capture . --project my-worker --json
+    wrangler deploy
+    agentsam deploy-receipt success . --deployment-id dep_123 --json
+    agentsam deploy-receipt failure . --deployment-id dep_124 --json
+`);
+}
+
+function parseJsonObject(value, flag) {
+  let parsed;
+  try { parsed = JSON.parse(value); } catch { throw new Error(`${flag} must be valid JSON.`); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error(`${flag} must be a JSON object.`);
+  return parsed;
+}
+
+function parse(argv) {
+  const [command, ...args] = argv;
+  const normalized = command === 'fail' ? 'failure' : command === 'promote' ? 'success' : command;
+  if (!['capture', 'success', 'failure', 'show'].includes(normalized)) throw new Error(`Unknown deploy-receipt command: ${command || ''}`);
+  const opts = { command: normalized, root: '.', include: [], exclude: [], json: false, metadata: {} };
+  let positional = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') { positional = true; continue; }
+    if (positional || !arg.startsWith('-')) {
+      if (opts.root !== '.') throw new Error('Only one root path may be supplied.');
+      opts.root = arg;
+      continue;
+    }
+    if (arg === '--json') { opts.json = true; continue; }
+    if (['--project', '--state-dir', '--baseline', '--baseline-source', '--deployment-id', '--worker-version', '--metadata-json', '--max-changed-files', '--include', '--exclude'].includes(arg)) {
+      const value = args[++i];
+      if (value == null || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (arg === '--include') opts.include.push(value);
+      else if (arg === '--exclude') opts.exclude.push(value);
+      else if (arg === '--metadata-json') opts.metadata = parseJsonObject(value, arg);
+      else if (arg === '--max-changed-files') {
+        const count = Number(value);
+        if (!Number.isSafeInteger(count) || count < 1 || count > 10000) throw new Error('--max-changed-files must be an integer from 1 to 10000.');
+        opts.maxChangedFiles = count;
+      } else opts[arg.slice(2).replaceAll('-', '_')] = value;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  if (opts.command !== 'capture' && (opts.baseline || opts.baseline_source || opts.include.length || opts.exclude.length || opts.maxChangedFiles)) {
+    throw new Error('Baseline/include/exclude/change-cap options apply only to capture.');
+  }
+  if (!['success', 'failure'].includes(opts.command) && (opts.deployment_id || opts.worker_version)) {
+    throw new Error('--deployment-id and --worker-version apply only to success/failure.');
+  }
+  return opts;
+}
+
+function human(result, command) {
+  if (!result) return 'No promoted deploy receipt.\n';
+  const receipt = result.receipt || result;
+  if (command === 'capture') {
+    const delta = receipt.diff_stats ? `${receipt.diff_stats.added} added, ${receipt.diff_stats.modified} modified, ${receipt.diff_stats.removed} removed` : 'no baseline';
+    return `Captured ${receipt.root_hash} (${delta}; baseline=${receipt.baseline_source}).\n`;
+  }
+  return `${receipt.status}: ${receipt.root_hash}${receipt.deployment_id ? ` deployment=${receipt.deployment_id}` : ''}\n`;
+}
+
+export async function runDeployReceipt(argv = []) {
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) { printDeployReceiptHelp(); return; }
+  try {
+    const opts = parse(argv);
+    let result;
+    if (opts.command === 'capture') {
+      result = await captureDeployReceipt({
+        root: opts.root,
+        project: opts.project,
+        stateDir: opts.state_dir,
+        baselineSnapshot: opts.baseline,
+        baselineSource: opts.baseline_source,
+        include: opts.include,
+        exclude: opts.exclude,
+        maxChangedFiles: opts.maxChangedFiles,
+        metadata: opts.metadata,
+      });
+    } else if (opts.command === 'show') {
+      result = await showLatestDeployReceipt({ root: opts.root, stateDir: opts.state_dir });
+    } else {
+      result = await finalizeDeployReceipt({
+        root: opts.root,
+        stateDir: opts.state_dir,
+        status: opts.command === 'success' ? 'success' : 'failed',
+        deploymentId: opts.deployment_id,
+        workerVersionId: opts.worker_version,
+        metadata: opts.metadata,
+      });
+    }
+    const output = result?.receipt || result;
+    if (opts.json) process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    else process.stdout.write(human(result, opts.command));
+    return result;
+  } catch (error) {
+    process.exitCode = 2;
+    const json = argv.includes('--json');
+    process.stderr.write(json ? JSON.stringify({ error: error.message }) + '\n' : `Deploy receipt: ${error.message}\n`);
+  }
+}

package/src/commands/deploy.js

@@ -97,7 +97,6 @@ async function runCloudflareDeploy(cwd, config, accountId) {
       hosting: 'cloudflare',
       provision_only: true,
       account_id: accountId || undefined,
-      workspace_id: ctx.workspace_id,
     },
     token,
     async (evt) => {

package/src/commands/knowledge.js

@@ -24,12 +24,12 @@ async function openStore(root, config, readOnly = false) {
 function provider() { return createGeminiEmbedder({ apiKey: process.env.GEMINI_API_KEY }); }
 
 export async function runRepositoryInit(argv) {
-  const { values: opts, positionals } = flags(argv, { existing: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, include: { type: 'string' }, exclude: { type: 'string' }, scope: { type: 'string' }, workspace: { type: 'string' }, target: { type: 'string' }, dimensions: { type: 'string' } });
-  if (opts.help) { console.log('agentsam init [.] [--cwd PATH] [--yes] [--include src,docs] [--exclude src/generated] [--scope NAME] [--target local|production] [--workspace ID] [--dimensions 768]'); return; }
+  const { values: opts, positionals } = flags(argv, { existing: { type: 'boolean' }, yes: { type: 'boolean', short: 'y' }, include: { type: 'string' }, exclude: { type: 'string' }, scope: { type: 'string' }, target: { type: 'string' }, dimensions: { type: 'string' } });
+  if (opts.help) { console.log('agentsam init [.] [--cwd PATH] [--yes] [--include src,docs] [--exclude src/generated] [--scope NAME] [--target local|production] [--dimensions 768]'); return; }
   if (positionals.length > 1 || (positionals[0] && positionals[0] !== '.')) throw new Error('Use init . --cwd PATH to adopt an existing repository, or init --name NAME to scaffold.');
   const root = repositoryRoot(opts.cwd);
   if (fs.existsSync(path.join(root, CONFIG_PATH))) throw new Error(`${CONFIG_PATH} already exists; edit it to change scope/profile. Existing configuration was preserved.`);
-  let include = opts.include, exclude = opts.exclude, target = opts.target, workspace = opts.workspace, dimensions = opts.dimensions;
+  let include = opts.include, exclude = opts.exclude, target = opts.target, dimensions = opts.dimensions;
   if (!opts.yes) {
     if (!process.stdin.isTTY) throw new Error('Existing-repository setup needs a terminal or --yes with explicit options.');
     const prompt = createInterface({ input: process.stdin, output: process.stdout });
@@ -38,11 +38,10 @@ export async function runRepositoryInit(argv) {
       include ??= await prompt.question('1) Include files/directories, comma-separated [.]: ') || '.';
       exclude ??= await prompt.question('2) Exclude files/directories [none]: ') || '';
       target ??= await prompt.question('3) Storage: local or production [local]: ') || 'local';
-      if (target === 'production') workspace ??= await prompt.question('4) Workspace identifier: ');
-      dimensions ??= await prompt.question('5) Gemini Embedding 2 dimensions [768]: ') || '768';
+      dimensions ??= await prompt.question('4) Gemini Embedding 2 dimensions [768]: ') || '768';
     } finally { prompt.close(); }
   }
-  const config = initRepository(root, { include: split(include || '.'), exclude: split(exclude || ''), scope: opts.scope || 'default', target: target || 'local', workspace: workspace || 'local', dimensions: Number(dimensions || 768) });
+  const config = initRepository(root, { include: split(include || '.'), exclude: split(exclude || ''), scope: opts.scope || 'default', target: target || 'local', dimensions: Number(dimensions || 768) });
   show({ root, config: CONFIG_PATH, storage: config.storage.driver, next: config.storage.driver === 'postgres' ? ['agentsam index setup-store', 'agentsam index plan', 'agentsam index run'] : ['agentsam index plan', 'agentsam index run', 'agentsam search "your symbol"'], note: 'No indexing, credentials, network calls, or source-file changes during setup.' });
 }
 

package/src/commands/product.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { getCapability, getCapabilityManifest, listCapabilities, repositorySnapshot } from '../capabilities/index.js';
+import { getAddon, listAddons, listPresets } from '../presets/index.js';
+
+function parseCommon(argv = []) {
+  const out = { json: false, cwd: process.cwd(), positionals: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') out.json = true;
+    else if (arg === '--cwd') out.cwd = argv[++i] || out.cwd;
+    else out.positionals.push(arg);
+  }
+  return out;
+}
+
+export async function runInspect(argv = []) {
+  const opts = parseCommon(argv);
+  let churnDays = 30;
+  for (let i = 0; i < opts.positionals.length; i += 1) {
+    if (opts.positionals[i] === '--churn-days') churnDays = Number(opts.positionals[++i] || 30);
+    else if (opts.positionals[i] === 'repository') continue;
+    else throw new Error(`unknown inspect option: ${opts.positionals[i]}`);
+  }
+  const result = await repositorySnapshot({ cwd: opts.cwd, churnDays });
+  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    console.log(`\nRepository snapshot ${result.snapshot_id}`);
+    console.log(`  repo       ${result.repository.full_name || result.repository.repository_id || '(local)'}`);
+    console.log(`  revision   ${result.repository.revision_sha}`);
+    console.log(`  merkle     ${result.tree.merkle_root}`);
+    console.log(`  files      ${result.intelligence.summary?.file_count ?? result.tree.stats?.files ?? 'unknown'}`);
+    console.log(`  knowledge  ${result.knowledge?.indexed ? result.knowledge.generation_id : result.knowledge?.configured ? 'configured / not indexed' : 'not configured'}`);
+    console.log(`  deploy     ${result.deploy?.status || 'no trusted receipt'}`);
+    console.log(`  content    ${result.content_hash}\n`);
+  }
+  return result;
+}
+
+export async function runCapabilities(argv = []) {
+  const opts = parseCommon(argv);
+  const id = opts.positionals[0] || '';
+  const result = id ? getCapability(id) : getCapabilityManifest();
+  if (id && !result) throw new Error(`unknown_capability:${id}`);
+  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else if (id) console.log(`${result.id}\n  ${result.description}\n  cli: ${result.cli || '(library only)'}\n  model required: ${result.model_required ? 'yes' : 'no'}`);
+  else {
+    console.log('\nAgentSam deterministic capabilities\n');
+    for (const row of listCapabilities()) console.log(`  ${row.id.padEnd(26)} ${row.description}`);
+    console.log('');
+  }
+  return result;
+}
+
+function projectConfigPath(cwd) { return path.join(cwd, '.agentsam', 'config.json'); }
+function featureStatePath(cwd) { return path.join(cwd, '.agentsam', 'features.json'); }
+
+export function applyPresetSelection(cwd, preset) {
+  const filename = projectConfigPath(cwd);
+  if (!fs.existsSync(filename)) throw new Error('not_agentsam_project');
+  const config = JSON.parse(fs.readFileSync(filename, 'utf8'));
+  const next = { ...config, preset: preset.id, features: [...preset.features], capabilities: [...preset.capabilities] };
+  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}
+
+export async function runAdd(argv = []) {
+  const opts = parseCommon(argv);
+  const id = opts.positionals[0];
+  if (!id || id === '--help') {
+    const rows = listAddons();
+    console.log(`agentsam add <${rows.map(x => x.id).join('|')}> [--cwd PATH] [--json]`);
+    return null;
+  }
+  const addon = getAddon(id);
+  if (!addon) throw new Error(`unknown_addon:${id}`);
+  const cwd = path.resolve(opts.cwd);
+  if (!fs.existsSync(projectConfigPath(cwd))) throw new Error('not_agentsam_project');
+  fs.mkdirSync(path.dirname(featureStatePath(cwd)), { recursive: true });
+  let state = { schema_version: 1, features: {} };
+  if (fs.existsSync(featureStatePath(cwd))) state = JSON.parse(fs.readFileSync(featureStatePath(cwd), 'utf8'));
+  state.features ||= {};
+  state.features[addon.id] = { selected: true, capabilities: addon.capabilities, selected_at: new Date().toISOString() };
+  fs.writeFileSync(featureStatePath(cwd), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  if (addon.id === 'deploy-cloudflare') {
+    const config = JSON.parse(fs.readFileSync(projectConfigPath(cwd), 'utf8'));
+    config.deploy_target = 'cloudflare';
+    fs.writeFileSync(projectConfigPath(cwd), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  }
+  const result = { ok: true, feature: addon.id, capabilities: addon.capabilities, description: addon.description, state_file: '.agentsam/features.json' };
+  if (opts.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else console.log(`\nAdded ${addon.id}\n  ${addon.description}\n  state: ${result.state_file}\n`);
+  return result;
+}
+
+export async function runDev(argv = []) {
+  const opts = parseCommon(argv);
+  if (opts.positionals.length) throw new Error(`unknown dev option: ${opts.positionals[0]}`);
+  const cwd = path.resolve(opts.cwd);
+  const pkgFile = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgFile)) throw new Error('package_json_not_found');
+  const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+  if (!pkg.scripts?.dev) throw new Error('dev_script_not_found');
+  if (/\bagentsam\s+dev\b/.test(pkg.scripts.dev)) throw new Error('recursive_agentsam_dev_script');
+  const child = spawn(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['run', 'dev'], { cwd, stdio: 'inherit', env: process.env });
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (signal) return reject(new Error(`dev_process_signal:${signal}`));
+      process.exitCode = code || 0;
+      resolve(code || 0);
+    });
+  });
+}
+
+export function printProductCatalog() {
+  return { presets: listPresets(), addons: listAddons(), capabilities: listCapabilities() };
+}

package/src/commands/recon.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PYTHON_ROOT = fileURLToPath(new URL('../../python', import.meta.url));
+
+export function printReconHelp() {
+  console.log(`
+  agentsam recon — bounded-worker task packets and finding-report validation
+
+  pack --repo-root <path> --question "..." --slice <path[:start-end]> [--slice ...]
+                               Build a bounded ReconTaskPacket (<=5 slices, hard ceilings)
+  validate --packet <file> --report <file>
+                               Validate a ReconFindingReport against its packet
+
+  pack options:
+    --repo-root <path>         Default: .
+    --question <text>          Required. Exactly one bounded question.
+    --slice <path[:start-end]> Repeatable, up to 5. e.g. --slice src/foo.js:10-40
+    --task-id <id>             Default: generated
+    --out <file>                Write the packet JSON to a file instead of stdout
+
+  validate options:
+    --packet <file>             Required. Path to a packet JSON file.
+    --report <file>              Required. Path to a worker's report JSON file.
+
+  Neither command calls a model or writes into the target repository. This is a thin
+  passthrough to the bundled Python module (agentsam_sdk.repository.recon) — same
+  engine as \`python -m agentsam_sdk.repository.recon\`. See docs/RECON.md.
+
+  Examples:
+    agentsam recon pack --repo-root . --question "Does this still read workspace_id?" \\
+      --slice backend/workflows/repository.js:1-180 --out /tmp/packet.json
+    agentsam recon validate --packet /tmp/packet.json --report /tmp/report.json
+
+  For a raw rg/ast-grep hit list instead of hand-picked slices, use
+  agentsam_sdk.repository.recon.{from_ripgrep,from_ast_grep,from_matches}() from
+  Python directly — those have no Node CLI surface yet since hit shapes vary by tool.
+`);
+}
+
+function run(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: { ...process.env, PYTHONPATH: [PYTHON_ROOT, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter) },
+    });
+    child.once('error', (err) => {
+      console.error(`\n  ✗ Could not run Python (${err.message}). Python 3.10+ must be on PATH for \`agentsam recon\`.\n`);
+      resolve(1);
+    });
+    child.once('exit', (code, signal) => {
+      if (signal) { console.error(`\n  ✗ recon ${signal}\n`); resolve(1); }
+      else resolve(code ?? 1);
+    });
+  });
+}
+
+export async function runRecon(argv = []) {
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) { printReconHelp(); return; }
+  const [command] = argv;
+  if (!['pack', 'validate'].includes(command)) {
+    console.error(`\n  ✗ Unknown recon command: ${command}. Use \`agentsam recon --help\`.\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const python = process.platform === 'win32' ? 'python' : 'python3';
+  const code = await run(python, ['-B', '-m', 'agentsam_sdk.repository.recon', ...argv]);
+  if (code !== 0) process.exitCode = code;
+}

package/src/index.js

@@ -6,6 +6,14 @@ export { AgentSam } from './AgentSam.js';
 export { routeIntent } from './lib/router.js';
 export { getToolCatalog } from './lib/tools.js';
 export { scaffoldProject } from './lib/scaffold.js';
+export {
+  DEFAULT_DEPLOY_EXCLUDES,
+  captureDeployReceipt,
+  finalizeDeployReceipt,
+  showLatestDeployReceipt,
+  captureCheckpoint,
+  promoteCheckpoint,
+} from './lib/deploy-receipt/index.js';
 export {
   normalizeGitRemote,
   resolveGitContext,
@@ -23,12 +31,21 @@ export {
   SHELL_PHASES,
   listSlashCommands,
 } from './lib/slash-commands.js';
+export {
+  CAPABILITY_MANIFEST_VERSION,
+  getCapability,
+  getCapabilityManifest,
+  listCapabilities,
+  repositorySnapshot,
+} from './capabilities/index.js';
+export { getPreset, listPresets, resolvePreset, getAddon, listAddons } from './presets/index.js';
 
 export {
   createIdentityClient,
   createIdentity,
   GoogleProvider,
   GithubProvider,
+  IamProvider,
   GcpProvider,
   EmailProvider,
   getIdentityProvider,

package/src/knowledge/config.js

@@ -37,7 +37,8 @@ export function validateConfig(input) {
   allowed(c.embedding, ['provider', 'model', 'revision', 'dimensions', 'parameters'], 'embedding');
   allowed(c.storage, ['driver', 'connection_env'], 'storage');
   if (c.version !== 1) throw new Error('Unsupported knowledge configuration version.');
-  for (const key of ['repository_id', 'workspace_id']) if (typeof c[key] !== 'string' || !c[key].trim()) throw new Error(`${key} is required.`);
+  if (typeof c.repository_id !== 'string' || !c.repository_id.trim()) throw new Error('repository_id is required.');
+  if (c.workspace_id != null && (typeof c.workspace_id !== 'string' || !c.workspace_id.trim())) throw new Error('workspace_id must be a non-empty string when present.');
   if (typeof c.scope?.name !== 'string' || !c.scope.name.trim() || !Array.isArray(c.scope.include) || !c.scope.include.length) throw new Error('A named scope with at least one include path is required.');
   c.scope.include = [...new Set(c.scope.include.map(relativeSelection))].sort();
   c.scope.exclude = [...new Set((c.scope.exclude || []).map(relativeSelection))].sort();
@@ -49,10 +50,9 @@ export function validateConfig(input) {
   if (c.storage.driver === 'postgres' && !/^[A-Z_][A-Z0-9_]*$/.test(c.storage.connection_env || '')) throw new Error('Postgres requires a connection_env name, never a connection string in config.');
   return c;
 }
-export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', workspace = 'local', target = 'local', dimensions = 768 } = {}) {
+export function defaultConfig({ include = ['.'], exclude = [], scope = 'default', target = 'local', dimensions = 768 } = {}) {
   if (!['local', 'production'].includes(target)) throw new Error('target must be local or production.');
-  if (target === 'production' && workspace === 'local') throw new Error('Production requires an explicit workspace identifier.');
-  return validateConfig({ version: 1, repository_id: randomUUID(), workspace_id: workspace,
+  return validateConfig({ version: 1, repository_id: randomUUID(),
     scope: { name: scope, include, exclude }, chunking: { max_chars: 4000 },
     embedding: { provider: 'gemini', model: 'gemini-embedding-2', revision: '1', dimensions, parameters: { task: 'code retrieval' } },
     storage: target === 'local' ? { driver: 'sqlite' } : { driver: 'postgres', connection_env: 'AGENTSAM_DATABASE_URL' } });
@@ -65,5 +65,11 @@ export function initRepository(root, options = {}) {
   fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
   return config;
 }
-export const scopeKey = config => fingerprint([config.workspace_id, config.repository_id, config.scope.name]);
-export const cacheNamespace = config => fingerprint([config.workspace_id, config.repository_id]);
+// New portable configs are repository-scoped. Legacy configs that still carry
+// workspace_id retain their original namespace so existing local generations stay readable.
+export const scopeKey = config => config.workspace_id
+  ? fingerprint([config.workspace_id, config.repository_id, config.scope.name])
+  : fingerprint([config.repository_id, config.scope.name]);
+export const cacheNamespace = config => config.workspace_id
+  ? fingerprint([config.workspace_id, config.repository_id])
+  : fingerprint([config.repository_id]);

package/src/knowledge/contracts.js

@@ -8,7 +8,7 @@ export const KNOWLEDGE_OPERATIONS = Object.freeze({
 export function assertRetrievalQuery(value) {
   if (!value || typeof value !== "object") throw new TypeError("RetrievalQuery must be an object");
   if (!String(value.text || "").trim()) throw new TypeError("RetrievalQuery.text is required");
-  if (!String(value.workspace_id || "").trim()) throw new TypeError("RetrievalQuery.workspace_id is required");
+  if (value.workspace_id != null && !String(value.workspace_id).trim()) throw new TypeError("RetrievalQuery.workspace_id must be non-empty when present");
   const topK = value.top_k ?? 12;
   if (!Number.isInteger(topK) || topK < 1 || topK > 100) throw new RangeError("top_k must be 1..100");
   if (!Number.isInteger(value.token_budget ?? 8000) || (value.token_budget ?? 8000) < 256) throw new RangeError("token_budget must be at least 256");

package/src/knowledge/engine.js

@@ -113,6 +113,6 @@ export async function retrieve({ store, config: input, text, semantic = false, e
       metadata: { generation_id: generation.id, symbol: hit.symbol, content_hash: hit.content_hash, freshness: 'working tree not checked' } }); estimatedTokens += tokens;
     if (hits.length === topK) break;
   }
-  return createContextPack({ queryId: randomUUID(), query: { text, workspace_id: config.workspace_id, top_k: topK, token_budget: tokenBudget }, hits,
+  return createContextPack({ queryId: randomUUID(), query: { text, top_k: topK, token_budget: tokenBudget }, hits,
     diagnostics: { generation_id: generation.id, source_hash: generation.source_hash, scope: generation.config.scope, mode: semantic ? 'semantic-exact' : 'lexical', freshness: 'snapshot; working tree not checked' } });
 }

package/src/knowledge/service/server.js

@@ -100,7 +100,7 @@ export async function startKnowledgeService({ stateDir, repositories, token, por
     });
     // Re-resolve registry on replay. Removed repositories do not get resumed.
     const payload = JSON.parse(row.payload), registered = repositories[payload.request.repository];
-    if (!registered || registered.config.repository_id !== payload.config.repository_id || registered.config.workspace_id !== payload.config.workspace_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
+    if (!registered || registered.config.repository_id !== payload.config.repository_id || fingerprint(registered.config.scope) !== payload.registered_scope || (!allowEmbeddings && ((payload.request.embed && payload.request.operation !== 'plan') || payload.request.semantic))) {
       response = { ok: false, error: 'Repository registration changed; resubmit this job.' }; child.kill(); return;
     }
     child.send({ ...payload, root: registered.root, filename: path.join(stateDir, 'knowledge.sqlite'), maxFiles });
@@ -124,7 +124,7 @@ export async function startKnowledgeService({ stateDir, repositories, token, por
       payload.registered_scope = fingerprint(repositories[payload.request.repository].config.scope);
       const key = req.headers['idempotency-key'];
       if (key !== undefined && (typeof key !== 'string' || !/^[\w:.-]{1,128}$/.test(key))) throw fail(400, 'Invalid Idempotency-Key.');
-      const digest = fingerprint(payload), idem = key ? fingerprint([payload.config.workspace_id, payload.config.repository_id, key]) : null;
+      const digest = fingerprint(payload), idem = key ? fingerprint([payload.config.repository_id, payload.registered_scope, key]) : null;
       const previous = idem && db.prepare('SELECT * FROM jobs WHERE idem=?').get(idem);
       if (previous) {
         if (previous.digest !== digest) throw fail(409, 'Idempotency-Key already used for a different job.');