@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/packages/agentsam-hooks/src/adapters/agents.js

@@ -0,0 +1,108 @@
+import { ensureHookRuntime } from '../runtime.js';
+
+function normalizeAgent(value) {
+  const source = typeof value === 'string' ? { id: value } : value;
+  const id = String(source?.id || source?.name || '').trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(id)) throw new Error(`invalid_agent_id:${id || '<missing>'}`);
+  return Object.freeze({
+    id,
+    description: String(source.description || `Delegate bounded work to the ${id} agent.`),
+    metadata: source.metadata && typeof source.metadata === 'object' ? structuredClone(source.metadata) : {},
+  });
+}
+
+export async function runWithSubagentHooks(options = {}) {
+  if (typeof options.run !== 'function') throw new TypeError('subagent_run_required');
+  const agentId = String(options.agentId || options.agent_id || '').trim();
+  if (!agentId) throw new TypeError('subagent_agent_id_required');
+  const task = String(options.task || '').trim();
+  if (!task) throw new TypeError('subagent_task_required');
+
+  const hooks = ensureHookRuntime(options.hooks || options.hookRuntime);
+  const context = options.context && typeof options.context === 'object' ? options.context : {};
+  const invocation = {
+    ...(options.invocation || {}),
+    agent_id: agentId,
+  };
+
+  await hooks.dispatch('subagent_start', {
+    agent_id: agentId,
+    task,
+    context,
+  }, invocation, { cwd: options.cwd });
+
+  try {
+    const result = await options.run({ task, context, invocation });
+    await hooks.dispatch('subagent_stop', {
+      agent_id: agentId,
+      task,
+      status: 'completed',
+      result,
+    }, invocation, { cwd: options.cwd });
+    return result;
+  } catch (error) {
+    await hooks.dispatch('subagent_stop', {
+      agent_id: agentId,
+      task,
+      status: 'failed',
+      error: { code: error?.code || null, message: String(error?.message || error) },
+    }, invocation, { cwd: options.cwd });
+    throw error;
+  }
+}
+
+export function createAgentCapabilityAdapter(options = {}) {
+  if (typeof options.runAgent !== 'function') throw new TypeError('run_agent_adapter_required');
+  const agents = (options.agents || []).map(normalizeAgent);
+  const hooks = ensureHookRuntime(options.hooks || options.hookRuntime);
+  const byCapability = new Map(agents.map((agent) => [`agent.delegate.${agent.id}`, agent]));
+  const parentInvocation = options.invocation || {};
+
+  return Object.freeze({
+    toolDescriptors() {
+      return [...byCapability].map(([name, agent]) => Object.freeze({
+        name,
+        description: agent.description,
+        category: 'agents',
+        risk: 'write',
+        strict: false,
+        input_schema: {
+          type: 'object',
+          properties: {
+            task: { type: 'string', minLength: 1, description: 'Bounded objective delegated to the sub-agent.' },
+            context: { type: 'object', description: 'Portable context references or structured evidence for the task.' },
+          },
+          required: ['task'],
+          additionalProperties: false,
+        },
+      }));
+    },
+    canInvoke(id) { return byCapability.has(String(id)); },
+    async invoke(id, input = {}, context = {}) {
+      const agent = byCapability.get(String(id));
+      if (!agent) throw new Error(`agent_capability_unavailable:${id}`);
+      const task = String(input.task || '').trim();
+      if (!task) throw new TypeError('subagent_task_required');
+      const agentInvocation = {
+        ...parentInvocation,
+        parent_agent_id: parentInvocation.agent_id || null,
+        agent_id: agent.id,
+      };
+      return runWithSubagentHooks({
+        hookRuntime: hooks,
+        agentId: agent.id,
+        task,
+        context: input.context || {},
+        invocation: agentInvocation,
+        cwd: context.cwd || options.cwd,
+        run: () => options.runAgent({
+          agent,
+          task,
+          context: input.context || {},
+          parent: context,
+          invocation: agentInvocation,
+        }),
+      });
+    },
+  });
+}

package/packages/agentsam-hooks/src/adapters/callback.js

@@ -0,0 +1,4 @@
+export function createCallbackHookAdapter(handler) {
+  if (typeof handler !== 'function') throw new TypeError('callback_hook_handler_required');
+  return async (envelope) => handler(envelope.input, envelope.invocation, envelope);
+}

