@open-mercato/ai-assistant 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/dist/modules/ai_assistant/lib/ai-overrides.js

@@ -0,0 +1,189 @@
+import {
+  registerModuleOverrideApplier
+} from "@open-mercato/shared/modules/overrides";
+const programmaticAgentOverrides = {};
+const programmaticToolOverrides = {};
+const programmaticAgentExtensions = [];
+const modulesConfigAgentOverrides = {};
+const modulesConfigToolOverrides = {};
+const modulesConfigAgentExtensions = [];
+function applyAiAgentOverrides(overrides) {
+  for (const [id, value] of Object.entries(overrides)) {
+    programmaticAgentOverrides[id] = value;
+  }
+}
+function applyAiToolOverrides(overrides) {
+  for (const [name, value] of Object.entries(overrides)) {
+    programmaticToolOverrides[name] = value;
+  }
+}
+function applyAiAgentExtensions(extensions) {
+  programmaticAgentExtensions.push(...extensions);
+}
+function applyAiOverridesFromEnabledModules(modules) {
+  for (const entry of modules) {
+    if (!entry || typeof entry.id !== "string" || !entry.id) continue;
+    const ai = entry.overrides?.ai;
+    if (!ai || typeof ai !== "object") continue;
+    if (ai.agents && typeof ai.agents === "object") {
+      for (const [id, value] of Object.entries(ai.agents)) {
+        modulesConfigAgentOverrides[id] = value;
+      }
+    }
+    if (ai.tools && typeof ai.tools === "object") {
+      for (const [name, value] of Object.entries(ai.tools)) {
+        modulesConfigToolOverrides[name] = value;
+      }
+    }
+    if (Array.isArray(ai.extensions)) {
+      modulesConfigAgentExtensions.push(...ai.extensions);
+    }
+  }
+}
+function applyAiOverridesDispatcherEntries(entries) {
+  applyAiOverridesFromEnabledModules(
+    entries.map((entry) => ({
+      id: entry.moduleId,
+      overrides: { ai: entry.overrides }
+    }))
+  );
+}
+registerModuleOverrideApplier(
+  "ai",
+  (entries) => {
+    applyAiOverridesDispatcherEntries(entries);
+  }
+);
+function resetProgrammaticOverridesForTests() {
+  for (const key of Object.keys(programmaticAgentOverrides)) {
+    delete programmaticAgentOverrides[key];
+  }
+  for (const key of Object.keys(programmaticToolOverrides)) {
+    delete programmaticToolOverrides[key];
+  }
+  for (const key of Object.keys(modulesConfigAgentOverrides)) {
+    delete modulesConfigAgentOverrides[key];
+  }
+  for (const key of Object.keys(modulesConfigToolOverrides)) {
+    delete modulesConfigToolOverrides[key];
+  }
+  programmaticAgentExtensions.length = 0;
+  modulesConfigAgentExtensions.length = 0;
+}
+function composeAgentOverrideMap(fileEntries) {
+  const out = {};
+  for (const entry of fileEntries) {
+    const overrides = entry?.overrides;
+    if (!overrides || typeof overrides !== "object") continue;
+    for (const [id, value] of Object.entries(overrides)) {
+      if (typeof id !== "string" || !id) continue;
+      out[id] = value;
+    }
+  }
+  for (const [id, value] of Object.entries(modulesConfigAgentOverrides)) {
+    out[id] = value;
+  }
+  for (const [id, value] of Object.entries(programmaticAgentOverrides)) {
+    out[id] = value;
+  }
+  return out;
+}
+function composeToolOverrideMap(fileEntries) {
+  const out = {};
+  for (const entry of fileEntries) {
+    const overrides = entry?.overrides;
+    if (!overrides || typeof overrides !== "object") continue;
+    for (const [name, value] of Object.entries(overrides)) {
+      if (typeof name !== "string" || !name) continue;
+      out[name] = value;
+    }
+  }
+  for (const [name, value] of Object.entries(modulesConfigToolOverrides)) {
+    out[name] = value;
+  }
+  for (const [name, value] of Object.entries(programmaticToolOverrides)) {
+    out[name] = value;
+  }
+  return out;
+}
+function composeAgentExtensionEntries(fileEntries) {
+  const out = [];
+  for (const entry of fileEntries) {
+    if (Array.isArray(entry?.extensions)) out.push(...entry.extensions);
+  }
+  out.push(...modulesConfigAgentExtensions);
+  out.push(...programmaticAgentExtensions);
+  return out;
+}
+function applyAgentOverrideMap(base, overrides) {
+  if (!overrides || Object.keys(overrides).length === 0) return base.slice();
+  const byId = /* @__PURE__ */ new Map();
+  for (const agent of base) {
+    if (agent && typeof agent.id === "string" && agent.id) {
+      byId.set(agent.id, agent);
+    }
+  }
+  for (const [id, value] of Object.entries(overrides)) {
+    if (!byId.has(id) && value !== null) {
+      console.warn(
+        `[AI Overrides] Override registers a new agent "${id}" \u2014 no base entry to replace.`
+      );
+    }
+    if (value === null) {
+      byId.delete(id);
+      continue;
+    }
+    if (!value || typeof value.id !== "string" || value.id !== id) {
+      console.warn(
+        `[AI Overrides] Skipping malformed agent override for id "${id}" \u2014 id mismatch or missing fields.`
+      );
+      continue;
+    }
+    byId.set(id, value);
+  }
+  return Array.from(byId.values());
+}
+function applyToolOverrideMap(base, overrides) {
+  const out = new Map(base);
+  if (!overrides) return out;
+  for (const [name, value] of Object.entries(overrides)) {
+    if (value === null) {
+      out.delete(name);
+      continue;
+    }
+    if (value === void 0) continue;
+    if (!value || typeof value.name !== "string" || value.name !== name) {
+      console.warn(
+        `[AI Overrides] Skipping malformed tool override for name "${name}" \u2014 name mismatch or missing fields.`
+      );
+      continue;
+    }
+    out.set(name, value);
+  }
+  return out;
+}
+function snapshotProgrammaticOverrides() {
+  return {
+    agents: { ...programmaticAgentOverrides },
+    tools: { ...programmaticToolOverrides },
+    modulesConfigAgents: { ...modulesConfigAgentOverrides },
+    modulesConfigTools: { ...modulesConfigToolOverrides },
+    agentExtensions: programmaticAgentExtensions.slice(),
+    modulesConfigAgentExtensions: modulesConfigAgentExtensions.slice()
+  };
+}
+export {
+  applyAgentOverrideMap,
+  applyAiAgentExtensions,
+  applyAiAgentOverrides,
+  applyAiOverridesDispatcherEntries,
+  applyAiOverridesFromEnabledModules,
+  applyAiToolOverrides,
+  applyToolOverrideMap,
+  composeAgentExtensionEntries,
+  composeAgentOverrideMap,
+  composeToolOverrideMap,
+  resetProgrammaticOverridesForTests,
+  snapshotProgrammaticOverrides
+};
+//# sourceMappingURL=ai-overrides.js.map

