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

package/src/modules/ai_assistant/lib/ai-overrides.ts

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

package/src/modules/ai_assistant/lib/ai-tool-definition.ts

@@ -0,0 +1,7 @@
+import type { AiToolDefinition } from './types'
+
+export function defineAiTool<TInput = unknown, TOutput = unknown>(
+  tool: AiToolDefinition<TInput, TOutput>,
+): AiToolDefinition<TInput, TOutput> {
+  return tool
+}

package/src/modules/ai_assistant/lib/ai-tools-generated.d.ts

@@ -0,0 +1,7 @@
+declare module '@/.mercato/generated/ai-tools.generated' {
+  export const aiToolConfigEntries: Array<{
+    moduleId: string
+    tools: unknown[]
+  }>
+  export const allAiTools: unknown[]
+}

package/src/modules/ai_assistant/lib/api-backed-tool.ts

@@ -0,0 +1,85 @@
+// Phase 2 of spec 2026-04-27-ai-tools-api-backed-dry-refactor.md.
+//
+// Sugar over `defineAiTool` that wires the in-process API operation runner so
+// typed AI tools can reuse documented API route logic without HTTP, fetch, or
+// a second RBAC pass. The synthesized handler delegates to
+// `createAiApiOperationRunner(ctx).run(toOperation(input, ctx))` and pipes the
+// response through `mapResponse(...)`. All other tool-runtime concerns
+// (registry indexing, schema serialization, mutation policy, pending-action
+// flow, `loadBeforeRecord(s)`, telemetry) remain owned by `defineAiTool`.
+import type { z } from 'zod'
+import { defineAiTool } from './ai-tool-definition'
+import {
+  createAiApiOperationRunner,
+  type AiApiOperationRequest,
+  type AiApiOperationResponse,
+  type AiToolExecutionContext,
+} from './ai-api-operation-runner'
+import type { AiToolDefinition, McpToolContext } from './types'
+
+export type ApiBackedAiToolConfig<TInput, TApi, TOutput> = {
+  name: string
+  displayName?: string
+  description: string
+  inputSchema: z.ZodType<TInput>
+  requiredFeatures: string[]
+  isMutation?: boolean
+  toOperation: (
+    input: TInput,
+    ctx: AiToolExecutionContext,
+  ) => AiApiOperationRequest | Promise<AiApiOperationRequest>
+  mapResponse: (
+    response: AiApiOperationResponse<TApi>,
+    input: TInput,
+    ctx: AiToolExecutionContext,
+  ) => TOutput | Promise<TOutput>
+  loadBeforeRecord?: AiToolDefinition<TInput, TOutput>['loadBeforeRecord']
+  loadBeforeRecords?: AiToolDefinition<TInput, TOutput>['loadBeforeRecords']
+}
+
+export function defineApiBackedAiTool<TInput, TApi, TOutput>(
+  config: ApiBackedAiToolConfig<TInput, TApi, TOutput>,
+): AiToolDefinition<TInput, TOutput> {
+  const {
+    name,
+    displayName,
+    description,
+    inputSchema,
+    requiredFeatures,
+    isMutation,
+    toOperation,
+    mapResponse,
+    loadBeforeRecord,
+    loadBeforeRecords,
+  } = config
+
+  let definition: AiToolDefinition<TInput, TOutput>
+
+  const handler = async (input: TInput, context: McpToolContext): Promise<TOutput> => {
+    const toolCtx: AiToolExecutionContext = {
+      ...context,
+      tool: definition as unknown as AiToolDefinition,
+    }
+    const operation = await toOperation(input, toolCtx)
+    const runner = createAiApiOperationRunner(toolCtx)
+    const response = await runner.run<TApi>(operation)
+    if (!response.success) {
+      throw new Error(response.error ?? `API operation failed for tool "${name}"`)
+    }
+    return await mapResponse(response, input, toolCtx)
+  }
+
+  definition = defineAiTool<TInput, TOutput>({
+    name,
+    description,
+    inputSchema,
+    requiredFeatures,
+    handler,
+    ...(displayName !== undefined ? { displayName } : {}),
+    ...(isMutation !== undefined ? { isMutation } : {}),
+    ...(loadBeforeRecord !== undefined ? { loadBeforeRecord } : {}),
+    ...(loadBeforeRecords !== undefined ? { loadBeforeRecords } : {}),
+  })
+
+  return definition
+}

package/src/modules/ai_assistant/lib/attachment-bridge-types.ts

@@ -0,0 +1,24 @@
+export type AttachmentSource = 'bytes' | 'signed-url' | 'text' | 'metadata-only'
+
+export interface AiResolvedAttachmentPart {
+  attachmentId: string
+  fileName: string
+  mediaType: string
+  source: AttachmentSource
+  textContent?: string | null
+  url?: string | null
+  data?: Uint8Array | string | null
+}
+
+export interface AiUiPart {
+  componentId: string
+  props: Record<string, unknown>
+}
+
+export interface AiChatRequestContext {
+  tenantId: string | null
+  organizationId: string | null
+  userId: string
+  features: string[]
+  isSuperAdmin: boolean
+}