package/packages/agentsam-hooks/src/adapters/capability.js

@@ -0,0 +1,122 @@
+import { ensureHookRuntime } from '../runtime.js';
+import { resolveHookPermission } from '../policy.js';
+
+const HOOKED_CAPABILITY_ADAPTER = Symbol.for('agentsam.hooks.capability-adapter');
+
+function serializedError(error) {
+  return Object.freeze({
+    name: error?.name || 'Error',
+    code: error?.code || null,
+    message: String(error?.message || error),
+    status: Number.isFinite(Number(error?.status)) ? Number(error.status) : null,
+  });
+}
+
+export function createHookedCapabilityAdapter(baseAdapter, options = {}) {
+  if (!baseAdapter?.toolDescriptors || !baseAdapter?.invoke) throw new TypeError('base_capability_adapter_required');
+  if (baseAdapter[HOOKED_CAPABILITY_ADAPTER]) return baseAdapter;
+  const hooks = ensureHookRuntime(options.hooks || options.hookRuntime);
+  const invocation = options.invocation || {};
+  const cwd = options.cwd;
+  const maxRetries = Number.isInteger(options.maxRetries) ? Math.max(0, Math.min(options.maxRetries, 10)) : 3;
+
+  const adapter = {
+    ...baseAdapter,
+    [HOOKED_CAPABILITY_ADAPTER]: true,
+    toolDescriptors(descriptorOptions = {}) { return baseAdapter.toolDescriptors(descriptorOptions); },
+    canInvoke(id) { return typeof baseAdapter.canInvoke === 'function' ? baseAdapter.canInvoke(id) : true; },
+    describe(id) { return typeof baseAdapter.describe === 'function' ? baseAdapter.describe(id) : undefined; },
+    list(listOptions = {}) { return typeof baseAdapter.list === 'function' ? baseAdapter.list(listOptions) : this.toolDescriptors(listOptions); },
+    async invoke(id, input = {}, context = {}) {
+      const toolName = String(id);
+      const pre = await hooks.dispatch('pre_tool_use', {
+        tool_name: toolName,
+        tool_args: input,
+        cwd: cwd || context.cwd,
+      }, invocation, { cwd: cwd || context.cwd });
+      await resolveHookPermission({
+        output: pre.output,
+        kind: 'tool',
+        name: toolName,
+        requestPermission: options.requestPermission,
+        envelope: pre,
+      });
+      const args = pre.input.tool_args;
+      const hookContext = pre.output.additional_context;
+      let retriesRemaining = maxRetries;
+
+      let value;
+      while (true) {
+        try {
+          value = await baseAdapter.invoke(toolName, args, {
+            ...context,
+            ...(hookContext ? { hook_context: hookContext } : {}),
+          });
+          break;
+        } catch (error) {
+          const failed = await hooks.dispatch('post_tool_use_failure', {
+            tool_name: toolName,
+            tool_args: args,
+            error: serializedError(error),
+            cwd: cwd || context.cwd,
+          }, invocation, { cwd: cwd || context.cwd });
+          if (failed.output.additional_context) error.hook_context = failed.output.additional_context;
+          const occurred = await hooks.dispatch('error_occurred', {
+            error: String(error?.message || error),
+            error_context: 'tool_execution',
+            recoverable: error?.recoverable !== false,
+            tool_name: toolName,
+            cwd: cwd || context.cwd,
+          }, invocation, { cwd: cwd || context.cwd });
+          const handling = occurred.output.error_handling;
+          const requestedRetries = Math.min(Number(occurred.output.retry_count || 1), maxRetries);
+          if (handling === 'retry' && retriesRemaining > 0 && requestedRetries > 0) {
+            retriesRemaining -= 1;
+            continue;
+          }
+          if (handling === 'skip') {
+            return Object.freeze({
+              schema: 'agentsam.hook.skipped.v1',
+              skipped: true,
+              kind: 'tool_error',
+              tool_name: toolName,
+              error: serializedError(error),
+              notification: occurred.output.user_notification || null,
+            });
+          }
+          if (occurred.output.additional_context) error.hook_context = [error.hook_context, occurred.output.additional_context].filter(Boolean).join('\n\n');
+          if (occurred.output.user_notification) error.user_notification = occurred.output.user_notification;
+          if (occurred.output.suppress_output === true) error.suppress_output = true;
+          throw error;
+        }
+      }
+
+      // Post-hook failures happen after the tool may have produced side effects.
+      // Never feed those failures into the tool retry policy.
+      const post = await hooks.dispatch('post_tool_use', {
+        tool_name: toolName,
+        tool_args: args,
+        tool_result: value,
+        cwd: cwd || context.cwd,
+      }, invocation, { cwd: cwd || context.cwd });
+      if (post.output.suppress_output === true) {
+        return Object.freeze({
+          schema: 'agentsam.hook.suppressed.v1',
+          suppressed: true,
+          kind: 'tool_result',
+          tool_name: toolName,
+        });
+      }
+      const contexts = [hookContext, post.output.additional_context].filter(Boolean);
+      if (contexts.length) {
+        return Object.freeze({
+          schema: 'agentsam.hook.contextualized-tool-result.v1',
+          result: post.input.tool_result,
+          additional_context: contexts.join('\n\n'),
+        });
+      }
+      return post.input.tool_result;
+    },
+  };
+  return Object.freeze(adapter);
+}

