@contractspec/lib.ai-agent 2.3.0 → 2.5.0

package/dist/node/agent/unified-agent.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êté",
         description: "Log message when MCP tool server stops",
         placeholders: [{ name: "name", type: "string" }]
+      },
+      "error.telemetry.posthogAiRequired": {
+        value: "PostHog LLM Analytics nécessite l'installation de @posthog/ai. Exécutez : npm install @posthog/ai posthog-node",
+        description: "Error when PostHog AI dependency is missing"
+      },
+      "error.telemetry.posthogClientOrKeyRequired": {
+        value: "PostHog LLM Analytics nécessite 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écessite l'installation de posthog-node. Exécutez : npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "Le fournisseur « {provider} » 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é 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é instalado. Ejecute: npm install posthog-node",
+        description: "Error when posthog-node dependency is missing"
+      },
+      "error.provider.notAvailable": {
+        value: "El proveedor '{provider}' no está 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"));
   }
@@ -2283,6 +2307,7 @@ function specToolToAISDKTool(specTool, handler, context = {}) {
         sessionId: context.sessionId ?? "unknown",
         tenantId: context.tenantId,
         actorId: context.actorId,
+        locale: context.locale,
         metadata: context.metadata,
         signal: context.signal
       });
@@ -2295,7 +2320,9 @@ function specToolsToAISDKTools(specTools, handlers, context = {}) {
   for (const specTool of specTools) {
     const handler = handlers.get(specTool.name);
     if (!handler) {
-      throw new Error(getDefaultI18n().t("error.missingToolHandler", { name: specTool.name }));
+      throw new Error(createAgentI18n(context.locale).t("error.missingToolHandler", {
+        name: specTool.name
+      }));
     }
     tools[specTool.name] = specToolToAISDKTool(specTool, handler, context);
   }
@@ -2802,14 +2829,14 @@ async function importPostHogAI() {
   try {
     return await import("@posthog/ai");
   } catch {
-    throw new Error("PostHog LLM Analytics requires @posthog/ai to be installed. Run: npm install @posthog/ai posthog-node");
+    throw new Error(createAgentI18n().t("error.telemetry.posthogAiRequired"));
   }
 }
 async function resolvePostHogClient(config) {
   if (config.client)
     return config.client;
   if (!config.apiKey) {
-    throw new Error("PostHog LLM Analytics requires either a client instance or an apiKey.");
+    throw new Error(createAgentI18n().t("error.telemetry.posthogClientOrKeyRequired"));
   }
   try {
     const { PostHog } = await import("posthog-node");
@@ -2817,7 +2844,7 @@ async function resolvePostHogClient(config) {
       host: config.host ?? "https://us.i.posthog.com"
     });
   } catch {
-    throw new Error("PostHog LLM Analytics requires posthog-node to be installed. Run: npm install posthog-node");
+    throw new Error(createAgentI18n().t("error.telemetry.posthogNodeRequired"));
   }
 }
 function mapTokenUsage(usage) {
@@ -2859,6 +2886,9 @@ function asDateIso(value) {
     return value.toISOString();
   return;
 }
+var init_posthog = __esm(() => {
+  init_i18n();
+});
 
 // src/agent/contract-spec-agent.ts
 var exports_contract_spec_agent = {};
@@ -3063,7 +3093,7 @@ ${params.prompt}` : params.prompt;
       posthogTraceId: params.traceId,
       posthogProperties: mergedProperties
     };
-    const { createPostHogTracedModel: createPostHogTracedModel2 } = await Promise.resolve().then(() => exports_posthog);
+    const { createPostHogTracedModel: createPostHogTracedModel2 } = await Promise.resolve().then(() => (init_posthog(), exports_posthog));
     return createPostHogTracedModel2(this.config.model, posthogConfig, tracingOptions);
   }
 }
@@ -3085,6 +3115,7 @@ var init_contract_spec_agent = __esm(() => {
 // src/providers/types.ts
 var ExternalProviderError, ProviderNotAvailableError, ProviderExecutionError, ContextCreationError;
 var init_types = __esm(() => {
+  init_i18n();
   ExternalProviderError = class ExternalProviderError extends Error {
     provider;
     code;
@@ -3098,8 +3129,12 @@ var init_types = __esm(() => {
     }
   };
   ProviderNotAvailableError = class ProviderNotAvailableError extends ExternalProviderError {
-    constructor(provider, reason) {
-      super(`Provider '${provider}' is not available${reason ? `: ${reason}` : ""}`, provider, "PROVIDER_NOT_AVAILABLE");
+    constructor(provider, reason, locale) {
+      const i18n = createAgentI18n(locale);
+      super(i18n.t("error.provider.notAvailable", {
+        provider,
+        reason: reason ? `: ${reason}` : ""
+      }), provider, "PROVIDER_NOT_AVAILABLE");
       this.name = "ProviderNotAvailableError";
     }
   };
@@ -3121,7 +3156,7 @@ var init_types = __esm(() => {
 function specToolToClaudeAgentTool(tool3, handler, context) {
   return {
     name: tool3.name,
-    description: tool3.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool3.name }),
+    description: tool3.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool3.name }),
     input_schema: normalizeSchema(tool3.schema),
     requires_confirmation: tool3.requiresApproval ?? !tool3.automationSafe,
     execute: async (input) => {
@@ -3141,7 +3176,7 @@ function specToolsToClaudeAgentTools(tools, handlers, context) {
   return tools.filter((tool3) => handlers.has(tool3.name)).map((tool3) => {
     const handler = handlers.get(tool3.name);
     if (!handler) {
-      throw new Error(getDefaultI18n().t("error.handlerNotFoundForTool", {
+      throw new Error(createAgentI18n().t("error.handlerNotFoundForTool", {
         name: tool3.name
       }));
     }
@@ -3174,7 +3209,7 @@ function claudeAgentToolsToSpecTools(claudeTools) {
 function specToolToExternalTool(tool3, handler, context) {
   return {
     name: tool3.name,
-    description: tool3.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool3.name }),
+    description: tool3.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool3.name }),
     inputSchema: tool3.schema ?? { type: "object" },
     requiresApproval: tool3.requiresApproval ?? !tool3.automationSafe,
     execute: handler ? async (input) => {
@@ -3370,7 +3405,7 @@ class ClaudeAgentSDKProvider {
   }
   async createContext(spec) {
     if (!this.isAvailable()) {
-      throw new ProviderNotAvailableError(this.name, getDefaultI18n().t("error.provider.sdkNotConfigured"));
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.sdkNotConfigured"));
     }
     try {
       const toolSet = {};
@@ -3395,7 +3430,7 @@ class ClaudeAgentSDKProvider {
         cleanup: async () => {}
       };
     } catch (error) {
-      throw new ContextCreationError(this.name, getDefaultI18n().t("error.provider.contextCreation", {
+      throw new ContextCreationError(this.name, createAgentI18n(this.config.locale).t("error.provider.contextCreation", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
     }
@@ -3453,7 +3488,7 @@ ${params.systemOverride}` : context.spec.instructions;
         }
       };
     } catch (error) {
-      throw new ProviderExecutionError(this.name, getDefaultI18n().t("error.provider.executionFailed", {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.executionFailed", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
     }
@@ -3535,7 +3570,7 @@ ${params.systemOverride}` : context.spec.instructions;
         }
       };
     } catch (error) {
-      throw new ProviderExecutionError(this.name, getDefaultI18n().t("error.provider.streamFailed", {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.streamFailed", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
     }
@@ -3545,7 +3580,7 @@ ${params.systemOverride}` : context.spec.instructions;
       const module = __require("@anthropic-ai/claude-agent-sdk");
       return module.default ?? module;
     } catch {
-      throw new ProviderNotAvailableError(this.name, getDefaultI18n().t("error.provider.claudeSdkMissing"));
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.claudeSdkMissing"));
     }
   }
   prepareToolsForSDK(context, params) {
@@ -3555,7 +3590,7 @@ ${params.systemOverride}` : context.spec.instructions;
       if (externalTool?.execute) {
         handlers.set(tool3.name, async (input) => {
           if (!externalTool.execute) {
-            throw new Error(getDefaultI18n().t("error.toolNoExecuteHandler", {
+            throw new Error(createAgentI18n(this.config.locale).t("error.toolNoExecuteHandler", {
               name: tool3.name
             }));
           }
@@ -3579,7 +3614,7 @@ ${params.systemOverride}` : context.spec.instructions;
       return {
         toolCallId: toolCall.toolCallId,
         toolName: toolCall.toolName,
-        output: getDefaultI18n().t("error.toolNotFoundOrNoHandler", {
+        output: createAgentI18n(this.config.locale).t("error.toolNotFoundOrNoHandler", {
           name: toolCall.toolName
         })
       };
@@ -3664,7 +3699,7 @@ var init_claude_agent_sdk = __esm(() => {
 function specToolToOpenCodeTool(tool3) {
   return {
     name: tool3.name,
-    description: tool3.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool3.name }),
+    description: tool3.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool3.name }),
     parameters: normalizeToOpenCodeParameters(tool3.schema),
     permission: getPermissionLevel(tool3)
   };
@@ -3696,7 +3731,7 @@ function openCodeToolsToSpecTools(openCodeTools) {
 function specToolToExternalToolForOpenCode(tool3, handler, context) {
   return {
     name: tool3.name,
-    description: tool3.description ?? getDefaultI18n().t("tool.fallbackDescription", { name: tool3.name }),
+    description: tool3.description ?? createAgentI18n().t("tool.fallbackDescription", { name: tool3.name }),
     inputSchema: tool3.schema ?? { type: "object" },
     requiresApproval: tool3.requiresApproval ?? !tool3.automationSafe,
     execute: handler ? async (input) => {
@@ -3760,7 +3795,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
@@ -3857,7 +3892,7 @@ function specToOpenCodeMarkdown(spec, options) {
   };
 }
 function buildMarkdownBody(spec) {
-  const i18n = getDefaultI18n();
+  const i18n = createAgentI18n(spec.locale);
   const lines = [];
   lines.push(`# ${spec.meta.key}`);
   lines.push("");
@@ -3979,7 +4014,7 @@ class OpenCodeSDKProvider {
   }
   async createContext(spec) {
     if (!this.isAvailable()) {
-      throw new ProviderNotAvailableError(this.name, getDefaultI18n().t("error.provider.sdkNotInstalled"));
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.sdkNotInstalled"));
     }
     try {
       const sdk = await this.loadSDK();
@@ -4018,7 +4053,7 @@ class OpenCodeSDKProvider {
         }
       };
     } catch (error) {
-      throw new ContextCreationError(this.name, getDefaultI18n().t("error.provider.contextCreation", {
+      throw new ContextCreationError(this.name, createAgentI18n(this.config.locale).t("error.provider.contextCreation", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
     }
@@ -4068,7 +4103,7 @@ ${params.systemOverride}` : context.spec.instructions;
         }
       };
     } catch (error) {
-      throw new ProviderExecutionError(this.name, getDefaultI18n().t("error.provider.executionFailed", {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.executionFailed", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
     }
@@ -4156,7 +4191,7 @@ ${params.systemOverride}` : context.spec.instructions;
         }
       };
     } catch (error) {
-      throw new ProviderExecutionError(this.name, getDefaultI18n().t("error.provider.streamFailed", {
+      throw new ProviderExecutionError(this.name, createAgentI18n(this.config.locale).t("error.provider.streamFailed", {
         error: error instanceof Error ? error.message : String(error)
       }), error instanceof Error ? error : undefined);
     }
@@ -4166,7 +4201,7 @@ ${params.systemOverride}` : context.spec.instructions;
       const module = __require("@opencode-ai/sdk");
       return module;
     } catch {
-      throw new ProviderNotAvailableError(this.name, getDefaultI18n().t("error.provider.opencodeSdkMissing"));
+      throw new ProviderNotAvailableError(this.name, createAgentI18n(this.config.locale).t("error.provider.opencodeSdkMissing"));
     }
   }
   getHostname() {
@@ -4261,6 +4296,9 @@ class UnifiedAgent {
       messageCount: 0
     };
   }
+  i18n(runtimeLocale) {
+    return createAgentI18n(this.spec.locale, runtimeLocale ?? this.config.locale);
+  }
   async initialize() {
     const backend = this.config.backend;
     try {
@@ -4275,14 +4313,14 @@ class UnifiedAgent {
           await this.initializeOpenCodeSDK();
           break;
         default:
-          throw new Error(getDefaultI18n().t("error.unknownBackend", {
+          throw new Error(this.i18n().t("error.unknownBackend", {
             backend: String(backend)
           }));
       }
     } catch (error) {
       this.state.lastError = error instanceof Error ? error : new Error(String(error));
       if (this.config.fallbackBackend && this.config.fallbackBackend !== backend) {
-        console.warn(getDefaultI18n().t("log.unifiedAgent.fallback", {
+        console.warn(this.i18n().t("log.unifiedAgent.fallback", {
           backend: String(backend),
           fallback: String(this.config.fallbackBackend)
         }));
@@ -4299,13 +4337,13 @@ class UnifiedAgent {
       const config = this.config.config;
       this.provider = new ClaudeAgentSDKProvider2(config ?? {});
       if (!this.provider.isAvailable()) {
-        throw new Error(getDefaultI18n().t("error.claudeSdk.notAvailable"));
+        throw new Error(this.i18n().t("error.claudeSdk.notAvailable"));
       }
       this.context = await this.provider.createContext(this.spec);
       this.state.isReady = true;
     } catch (error) {
       if (error.code === "MODULE_NOT_FOUND") {
-        throw new Error(getDefaultI18n().t("error.claudeSdk.notInstalled"));
+        throw new Error(this.i18n().t("error.claudeSdk.notInstalled"));
       }
       throw error;
     }
@@ -4316,13 +4354,13 @@ class UnifiedAgent {
       const config = this.config.config;
       this.provider = new OpenCodeSDKProvider2(config ?? {});
       if (!this.provider.isAvailable()) {
-        throw new Error(getDefaultI18n().t("error.opencodeSdk.notAvailable"));
+        throw new Error(this.i18n().t("error.opencodeSdk.notAvailable"));
       }
       this.context = await this.provider.createContext(this.spec);
       this.state.isReady = true;
     } catch (error) {
       if (error.code === "MODULE_NOT_FOUND") {
-        throw new Error(getDefaultI18n().t("error.opencodeSdk.notInstalled"));
+        throw new Error(this.i18n().t("error.opencodeSdk.notInstalled"));
       }
       throw error;
     }
@@ -4341,7 +4379,7 @@ class UnifiedAgent {
         case "opencode-sdk":
           return await this.runWithExternalProvider(message, options);
         default:
-          throw new Error(getDefaultI18n().t("error.unknownBackend", {
+          throw new Error(this.i18n().t("error.unknownBackend", {
             backend: String(backend)
           }));
       }
@@ -4365,7 +4403,7 @@ class UnifiedAgent {
   }
   async runWithExternalProvider(message, options) {
     if (!this.provider || !this.context) {
-      throw new Error(getDefaultI18n().t("error.providerNotInitialized"));
+      throw new Error(this.i18n().t("error.providerNotInitialized"));
     }
     const result = await this.provider.execute(this.context, {
       prompt: message,