package/dist/modules/ai_assistant/lib/ai-overrides.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/ai_assistant/lib/ai-overrides.ts"],
+  "sourcesContent": ["import {\n  registerModuleOverrideApplier,\n  type ModuleOverrideEntry,\n} from '@open-mercato/shared/modules/overrides'\n\n/**\n * Module-to-module override pipeline for AI agents and AI tools.\n *\n * Modules contribute overrides through two surfaces:\n *\n * 1. Per-module: declare additional `aiAgentOverrides` / `aiToolOverrides`\n *    exports in the existing `<module>/ai-agents.ts` / `<module>/ai-tools.ts`\n *    files (no separate `ai-overrides.ts` file). The generator picks the\n *    exports up alongside `aiAgents` / `aiTools` and emits override entries\n *    inside `apps/<app>/.mercato/generated/ai-agents.generated.ts`\n *    (`aiAgentOverrideEntries`) and `ai-tools.generated.ts`\n *    (`aiToolOverrideEntries`).\n *\n * 2. App-level: declare `aiAgentOverrides` / `aiToolOverrides` directly on a\n *    `ModuleEntry` inside the app's `src/modules.ts`. {@link\n *    applyAiOverridesFromEnabledModules} feeds these into the runtime; they\n *    sit one tier higher than the per-module file-based entries but below\n *    explicit programmatic calls.\n *\n * Tests and bootstrap code can also override imperatively via\n * {@link applyAiAgentOverrides} and {@link applyAiToolOverrides}, which\n * supersede every other tier and persist for the process lifetime.\n *\n * `null` always means \"remove from the registry\"; a definition replaces.\n *\n * @see ../../../../../../.ai/specs/2026-04-30-ai-overrides-and-module-disable.md\n */\nimport type { AiAgentDefinition, AiAgentExtension } from './ai-agent-definition'\nimport type { AiToolDefinition } from './types'\n\n/** Override for a single agent: replace with a definition or remove with `null`. */\nexport type AiAgentOverride = AiAgentDefinition | null\n\n/** Override for a single tool: replace with a definition or remove with `null`. */\nexport type AiToolOverride = AiToolDefinition | null\n\n/** Map of agent id \u2192 override. Used in the per-module `ai-agents.ts` file. */\nexport type AiAgentOverridesMap = Record<string, AiAgentOverride>\n\n/** Map of tool name \u2192 override. Used in the per-module `ai-tools.ts` file. */\nexport type AiToolOverridesMap = Record<string, AiToolOverride>\n\n/**\n * Per-entry shape produced by the agent generator. Mirrors the per-module\n * record format used elsewhere in the registry generators so the file\n * stays grep-friendly.\n */\nexport interface AiAgentOverrideConfigEntry {\n  moduleId: string\n  overrides: AiAgentOverridesMap\n}\n\nexport interface AiAgentExtensionConfigEntry {\n  moduleId: string\n  extensions: AiAgentExtension[]\n}\n\n/**\n * Per-entry shape produced by the tool generator. Same record format as\n * {@link AiAgentOverrideConfigEntry}, but with tool definitions.\n */\nexport interface AiToolOverrideConfigEntry {\n  moduleId: string\n  overrides: AiToolOverridesMap\n}\n\n/** Shape of the `entry.overrides.ai` sub-tree on a `modules.ts` entry. */\nexport interface AiModuleOverridesShape {\n  agents?: AiAgentOverridesMap\n  tools?: AiToolOverridesMap\n  extensions?: AiAgentExtension[]\n}\n\n/** Shape of a `modules.ts` `ModuleEntry` with the umbrella `overrides.ai`. */\nexport interface EnabledModuleAiOverrides {\n  id: string\n  overrides?: { ai?: AiModuleOverridesShape }\n}\n\nconst programmaticAgentOverrides: AiAgentOverridesMap = {}\nconst programmaticToolOverrides: AiToolOverridesMap = {}\nconst programmaticAgentExtensions: AiAgentExtension[] = []\n\nconst modulesConfigAgentOverrides: AiAgentOverridesMap = {}\nconst modulesConfigToolOverrides: AiToolOverridesMap = {}\nconst modulesConfigAgentExtensions: AiAgentExtension[] = []\n\n/**\n * Apply programmatic agent overrides \u2014 survive after the registries load\n * and take precedence over both file-based and `modules.ts`-tier overrides\n * for the same id.\n *\n * @example\n * ```ts\n * applyAiAgentOverrides({\n *   'catalog.catalog_assistant': null,           // disable\n *   'catalog.merchandising_assistant': customAgent,  // replace\n * })\n * ```\n */\nexport function applyAiAgentOverrides(overrides: AiAgentOverridesMap): void {\n  for (const [id, value] of Object.entries(overrides)) {\n    programmaticAgentOverrides[id] = value\n  }\n}\n\n/**\n * Apply programmatic tool overrides \u2014 survive after the registries load\n * and take precedence over both file-based and `modules.ts`-tier overrides\n * for the same name.\n */\nexport function applyAiToolOverrides(overrides: AiToolOverridesMap): void {\n  for (const [name, value] of Object.entries(overrides)) {\n    programmaticToolOverrides[name] = value\n  }\n}\n\n/**\n * Apply programmatic additive agent extensions. Extensions append to an\n * already-registered agent after replacements/disable overrides resolve.\n */\nexport function applyAiAgentExtensions(extensions: readonly AiAgentExtension[]): void {\n  programmaticAgentExtensions.push(...extensions)\n}\n\n/**\n * Walk a list of `enabledModules` entries (the `apps/<app>/src/modules.ts`\n * shape) and register their `overrides.ai.agents` / `overrides.ai.tools`\n * into the `modules.ts` tier. Tier precedence (highest first):\n *\n *   1. {@link applyAiAgentOverrides} / {@link applyAiToolOverrides}\n *   2. `modules.ts` inline (this function)\n *   3. `<module>/ai-agents.ts` `aiAgentOverrides` / `<module>/ai-tools.ts`\n *      `aiToolOverrides`\n *   4. base `aiAgents` / `aiTools`\n *\n * Calling this multiple times is additive: later calls overlay on the\n * existing tier (last wins per id). Use only at boot time \u2014 re-entering\n * mid-request blurs the resolution order.\n *\n * In practice this is invoked from `applyModuleOverridesFromEnabledModules`\n * (the umbrella dispatcher in `@open-mercato/shared/modules/overrides`)\n * via the registered `'ai'` applier; downstream apps call the dispatcher\n * once from `bootstrap.ts`. The standalone signature is kept for tests\n * and ad-hoc use.\n */\nexport function applyAiOverridesFromEnabledModules(\n  modules: ReadonlyArray<EnabledModuleAiOverrides>,\n): void {\n  for (const entry of modules) {\n    if (!entry || typeof entry.id !== 'string' || !entry.id) continue\n    const ai = entry.overrides?.ai\n    if (!ai || typeof ai !== 'object') continue\n    if (ai.agents && typeof ai.agents === 'object') {\n      for (const [id, value] of Object.entries(ai.agents)) {\n        modulesConfigAgentOverrides[id] = value as AiAgentOverride\n      }\n    }\n    if (ai.tools && typeof ai.tools === 'object') {\n      for (const [name, value] of Object.entries(ai.tools)) {\n        modulesConfigToolOverrides[name] = value as AiToolOverride\n      }\n    }\n    if (Array.isArray(ai.extensions)) {\n      modulesConfigAgentExtensions.push(...ai.extensions)\n    }\n  }\n}\n\n/**\n * Bucketed entry shape passed to the umbrella dispatcher's per-domain\n * applier. Each entry carries one module's `overrides.ai` sub-tree.\n */\ntype AiOverrideEntryFromDispatcher = {\n  moduleId: string\n  overrides: AiModuleOverridesShape\n}\n\n/**\n * Applier registered with `@open-mercato/shared/modules/overrides` for\n * the `'ai'` domain. The dispatcher hands us per-module entries already\n * scoped to `overrides.ai`; we re-shape into `EnabledModuleAiOverrides`\n * and reuse {@link applyAiOverridesFromEnabledModules} so the AI tier\n * has exactly one code path.\n */\nexport function applyAiOverridesDispatcherEntries(\n  entries: ReadonlyArray<AiOverrideEntryFromDispatcher>,\n): void {\n  applyAiOverridesFromEnabledModules(\n    entries.map((entry) => ({\n      id: entry.moduleId,\n      overrides: { ai: entry.overrides },\n    })),\n  )\n}\n\n// Side-effect: register the `'ai'` applier on first module load so the\n// umbrella dispatcher in `@open-mercato/shared/modules/overrides` can\n// route `entry.overrides.ai` here. Any consumer that imports\n// `@open-mercato/ai-assistant` (which apps do via `bootstrap.ts`) gets\n// the registration for free \u2014 no second import needed.\nregisterModuleOverrideApplier<AiModuleOverridesShape>(\n  'ai',\n  (entries: ReadonlyArray<ModuleOverrideEntry<AiModuleOverridesShape>>) => {\n    applyAiOverridesDispatcherEntries(entries)\n  },\n)\n\n/** @__internal Test-only hook \u2014 reset programmatic + modules.ts override state. */\nexport function resetProgrammaticOverridesForTests(): void {\n  for (const key of Object.keys(programmaticAgentOverrides)) {\n    delete programmaticAgentOverrides[key]\n  }\n  for (const key of Object.keys(programmaticToolOverrides)) {\n    delete programmaticToolOverrides[key]\n  }\n  for (const key of Object.keys(modulesConfigAgentOverrides)) {\n    delete modulesConfigAgentOverrides[key]\n  }\n  for (const key of Object.keys(modulesConfigToolOverrides)) {\n    delete modulesConfigToolOverrides[key]\n  }\n  programmaticAgentExtensions.length = 0\n  modulesConfigAgentExtensions.length = 0\n}\n\n/**\n * Resolve the final agent override map from a list of file-based entries\n * plus the `modules.ts` and programmatic state.\n *\n * Resolution order (lowest precedence \u2192 highest):\n *   1. file entries in module load order\n *   2. modules.ts entries\n *   3. programmatic\n */\nexport function composeAgentOverrideMap(\n  fileEntries: readonly AiAgentOverrideConfigEntry[],\n): AiAgentOverridesMap {\n  const out: AiAgentOverridesMap = {}\n  for (const entry of fileEntries) {\n    const overrides = entry?.overrides\n    if (!overrides || typeof overrides !== 'object') continue\n    for (const [id, value] of Object.entries(overrides)) {\n      if (typeof id !== 'string' || !id) continue\n      out[id] = value as AiAgentOverride\n    }\n  }\n  for (const [id, value] of Object.entries(modulesConfigAgentOverrides)) {\n    out[id] = value\n  }\n  for (const [id, value] of Object.entries(programmaticAgentOverrides)) {\n    out[id] = value\n  }\n  return out\n}\n\n/**\n * Resolve the final tool override map from a list of file-based entries\n * plus the `modules.ts` and programmatic state.\n */\nexport function composeToolOverrideMap(\n  fileEntries: readonly AiToolOverrideConfigEntry[],\n): AiToolOverridesMap {\n  const out: AiToolOverridesMap = {}\n  for (const entry of fileEntries) {\n    const overrides = entry?.overrides\n    if (!overrides || typeof overrides !== 'object') continue\n    for (const [name, value] of Object.entries(overrides)) {\n      if (typeof name !== 'string' || !name) continue\n      out[name] = value as AiToolOverride\n    }\n  }\n  for (const [name, value] of Object.entries(modulesConfigToolOverrides)) {\n    out[name] = value\n  }\n  for (const [name, value] of Object.entries(programmaticToolOverrides)) {\n    out[name] = value\n  }\n  return out\n}\n\nexport function composeAgentExtensionEntries(\n  fileEntries: readonly AiAgentExtensionConfigEntry[],\n): AiAgentExtension[] {\n  const out: AiAgentExtension[] = []\n  for (const entry of fileEntries) {\n    if (Array.isArray(entry?.extensions)) out.push(...entry.extensions)\n  }\n  out.push(...modulesConfigAgentExtensions)\n  out.push(...programmaticAgentExtensions)\n  return out\n}\n\n/**\n * Apply an agent override map to a base list. Returns a new array.\n * `null` removes the entry; a non-null override replaces it. Override\n * entries naming an id that is not in `base` log a structured warning so\n * an operator can spot stale override files.\n */\nexport function applyAgentOverrideMap(\n  base: readonly AiAgentDefinition[],\n  overrides: AiAgentOverridesMap,\n): AiAgentDefinition[] {\n  if (!overrides || Object.keys(overrides).length === 0) return base.slice()\n  const byId = new Map<string, AiAgentDefinition>()\n  for (const agent of base) {\n    if (agent && typeof agent.id === 'string' && agent.id) {\n      byId.set(agent.id, agent)\n    }\n  }\n  for (const [id, value] of Object.entries(overrides)) {\n    if (!byId.has(id) && value !== null) {\n      // Allow registering a brand-new agent through the override surface\n      // \u2014 useful for app-level \"synthetic\" agents without authoring a\n      // module file. Warn at the structured logger so the operator\n      // notices a stale id slipping through.\n      console.warn(\n        `[AI Overrides] Override registers a new agent \"${id}\" \u2014 no base entry to replace.`,\n      )\n    }\n    if (value === null) {\n      byId.delete(id)\n      continue\n    }\n    if (!value || typeof value.id !== 'string' || value.id !== id) {\n      console.warn(\n        `[AI Overrides] Skipping malformed agent override for id \"${id}\" \u2014 id mismatch or missing fields.`,\n      )\n      continue\n    }\n    byId.set(id, value)\n  }\n  return Array.from(byId.values())\n}\n\n/**\n * Apply a tool override map to a base map. Returns a new Map.\n * `null` removes the entry; a non-null override replaces it.\n */\nexport function applyToolOverrideMap<TTool extends { name: string }>(\n  base: ReadonlyMap<string, TTool>,\n  overrides: Record<string, TTool | null | undefined>,\n): Map<string, TTool> {\n  const out = new Map<string, TTool>(base)\n  if (!overrides) return out\n  for (const [name, value] of Object.entries(overrides)) {\n    if (value === null) {\n      out.delete(name)\n      continue\n    }\n    if (value === undefined) continue\n    if (!value || typeof (value as TTool).name !== 'string' || (value as TTool).name !== name) {\n      console.warn(\n        `[AI Overrides] Skipping malformed tool override for name \"${name}\" \u2014 name mismatch or missing fields.`,\n      )\n      continue\n    }\n    out.set(name, value as TTool)\n  }\n  return out\n}\n\n/**\n * @__internal \u2014 read the snapshot of programmatic + modules.ts overrides.\n * Used by tests and by the diagnostic helper that reports which overrides\n * are in effect.\n */\nexport function snapshotProgrammaticOverrides(): {\n  agents: Readonly<AiAgentOverridesMap>\n  tools: Readonly<AiToolOverridesMap>\n  modulesConfigAgents: Readonly<AiAgentOverridesMap>\n  modulesConfigTools: Readonly<AiToolOverridesMap>\n  agentExtensions: readonly AiAgentExtension[]\n  modulesConfigAgentExtensions: readonly AiAgentExtension[]\n} {\n  return {\n    agents: { ...programmaticAgentOverrides },\n    tools: { ...programmaticToolOverrides },\n    modulesConfigAgents: { ...modulesConfigAgentOverrides },\n    modulesConfigTools: { ...modulesConfigToolOverrides },\n    agentExtensions: programmaticAgentExtensions.slice(),\n    modulesConfigAgentExtensions: modulesConfigAgentExtensions.slice(),\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/ai_assistant/lib/ai-tool-definition.js

@@ -0,0 +1,7 @@
+function defineAiTool(tool) {
+  return tool;
+}
+export {
+  defineAiTool
+};
+//# sourceMappingURL=ai-tool-definition.js.map

package/dist/modules/ai_assistant/lib/ai-tool-definition.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/ai_assistant/lib/ai-tool-definition.ts"],
+  "sourcesContent": ["import type { AiToolDefinition } from './types'\n\nexport function defineAiTool<TInput = unknown, TOutput = unknown>(\n  tool: AiToolDefinition<TInput, TOutput>,\n): AiToolDefinition<TInput, TOutput> {\n  return tool\n}\n"],
+  "mappings": "AAEO,SAAS,aACd,MACmC;AACnC,SAAO;AACT;",
+  "names": []
+}