package/packages/agentsam-hooks/src/adapters/command.js

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process';
+
+const PORTABLE_ENV_KEYS = Object.freeze([
+  'PATH', 'Path', 'PATHEXT', 'SYSTEMROOT', 'WINDIR',
+  'HOME', 'USERPROFILE', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL',
+]);
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function portableEnvironment(extra = {}, inheritEnvironment = false) {
+  const environment = {};
+  const source = typeof process === 'undefined' ? {} : process.env;
+  if (inheritEnvironment) Object.assign(environment, source);
+  else for (const key of PORTABLE_ENV_KEYS) if (source[key] != null) environment[key] = source[key];
+  for (const [key, value] of Object.entries(extra || {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`invalid_hook_environment_key:${key}`);
+    if (value != null) environment[key] = String(value);
+  }
+  return environment;
+}
+
+function parseOutput(stdout, command) {
+  const text = stdout.trim();
+  if (!text) return null;
+  const lines = text.split(/\r?\n/).filter(Boolean);
+  try { return JSON.parse(lines.at(-1)); }
+  catch (error) {
+    const failure = new Error(`hook_command_invalid_json:${command}:${error.message}`);
+    failure.code = 'AGENTSAM_HOOK_INVALID_OUTPUT';
+    failure.adapter = 'command';
+    failure.protocol = 'agentsam.hook.v1';
+    failure.transport = 'process';
+    throw failure;
+  }
+}
+
+export function createCommandHookAdapter(options = {}) {
+  const command = clean(options.command);
+  if (!command) throw new TypeError('hook_command_required');
+  const args = Array.isArray(options.args) ? options.args.map(String) : [];
+  const timeoutMs = Number(options.timeout_ms ?? options.timeoutMs ?? 10_000);
+  const maxOutputBytes = Number(options.max_output_bytes ?? options.maxOutputBytes ?? 1_048_576);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600_000) throw new RangeError('invalid_hook_command_timeout');
+  if (!Number.isInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 16_777_216) throw new RangeError('invalid_hook_command_output_limit');
+
+  return (envelope) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || envelope.cwd,
+      env: portableEnvironment(options.env, options.inherit_environment === true || options.inheritEnvironment === true),
+      shell: false,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let outputBytes = 0;
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      callback(value);
+    };
+    const fail = (message, code = 'AGENTSAM_HOOK_COMMAND_FAILED') => {
+      const error = new Error(message);
+      error.code = code;
+      error.adapter = 'command';
+      error.protocol = 'agentsam.hook.v1';
+      error.transport = 'process';
+      finish(reject, error);
+    };
+    const append = (target, chunk) => {
+      outputBytes += chunk.length;
+      if (outputBytes > maxOutputBytes) {
+        child.kill('SIGKILL');
+        fail(`hook_command_output_limit_exceeded:${command}:${maxOutputBytes}`, 'AGENTSAM_HOOK_OUTPUT_LIMIT');
+        return target;
+      }
+      return target + chunk.toString('utf8');
+    };
+    child.stdout.on('data', (chunk) => { stdout = append(stdout, chunk); });
+    child.stderr.on('data', (chunk) => { stderr = append(stderr, chunk); });
+    child.on('error', (error) => fail(`hook_command_spawn_failed:${command}:${error.message}`));
+    child.on('close', (code, signal) => {
+      if (settled) return;
+      if (code !== 0) {
+        fail(`hook_command_failed:${command}:exit=${code ?? 'null'}:signal=${signal || 'none'}:${stderr.trim().slice(0, 512)}`);
+        return;
+      }
+      try { finish(resolve, parseOutput(stdout, command)); }
+      catch (error) { finish(reject, error); }
+    });
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      const killTimer = setTimeout(() => child.kill('SIGKILL'), 250);
+      killTimer.unref?.();
+      fail(`hook_command_timeout:${command}:${timeoutMs}`, 'AGENTSAM_HOOK_TIMEOUT');
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdin.end(`${JSON.stringify(envelope)}\n`);
+  });
+}

