@contractspec/lib.ai-agent 2.3.0 → 2.5.0

package/dist/interop/spec-consumer.js

@@ -603,6 +603,26 @@ var init_en = __esm(() => {
         value: "[MCPToolServer] Stopped {name}",
         description: "Log message when MCP tool server stops",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics requires @posthog/ai to be installed. Run: npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics requires either a client instance or an apiKey.",
+        description: "Error when PostHog client or API key is not configured"
+      },
+      "error.telemetry.posthogNodeRequired": {
+        value: "PostHog LLM Analytics requires posthog-node to be installed. Run: npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "Provider '{provider}' is not available{reason}",
+        description: "Error when a provider is unavailable",
+        placeholders: [
+          { name: "provider", type: "string" },
+          { name: "reason", type: "string" }
+        ]
       }
     }
   });
@@ -1214,6 +1234,26 @@ var init_fr = __esm(() => {
         value: "[MCPToolServer] {name} arr\xEAt\xE9",
         description: "Log message when MCP tool server stops",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics n\xE9cessite l'installation de @posthog/ai. Ex\xE9cutez : npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics n\xE9cessite soit une instance client, soit une apiKey.",
+        description: "Error when PostHog client or API key is not configured"
+      },
+      "error.telemetry.posthogNodeRequired": {
+        value: "PostHog LLM Analytics n\xE9cessite l'installation de posthog-node. Ex\xE9cutez : npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "Le fournisseur \xAB {provider} \xBB n'est pas disponible{reason}",
+        description: "Error when a provider is unavailable",
+        placeholders: [
+          { name: "provider", type: "string" },
+          { name: "reason", type: "string" }
+        ]
       }
     }
   });
@@ -1859,78 +1899,58 @@ var init_es = __esm(() => {
         value: "[MCPToolServer] Detenido {name}",
         description: "Mensaje de registro cuando el servidor de herramientas MCP se detiene",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics requiere que @posthog/ai est\xE9 instalado. Ejecute: npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics requiere una instancia de cliente o una apiKey.",
+        description: "Error when PostHog client or API key is not configured"
+      },
+      "error.telemetry.posthogNodeRequired": {
+        value: "PostHog LLM Analytics requiere que posthog-node est\xE9 instalado. Ejecute: npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "El proveedor '{provider}' no est\xE1 disponible{reason}",
+        description: "Error when a provider is unavailable",
+        placeholders: [
+          { name: "provider", type: "string" },
+          { name: "reason", type: "string" }
+        ]
       }
     }
   });
 });
 
-// src/i18n/locale.ts
-function resolveLocale(specLocale, runtimeLocale) {
-  const raw = runtimeLocale ?? specLocale ?? DEFAULT_LOCALE;
-  if (isSupportedLocale(raw)) {
-    return raw;
-  }
-  const base = raw.split("-")[0];
-  if (base && isSupportedLocale(base)) {
-    return base;
-  }
-  return DEFAULT_LOCALE;
-}
-function isSupportedLocale(locale) {
-  return SUPPORTED_LOCALES.includes(locale);
-}
-var DEFAULT_LOCALE = "en", SUPPORTED_LOCALES;
-var init_locale = __esm(() => {
-  SUPPORTED_LOCALES = ["en", "fr", "es"];
-});
-
 // src/i18n/messages.ts
-import { TranslationRegistry } from "@contractspec/lib.contracts-spec/translations";
-function getRegistry() {
-  if (!sharedRegistry) {
-    sharedRegistry = new TranslationRegistry([
-      enMessages,
-      frMessages,
-      esMessages
-    ]);
-  }
-  return sharedRegistry;
-}
-function interpolate(template, params) {
-  if (!params)
-    return template;
-  return template.replace(/\{(\w+)\}/g, (match, key) => {
-    if (key in params) {
-      return String(params[key]);
-    }
-    return match;
-  });
-}
-function createAgentI18n(specLocale, runtimeLocale) {
-  const locale = resolveLocale(specLocale, runtimeLocale);
-  const registry = getRegistry();
-  return {
-    locale,
-    t(key, params) {
-      const raw = registry.getValue(SPEC_KEY, key, locale, key);
-      return interpolate(raw, params);
-    }
-  };
-}
-function getDefaultI18n() {
-  return createAgentI18n(DEFAULT_LOCALE);
-}
-function resetI18nRegistry() {
-  sharedRegistry = null;
-}
-var SPEC_KEY = "ai-agent.messages", sharedRegistry = null;
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory, createAgentI18n, getDefaultI18n, resetI18nRegistry;
 var init_messages = __esm(() => {
   init_en();
   init_fr();
   init_es();
-  init_locale();
+  factory = createI18nFactory({
+    specKey: "ai-agent.messages",
+    catalogs: [enMessages, frMessages, esMessages]
+  });
+  createAgentI18n = factory.create;
+  getDefaultI18n = factory.getDefault;
+  resetI18nRegistry = factory.resetRegistry;
 });
 