package/dist/modules/ai_assistant/lib/ai-tools-generated.d.js

@@ -0,0 +1 @@
+//# sourceMappingURL=ai-tools-generated.d.js.map

package/dist/modules/ai_assistant/lib/ai-tools-generated.d.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/modules/ai_assistant/lib/api-backed-tool.js

@@ -0,0 +1,48 @@
+import { defineAiTool } from "./ai-tool-definition.js";
+import {
+  createAiApiOperationRunner
+} from "./ai-api-operation-runner.js";
+function defineApiBackedAiTool(config) {
+  const {
+    name,
+    displayName,
+    description,
+    inputSchema,
+    requiredFeatures,
+    isMutation,
+    toOperation,
+    mapResponse,
+    loadBeforeRecord,
+    loadBeforeRecords
+  } = config;
+  let definition;
+  const handler = async (input, context) => {
+    const toolCtx = {
+      ...context,
+      tool: definition
+    };
+    const operation = await toOperation(input, toolCtx);
+    const runner = createAiApiOperationRunner(toolCtx);
+    const response = await runner.run(operation);
+    if (!response.success) {
+      throw new Error(response.error ?? `API operation failed for tool "${name}"`);
+    }
+    return await mapResponse(response, input, toolCtx);
+  };
+  definition = defineAiTool({
+    name,
+    description,
+    inputSchema,
+    requiredFeatures,
+    handler,
+    ...displayName !== void 0 ? { displayName } : {},
+    ...isMutation !== void 0 ? { isMutation } : {},
+    ...loadBeforeRecord !== void 0 ? { loadBeforeRecord } : {},
+    ...loadBeforeRecords !== void 0 ? { loadBeforeRecords } : {}
+  });
+  return definition;
+}
+export {
+  defineApiBackedAiTool
+};
+//# sourceMappingURL=api-backed-tool.js.map

