@inneranimalmedia/agentsam-sdk 2.1.0 → 2.2.1

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/shell.js

@@ -0,0 +1,253 @@
+import readline from 'node:readline';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SLASH_COMMANDS, SHELL_PHASES } from '../lib/slash-commands.js';
+import { runContext } from './context.js';
+import { runDb } from './db.js';
+import { runDeploy } from './deploy.js';
+import { runStatus } from './status.js';
+import { runTui } from './tui.js';
+
+function writeLine(write, value = '') {
+  write(`${value}\n`);
+}
+
+export function tokenizeShellLine(input = '') {
+  const source = String(input);
+  const tokens = [];
+  let token = '';
+  let quote = '';
+  let started = false;
+
+  const flush = () => {
+    if (!started) return;
+    tokens.push(token);
+    token = '';
+    started = false;
+  };
+
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === quote) {
+        quote = '';
+      } else {
+        token += ch;
+      }
+      started = true;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      flush();
+      continue;
+    }
+    token += ch;
+    started = true;
+  }
+  flush();
+  return tokens;
+}
+
+export function renderShellCatalog() {
+  const next = SHELL_PHASES.find((phase) => phase.status === 'next' || phase.status === 'current');
+  const rows = SLASH_COMMANDS.map((row) => `    ${row.cmd.padEnd(14)} ${row.description}`).join('\n');
+  return `
+  ╔════════════════════════════════╗
+  ║        Agent Sam Terminal      ║
+  ╚════════════════════════════════╝
+
+  Local PTY   agentsam start-local     ws://127.0.0.1:3099
+  ANSI TUI    agentsam tui             zero-dependency Node UI
+  Rich TUI    agentsam tui rich        optional richer Python UI
+              agentsam tui rich --install
+  DB          agentsam db status       local SQLite
+
+  Current milestone: ${next?.label ?? 'local terminal experience'}
+
+  Slash commands (${SLASH_COMMANDS.length} registered):
+${rows}
+`;
+}
+
+function parseDeployOptions(args, cwd) {
+  const opts = { cwd, target: '', accountId: '' };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--target') opts.target = args[++i] || '';
+    else if (arg === '--account-id') opts.accountId = args[++i] || '';
+    else throw new Error(`unknown /deploy option: ${arg}`);
+  }
+  return opts;
+}
+
+async function withProcessCwd(cwd, fn) {
+  const previous = process.cwd();
+  process.chdir(cwd);
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+async function runLocalAgent(goal, write) {
+  if (!goal) {
+    writeLine(write, '  Usage: /agent <goal>');
+    writeLine(write, '  Requires the local Agent Sam dev server (default http://127.0.0.1:8787).');
+    return;
+  }
+  const base = String(process.env.AGENTSAM_LOCAL_URL || 'http://127.0.0.1:8787').replace(/\/$/, '');
+  let response;
+  try {
+    response = await fetch(`${base}/api/agentsam/message`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ message: goal }),
+    });
+  } catch (error) {
+    throw new Error(`local Agent Sam unavailable at ${base} — run \`npm run dev\` first (${error?.message || error})`);
+  }
+  const text = await response.text();
+  if (!response.ok) throw new Error(`local Agent Sam returned HTTP ${response.status}: ${text.slice(0, 400)}`);
+  try {
+    writeLine(write, JSON.stringify(JSON.parse(text), null, 2));
+  } catch {
+    writeLine(write, text);
+  }
+}
+
+async function showLocalLogs(cwd, write) {
+  const dbPath = path.join(cwd, '.agentsam', 'data', 'agentsam.sqlite');
+  if (!fs.existsSync(dbPath)) {
+    writeLine(write, '  No local Agent Sam DB found. Run `agentsam init . --yes` first.');
+    return;
+  }
+  const { createLocalSqliteDatabase } = await import('../local/sqlite.js');
+  const db = await createLocalSqliteDatabase(dbPath);
+  try {
+    const calls = await db
+      .prepare('SELECT id, session_id, tool_name, status, created_at, completed_at FROM agent_tool_calls ORDER BY created_at DESC LIMIT 20')
+      .all();
+    if (!calls.results.length) {
+      writeLine(write, '  No local Agent Sam tool-call events yet.');
+      return;
+    }
+    writeLine(write, '');
+    writeLine(write, '  Recent Agent Sam tool calls');
+    for (const row of calls.results) {
+      writeLine(write, `  ${String(row.created_at || '').padEnd(20)} ${String(row.status || '').padEnd(10)} ${row.tool_name}`);
+    }
+    writeLine(write, '');
+  } finally {
+    db.close();
+  }
+}
+
+export async function dispatchShellLine(line, state = {}) {
+  const tokens = tokenizeShellLine(line);
+  const write = state.write || ((text) => process.stdout.write(text));
+  state.cwd = path.resolve(state.cwd || process.cwd());
+  if (!tokens.length) return { handled: true, exit: false, cwd: state.cwd };
+
+  const [command, ...args] = tokens;
+  try {
+    switch (command.toLowerCase()) {
+      case '/help':
+        write(renderShellCatalog());
+        return { handled: true, exit: false, cwd: state.cwd };
+      case '/exit':
+      case '/quit':
+        return { handled: true, exit: true, cwd: state.cwd };
+      case '/status':
+        await runStatus(args, { cwd: state.cwd });
+        break;
+      case '/context':
+        await runContext(['--cwd', state.cwd, ...args]);
+        break;
+      case '/pwd':
+        writeLine(write, state.cwd);
+        break;
+      case '/cd': {
+        const destination = args.length ? args.join(' ') : process.env.HOME || process.env.USERPROFILE || state.cwd;
+        const next = path.resolve(state.cwd, destination);
+        if (!fs.existsSync(next) || !fs.statSync(next).isDirectory()) throw new Error(`directory not found: ${next}`);
+        state.cwd = next;
+        writeLine(write, state.cwd);
+        break;
+      }
+      case '/git': {
+        const gitArgs = args.length ? args : ['status', '--short', '--branch'];
+        const result = spawnSync('git', gitArgs, { cwd: state.cwd, stdio: 'inherit', shell: false });
+        if (result.error) throw result.error;
+        if (result.status !== 0) throw new Error(`git exited ${result.status}`);
+        break;
+      }
+      case '/db':
+        await runDb(args.length ? args : ['status'], { cwd: state.cwd });
+        break;
+      case '/agent':
+        await runLocalAgent(args.join(' '), write);
+        break;
+      case '/logs':
+        await showLocalLogs(state.cwd, write);
+        break;
+      case '/tui':
+        await withProcessCwd(state.cwd, () => runTui(args));
+        break;
+      case '/deploy':
+        await runDeploy(parseDeployOptions(args, state.cwd));
+        break;
+      default:
+        writeLine(write, `  Unknown Agent Sam command: ${command}`);
+        writeLine(write, '  Type /help for available commands.');
+        return { handled: false, exit: false, cwd: state.cwd };
+    }
+  } catch (error) {
+    writeLine(write, `  ✗ ${error?.message || error}`);
+  }
+
+  return { handled: true, exit: false, cwd: state.cwd };
+}
+
+export async function runShell(argv = [], options = {}) {
+  const write = options.write || ((text) => process.stdout.write(text));
+  const state = { cwd: path.resolve(options.cwd || process.cwd()), write };
+  const sub = argv[0] || '';
+
+  if (sub === 'list' || sub === 'status') {
+    write(renderShellCatalog());
+    return;
+  }
+  if (sub === '--command' || sub === '--once') {
+    const line = argv.slice(1).join(' ');
+    if (!line) throw new Error(`${sub} requires a slash command`);
+    await dispatchShellLine(line, state);
+    return;
+  }
+  if (sub) throw new Error(`unknown shell option: ${sub}`);
+
+  write(renderShellCatalog());
+  writeLine(write, '  Interactive shell ready. Type /help for commands; /exit to return to your host shell.');
+  writeLine(write, '');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+  if (rl.terminal) {
+    rl.setPrompt('agentsam> ');
+    rl.prompt();
+  }
+
+  for await (const line of rl) {
+    const result = await dispatchShellLine(line, state);
+    if (result.exit) {
+      rl.close();
+      break;
+    }
+    if (rl.terminal) rl.prompt();
+  }
+}