package/packages/agentsam-hooks/src/adapters/composite.js

@@ -0,0 +1,31 @@
+export function createCompositeCapabilityAdapter(adapters = []) {
+  const active = adapters.filter(Boolean);
+  if (!active.length || active.some((adapter) => !adapter?.toolDescriptors || !adapter?.invoke)) {
+    throw new TypeError('composite_capability_adapters_required');
+  }
+
+  function catalog(options = {}) {
+    const byName = new Map();
+    for (const adapter of active) {
+      for (const descriptor of adapter.toolDescriptors(options)) {
+        if (byName.has(descriptor.name)) throw new Error(`duplicate_capability_descriptor:${descriptor.name}`);
+        byName.set(descriptor.name, { descriptor, adapter });
+      }
+    }
+    return byName;
+  }
+
+  return Object.freeze({
+    toolDescriptors(options = {}) { return [...catalog(options).values()].map((row) => row.descriptor); },
+    canInvoke(id) {
+      return active.some((adapter) => typeof adapter.canInvoke === 'function'
+        ? adapter.canInvoke(id)
+        : adapter.toolDescriptors().some((row) => row.name === id));
+    },
+    async invoke(id, input = {}, context = {}) {
+      const row = catalog().get(String(id));
+      if (!row) throw new Error(`capability_handler_unavailable:${id}`);
+      return row.adapter.invoke(id, input, context);
+    },
+  });
+}

package/packages/agentsam-hooks/src/adapters/http.js

@@ -0,0 +1,58 @@
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function safeUrl(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error(`unsupported_hook_http_protocol:${url.protocol}`);
+  if (url.username || url.password) throw new Error('hook_http_url_must_not_contain_credentials');
+  return url;
+}
+
+export function createHttpHookAdapter(options = {}) {
+  const url = safeUrl(clean(options.url));
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') throw new TypeError('hook_http_fetch_required');
+  const timeoutMs = Number(options.timeout_ms ?? options.timeoutMs ?? 10_000);
+  const maxResponseBytes = Number(options.max_response_bytes ?? options.maxResponseBytes ?? 1_048_576);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600_000) throw new RangeError('invalid_hook_http_timeout');
+  if (!Number.isInteger(maxResponseBytes) || maxResponseBytes < 1 || maxResponseBytes > 16_777_216) throw new RangeError('invalid_hook_http_response_limit');
+  const configuredHeaders = Object.fromEntries(Object.entries(options.headers || {}).map(([key, value]) => [key, String(value)]));
+
+  return async (envelope) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`hook_http_timeout:${timeoutMs}`)), timeoutMs);
+    try {
+      const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: { accept: 'application/json', 'content-type': 'application/json', ...configuredHeaders },
+        body: JSON.stringify(envelope),
+        signal: controller.signal,
+      });
+      const length = Number(response.headers?.get?.('content-length') || 0);
+      if (length > maxResponseBytes) throw new Error(`hook_http_response_limit_exceeded:${maxResponseBytes}`);
+      const text = await response.text();
+      if (new TextEncoder().encode(text).byteLength > maxResponseBytes) throw new Error(`hook_http_response_limit_exceeded:${maxResponseBytes}`);
+      if (!response.ok) {
+        const error = new Error(`hook_http_failed:${response.status}:${text.slice(0, 512)}`);
+        error.status = response.status;
+        error.code = 'AGENTSAM_HOOK_HTTP_FAILED';
+        throw error;
+      }
+      if (!text.trim()) return null;
+      try { return JSON.parse(text); }
+      catch (error) {
+        const invalid = new Error(`hook_http_invalid_json:${error.message}`);
+        invalid.code = 'AGENTSAM_HOOK_INVALID_OUTPUT';
+        throw invalid;
+      }
+    } catch (error) {
+      error.adapter = 'http';
+      error.protocol = 'http';
+      error.transport = url.protocol.slice(0, -1);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}

