@contractspec/lib.ai-agent 3.0.0 → 3.1.1

package/dist/node/exporters/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/exporters/opencode-exporter.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/interop/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/interop/spec-consumer.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/providers/claude-agent-sdk/adapter.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/providers/claude-agent-sdk/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/providers/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/providers/opencode-sdk/adapter.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/providers/opencode-sdk/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/spec/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/spec/spec.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/node/tools/index.js

@@ -2263,21 +2263,39 @@ var init_json_schema_to_zod = () => {};
 // src/tools/tool-adapter.ts
 import { tool } from "ai";
 function specToolToAISDKTool(specTool, handler, context = {}) {
+  let lastInvocationAt;
   return tool({
     description: specTool.description ?? specTool.name,
     inputSchema: jsonSchemaToZodSafe(specTool.schema),
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
     execute: async (input) => {
-      const result = await handler(input, {
-        agentId: context.agentId ?? "unknown",
-        sessionId: context.sessionId ?? "unknown",
-        tenantId: context.tenantId,
-        actorId: context.actorId,
-        locale: context.locale,
-        metadata: context.metadata,
-        signal: context.signal
-      });
-      return typeof result === "string" ? result : JSON.stringify(result);
+      const now = Date.now();
+      const cooldownMs = normalizeDuration(specTool.cooldownMs);
+      if (cooldownMs && lastInvocationAt !== undefined) {
+        const elapsed = now - lastInvocationAt;
+        if (elapsed < cooldownMs) {
+          const retryAfterMs = cooldownMs - elapsed;
+          throw createToolExecutionError(`Tool "${specTool.name}" is cooling down. Retry in ${retryAfterMs}ms.`, "TOOL_COOLDOWN_ACTIVE", retryAfterMs);
+        }
+      }
+      const timeoutMs = normalizeDuration(specTool.timeoutMs);
+      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      try {
+        const execution = handler(input, {
+          agentId: context.agentId ?? "unknown",
+          sessionId: context.sessionId ?? "unknown",
+          tenantId: context.tenantId,
+          actorId: context.actorId,
+          locale: context.locale,
+          metadata: context.metadata,
+          signal
+        });
+        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
+        return typeof result === "string" ? result : JSON.stringify(result);
+      } finally {
+        dispose();
+        lastInvocationAt = Date.now();
+      }
     }
   });
 }
@@ -2302,6 +2320,64 @@ function createToolHandler(handler) {
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function normalizeDuration(value) {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isFinite(value)) {
+    return;
+  }
+  if (value <= 0) {
+    return;
+  }
+  return Math.round(value);
+}
+function withTimeout(execution, timeoutMs, toolName) {
+  return new Promise((resolve, reject) => {
+    const timeoutHandle = setTimeout(() => {
+      reject(createToolExecutionError(`Tool "${toolName}" timed out after ${timeoutMs}ms.`, "TOOL_EXECUTION_TIMEOUT"));
+    }, timeoutMs);
+    execution.then((result) => {
+      clearTimeout(timeoutHandle);
+      resolve(result);
+    }).catch((error) => {
+      clearTimeout(timeoutHandle);
+      reject(error);
+    });
+  });
+}
+function createTimeoutSignal(signal, timeoutMs) {
+  const controller = new AbortController;
+  const abortFromSource = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener("abort", abortFromSource);
+    }
+  }
+  const timeoutHandle = timeoutMs !== undefined ? setTimeout(() => {
+    controller.abort();
+  }, timeoutMs) : undefined;
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      if (signal) {
+        signal.removeEventListener("abort", abortFromSource);
+      }
+    }
+  };
+}
+function createToolExecutionError(message, code, retryAfterMs) {
+  return Object.assign(new Error(message), {
+    code,
+    kind: "retryable",
+    retryAfterMs
+  });
+}
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();

package/dist/node/tools/tool-adapter.js

@@ -2263,21 +2263,39 @@ var init_json_schema_to_zod = () => {};
 // src/tools/tool-adapter.ts
 import { tool } from "ai";
 function specToolToAISDKTool(specTool, handler, context = {}) {
+  let lastInvocationAt;
   return tool({
     description: specTool.description ?? specTool.name,
     inputSchema: jsonSchemaToZodSafe(specTool.schema),
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
     execute: async (input) => {
-      const result = await handler(input, {
-        agentId: context.agentId ?? "unknown",
-        sessionId: context.sessionId ?? "unknown",
-        tenantId: context.tenantId,
-        actorId: context.actorId,
-        locale: context.locale,
-        metadata: context.metadata,
-        signal: context.signal
-      });
-      return typeof result === "string" ? result : JSON.stringify(result);
+      const now = Date.now();
+      const cooldownMs = normalizeDuration(specTool.cooldownMs);
+      if (cooldownMs && lastInvocationAt !== undefined) {
+        const elapsed = now - lastInvocationAt;
+        if (elapsed < cooldownMs) {
+          const retryAfterMs = cooldownMs - elapsed;
+          throw createToolExecutionError(`Tool "${specTool.name}" is cooling down. Retry in ${retryAfterMs}ms.`, "TOOL_COOLDOWN_ACTIVE", retryAfterMs);
+        }
+      }
+      const timeoutMs = normalizeDuration(specTool.timeoutMs);
+      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      try {
+        const execution = handler(input, {
+          agentId: context.agentId ?? "unknown",
+          sessionId: context.sessionId ?? "unknown",
+          tenantId: context.tenantId,
+          actorId: context.actorId,
+          locale: context.locale,
+          metadata: context.metadata,
+          signal
+        });
+        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
+        return typeof result === "string" ? result : JSON.stringify(result);
+      } finally {
+        dispose();
+        lastInvocationAt = Date.now();
+      }
     }
   });
 }
