@contractspec/lib.ai-agent 1.61.0 → 2.0.0

package/dist/i18n/keys.js

@@ -0,0 +1,188 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// 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(() => {
+  AGENT_KEYS = {
+    "agent.json.rules.validJsonOnly": "agent.json.rules.validJsonOnly",
+    "agent.json.rules.noMarkdownFences": "agent.json.rules.noMarkdownFences",
+    "agent.json.rules.noCommentary": "agent.json.rules.noCommentary",
+    "agent.json.rules.doubleQuotes": "agent.json.rules.doubleQuotes",
+    "agent.json.rules.noTrailingCommas": "agent.json.rules.noTrailingCommas",
+    "agent.json.defaultDescription": "agent.json.defaultDescription",
+    "agent.json.systemPrompt": "agent.json.systemPrompt"
+  };
+  KNOWLEDGE_KEYS = {
+    "knowledge.header": "knowledge.header",
+    "knowledge.description": "knowledge.description"
+  };
+  TOOL_KEYS = {
+    "tool.knowledge.description": "tool.knowledge.description",
+    "tool.knowledge.availableSpaces": "tool.knowledge.availableSpaces",
+    "tool.knowledge.spaceDefault": "tool.knowledge.spaceDefault",
+    "tool.knowledge.param.query": "tool.knowledge.param.query",
+    "tool.knowledge.param.spaceKey": "tool.knowledge.param.spaceKey",
+    "tool.knowledge.param.topK": "tool.knowledge.param.topK",
+    "tool.knowledge.noResults": "tool.knowledge.noResults",
+    "tool.knowledge.sourceLabel": "tool.knowledge.sourceLabel",
+    "tool.fallbackDescription": "tool.fallbackDescription",
+    "tool.mcp.param.message": "tool.mcp.param.message",
+    "tool.mcp.param.sessionId": "tool.mcp.param.sessionId",
+    "tool.mcp.agentDescription": "tool.mcp.agentDescription",
+    "tool.mcp.executePrompt": "tool.mcp.executePrompt",
+    "tool.mcp.toolDescription": "tool.mcp.toolDescription"
+  };
+  INTEROP_KEYS = {
+    "interop.prompt.agentIdentity": "interop.prompt.agentIdentity",
+    "interop.prompt.youAre": "interop.prompt.youAre",
+    "interop.prompt.description": "interop.prompt.description",
+    "interop.prompt.instructions": "interop.prompt.instructions",
+    "interop.prompt.availableTools": "interop.prompt.availableTools",
+    "interop.prompt.toolsIntro": "interop.prompt.toolsIntro",
+    "interop.prompt.parameters": "interop.prompt.parameters",
+    "interop.prompt.knowledgeContext": "interop.prompt.knowledgeContext",
+    "interop.prompt.additionalContext": "interop.prompt.additionalContext",
+    "interop.md.toc": "interop.md.toc",
+    "interop.md.overview": "interop.md.overview",
+    "interop.md.tools": "interop.md.tools",
+    "interop.md.knowledge": "interop.md.knowledge",
+    "interop.md.policy": "interop.md.policy",
+    "interop.md.metaKey": "interop.md.metaKey",
+    "interop.md.metaVersion": "interop.md.metaVersion",
+    "interop.md.metaStability": "interop.md.metaStability",
+    "interop.md.metaOwners": "interop.md.metaOwners",
+    "interop.md.metaTags": "interop.md.metaTags",
+    "interop.md.schema": "interop.md.schema",
+    "interop.md.automationSafe": "interop.md.automationSafe",
+    "interop.md.required": "interop.md.required",
+    "interop.md.optional": "interop.md.optional",
+    "interop.md.minConfidence": "interop.md.minConfidence",
+    "interop.md.escalationThreshold": "interop.md.escalationThreshold",
+    "interop.md.escalateToolFailure": "interop.md.escalateToolFailure",
+    "interop.md.escalateTimeout": "interop.md.escalateTimeout",
+    "interop.md.yes": "interop.md.yes",
+    "interop.md.no": "interop.md.no"
+  };
+  ERROR_KEYS = {
+    "error.jsonRunner.requiresModel": "error.jsonRunner.requiresModel",
+    "error.missingToolHandler": "error.missingToolHandler",
+    "error.unknownBackend": "error.unknownBackend",
+    "error.claudeSdk.notAvailable": "error.claudeSdk.notAvailable",
+    "error.claudeSdk.notInstalled": "error.claudeSdk.notInstalled",
+    "error.opencodeSdk.notAvailable": "error.opencodeSdk.notAvailable",
+    "error.opencodeSdk.notInstalled": "error.opencodeSdk.notInstalled",
+    "error.providerNotInitialized": "error.providerNotInitialized",
+    "error.agentKeyRequired": "error.agentKeyRequired",
+    "error.agentMissingVersion": "error.agentMissingVersion",
+    "error.agentRequiresInstructions": "error.agentRequiresInstructions",
+    "error.agentRequiresTool": "error.agentRequiresTool",
+    "error.agentDuplicateTool": "error.agentDuplicateTool",
+    "error.agentSpecNotFound": "error.agentSpecNotFound",
+    "error.specNotFound": "error.specNotFound",
+    "error.toolNotFound": "error.toolNotFound",
+    "error.noHandlerForTool": "error.noHandlerForTool",
+    "error.noToolHandler": "error.noToolHandler",
+    "error.unknownExportFormat": "error.unknownExportFormat",
+    "error.handlerNotFoundForTool": "error.handlerNotFoundForTool",
+    "error.toolNotFoundOrNoHandler": "error.toolNotFoundOrNoHandler",
+    "error.toolNoExecuteHandler": "error.toolNoExecuteHandler",
+    "error.provider.notRegistered": "error.provider.notRegistered",
+    "error.provider.depsNotInstalled": "error.provider.depsNotInstalled",
+    "error.provider.sdkNotConfigured": "error.provider.sdkNotConfigured",
+    "error.provider.claudeSdkMissing": "error.provider.claudeSdkMissing",
+    "error.provider.opencodeSdkMissing": "error.provider.opencodeSdkMissing",
+    "error.provider.sdkNotInstalled": "error.provider.sdkNotInstalled",
+    "error.provider.contextCreation": "error.provider.contextCreation",
+    "error.provider.executionFailed": "error.provider.executionFailed",
+    "error.provider.streamFailed": "error.provider.streamFailed"
+  };
+  EXPORT_KEYS = {
+    "export.agentConfiguration": "export.agentConfiguration",
+    "export.metadata": "export.metadata",
+    "export.metaName": "export.metaName",
+    "export.metaVersion": "export.metaVersion",
+    "export.metaOwners": "export.metaOwners",
+    "export.metaModel": "export.metaModel",
+    "export.instructions": "export.instructions",
+    "export.availableTools": "export.availableTools",
+    "export.tools": "export.tools",
+    "export.knowledgeSources": "export.knowledgeSources",
+    "export.policy": "export.policy",
+    "export.additionalContext": "export.additionalContext",
+    "export.configuration": "export.configuration",
+    "export.mcpServers": "export.mcpServers",
+    "export.parameters": "export.parameters",
+    "export.requiresApproval": "export.requiresApproval",
+    "export.notAutomationSafe": "export.notAutomationSafe",
+    "export.requiresApprovalMd": "export.requiresApprovalMd",
+    "export.notAutomationSafeMd": "export.notAutomationSafeMd",
+    "export.required": "export.required",
+    "export.optional": "export.optional",
+    "export.minConfidence": "export.minConfidence",
+    "export.escalationConfigured": "export.escalationConfigured",
+    "export.escalationPolicyConfigured": "export.escalationPolicyConfigured",
+    "export.featureFlags": "export.featureFlags",
+    "export.generatedFrom": "export.generatedFrom",
+    "export.exportedAt": "export.exportedAt",
+    "export.agentType": "export.agentType",
+    "export.noDescription": "export.noDescription",
+    "export.validation.requiresKey": "export.validation.requiresKey",
+    "export.validation.requiresInstructions": "export.validation.requiresInstructions",
+    "export.validation.requiresTool": "export.validation.requiresTool",
+    "export.validation.toolRequiresName": "export.validation.toolRequiresName",
+    "export.validation.toolRequiresDescOrName": "export.validation.toolRequiresDescOrName",
+    "export.validation.toolInvalidName": "export.validation.toolInvalidName",
+    "export.agentType.build": "export.agentType.build",
+    "export.agentType.plan": "export.agentType.plan",
+    "export.agentType.general": "export.agentType.general",
+    "export.agentType.explore": "export.agentType.explore",
+    "export.bridge.requiresApproval": "export.bridge.requiresApproval",
+    "export.bridge.askMode": "export.bridge.askMode"
+  };
+  APPROVAL_KEYS = {
+    "approval.toolRequiresApproval": "approval.toolRequiresApproval"
+  };
+  LOG_KEYS = {
+    "log.unifiedAgent.fallback": "log.unifiedAgent.fallback",
+    "log.knowledge.spaceNotAvailable": "log.knowledge.spaceNotAvailable",
+    "log.knowledge.loadFailed": "log.knowledge.loadFailed",
+    "log.knowledge.queryFailed": "log.knowledge.queryFailed",
+    "log.mcpServer.started": "log.mcpServer.started",
+    "log.mcpServer.stopped": "log.mcpServer.stopped"
+  };
+  I18N_KEYS = {
+    ...AGENT_KEYS,
+    ...KNOWLEDGE_KEYS,
+    ...TOOL_KEYS,
+    ...INTEROP_KEYS,
+    ...ERROR_KEYS,
+    ...EXPORT_KEYS,
+    ...APPROVAL_KEYS,
+    ...LOG_KEYS
+  };
+});
+init_keys();
+
+export {
+  TOOL_KEYS,
+  LOG_KEYS,
+  KNOWLEDGE_KEYS,
+  INTEROP_KEYS,
+  I18N_KEYS,
+  EXPORT_KEYS,
+  ERROR_KEYS,
+  APPROVAL_KEYS,
+  AGENT_KEYS
+};