package/packages/agentsam-hooks/src/adapters/lsp.js

@@ -0,0 +1,116 @@
+const LSP_TOOLS = Object.freeze([
+  {
+    name: 'lsp.hover',
+    method: 'textDocument/hover',
+    description: 'Read type, symbol, and documentation information at a source position.',
+    required: ['document_uri', 'line', 'character'],
+  },
+  {
+    name: 'lsp.definition',
+    method: 'textDocument/definition',
+    description: 'Find the definition locations for a symbol at a source position.',
+    required: ['document_uri', 'line', 'character'],
+  },
+  {
+    name: 'lsp.references',
+    method: 'textDocument/references',
+    description: 'Find source references for a symbol at a source position.',
+    required: ['document_uri', 'line', 'character'],
+  },
+  {
+    name: 'lsp.symbols',
+    method: 'textDocument/documentSymbol',
+    description: 'List the structural symbols in a source document.',
+    required: ['document_uri'],
+  },
+  {
+    name: 'lsp.diagnostics',
+    method: 'textDocument/diagnostic',
+    description: 'Request current diagnostics for a source document.',
+    required: ['document_uri'],
+  },
+]);
+
+function descriptor(tool, languages) {
+  const properties = {
+    language: {
+      type: 'string',
+      description: 'Configured language-server key.',
+      ...(languages.length ? { enum: languages } : {}),
+    },
+    document_uri: { type: 'string', description: 'Absolute file URI for the source document.' },
+    line: { type: 'integer', minimum: 0 },
+    character: { type: 'integer', minimum: 0 },
+    include_declaration: { type: 'boolean' },
+    previous_result_id: { type: 'string' },
+  };
+  return Object.freeze({
+    name: tool.name,
+    description: tool.description,
+    category: 'lsp',
+    risk: 'read',
+    strict: true,
+    protocol: 'lsp',
+    input_schema: {
+      type: 'object',
+      properties,
+      required: ['language', ...tool.required],
+      additionalProperties: false,
+    },
+  });
+}
+
+function paramsFor(tool, input) {
+  const textDocument = { uri: input.document_uri };
+  if (tool.method === 'textDocument/documentSymbol') return { textDocument };
+  if (tool.method === 'textDocument/diagnostic') return { textDocument, ...(input.previous_result_id ? { previousResultId: input.previous_result_id } : {}) };
+  const position = { line: input.line, character: input.character };
+  if (tool.method === 'textDocument/references') {
+    return { textDocument, position, context: { includeDeclaration: input.include_declaration !== false } };
+  }
+  return { textDocument, position };
+}
+
+function annotateLspFailure(value, server) {
+  const error = value && typeof value === 'object' ? value : new Error(String(value || 'LSP request failed'));
+  const message = String(error?.message || error || '').toLowerCase();
+  if (!error.reason) {
+    error.reason = /timeout|timed out|deadline/.test(message)
+      ? 'lsp_timeout'
+      : /unavailable|not running|econnrefused|enoent/.test(message)
+        ? 'lsp_server_unavailable'
+        : /connection|transport|socket|stdio/.test(message)
+          ? 'lsp_transport_failed'
+          : 'lsp_request_failed';
+  }
+  error.adapter = error.adapter || 'lsp';
+  error.protocol = error.protocol || 'lsp';
+  error.transport = error.transport || server?.transport || (server?.command ? 'stdio' : null);
+  return error;
+}
+
+export function createLspCapabilityAdapter(options = {}) {
+  if (typeof options.request !== 'function') throw new TypeError('lsp_request_adapter_required');
+  const languages = Object.keys(options.languages || {}).sort();
+  const byName = new Map(LSP_TOOLS.map((tool) => [tool.name, tool]));
+  return Object.freeze({
+    toolDescriptors() { return LSP_TOOLS.map((tool) => descriptor(tool, languages)); },
+    canInvoke(id) { return byName.has(String(id)); },
+    async invoke(id, input = {}, context = {}) {
+      const tool = byName.get(String(id));
+      if (!tool) throw new Error(`lsp_capability_unavailable:${id}`);
+      const language = String(input.language || '').trim();
+      if (!language) throw new TypeError('lsp_language_required');
+      if (languages.length && !Object.hasOwn(options.languages, language)) throw new Error(`lsp_language_not_configured:${language}`);
+      const server = options.languages?.[language] || null;
+      try {
+        return await options.request(language, tool.method, paramsFor(tool, input), {
+          ...context,
+          server,
+        });
+      } catch (error) {
+        throw annotateLspFailure(error, server);
+      }
+    },
+  });
+}