@@ -2302,6 +2320,64 @@ function createToolHandler(handler) {
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function normalizeDuration(value) {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isFinite(value)) {
+    return;
+  }
+  if (value <= 0) {
+    return;
+  }
+  return Math.round(value);
+}
+function withTimeout(execution, timeoutMs, toolName) {
+  return new Promise((resolve, reject) => {
+    const timeoutHandle = setTimeout(() => {
+      reject(createToolExecutionError(`Tool "${toolName}" timed out after ${timeoutMs}ms.`, "TOOL_EXECUTION_TIMEOUT"));
+    }, timeoutMs);
+    execution.then((result) => {
+      clearTimeout(timeoutHandle);
+      resolve(result);
+    }).catch((error) => {
+      clearTimeout(timeoutHandle);
+      reject(error);
+    });
+  });
+}
+function createTimeoutSignal(signal, timeoutMs) {
+  const controller = new AbortController;
+  const abortFromSource = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener("abort", abortFromSource);
+    }
+  }
+  const timeoutHandle = timeoutMs !== undefined ? setTimeout(() => {
+    controller.abort();
+  }, timeoutMs) : undefined;
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      if (signal) {
+        signal.removeEventListener("abort", abortFromSource);
+      }
+    }
+  };
+}
+function createToolExecutionError(message, code, retryAfterMs) {
+  return Object.assign(new Error(message), {
+    code,
+    kind: "retryable",
+    retryAfterMs
+  });
+}
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();

package/dist/providers/claude-agent-sdk/adapter.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/providers/claude-agent-sdk/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/providers/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/providers/opencode-sdk/adapter.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/providers/opencode-sdk/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/spec/index.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/spec/spec.d.ts

@@ -5,6 +5,31 @@ import type { PolicyRef } from '@contractspec/lib.contracts-spec/policy/spec';
  * Metadata for an agent specification.
  */
 export type AgentMeta = OwnerShipMeta;
+export type AgentRuntimeAdapterKey = 'langgraph' | 'langchain' | 'workflow-devkit';
+export interface AgentRuntimeCapabilities {
+    /** Optional external adapter availability map for runtime interoperability. */
+    adapters?: Partial<Record<AgentRuntimeAdapterKey, boolean>>;
+    /** Whether the agent should persist checkpoints for replay/resume. */
+    checkpointing?: boolean;
+    /** Whether the agent supports external suspend/resume semantics. */
+    suspendResume?: boolean;
+    /** Whether the agent can delegate approvals to external gateways. */
+    approvalGateway?: boolean;
+}
+export interface AgentRuntimePorts {
+    /** Symbolic checkpoint store adapter identifier. */
+    checkpointStore?: string;
+    /** Symbolic suspend/resume adapter identifier. */
+    suspension?: string;
+    /** Symbolic retry classifier identifier. */
+    retryClassifier?: string;
+    /** Symbolic approval gateway identifier. */
+    approvalGateway?: string;
+}
+export interface AgentRuntimeConfig {
+    capabilities?: AgentRuntimeCapabilities;
+    ports?: AgentRuntimePorts;
+}
 /**
  * Configuration for a tool that an agent can use.
  */
@@ -106,6 +131,8 @@ export interface AgentSpec {
     knowledge?: AgentKnowledgeRef[];
     /** Policy configuration */
     policy?: AgentPolicy;
+    /** Runtime adapter and portability config. */
+    runtime?: AgentRuntimeConfig;
     /** Maximum steps per generation (defaults to 10) */
     maxSteps?: number;
 }

package/dist/spec/spec.js