package/dist/i18n/locale.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Locale resolution and configuration for the ai-agent i18n system.
+ *
+ * Locale priority: runtime override > spec-level > DEFAULT_LOCALE
+ *
+ * @module i18n/locale
+ */
+/** Default locale when none is specified */
+export declare const DEFAULT_LOCALE = "en";
+/** Supported locales shipped with the ai-agent package */
+export declare const SUPPORTED_LOCALES: readonly ["en", "fr", "es"];
+/** Type for supported locales */
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+/**
+ * Resolve the effective locale from spec-level and runtime overrides.
+ *
+ * Priority (highest wins):
+ *   1. runtimeLocale (from AgentCallOptions.locale)
+ *   2. specLocale    (from AgentSpec.locale)
+ *   3. DEFAULT_LOCALE ("en")
+ *
+ * If the resolved locale is not in SUPPORTED_LOCALES, falls back
+ * to the base language (e.g., "fr-CA" -> "fr") or DEFAULT_LOCALE.
+ *
+ * @param specLocale    - Locale from the agent spec definition
+ * @param runtimeLocale - Locale override passed at execution time
+ * @returns The effective locale string
+ */
+export declare function resolveLocale(specLocale?: string, runtimeLocale?: string): string;
+/**
+ * Check if a locale string is one of the supported locales.
+ */
+export declare function isSupportedLocale(locale: string): locale is SupportedLocale;