package/packages/agentsam-hooks/src/adapters/mcp.js

@@ -0,0 +1,76 @@
+function cleanName(value, label) {
+  const normalized = String(value || '').trim();
+  if (!normalized || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(normalized)) throw new Error(`invalid_${label}:${normalized || '<missing>'}`);
+  return normalized;
+}
+
+function toolRows(value) {
+  return Array.isArray(value) ? value : Array.isArray(value?.tools) ? value.tools : [];
+}
+
+function annotateMcpFailure(value, server) {
+  const error = value && typeof value === 'object' ? value : new Error(String(value || 'MCP call failed'));
+  const message = String(error?.message || error || '').toLowerCase();
+  if (!error.reason) {
+    error.reason = /timeout|timed out|deadline/.test(message)
+      ? 'mcp_timeout'
+      : /unavailable|not running|econnrefused|enoent/.test(message)
+        ? 'mcp_server_unavailable'
+        : /connection|transport|socket|stdio|http|sse/.test(message)
+          ? 'mcp_transport_failed'
+          : 'mcp_call_failed';
+  }
+  error.adapter = error.adapter || 'mcp';
+  error.protocol = error.protocol || 'mcp';
+  error.transport = error.transport || server?.transport || null;
+  return error;
+}
+
+export async function createMcpCapabilityAdapter(options = {}) {
+  const servers = options.servers || {};
+  const listTools = options.listTools;
+  const callTool = options.callTool;
+  if (typeof callTool !== 'function') throw new TypeError('mcp_call_tool_adapter_required');
+  const tools = new Map();
+
+  for (const [rawServerName, configValue] of Object.entries(servers)) {
+    const serverName = cleanName(rawServerName, 'mcp_server_name');
+    const config = configValue || {};
+    const discovered = config.tools || (typeof listTools === 'function' ? await listTools(serverName, config) : []);
+    for (const tool of toolRows(discovered)) {
+      const toolName = cleanName(tool.name, 'mcp_tool_name');
+      const capabilityId = `mcp.${serverName}.${toolName}`;
+      if (tools.has(capabilityId)) throw new Error(`duplicate_mcp_capability:${capabilityId}`);
+      tools.set(capabilityId, Object.freeze({
+        server_name: serverName,
+        tool_name: toolName,
+        server_config: config,
+        descriptor: Object.freeze({
+          name: capabilityId,
+          description: String(tool.description || `Call ${toolName} on MCP server ${serverName}`),
+          category: 'mcp',
+          risk: tool.annotations?.readOnlyHint === true ? 'read' : (tool.risk || 'write'),
+          input_schema: tool.inputSchema || tool.input_schema || { type: 'object', properties: {}, additionalProperties: true },
+          strict: false,
+          protocol: 'mcp',
+          remote_name: toolName,
+          server_name: serverName,
+        }),
+      }));
+    }
+  }
+
+  return Object.freeze({
+    toolDescriptors() { return [...tools.values()].map((row) => row.descriptor); },
+    canInvoke(id) { return tools.has(String(id)); },
+    async invoke(id, input = {}, context = {}) {
+      const row = tools.get(String(id));
+      if (!row) throw new Error(`mcp_capability_unavailable:${id}`);
+      try {
+        return await callTool(row.server_name, row.tool_name, input, { ...context, server: row.server_config });
+      } catch (error) {
+        throw annotateMcpFailure(error, row.server_config);
+      }
+    },
+  });
+}