package/src/index.js

@@ -31,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.');

package/src/lib/git-context.js

@@ -66,7 +66,9 @@ export function resolveGitContext(options = {}) {
     ? preferredRemote
     : availableRemotes[0] || preferredRemote;
   const remoteUrl = runGit(root, ['remote', 'get-url', remote], { required: false });
-  const revisionSha = runGit(root, ['rev-parse', 'HEAD']);
+  // A newly initialized repository can have an unborn HEAD. Repository identity
+  // and local inspection must still work before the first commit.
+  const revisionSha = runGit(root, ['rev-parse', 'HEAD'], { required: false }) || null;
   const branch = runGit(root, ['branch', '--show-current'], { required: false }) || null;
   const status = runGit(root, ['status', '--porcelain=v1'], { required: false });
 

package/src/lib/slash-commands.js

@@ -1,6 +1,6 @@
 /**
  * Canonical slash-command surface for Agent Sam SDK CLI / shell UX.
- * Consumed by the gorilla-shell example and future `agentsam shell` PTY bridge.
+ * Consumed by the interactive `agentsam shell` REPL and presentation layers.
  */
 
 export const SHELL_THEMES = ['NIGHT', 'DAY', 'LAVA', 'VOID'];
@@ -18,6 +18,7 @@ export const SLASH_COMMANDS = [
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
   { cmd: '/tui', description: 'Switch or preview terminal presentation', lane: 'terminal' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
+  { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];
 
 /** Shell UX rollout phases (gorilla-shell → SDK default CLI experience). */

package/src/presets/index.js

@@ -0,0 +1,20 @@
+import catalog from '../../protocol/presets/catalog.json' with { type: 'json' };
+
+export const PRESET_CATALOG_VERSION = catalog.schema_version;
+
+export function getPresetCatalog() { return structuredClone(catalog); }
+export function listPresets() { return Object.values(catalog.presets).map((row) => structuredClone(row)); }
+export function getPreset(id) {
+  const row = catalog.presets[String(id || '').trim().toLowerCase()];
+  return row ? structuredClone(row) : null;
+}
+export function resolvePreset(id = 'fullstack') {
+  const preset = getPreset(id);
+  if (!preset) throw new Error(`unknown_preset:${id}; expected ${Object.keys(catalog.presets).join(',')}`);
+  return preset;
+}
+export function listAddons() { return Object.values(catalog.addons).map((row) => structuredClone(row)); }
+export function getAddon(id) {
+  const row = catalog.addons[String(id || '').trim().toLowerCase()];
+  return row ? structuredClone(row) : null;
+}

package/src/repository/index.js

@@ -0,0 +1,4 @@
+export { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+export { buildMerkleTree, diffTrees, readSnapshot, saveSnapshot, validateSnapshot } from '../lib/merkle/index.js';
+export { resolveGitContext, tryResolveGitContext, normalizeGitRemote } from '../lib/git-context.js';
+export { buildRetrievalPlan, createContextPack } from '../knowledge/index.js';

package/test/agent-capabilities.test.mjs

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createCapabilityAdapter } from '../src/agent/index.js';
+import { buildRepositoryAuditPacket, runRepositoryAudit } from '../src/agent/repository-audit.js';
+
+const snapshot = {
+  schema_version: 1,
+  capability: 'repository.snapshot',
+  snapshot_id: 'rsnap_0123456789abcdef01234567',
+  content_hash: `sha256:${'a'.repeat(64)}`,
+  repository: { repository_id: 'github:owner/repo', provider: 'github', full_name: 'owner/repo', branch: 'main', revision_sha: 'b'.repeat(40), dirty: false },
+  tree: { merkle_root: `sha256:${'c'.repeat(64)}`, stats: { files: 10 } },
+  intelligence: {
+    summary: { file_count: 10, total_lines: 500 },
+    languages: [{ language: 'JavaScript', files: 7 }],
+    manifests: [{ path: 'package.json', kind: 'node' }],
+    top_level: [{ path: 'src', files: 7 }],
+    pressure_points: [{ path: 'src', pressure_score: 70 }],
+  },
+  packages: [{ path: 'package.json', name: 'demo', version: '1.0.0' }],
+  knowledge: { configured: false },
+  deploy: null,
+};
+
+test('repository audit packet is bounded read-only evidence', () => {
+  const packet = buildRepositoryAuditPacket({ snapshot, focus: ['packages'], evidenceBudget: 1000 });
+  assert.equal(packet.primitive, 'repository.audit');
+  assert.equal(packet.rules.read_only, true);
+  assert.equal(packet.rules.may_edit, false);
+  assert.equal(packet.snapshot_id, snapshot.snapshot_id);
+  assert.ok(JSON.stringify(packet.evidence).length <= 4000);
+});
+
+test('repository audit uses injected reasoning and validates read-only output', async () => {
+  const audit = await runRepositoryAudit({
+    snapshot,
+    reasoner: async packet => ({
+      summary: `Audited ${packet.evidence.repository.full_name}`,
+      packages: packet.evidence.packages,
+      notable_combinations: ['snapshot + audit'],
+      findings: [{ severity: 'low', finding: 'example' }],
+      recommended_routes: ['inspect capability registry'],
+      evidence_refs: [packet.evidence_index.packages],
+    }),
+  });
+  assert.equal(audit.primitive, 'repository.audit');
+  assert.equal(audit.summary, 'Audited owner/repo');
+  assert.equal(audit.packages.length, 1);
+  assert.deepEqual(audit.commands, []);
+
+  await assert.rejects(() => runRepositoryAudit({ snapshot, reasoner: async () => ({ summary: 'bad', jobs: [] }) }), /mutation field: jobs/);
+});
+
+test('agent capability adapter exposes only executable tools by default', async () => {
+  const adapter = createCapabilityAdapter({
+    reasoner: async packet => ({ summary: 'ok', evidence_refs: [packet.evidence_index.summary] }),
+    handlers: { 'knowledge.search': async input => ({ query: input.text, hits: [] }) },
+  });
+  const names = adapter.toolDescriptors().map(row => row.name);
+  assert.ok(names.includes('repository.snapshot'));
+  assert.ok(names.includes('repository.audit'));
+  assert.ok(names.includes('knowledge.search'));
+  assert.equal(names.includes('knowledge.index'), false);
+  const result = await adapter.invoke('knowledge.search', { text: 'hello' });
+  assert.equal(result.capability_id, 'knowledge.search');
+  assert.deepEqual(result.result.hits, []);
+});