package/dist/i18n/locale.js

@@ -0,0 +1,41 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// 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"];
+});
+init_locale();
+
+export {
+  resolveLocale,
+  isSupportedLocale,
+  SUPPORTED_LOCALES,
+  DEFAULT_LOCALE
+};

package/dist/i18n/messages.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Translation helper for the ai-agent package.
+ *
+ * Provides a lightweight `t()` function that resolves message keys
+ * to translated strings using the TranslationRegistry from
+ * @contractspec/lib.contracts-spec.
+ *
+ * @module i18n/messages
+ */
+import type { AgentMessageKey } from './keys';
+/**
+ * Interface for the agent i18n helper.
+ */
+export interface AgentI18n {
+    /**
+     * Translate a message key, with optional placeholder interpolation.
+     *
+     * @param key    - A key from I18N_KEYS
+     * @param params - Optional placeholder values to interpolate
+     * @returns The translated string (falls back to English, then to the key itself)
+     *
+     * @example
+     * ```ts
+     * const i18n = createAgentI18n("fr");
+     * i18n.t("error.missingToolHandler", { name: "search" });
+     * // => "Gestionnaire manquant pour l'outil : search"
+     * ```
+     */
+    t(key: AgentMessageKey | string, params?: Record<string, string | number>): string;
+    /** The effective locale being used */
+    readonly locale: string;
+}
+/**
+ * Create an AgentI18n instance for a given locale.
+ *
+ * The locale is resolved through the standard priority chain:
+ *   runtimeLocale > specLocale > DEFAULT_LOCALE ("en")
+ *
+ * @param specLocale    - Locale from the agent spec (optional)
+ * @param runtimeLocale - Runtime locale override (optional)
+ * @returns An AgentI18n instance bound to the resolved locale
+ *
+ * @example
+ * ```ts
+ * // Use spec locale
+ * const i18n = createAgentI18n("fr");
+ *
+ * // Use runtime override
+ * const i18n = createAgentI18n("fr", "es"); // resolves to "es"
+ *
+ * // Use default
+ * const i18n = createAgentI18n(); // resolves to "en"
+ * ```
+ */
+export declare function createAgentI18n(specLocale?: string, runtimeLocale?: string): AgentI18n;
+/**
+ * Convenience: create a default (English) i18n instance.
+ * Useful in contexts where no locale information is available.
+ */
+export declare function getDefaultI18n(): AgentI18n;
+/**
+ * Reset the shared registry (useful for testing).
+ * @internal
+ */
+export declare function resetI18nRegistry(): void;