@@ -2142,6 +2142,11 @@ function defineAgent(spec) {
   if (!spec.tools?.length) {
     throw new Error(i18n.t("error.agentRequiresTool", { key: spec.meta.key }));
   }
+  for (const [portName, portRef] of Object.entries(spec.runtime?.ports ?? {})) {
+    if (portRef !== undefined && portRef.trim().length === 0) {
+      throw new Error(`Agent ${spec.meta.key} has invalid runtime config: port "${portName}" must not be empty`);
+    }
+  }
   const toolNames = new Set;
   for (const tool of spec.tools) {
     if (toolNames.has(tool.name)) {

package/dist/spec/spec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/index.js

@@ -2263,21 +2263,39 @@ var init_json_schema_to_zod = () => {};
 // src/tools/tool-adapter.ts
 import { tool } from "ai";
 function specToolToAISDKTool(specTool, handler, context = {}) {
+  let lastInvocationAt;
   return tool({
     description: specTool.description ?? specTool.name,
     inputSchema: jsonSchemaToZodSafe(specTool.schema),
     needsApproval: specTool.requiresApproval ?? !specTool.automationSafe,
     execute: async (input) => {
-      const result = await handler(input, {
-        agentId: context.agentId ?? "unknown",
-        sessionId: context.sessionId ?? "unknown",
-        tenantId: context.tenantId,
-        actorId: context.actorId,
-        locale: context.locale,
-        metadata: context.metadata,
-        signal: context.signal
-      });
-      return typeof result === "string" ? result : JSON.stringify(result);
+      const now = Date.now();
+      const cooldownMs = normalizeDuration(specTool.cooldownMs);
+      if (cooldownMs && lastInvocationAt !== undefined) {
+        const elapsed = now - lastInvocationAt;
+        if (elapsed < cooldownMs) {
+          const retryAfterMs = cooldownMs - elapsed;
+          throw createToolExecutionError(`Tool "${specTool.name}" is cooling down. Retry in ${retryAfterMs}ms.`, "TOOL_COOLDOWN_ACTIVE", retryAfterMs);
+        }
+      }
+      const timeoutMs = normalizeDuration(specTool.timeoutMs);
+      const { signal, dispose } = createTimeoutSignal(context.signal, timeoutMs);
+      try {
+        const execution = handler(input, {
+          agentId: context.agentId ?? "unknown",
+          sessionId: context.sessionId ?? "unknown",
+          tenantId: context.tenantId,
+          actorId: context.actorId,
+          locale: context.locale,
+          metadata: context.metadata,
+          signal
+        });
+        const result = timeoutMs ? await withTimeout(execution, timeoutMs, specTool.name) : await execution;
+        return typeof result === "string" ? result : JSON.stringify(result);
+      } finally {
+        dispose();
+        lastInvocationAt = Date.now();
+      }
     }
   });
 }
@@ -2302,6 +2320,64 @@ function createToolHandler(handler) {
 function buildToolHandlers(handlersObj) {
   return new Map(Object.entries(handlersObj));
 }
+function normalizeDuration(value) {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isFinite(value)) {
+    return;
+  }
+  if (value <= 0) {
+    return;
+  }
+  return Math.round(value);
+}
+function withTimeout(execution, timeoutMs, toolName) {
+  return new Promise((resolve, reject) => {
+    const timeoutHandle = setTimeout(() => {
+      reject(createToolExecutionError(`Tool "${toolName}" timed out after ${timeoutMs}ms.`, "TOOL_EXECUTION_TIMEOUT"));
+    }, timeoutMs);
+    execution.then((result) => {
+      clearTimeout(timeoutHandle);
+      resolve(result);
+    }).catch((error) => {
+      clearTimeout(timeoutHandle);
+      reject(error);
+    });
+  });
+}
+function createTimeoutSignal(signal, timeoutMs) {
+  const controller = new AbortController;
+  const abortFromSource = () => controller.abort();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort();
+    } else {
+      signal.addEventListener("abort", abortFromSource);
+    }
+  }
+  const timeoutHandle = timeoutMs !== undefined ? setTimeout(() => {
+    controller.abort();
+  }, timeoutMs) : undefined;
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      if (signal) {
+        signal.removeEventListener("abort", abortFromSource);
+      }
+    }
+  };
+}
+function createToolExecutionError(message, code, retryAfterMs) {
+  return Object.assign(new Error(message), {
+    code,
+    kind: "retryable",
+    retryAfterMs
+  });
+}
 var init_tool_adapter = __esm(() => {
   init_json_schema_to_zod();
   init_i18n();

package/dist/tools/mcp-client.d.ts

@@ -16,6 +16,12 @@ interface McpClientBaseConfig {
     clientName?: string;
     /** Optional MCP client version override */
     clientVersion?: string;
+    /** Auth method for the MCP connection. */
+    authMethod?: 'api-key' | 'oauth2' | 'bearer';
+    /** Custom auth headers. */
+    authHeaders?: Record<string, string>;
+    /** API version for the MCP server. */
+    apiVersion?: string;
 }
 /**
  * Configuration for stdio MCP servers.

package/dist/tools/mcp-server.d.ts

@@ -33,6 +33,10 @@ export interface AgentMcpServerConfig {
     name?: string;
     /** Optional version override */
     version?: string;
+    /** Auth validation function for incoming MCP requests. */
+    validateAuth?: (headers: Record<string, string>) => Promise<boolean> | boolean;
+    /** Required auth methods for clients connecting to this MCP server. */
+    requiredAuthMethods?: ('api-key' | 'bearer' | 'oauth2')[];
 }
 /**
  * Create an MCP server from configuration.