package/dist/modules/ai_assistant/lib/api-backed-tool.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/ai_assistant/lib/api-backed-tool.ts"],
+  "sourcesContent": ["// Phase 2 of spec 2026-04-27-ai-tools-api-backed-dry-refactor.md.\n//\n// Sugar over `defineAiTool` that wires the in-process API operation runner so\n// typed AI tools can reuse documented API route logic without HTTP, fetch, or\n// a second RBAC pass. The synthesized handler delegates to\n// `createAiApiOperationRunner(ctx).run(toOperation(input, ctx))` and pipes the\n// response through `mapResponse(...)`. All other tool-runtime concerns\n// (registry indexing, schema serialization, mutation policy, pending-action\n// flow, `loadBeforeRecord(s)`, telemetry) remain owned by `defineAiTool`.\nimport type { z } from 'zod'\nimport { defineAiTool } from './ai-tool-definition'\nimport {\n  createAiApiOperationRunner,\n  type AiApiOperationRequest,\n  type AiApiOperationResponse,\n  type AiToolExecutionContext,\n} from './ai-api-operation-runner'\nimport type { AiToolDefinition, McpToolContext } from './types'\n\nexport type ApiBackedAiToolConfig<TInput, TApi, TOutput> = {\n  name: string\n  displayName?: string\n  description: string\n  inputSchema: z.ZodType<TInput>\n  requiredFeatures: string[]\n  isMutation?: boolean\n  toOperation: (\n    input: TInput,\n    ctx: AiToolExecutionContext,\n  ) => AiApiOperationRequest | Promise<AiApiOperationRequest>\n  mapResponse: (\n    response: AiApiOperationResponse<TApi>,\n    input: TInput,\n    ctx: AiToolExecutionContext,\n  ) => TOutput | Promise<TOutput>\n  loadBeforeRecord?: AiToolDefinition<TInput, TOutput>['loadBeforeRecord']\n  loadBeforeRecords?: AiToolDefinition<TInput, TOutput>['loadBeforeRecords']\n}\n\nexport function defineApiBackedAiTool<TInput, TApi, TOutput>(\n  config: ApiBackedAiToolConfig<TInput, TApi, TOutput>,\n): AiToolDefinition<TInput, TOutput> {\n  const {\n    name,\n    displayName,\n    description,\n    inputSchema,\n    requiredFeatures,\n    isMutation,\n    toOperation,\n    mapResponse,\n    loadBeforeRecord,\n    loadBeforeRecords,\n  } = config\n\n  let definition: AiToolDefinition<TInput, TOutput>\n\n  const handler = async (input: TInput, context: McpToolContext): Promise<TOutput> => {\n    const toolCtx: AiToolExecutionContext = {\n      ...context,\n      tool: definition as unknown as AiToolDefinition,\n    }\n    const operation = await toOperation(input, toolCtx)\n    const runner = createAiApiOperationRunner(toolCtx)\n    const response = await runner.run<TApi>(operation)\n    if (!response.success) {\n      throw new Error(response.error ?? `API operation failed for tool \"${name}\"`)\n    }\n    return await mapResponse(response, input, toolCtx)\n  }\n\n  definition = defineAiTool<TInput, TOutput>({\n    name,\n    description,\n    inputSchema,\n    requiredFeatures,\n    handler,\n    ...(displayName !== undefined ? { displayName } : {}),\n    ...(isMutation !== undefined ? { isMutation } : {}),\n    ...(loadBeforeRecord !== undefined ? { loadBeforeRecord } : {}),\n    ...(loadBeforeRecords !== undefined ? { loadBeforeRecords } : {}),\n  })\n\n  return definition\n}\n"],
+  "mappings": "AAUA,SAAS,oBAAoB;AAC7B;AAAA,EACE;AAAA,OAIK;AAuBA,SAAS,sBACd,QACmC;AACnC,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,MAAI;AAEJ,QAAM,UAAU,OAAO,OAAe,YAA8C;AAClF,UAAM,UAAkC;AAAA,MACtC,GAAG;AAAA,MACH,MAAM;AAAA,IACR;AACA,UAAM,YAAY,MAAM,YAAY,OAAO,OAAO;AAClD,UAAM,SAAS,2BAA2B,OAAO;AACjD,UAAM,WAAW,MAAM,OAAO,IAAU,SAAS;AACjD,QAAI,CAAC,SAAS,SAAS;AACrB,YAAM,IAAI,MAAM,SAAS,SAAS,kCAAkC,IAAI,GAAG;AAAA,IAC7E;AACA,WAAO,MAAM,YAAY,UAAU,OAAO,OAAO;AAAA,EACnD;AAEA,eAAa,aAA8B;AAAA,IACzC;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAI,gBAAgB,SAAY,EAAE,YAAY,IAAI,CAAC;AAAA,IACnD,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,IACjD,GAAI,qBAAqB,SAAY,EAAE,iBAAiB,IAAI,CAAC;AAAA,IAC7D,GAAI,sBAAsB,SAAY,EAAE,kBAAkB,IAAI,CAAC;AAAA,EACjE,CAAC;AAED,SAAO;AACT;",
+  "names": []
+}

