@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/src/security/local-vault.js

@@ -0,0 +1,415 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { normalizeProviderId, PROVIDER_CREDENTIALS } from '../lib/provider-credentials.js';
+
+function homeDirectory(options = {}) {
+  return path.resolve(
+    options.home ||
+    options.env?.HOME ||
+    options.env?.USERPROFILE ||
+    os.homedir()
+  );
+}
+
+export function localVaultDirectory(options = {}) {
+  return path.join(homeDirectory(options), '.agentsam', 'vault');
+}
+
+export function localVaultPath(options = {}) {
+  return path.join(localVaultDirectory(options), 'credentials.enc');
+}
+
+export function localVaultSaltPath(options = {}) {
+  return path.join(localVaultDirectory(options), '.salt');
+}
+
+function ensureVaultDirectory(options = {}) {
+  const dir = localVaultDirectory(options);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32') {
+      try { fs.chmodSync(dir, 0o700); } catch { /* ignore */ }
+    }
+  }
+  return dir;
+}
+
+function getMachineFingerprint() {
+  const parts = [
+    os.hostname(),
+    os.userInfo?.()?.username || process.env.USER || process.env.USERNAME || 'unknown-user',
+    os.homedir(),
+    process.arch,
+    process.platform,
+  ];
+  return parts.join(':');
+}
+
+function getOrCreateSalt(options = {}) {
+  ensureVaultDirectory(options);
+  const saltFile = localVaultSaltPath(options);
+  if (fs.existsSync(saltFile)) {
+    try {
+      const raw = fs.readFileSync(saltFile);
+      if (raw.length === 32) return raw;
+    } catch {
+      // re-create if unreadable
+    }
+  }
+  const salt = crypto.randomBytes(32);
+  fs.writeFileSync(saltFile, salt, { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(saltFile, 0o600); } catch { /* ignore */ }
+  }
+  return salt;
+}
+
+function deriveKey(options = {}) {
+  const salt = getOrCreateSalt(options);
+  const fingerprint = getMachineFingerprint();
+  return crypto.pbkdf2Sync(fingerprint, salt, 100_000, 32, 'sha256');
+}
+
+function encryptAes256Gcm(plaintext, aad, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  cipher.setAAD(Buffer.from(aad, 'utf8'));
+  const encrypted = Buffer.concat([cipher.update(Buffer.from(plaintext, 'utf8')), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    iv: iv.toString('hex'),
+    tag: tag.toString('hex'),
+    data: encrypted.toString('hex'),
+  };
+}
+
+function decryptAes256Gcm(payload, aad, key) {
+  if (!payload?.iv || !payload?.tag || !payload?.data) return null;
+  const iv = Buffer.from(payload.iv, 'hex');
+  const tag = Buffer.from(payload.tag, 'hex');
+  const data = Buffer.from(payload.data, 'hex');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAAD(Buffer.from(aad, 'utf8'));
+  decipher.setAuthTag(tag);
+  const decrypted = Buffer.concat([decipher.update(data), decipher.final()]);
+  return decrypted.toString('utf8');
+}
+
+// --------------------------------------------------------------------------
+// OS Credential Store Adapters
+// --------------------------------------------------------------------------
+
+function osStoreReadDarwin(provider) {
+  try {
+    const res = spawnSync('/usr/bin/security', ['find-generic-password', '-a', `agentsam:${provider}`, '-s', 'agentsam', '-w'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (res.status === 0 && res.stdout) {
+      const val = res.stdout.trim();
+      if (val) return val;
+    }
+  } catch { /* fallback to local encrypted store */ }
+  return null;
+}
+
+function osStoreWriteDarwin(provider, secret) {
+  try {
+    const res = spawnSync('/usr/bin/security', ['add-generic-password', '-a', `agentsam:${provider}`, '-s', 'agentsam', '-w', secret, '-U'], {
+      stdio: 'ignore',
+    });
+    return res.status === 0;
+  } catch { return false; }
+}
+
+function osStoreDeleteDarwin(provider) {
+  try {
+    const res = spawnSync('/usr/bin/security', ['delete-generic-password', '-a', `agentsam:${provider}`, '-s', 'agentsam'], {
+      stdio: 'ignore',
+    });
+    return res.status === 0;
+  } catch { return false; }
+}
+
+function osStoreReadWin32(provider, options = {}) {
+  const file = path.join(localVaultDirectory(options), `${provider}.dpapi`);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const script = `
+$bytes = [System.IO.File]::ReadAllBytes('${file.replace(/'/g, "''")}');
+$dec = [System.Security.Cryptography.ProtectedData]::Unprotect($bytes, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser);
+[System.Text.Encoding]::UTF8.GetString($dec);
+`;
+    const res = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (res.status === 0 && res.stdout) {
+      const val = res.stdout.trim();
+      if (val) return val;
+    }
+  } catch { /* fallback */ }
+  return null;
+}
+
+function osStoreWriteWin32(provider, secret, options = {}) {
+  ensureVaultDirectory(options);
+  const file = path.join(localVaultDirectory(options), `${provider}.dpapi`);
+  try {
+    const b64 = Buffer.from(secret, 'utf8').toString('base64');
+    const script = `
+$bytes = [System.Convert]::FromBase64String('${b64}');
+$enc = [System.Security.Cryptography.ProtectedData]::Protect($bytes, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser);
+[System.IO.File]::WriteAllBytes('${file.replace(/'/g, "''")}', $enc);
+`;
+    const res = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+      stdio: 'ignore',
+    });
+    return res.status === 0;
+  } catch { return false; }
+}
+
+function osStoreDeleteWin32(provider, options = {}) {
+  const file = path.join(localVaultDirectory(options), `${provider}.dpapi`);
+  if (fs.existsSync(file)) {
+    try { fs.unlinkSync(file); return true; } catch { return false; }
+  }
+  return false;
+}
+
+function osStoreReadLinux(provider) {
+  try {
+    const res = spawnSync('secret-tool', ['lookup', 'service', 'agentsam', 'provider', provider], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (res.status === 0 && res.stdout) {
+      const val = res.stdout.trim();
+      if (val) return val;
+    }
+  } catch { /* fallback */ }
+  return null;
+}
+
+function osStoreWriteLinux(provider, secret) {
+  try {
+    const res = spawnSync('secret-tool', ['store', `--label=AgentSam ${provider}`, 'service', 'agentsam', 'provider', provider], {
+      input: secret,
+      encoding: 'utf8',
+      stdio: ['pipe', 'ignore', 'ignore'],
+    });
+    return res.status === 0;
+  } catch { return false; }
+}
+
+function osStoreDeleteLinux(provider) {
+  try {
+    const res = spawnSync('secret-tool', ['clear', 'service', 'agentsam', 'provider', provider], {
+      stdio: 'ignore',
+    });
+    return res.status === 0;
+  } catch { return false; }
+}
+
+// --------------------------------------------------------------------------
+// Encrypted Local File Store (AES-256-GCM)
+// --------------------------------------------------------------------------
+
+function readEncryptedStore(options = {}) {
+  const encFile = localVaultPath(options);
+  if (!fs.existsSync(encFile)) return { version: 1, secrets: {} };
+  try {
+    const content = fs.readFileSync(encFile, 'utf8');
+    const parsed = JSON.parse(content);
+    if (parsed && typeof parsed === 'object' && parsed.secrets) return parsed;
+  } catch { /* re-initialize on corrupt file */ }
+  return { version: 1, secrets: {} };
+}
+
+function writeEncryptedStore(store, options = {}) {
+  ensureVaultDirectory(options);
+  const encFile = localVaultPath(options);
+  const tempFile = `${encFile}.${process.pid}.${Date.now()}.tmp`;
+  const json = JSON.stringify({
+    version: 1,
+    updated_at: new Date().toISOString(),
+    secrets: store.secrets || {},
+  }, null, 2);
+
+  fs.writeFileSync(tempFile, json, { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(tempFile, 0o600); } catch { /* ignore */ }
+  }
+  fs.renameSync(tempFile, encFile);
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(encFile, 0o600); } catch { /* ignore */ }
+  }
+}
+
+// --------------------------------------------------------------------------
+// Public API
+// --------------------------------------------------------------------------
+
+/**
+ * Retrieve a provider credential from OS keychain or local AES-256-GCM vault.
+ * Returns { value: string, accountId?: string, source: string } or null.
+ */
+export function getSecureProviderKey(provider, options = {}) {
+  const id = normalizeProviderId(provider);
+  if (!id) return null;
+
+  // 1. Try OS Credential Store if enabled/available
+  if (options.disableOsStore !== true) {
+    let osSecret = null;
+    if (process.platform === 'darwin') {
+      osSecret = osStoreReadDarwin(id);
+    } else if (process.platform === 'win32') {
+      osSecret = osStoreReadWin32(id, options);
+    } else if (process.platform === 'linux') {
+      osSecret = osStoreReadLinux(id);
+    }
+    if (osSecret) {
+      try {
+        const parsed = JSON.parse(osSecret);
+        if (parsed && typeof parsed === 'object' && parsed.value) {
+          return { value: parsed.value, accountId: parsed.accountId || null, source: 'os_keychain' };
+        }
+      } catch {
+        return { value: osSecret, accountId: null, source: 'os_keychain' };
+      }
+    }
+  }
+
+  // 2. Encrypted Local Store (AES-256-GCM)
+  try {
+    const store = readEncryptedStore(options);
+    const entry = store.secrets?.[id];
+    if (!entry) return null;
+
+    const key = deriveKey(options);
+    const plaintext = decryptAes256Gcm(entry, `provider:${id}`, key);
+    if (!plaintext) return null;
+
+    try {
+      const parsed = JSON.parse(plaintext);
+      if (parsed && typeof parsed === 'object' && parsed.value) {
+        return { value: parsed.value, accountId: parsed.accountId || null, source: 'local_vault' };
+      }
+    } catch {
+      return { value: plaintext, accountId: null, source: 'local_vault' };
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Store a provider credential into OS keychain and local AES-256-GCM vault.
+ */
+export function setSecureProviderKey(provider, credential, options = {}) {
+  const id = normalizeProviderId(provider);
+  if (!id) throw new Error('provider_required');
+
+  let value = '';
+  let accountId = null;
+  if (typeof credential === 'object' && credential !== null) {
+    value = String(credential.value || credential.secret || '').trim();
+    accountId = credential.accountId ? String(credential.accountId).trim() : null;
+  } else {
+    value = String(credential || '').trim();
+    if (options.accountId) accountId = String(options.accountId).trim();
+  }
+
+  if (!value) throw new Error('credential_value_required');
+
+  const payloadString = JSON.stringify({ value, accountId });
+
+  // 1. Mirror into OS Credential Store (best-effort)
+  let osStoreSuccess = false;
+  if (options.disableOsStore !== true) {
+    if (process.platform === 'darwin') {
+      osStoreSuccess = osStoreWriteDarwin(id, payloadString);
+    } else if (process.platform === 'win32') {
+      osStoreSuccess = osStoreWriteWin32(id, payloadString, options);
+    } else if (process.platform === 'linux') {
+      osStoreSuccess = osStoreWriteLinux(id, payloadString);
+    }
+  }
+
+  // 2. Encrypt with AES-256-GCM into local store
+  const key = deriveKey(options);
+  const encrypted = encryptAes256Gcm(payloadString, `provider:${id}`, key);
+
+  const store = readEncryptedStore(options);
+  store.secrets[id] = {
+    ...encrypted,
+    updated_at: new Date().toISOString(),
+  };
+  writeEncryptedStore(store, options);
+
+  return {
+    provider: id,
+    stored: true,
+    os_keychain: osStoreSuccess,
+    local_vault: true,
+  };
+}
+
+/**
+ * Delete a provider credential from OS keychain and local AES-256-GCM vault.
+ */
+export function deleteSecureProviderKey(provider, options = {}) {
+  const id = normalizeProviderId(provider);
+  if (!id) return false;
+
+  if (options.disableOsStore !== true) {
+    if (process.platform === 'darwin') osStoreDeleteDarwin(id);
+    else if (process.platform === 'win32') osStoreDeleteWin32(id, options);
+    else if (process.platform === 'linux') osStoreDeleteLinux(id);
+  }
+
+  const store = readEncryptedStore(options);
+  if (store.secrets?.[id]) {
+    delete store.secrets[id];
+    writeEncryptedStore(store, options);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * List all providers that currently have credentials in the secure local vault.
+ */
+export function listSecureConfiguredProviders(options = {}) {
+  const store = readEncryptedStore(options);
+  return Object.keys(store.secrets || {});
+}
+
+/**
+ * Hydrates environment variables from the secure vault for any unconfigured providers.
+ * Loads into `env` (defaults to process.env).
+ */
+export function hydrateSecureCredentials(env = process.env, options = {}) {
+  const hydrated = [];
+  for (const [providerId, spec] of Object.entries(PROVIDER_CREDENTIALS)) {
+    if (env[spec.env]) continue;
+    try {
+      const cred = getSecureProviderKey(providerId, options);
+      if (cred?.value) {
+        env[spec.env] = cred.value;
+        if (providerId === 'cloudflare' && cred.accountId) {
+          if (!env.CLOUDFLARE_ACCOUNT_ID) env.CLOUDFLARE_ACCOUNT_ID = cred.accountId;
+        }
+        hydrated.push(providerId);
+      }
+    } catch {
+      // best-effort
+    }
+  }
+  return hydrated;
+}

package/src/security/process.js

@@ -1,13 +1,29 @@
 import { spawn } from 'node:child_process';
 import { createProcessDiagnosticError } from '../errors/index.js';
 
-export function runProcess(command, args, { cwd, timeoutMs = 300_000, signal, env = process.env, maxBytes = 8 * 1024 * 1024 } = {}) {
+export function resolveExecutableCommand(command, platform = process.platform) {
+  if (platform !== 'win32' || !command) return { command: String(command || ''), shell: false };
+  const str = String(command).trim();
+  const lower = str.toLowerCase();
+  if (lower === 'npx') return { command: 'npx.cmd', shell: true };
+  if (lower === 'npm') return { command: 'npm.cmd', shell: true };
+  if (lower === 'wrangler') return { command: 'wrangler.cmd', shell: true };
+  if (lower === 'pnpm') return { command: 'pnpm.cmd', shell: true };
+  if (lower === 'yarn') return { command: 'yarn.cmd', shell: true };
+  if (lower.endsWith('.cmd') || lower.endsWith('.bat')) return { command: str, shell: true };
+  return { command: str, shell: false };
+}
+
+export function runProcess(command, args, { cwd, timeoutMs = 300_000, signal, env = process.env, maxBytes = 8 * 1024 * 1024, shell } = {}) {
   return new Promise((resolve, reject) => {
     const safeArgs = Array.isArray(args) ? args : [];
+    const resolved = resolveExecutableCommand(command);
+    const useShell = shell ?? resolved.shell;
+    const finalCommand = resolved.command;
     const diagnostic = (code, message, extra = {}) => createProcessDiagnosticError({
       code,
       message,
-      command,
+      command: finalCommand,
       args: safeArgs,
       cwd,
       stdout,
@@ -15,8 +31,8 @@ export function runProcess(command, args, { cwd, timeoutMs = 300_000, signal, en
       ...extra,
     });
     let stdout = '', stderr = '', size = 0, failure, hardKill;
-    if (signal?.aborted) return reject(createProcessDiagnosticError({ code: 'process_cancelled', message: 'Command cancelled', command, args: safeArgs, cwd }));
-    const child = spawn(command, safeArgs, { cwd, env, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
+    if (signal?.aborted) return reject(createProcessDiagnosticError({ code: 'process_cancelled', message: 'Command cancelled', command: finalCommand, args: safeArgs, cwd }));
+    const child = spawn(finalCommand, safeArgs, { cwd, env, shell: useShell, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] });
     function kill(sig) {
       try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, sig); } catch { /* already exited */ }
     }

package/src/status/actions.js

@@ -0,0 +1,192 @@
+import pc from 'picocolors';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function healthUrl(status) {
+  return clean(
+    status?.cloudflare?.health?.url ||
+    status?.cloudflare?.contract?.health_url ||
+    status?.local?.live?.url
+  );
+}
+
+function liveAppUrl(status) {
+  const explicit = clean(
+    status?.cloudflare?.public_url ||
+    status?.cloudflare?.contract?.public_url
+  );
+  if (explicit) return explicit;
+
+  const health = healthUrl(status);
+  if (!health) return '';
+
+  return health.replace(/\/(?:api\/)?health\/?$/i, '');
+}
+
+export function buildStatusActionPlan(status = {}) {
+  const actions = [];
+  const tips = [];
+  const checks = status.checks || {};
+  const cloudflare = status.cloudflare || {};
+  const liveOk = cloudflare.configured === true && cloudflare.health?.ok === true;
+  const liveHealth = healthUrl(status);
+  const liveApp = liveAppUrl(status);
+  const localApiOnline = status.local?.api?.online === true;
+  const deployTarget = clean(
+    status.local?.deployTarget || status.local?.deploy_target
+  );
+
+  if (!checks.account) {
+    actions.push({
+      id: 'auth_login',
+      label: 'Sign in to IAM',
+      command: 'agentsam login',
+      why: 'Account auth is required for connected models, terminal authority, and deploy receipts.',
+      kind: 'auth',
+    });
+    tips.push('Not signed in — run agentsam login, or use AGENTSAM_API_KEY for headless access.');
+  } else {
+    actions.push({
+      id: 'whoami',
+      label: 'Inspect account / auth source',
+      command: 'agentsam whoami',
+      why: 'See which AgentSam credential is currently authoritative.',
+      kind: 'inspect',
+    });
+  }
+
+  if (cloudflare.configured) {
+    if (liveOk && liveApp) {
+      actions.push({
+        id: 'open_health',
+        label: `Open live app (${liveApp})`,
+        command: liveApp,
+        why: 'Open the healthy deployed project rather than localhost.',
+        kind: 'deploy',
+      });
+    }
+
+    actions.push({
+      id: 'cf_status',
+      label: 'Inspect Cloudflare Worker + bindings',
+      command: 'agentsam cloudflare status',
+      why: 'Inspect the active Worker version, routes, bindings, and deployment evidence.',
+      kind: 'inspect',
+    });
+
+    if (!liveOk) {
+      tips.push(
+        cloudflare.health?.error
+          ? `Live health failed: ${cloudflare.health.error}`
+          : 'Cloudflare deployment is configured but live health is not verified.',
+      );
+      actions.push({
+        id: 'deploy',
+        label: 'Deploy / refresh Cloudflare Worker',
+        command: 'agentsam deploy',
+        why: 'Bring live health and bindings back in sync with this repository.',
+        kind: 'deploy',
+      });
+    } else {
+      tips.push(`Live API healthy · ${liveHealth || cloudflare.worker_name}`);
+    }
+  } else if (deployTarget === 'cloudflare') {
+    tips.push('Cloudflare is the deploy target but its deployment contract is incomplete.');
+    actions.push({
+      id: 'cf_wire',
+      label: 'Inspect Cloudflare deployment contract',
+      command: 'agentsam cloudflare status',
+      why: 'Resolve Worker/config/health URL before recommending localhost.',
+      kind: 'fix',
+    });
+  } else if (!localApiOnline) {
+    tips.push('No live deployment contract is active; localhost is optional.');
+    actions.push({
+      id: 'local_dev',
+      label: 'Start local API',
+      command: 'npm run dev',
+      why: 'Use only for local-first projects without a healthy hosted deployment.',
+      kind: 'local',
+    });
+  }
+
+  if (!checks.models) {
+    actions.push({
+      id: 'models',
+      label: 'Inspect models',
+      command: 'agentsam models',
+      why: 'Inspect account-visible and local models.',
+      kind: 'fix',
+    });
+  }
+
+  if (!checks.terminal) {
+    actions.push({
+      id: 'terminal',
+      label: 'Inspect terminal authority',
+      command: 'agentsam status --json',
+      why: 'Inspect local PTY and enrolled execution connections.',
+      kind: 'inspect',
+    });
+  }
+
+  if (status.local?.db?.ready === false && status.local?.db?.exists === false) {
+    actions.push({
+      id: 'db_init',
+      label: 'Initialize AgentSam SQLite',
+      command: 'agentsam db init',
+      why: 'Initialize the project-local runtime state database.',
+      kind: 'local',
+    });
+  }
+
+  actions.push({
+    id: 'inspect',
+    label: 'Inspect repository',
+    command: 'agentsam inspect',
+    why: 'Capture repository identity and structural evidence.',
+    kind: 'inspect',
+  });
+
+  actions.push({
+    id: 'refresh',
+    label: 'Refresh status',
+    command: 'agentsam status',
+    why: 'Re-probe account, models, terminal, and deployment health.',
+    kind: 'inspect',
+  });
+
+  let headline = 'Project awareness';
+  if (status.ready) headline = liveOk ? 'Live project healthy' : 'Ready';
+  else if (!checks.account) headline = 'Sign in to unlock connected features';
+  else if (cloudflare.configured && !liveOk) headline = 'Deploy / health needs attention';
+  else headline = 'Setup remaining';
+
+  return { headline, tips, actions };
+}
+
+export function formatStatusNextSteps(plan) {
+  const lines = ['', `  ${pc.bold('next')}        ${plan.headline}`];
+
+  for (const tip of plan.tips.slice(0, 4)) {
+    lines.push(`               ${pc.dim('•')} ${tip}`);
+  }
+
+  const primary = plan.actions.filter((action) => action.kind !== 'inspect').slice(0, 3);
+  const inspect = plan.actions.filter((action) => action.kind === 'inspect').slice(0, 2);
+
+  for (const action of [...primary, ...inspect].slice(0, 5)) {
+    const command = action.id === 'open_health'
+      ? `open ${action.command}`
+      : action.command;
+
+    lines.push(`               ${pc.cyan('$')} ${command}`);
+    lines.push(`                 ${pc.dim(action.why)}`);
+  }
+
+  lines.push(`               ${pc.dim('Interactive menu: agentsam status -i')}`);
+
+  return lines.join('\n');
+}

package/src/tools/hydrate.js

@@ -1,12 +1,16 @@
 function clean(value) { return value == null ? '' : String(value).trim(); }
 
+function toolName(tool) {
+  return clean(tool?.toolKey || tool?.tool || tool?.name);
+}
+
 export function hydrateToolSchemas(catalog = [], selected = [], options = {}) {
   if (!Array.isArray(catalog)) throw new TypeError('catalog must be an array');
   if (!Array.isArray(selected)) throw new TypeError('selected must be an array');
   const maxTools = Number.isInteger(options.maxTools) && options.maxTools > 0 ? options.maxTools : 8;
   const maxChars = Number.isInteger(options.maxChars) && options.maxChars > 0 ? options.maxChars : 40_000;
   const wanted = [...new Set(selected.map(clean).filter(Boolean))].slice(0, maxTools);
-  const byName = new Map(catalog.map((tool) => [clean(tool.tool || tool.name), tool]).filter(([name]) => name));
+  const byName = new Map(catalog.map((tool) => [toolName(tool), tool]).filter(([name]) => name));
   const tools = [];
   const missing = [];
   const deferred = [];

package/src/tools/index.js

@@ -1,2 +1,9 @@
 export { searchToolCards, toToolCard } from './search.js';
 export { hydrateToolSchemas } from './hydrate.js';
+export { createToolRegistry } from './registry.js';
+export { createToolExecutor } from './runtime.js';
+export {
+  AGENTSAM_REDACTED_VALUE,
+  receiptPayload,
+  redactToolValue,
+} from './redact.js';