+// src/i18n/locale.ts
+import {
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  resolveLocale,
+  isSupportedLocale
+} from "@contractspec/lib.contracts-spec/translations";
+var init_locale = () => {};
+
 // src/i18n/keys.ts
 var AGENT_KEYS, KNOWLEDGE_KEYS, TOOL_KEYS, INTEROP_KEYS, ERROR_KEYS, EXPORT_KEYS, APPROVAL_KEYS, LOG_KEYS, I18N_KEYS;
 var init_keys = __esm(() => {
@@ -2025,7 +2045,11 @@ var init_keys = __esm(() => {
     "error.provider.sdkNotInstalled": "error.provider.sdkNotInstalled",
     "error.provider.contextCreation": "error.provider.contextCreation",
     "error.provider.executionFailed": "error.provider.executionFailed",
-    "error.provider.streamFailed": "error.provider.streamFailed"
+    "error.provider.streamFailed": "error.provider.streamFailed",
+    "error.provider.notAvailable": "error.provider.notAvailable",
+    "error.telemetry.posthogAiRequired": "error.telemetry.posthogAiRequired",
+    "error.telemetry.posthogClientOrKeyRequired": "error.telemetry.posthogClientOrKeyRequired",
+    "error.telemetry.posthogNodeRequired": "error.telemetry.posthogNodeRequired"
   };
   EXPORT_KEYS = {
     "export.agentConfiguration": "export.agentConfiguration",
@@ -2105,7 +2129,7 @@ var init_i18n = __esm(() => {
 
 // src/spec/spec.ts
 function defineAgent(spec) {
-  const i18n = getDefaultI18n();
+  const i18n = createAgentI18n(spec.locale);
   if (!spec.meta?.key) {
     throw new Error(i18n.t("error.agentKeyRequired"));
   }
@@ -2145,10 +2169,12 @@ class ContractSpecConsumer {
   specs;
   includeMetadata;
   baseUrl;
+  locale;
   constructor(config) {
     this.specs = new Map;
     this.includeMetadata = config.includeMetadata ?? true;
     this.baseUrl = config.baseUrl;
+    this.locale = config.locale;
     for (const spec of config.specs) {
       const key = agentKey(spec.meta);
       this.specs.set(key, spec);
@@ -2157,9 +2183,9 @@ class ContractSpecConsumer {
   getSpecMarkdown(specKey, options) {
     const spec = this.specs.get(specKey);
     if (!spec) {
-      throw new Error(getDefaultI18n().t("error.specNotFound", { specKey }));
+      throw new Error(createAgentI18n(this.locale).t("error.specNotFound", { specKey }));
     }
-    const i18n = getDefaultI18n();
+    const i18n = createAgentI18n(options?.locale ?? this.locale);
     const sections = [];
     const opts = {
       includeToc: options?.includeToc ?? true,
@@ -2282,9 +2308,9 @@ class ContractSpecConsumer {
   getSpecPrompt(specKey, options) {
     const spec = this.specs.get(specKey);
     if (!spec) {
-      throw new Error(getDefaultI18n().t("error.specNotFound", { specKey }));
+      throw new Error(createAgentI18n(this.locale).t("error.specNotFound", { specKey }));
     }
-    const i18n = getDefaultI18n();
+    const i18n = createAgentI18n(options?.locale ?? this.locale);
     const sections = [];
     const opts = {
       includeTools: options?.includeTools ?? true,

package/dist/interop/tool-consumer.d.ts

@@ -14,6 +14,7 @@ import type { ToolConsumer, ToolConsumerConfig, ToolServerConfig, ToolServer, To
  */
 export declare class ContractSpecToolConsumer implements ToolConsumer {
     private readonly tools;
+    private readonly locale?;
     constructor(config: ToolConsumerConfig);
     /**
      * Create an MCP server exposing the tools.

package/dist/interop/tool-consumer.js

@@ -603,6 +603,26 @@ var init_en = __esm(() => {
         value: "[MCPToolServer] Stopped {name}",
         description: "Log message when MCP tool server stops",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics requires @posthog/ai to be installed. Run: npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics requires either a client instance or an apiKey.",
+        description: "Error when PostHog client or API key is not configured"
+      },
+      "error.telemetry.posthogNodeRequired": {
+        value: "PostHog LLM Analytics requires posthog-node to be installed. Run: npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "Provider '{provider}' is not available{reason}",
+        description: "Error when a provider is unavailable",
+        placeholders: [
+          { name: "provider", type: "string" },
+          { name: "reason", type: "string" }
+        ]
       }
     }
   });
@@ -1214,6 +1234,26 @@ var init_fr = __esm(() => {
         value: "[MCPToolServer] {name} arr\xEAt\xE9",
         description: "Log message when MCP tool server stops",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics n\xE9cessite l'installation de @posthog/ai. Ex\xE9cutez : npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics n\xE9cessite soit une instance client, soit une apiKey.",
+        description: "Error when PostHog client or API key is not configured"
+      },
+      "error.telemetry.posthogNodeRequired": {
+        value: "PostHog LLM Analytics n\xE9cessite l'installation de posthog-node. Ex\xE9cutez : npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "Le fournisseur \xAB {provider} \xBB n'est pas disponible{reason}",
+        description: "Error when a provider is unavailable",
+        placeholders: [
+          { name: "provider", type: "string" },
+          { name: "reason", type: "string" }
+        ]
       }
     }
   });
@@ -1859,78 +1899,58 @@ var init_es = __esm(() => {
         value: "[MCPToolServer] Detenido {name}",
         description: "Mensaje de registro cuando el servidor de herramientas MCP se detiene",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics requiere que @posthog/ai est\xE9 instalado. Ejecute: npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics requiere una instancia de cliente o una apiKey.",
+        description: "Error when PostHog client or API key is not configured"
+      },
+      "error.telemetry.posthogNodeRequired": {
+        value: "PostHog LLM Analytics requiere que posthog-node est\xE9 instalado. Ejecute: npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "El proveedor '{provider}' no est\xE1 disponible{reason}",
+        description: "Error when a provider is unavailable",
+        placeholders: [
+          { name: "provider", type: "string" },
+          { name: "reason", type: "string" }
+        ]
       }
     }
   });
 });
 
-// src/i18n/locale.ts
-function resolveLocale(specLocale, runtimeLocale) {
-  const raw = runtimeLocale ?? specLocale ?? DEFAULT_LOCALE;
-  if (isSupportedLocale(raw)) {
-    return raw;
-  }
-  const base = raw.split("-")[0];
-  if (base && isSupportedLocale(base)) {
-    return base;
-  }
-  return DEFAULT_LOCALE;
-}
-function isSupportedLocale(locale) {
-  return SUPPORTED_LOCALES.includes(locale);
-}
-var DEFAULT_LOCALE = "en", SUPPORTED_LOCALES;
-var init_locale = __esm(() => {
-  SUPPORTED_LOCALES = ["en", "fr", "es"];
-});
-
 // src/i18n/messages.ts
-import { TranslationRegistry } from "@contractspec/lib.contracts-spec/translations";
-function getRegistry() {
-  if (!sharedRegistry) {
-    sharedRegistry = new TranslationRegistry([
-      enMessages,
-      frMessages,
-      esMessages
-    ]);
-  }
-  return sharedRegistry;
-}
-function interpolate(template, params) {
-  if (!params)
-    return template;
-  return template.replace(/\{(\w+)\}/g, (match, key) => {
-    if (key in params) {
-      return String(params[key]);
-    }
-    return match;
-  });
-}
-function createAgentI18n(specLocale, runtimeLocale) {
-  const locale = resolveLocale(specLocale, runtimeLocale);
-  const registry = getRegistry();
-  return {
-    locale,
-    t(key, params) {
-      const raw = registry.getValue(SPEC_KEY, key, locale, key);
-      return interpolate(raw, params);
-    }
-  };
-}
-function getDefaultI18n() {
-  return createAgentI18n(DEFAULT_LOCALE);
-}
-function resetI18nRegistry() {
-  sharedRegistry = null;
-}
-var SPEC_KEY = "ai-agent.messages", sharedRegistry = null;
+import {
+  createI18nFactory
+} from "@contractspec/lib.contracts-spec/translations";
+var factory, createAgentI18n, getDefaultI18n, resetI18nRegistry;
 var init_messages = __esm(() => {
   init_en();
   init_fr();
   init_es();
-  init_locale();
+  factory = createI18nFactory({
+    specKey: "ai-agent.messages",
+    catalogs: [enMessages, frMessages, esMessages]
+  });
+  createAgentI18n = factory.create;
+  getDefaultI18n = factory.getDefault;
+  resetI18nRegistry = factory.resetRegistry;
 });
 
+// src/i18n/locale.ts
+import {
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  resolveLocale,
+  isSupportedLocale
+} from "@contractspec/lib.contracts-spec/translations";
+var init_locale = () => {};
+
 // src/i18n/keys.ts
 var AGENT_KEYS, KNOWLEDGE_KEYS, TOOL_KEYS, INTEROP_KEYS, ERROR_KEYS, EXPORT_KEYS, APPROVAL_KEYS, LOG_KEYS, I18N_KEYS;
 var init_keys = __esm(() => {
@@ -2025,7 +2045,11 @@ var init_keys = __esm(() => {
     "error.provider.sdkNotInstalled": "error.provider.sdkNotInstalled",
     "error.provider.contextCreation": "error.provider.contextCreation",
     "error.provider.executionFailed": "error.provider.executionFailed",
-    "error.provider.streamFailed": "error.provider.streamFailed"
+    "error.provider.streamFailed": "error.provider.streamFailed",
+    "error.provider.notAvailable": "error.provider.notAvailable",
+    "error.telemetry.posthogAiRequired": "error.telemetry.posthogAiRequired",
+    "error.telemetry.posthogClientOrKeyRequired": "error.telemetry.posthogClientOrKeyRequired",
+    "error.telemetry.posthogNodeRequired": "error.telemetry.posthogNodeRequired"
   };
   EXPORT_KEYS = {
     "export.agentConfiguration": "export.agentConfiguration",
@@ -2107,7 +2131,7 @@ var init_i18n = __esm(() => {
 function specToolToClaudeAgentTool(tool, handler, context) {
   return {
     name: tool.name,
-    description: tool.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool.name }),
+    description: tool.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool.name }),
     input_schema: normalizeSchema(tool.schema),
     requires_confirmation: tool.requiresApproval ?? !tool.automationSafe,
     execute: async (input) => {
@@ -2127,7 +2151,7 @@ function specToolsToClaudeAgentTools(tools, handlers, context) {
   return tools.filter((tool) => handlers.has(tool.name)).map((tool) => {
     const handler = handlers.get(tool.name);
     if (!handler) {
-      throw new Error(getDefaultI18n().t("error.handlerNotFoundForTool", {
+      throw new Error(createAgentI18n().t("error.handlerNotFoundForTool", {
         name: tool.name
       }));
     }
@@ -2160,7 +2184,7 @@ function claudeAgentToolsToSpecTools(claudeTools) {
 function specToolToExternalTool(tool, handler, context) {
   return {
     name: tool.name,
-    description: tool.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool.name }),
+    description: tool.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool.name }),
     inputSchema: tool.schema ?? { type: "object" },
     requiresApproval: tool.requiresApproval ?? !tool.automationSafe,
     execute: handler ? async (input) => {
@@ -2209,7 +2233,7 @@ var init_tool_bridge = __esm(() => {
 function specToolToOpenCodeTool(tool) {
   return {
     name: tool.name,
-    description: tool.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool.name }),
+    description: tool.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool.name }),
     parameters: normalizeToOpenCodeParameters(tool.schema),
     permission: getPermissionLevel(tool)
   };
@@ -2241,7 +2265,7 @@ function openCodeToolsToSpecTools(openCodeTools) {
 function specToolToExternalToolForOpenCode(tool, handler, context) {
   return {
     name: tool.name,
-    description: tool.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool.name }),
+    description: tool.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool.name }),
     inputSchema: tool.schema ?? { type: "object" },
     requiresApproval: tool.requiresApproval ?? !tool.automationSafe,
     execute: handler ? async (input) => {
@@ -2305,7 +2329,7 @@ async function executeToolCall(toolCall, handlers) {
   if (!handler) {
     return {
       tool_call_id: toolCall.id,
-      output: getDefaultI18n().t("error.toolNotFoundOrNoHandler", {
+      output: createAgentI18n().t("error.toolNotFoundOrNoHandler", {
         name: toolCall.name
       }),
       is_error: true
@@ -2338,11 +2362,13 @@ class MCPToolServer {
   tools;
   name;
   version;
+  locale;
   running = false;
   constructor(config) {
     this.tools = new Map;
     this.name = config.name ?? "contractspec-tools";
     this.version = config.version ?? "1.0.0";
+    this.locale = config.locale;
     for (const tool of config.tools) {
       this.tools.set(tool.config.name, tool);
     }
@@ -2352,7 +2378,7 @@ class MCPToolServer {
       return;
     }
     this.running = true;
-    console.log(getDefaultI18n().t("log.mcpServer.started", {
+    console.log(createAgentI18n(this.locale).t("log.mcpServer.started", {
       name: this.name,
       version: this.version,
       count: this.tools.size
@@ -2363,7 +2389,9 @@ class MCPToolServer {
       return;
     }
     this.running = false;
-    console.log(getDefaultI18n().t("log.mcpServer.stopped", { name: this.name }));
+    console.log(createAgentI18n(this.locale).t("log.mcpServer.stopped", {
+      name: this.name
+    }));
   }
   isRunning() {
     return this.running;
@@ -2372,18 +2400,20 @@ class MCPToolServer {
     return Array.from(this.tools.values()).map((t) => t.config);
   }
   async executeTool(toolName, args, context) {
+    const i18n = createAgentI18n(context?.locale ?? this.locale);
     const tool = this.tools.get(toolName);
     if (!tool) {
-      throw new Error(getDefaultI18n().t("error.toolNotFound", { name: toolName }));
+      throw new Error(i18n.t("error.toolNotFound", { name: toolName }));
     }
     if (!tool.handler) {
-      throw new Error(getDefaultI18n().t("error.noHandlerForTool", { name: toolName }));
+      throw new Error(i18n.t("error.noHandlerForTool", { name: toolName }));
     }
     const fullContext = {
       agentId: context?.agentId ?? "mcp-server",
       sessionId: context?.sessionId ?? "mcp-session",
       tenantId: context?.tenantId,
       actorId: context?.actorId,
+      locale: context?.locale ?? this.locale,
       metadata: context?.metadata,
       signal: context?.signal
     };
@@ -2412,8 +2442,10 @@ class MCPToolServer {
 
 class ContractSpecToolConsumer {
   tools;
+  locale;
   constructor(config) {
     this.tools = new Map;
+    this.locale = config.locale;
     for (const tool of config.tools) {
       this.tools.set(tool.config.name, tool);
     }
@@ -2454,7 +2486,9 @@ class ContractSpecToolConsumer {
           }
         }));
       default:
-        throw new Error(getDefaultI18n().t("error.unknownExportFormat", { format }));
+        throw new Error(createAgentI18n(this.locale).t("error.unknownExportFormat", {
+          format
+        }));
     }
   }
   createBridgedHandler(toolName, _format) {
@@ -2481,18 +2515,20 @@ class ContractSpecToolConsumer {
     return this.tools.has(name);
   }
   async executeTool(name, args, context) {
+    const i18n = createAgentI18n(context?.locale ?? this.locale);
     const tool = this.tools.get(name);
     if (!tool) {
-      throw new Error(getDefaultI18n().t("error.toolNotFound", { name }));
+      throw new Error(i18n.t("error.toolNotFound", { name }));
     }
     if (!tool.handler) {
-      throw new Error(getDefaultI18n().t("error.noToolHandler", { name }));
+      throw new Error(i18n.t("error.noToolHandler", { name }));
     }
     const fullContext = {
       agentId: context?.agentId ?? "consumer",
       sessionId: context?.sessionId ?? "consumer-session",
       tenantId: context?.tenantId,
       actorId: context?.actorId,
+      locale: context?.locale ?? this.locale,
       metadata: context?.metadata,
       signal: context?.signal
     };

package/dist/interop/types.d.ts

@@ -16,6 +16,8 @@ export interface SpecConsumerConfig {
     includeMetadata?: boolean;
     /** Base URL for linking */
     baseUrl?: string;
+    /** Locale for i18n (BCP 47). Falls back to 'en'. */
+    locale?: string;
 }
 /**
  * Options for markdown generation.
@@ -31,6 +33,8 @@ export interface SpecMarkdownOptions {
     includeConstraints?: boolean;
     /** Custom header */
     customHeader?: string;
+    /** Locale override for this call (BCP 47). */
+    locale?: string;
 }
 /**
  * Options for prompt generation.
@@ -46,6 +50,8 @@ export interface SpecPromptOptions {
     format?: 'structured' | 'natural';
     /** Custom context to append */
     customContext?: string;
+    /** Locale override for this call (BCP 47). */
+    locale?: string;
 }
 /**
  * Result from querying a spec.
@@ -112,6 +118,8 @@ export interface ToolConsumerConfig {
         config: AgentToolConfig;
         handler?: ToolHandler;
     }[];
+    /** Locale for i18n (BCP 47). Falls back to 'en'. */
+    locale?: string;
 }
 /**
  * Configuration for a tool server.
@@ -128,6 +136,8 @@ export interface ToolServerConfig {
     version?: string;
     /** Port to run on */
     port?: number;
+    /** Locale for i18n (BCP 47). Falls back to 'en'. */
+    locale?: string;
 }
 /**
  * Interface for tool servers.