package/dist/modules/ai_assistant/lib/attachment-bridge-types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=attachment-bridge-types.js.map

package/dist/modules/ai_assistant/lib/attachment-bridge-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/modules/ai_assistant/lib/attachment-parts.js

@@ -0,0 +1,276 @@
+import { promises as fs } from "fs";
+import { findOneWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+const DEFAULT_MAX_INLINE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_TEXT_CHARS = 64 * 1024;
+function classifyMediaType(mimeType) {
+  const normalized = (mimeType ?? "").toLowerCase().trim();
+  if (normalized.startsWith("image/")) return "image";
+  if (normalized === "application/pdf") return "pdf";
+  return "file";
+}
+function isTextLikeMime(mimeType) {
+  const normalized = (mimeType ?? "").toLowerCase().trim();
+  if (!normalized) return false;
+  if (normalized.startsWith("text/")) return true;
+  if (normalized === "application/json") return true;
+  if (normalized === "application/xml") return true;
+  if (normalized === "application/x-yaml" || normalized === "text/yaml") return true;
+  if (normalized === "application/csv") return true;
+  return false;
+}
+function truncateText(value, maxChars) {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 16))}
+[... truncated]`;
+}
+function resolveEm(container) {
+  if (!container) return null;
+  try {
+    const candidate = container.resolve("em");
+    return candidate ?? null;
+  } catch {
+    return null;
+  }
+}
+function resolveSigner(container) {
+  if (!container) return null;
+  try {
+    const candidate = container.resolve("attachmentSigner");
+    if (candidate && typeof candidate.sign === "function") {
+      return candidate;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function loadAttachmentRow(em, attachmentId, authContext) {
+  const { Attachment } = await import("@open-mercato/core/modules/attachments/data/entities");
+  const record = await findOneWithDecryption(
+    em,
+    Attachment,
+    { id: attachmentId },
+    void 0,
+    {
+      tenantId: authContext.tenantId,
+      organizationId: authContext.organizationId
+    }
+  );
+  if (!record) return null;
+  const row = record;
+  return {
+    id: row.id,
+    entityId: row.entityId,
+    fileName: row.fileName,
+    mimeType: row.mimeType,
+    fileSize: row.fileSize,
+    storagePath: row.storagePath,
+    storageDriver: row.storageDriver,
+    partitionCode: row.partitionCode,
+    tenantId: row.tenantId ?? null,
+    organizationId: row.organizationId ?? null,
+    content: row.content ?? null
+  };
+}
+function rowBelongsToCaller(row, authContext) {
+  if (authContext.isSuperAdmin) return true;
+  if (row.tenantId && row.tenantId !== authContext.tenantId) return false;
+  if (row.organizationId && row.organizationId !== authContext.organizationId) return false;
+  return true;
+}
+async function readAttachmentBytes(row) {
+  const { resolveAttachmentAbsolutePath } = await import("@open-mercato/core/modules/attachments/lib/storage");
+  const absolutePath = resolveAttachmentAbsolutePath(
+    row.partitionCode,
+    row.storagePath,
+    row.storageDriver
+  );
+  try {
+    const buffer = await fs.readFile(absolutePath);
+    return new Uint8Array(buffer);
+  } catch (error) {
+    console.warn(
+      `[AI Agents] Failed to read attachment ${row.id} from storage; falling back to metadata-only:`,
+      error
+    );
+    return null;
+  }
+}
+async function classifyAndBuildPart(row, mediaClass, maxInlineBytes, maxTextChars, signer, authContext) {
+  const base = {
+    attachmentId: row.id,
+    fileName: row.fileName,
+    mediaType: row.mimeType || "application/octet-stream"
+  };
+  if (mediaClass === "file" && isTextLikeMime(row.mimeType) && typeof row.content === "string" && row.content.length > 0) {
+    return {
+      ...base,
+      source: "text",
+      textContent: truncateText(row.content, maxTextChars)
+    };
+  }
+  if (mediaClass === "image" || mediaClass === "pdf") {
+    if (row.fileSize > 0 && row.fileSize <= maxInlineBytes) {
+      const bytes = await readAttachmentBytes(row);
+      if (bytes) {
+        return {
+          ...base,
+          source: "bytes",
+          data: bytes
+        };
+      }
+    }
+    if (signer) {
+      try {
+        const url = await signer.sign({
+          attachmentId: row.id,
+          fileName: row.fileName,
+          mediaType: row.mimeType,
+          tenantId: authContext.tenantId,
+          organizationId: authContext.organizationId
+        });
+        if (typeof url === "string" && url.length > 0) {
+          return {
+            ...base,
+            source: "signed-url",
+            url
+          };
+        }
+      } catch (error) {
+        console.warn(
+          `[AI Agents] attachmentSigner failed for ${row.id}; falling back to metadata-only:`,
+          error
+        );
+      }
+    }
+    return { ...base, source: "metadata-only" };
+  }
+  return { ...base, source: "metadata-only" };
+}
+async function resolveAttachmentParts(input) {
+  const ids = Array.from(input.attachmentIds ?? []);
+  if (ids.length === 0) return [];
+  const em = resolveEm(input.container);
+  if (!em) {
+    console.warn(
+      "[AI Agents] resolveAttachmentParts called without a DI container exposing `em`; skipping attachment resolution."
+    );
+    return [];
+  }
+  const maxInlineBytes = input.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+  const maxTextChars = input.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS;
+  const signer = resolveSigner(input.container);
+  const acceptedSet = input.acceptedMediaTypes ? new Set(input.acceptedMediaTypes) : null;
+  const parts = [];
+  for (const id of ids) {
+    if (typeof id !== "string" || id.length === 0) continue;
+    let row;
+    try {
+      row = await loadAttachmentRow(em, id, input.authContext);
+    } catch (error) {
+      console.warn(
+        `[AI Agents] Failed to load attachment ${id}; skipping:`,
+        error
+      );
+      continue;
+    }
+    if (!row) {
+      console.warn(`[AI Agents] Attachment ${id} not found; skipping.`);
+      continue;
+    }
+    if (!rowBelongsToCaller(row, input.authContext)) {
+      console.warn(
+        `[AI Agents] Attachment ${id} is out of scope for caller (tenant=${input.authContext.tenantId}, org=${input.authContext.organizationId}); skipping.`
+      );
+      continue;
+    }
+    const mediaClass = classifyMediaType(row.mimeType);
+    if (acceptedSet && !acceptedSet.has(mediaClass)) {
+      console.warn(
+        `[AI Agents] Attachment ${id} (${row.mimeType}) is not in agent acceptedMediaTypes=${[...acceptedSet].join(",")}; skipping.`
+      );
+      continue;
+    }
+    try {
+      const part = await classifyAndBuildPart(
+        row,
+        mediaClass,
+        maxInlineBytes,
+        maxTextChars,
+        signer,
+        input.authContext
+      );
+      parts.push(part);
+    } catch (error) {
+      console.warn(
+        `[AI Agents] Failed to build attachment part for ${id}; skipping:`,
+        error
+      );
+    }
+  }
+  return parts;
+}
+async function resolveAttachmentPartsForAgent(input) {
+  if (!input.attachmentIds || input.attachmentIds.length === 0) return [];
+  return resolveAttachmentParts({
+    attachmentIds: input.attachmentIds,
+    authContext: input.authContext,
+    acceptedMediaTypes: input.agent.acceptedMediaTypes,
+    container: input.container
+  });
+}
+function attachmentPartsToUiFileParts(parts) {
+  const output = [];
+  for (const part of parts) {
+    if (part.source === "bytes" && part.data) {
+      const base64 = toBase64(part.data);
+      if (base64) {
+        output.push({
+          type: "file",
+          mediaType: part.mediaType,
+          filename: part.fileName,
+          url: `data:${part.mediaType};base64,${base64}`
+        });
+      }
+      continue;
+    }
+    if (part.source === "signed-url" && typeof part.url === "string" && part.url.length > 0) {
+      output.push({
+        type: "file",
+        mediaType: part.mediaType,
+        filename: part.fileName,
+        url: part.url
+      });
+    }
+  }
+  return output;
+}
+function summarizeAttachmentPartsForPrompt(parts) {
+  if (parts.length === 0) return null;
+  const lines = ["[ATTACHMENTS]"];
+  for (const part of parts) {
+    const header = `- ${part.fileName} (${part.mediaType}, source=${part.source})`;
+    if (part.source === "text" && typeof part.textContent === "string" && part.textContent.length > 0) {
+      lines.push(header);
+      lines.push(part.textContent);
+    } else {
+      lines.push(header);
+    }
+  }
+  return lines.join("\n");
+}
+function toBase64(data) {
+  if (typeof data === "string") return data;
+  try {
+    return Buffer.from(data).toString("base64");
+  } catch {
+    return null;
+  }
+}
+export {
+  attachmentPartsToUiFileParts,
+  resolveAttachmentParts,
+  resolveAttachmentPartsForAgent,
+  summarizeAttachmentPartsForPrompt
+};
+//# sourceMappingURL=attachment-parts.js.map