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

package/src/modules/ai_assistant/lib/prompt-override-merge.ts

@@ -0,0 +1,253 @@
+import type {
+  PromptSection,
+  PromptSectionName,
+  PromptTemplate,
+} from './prompt-composition-types'
+
+/**
+ * Canonical prompt section names the built-in agent prompt templates ship.
+ * These align with the 7 section headers the spec (§8) mandates, plus the
+ * free-form `overrides` bucket the template already reserves.
+ */
+export const CANONICAL_PROMPT_SECTIONS: readonly PromptSectionName[] = [
+  'role',
+  'scope',
+  'data',
+  'tools',
+  'attachments',
+  'mutationPolicy',
+  'responseStyle',
+  'overrides',
+] as const
+
+/**
+ * Reserved keys that MUST NOT appear in a prompt override. These name policy
+ * fields that live on the agent definition itself — allowing them to be
+ * modified via the prompt-override layer would let a tenant silently escalate
+ * an agent beyond the mutation / tool / attachment contract enforced by
+ * `checkAgentPolicy` at dispatch time.
+ */
+export const RESERVED_OVERRIDE_KEYS: readonly string[] = [
+  'mutationPolicy',
+  'readOnly',
+  'allowedTools',
+  'acceptedMediaTypes',
+] as const
+
+const HEADER_MAP: Readonly<Record<string, PromptSectionName>> = {
+  role: 'role',
+  scope: 'scope',
+  data: 'data',
+  tools: 'tools',
+  attachments: 'attachments',
+  'mutation policy': 'mutationPolicy',
+  mutation_policy: 'mutationPolicy',
+  mutationpolicy: 'mutationPolicy',
+  'response style': 'responseStyle',
+  response_style: 'responseStyle',
+  responsestyle: 'responseStyle',
+  overrides: 'overrides',
+}
+
+function canonicalize(key: string): PromptSectionName | null {
+  const normalized = key.trim().toLowerCase()
+  if (!normalized) return null
+  return HEADER_MAP[normalized] ?? null
+}
+
+function prettyHeader(name: PromptSectionName): string {
+  switch (name) {
+    case 'mutationPolicy':
+      return 'MUTATION POLICY'
+    case 'responseStyle':
+      return 'RESPONSE STYLE'
+    default:
+      return name.toUpperCase()
+  }
+}
+
+export interface AppliedPromptOverride {
+  sections: PromptSection[]
+  systemPrompt: string
+}
+
+export interface PromptOverrideInput {
+  /** Additive text keyed by canonical section id or free-form new header. */
+  sections: Record<string, string> | null | undefined
+}
+
+/**
+ * Applies an additive prompt override to a built-in template. Rules:
+ *
+ * - A canonical section key (`role`, `scope`, `data`, `tools`, `attachments`,
+ *   `MUTATION POLICY`, `RESPONSE STYLE`, `overrides`) APPENDS the override
+ *   text below the built-in section content with a blank line separator.
+ *   The built-in content is never removed or rewritten.
+ * - A non-canonical key is treated as a brand-new section and inserted
+ *   after the canonical `RESPONSE STYLE` position (before `overrides`,
+ *   if any). Canonical section order is always preserved.
+ * - Empty or whitespace-only override values are ignored.
+ * - If any reserved policy key is present (`mutationPolicy`, `readOnly`,
+ *   `allowedTools`, `acceptedMediaTypes`), this function throws. Call sites
+ *   SHOULD validate via {@link validatePromptOverrideInput} first so the
+ *   error surfaces as a 400 to the API caller.
+ */
+export function applyPromptOverride(
+  template: PromptTemplate,
+  override: PromptOverrideInput | null | undefined,
+): AppliedPromptOverride {
+  const baseSections = [...template.sections]
+  const sections = override?.sections ?? null
+
+  if (!sections || typeof sections !== 'object') {
+    return {
+      sections: baseSections,
+      systemPrompt: renderPrompt(baseSections),
+    }
+  }
+
+  assertNoReservedKeys(sections)
+
+  // First pass: append to canonical sections.
+  const byCanonical = new Map<PromptSectionName, string>()
+  const unknownKeys: Array<{ rawKey: string; value: string }> = []
+  for (const [rawKey, value] of Object.entries(sections)) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (!trimmed) continue
+    const canonical = canonicalize(rawKey)
+    if (canonical) {
+      const existing = byCanonical.get(canonical)
+      byCanonical.set(canonical, existing ? `${existing}\n\n${trimmed}` : trimmed)
+    } else {
+      unknownKeys.push({ rawKey, value: trimmed })
+    }
+  }
+
+  const appended: PromptSection[] = baseSections.map((section) => {
+    const addendum = byCanonical.get(section.name)
+    if (!addendum) return section
+    const nextContent = section.content.trim().length === 0
+      ? addendum
+      : `${section.content}\n\n${addendum}`
+    return { ...section, content: nextContent }
+  })
+
+  // If a canonical section wasn't already present but an override targets it,
+  // append it using its canonical header. Catalog / customer templates ship
+  // all 7 canonical headers today, but we defend against future templates
+  // that may omit some.
+  const declaredNames = new Set(appended.map((s) => s.name))
+  for (const [canonical, addendum] of byCanonical.entries()) {
+    if (!declaredNames.has(canonical)) {
+      appended.push({ name: canonical, content: addendum })
+      declaredNames.add(canonical)
+    }
+  }
+
+  // Brand-new sections inject after RESPONSE STYLE. We insert by splitting the
+  // array at the index directly after `responseStyle`. If `overrides` is
+  // already present, new sections land before it so `overrides` stays last.
+  if (unknownKeys.length > 0) {
+    const newSections: PromptSection[] = unknownKeys.map(({ rawKey, value }) => ({
+      name: 'overrides',
+      content: `[${rawKey.trim().toUpperCase()}]\n${value}`,
+    }))
+    const responseStyleIndex = appended.findIndex((s) => s.name === 'responseStyle')
+    const overridesIndex = appended.findIndex((s) => s.name === 'overrides')
+    let insertAt: number
+    if (overridesIndex >= 0) {
+      insertAt = overridesIndex
+    } else if (responseStyleIndex >= 0) {
+      insertAt = responseStyleIndex + 1
+    } else {
+      insertAt = appended.length
+    }
+    appended.splice(insertAt, 0, ...newSections)
+  }
+
+  return {
+    sections: appended,
+    systemPrompt: renderPrompt(appended),
+  }
+}
+
+/**
+ * Produces a flat string representation of a prompt template. The runtime uses
+ * this when the agent definition declares sections but the underlying call
+ * site expects a single-string `systemPrompt` (today: both `runAiAgentText`
+ * and `runAiAgentObject`).
+ */
+export function renderPrompt(sections: readonly PromptSection[]): string {
+  const lines: string[] = []
+  for (const section of sections) {
+    const content = section.content.trim()
+    if (!content) continue
+    lines.push(`[${prettyHeader(section.name)}]\n${content}`)
+  }
+  return lines.join('\n\n')
+}
+
+/**
+ * Returns the list of reserved keys present in the supplied override payload.
+ * Empty array means the body is safe for persistence. Call this before the
+ * repository `save` so the API layer can reject with a 400 / `reserved_key`.
+ */
+export function findReservedKeys(sections: Record<string, unknown> | null | undefined): string[] {
+  if (!sections || typeof sections !== 'object') return []
+  const reservedSet = new Set(RESERVED_OVERRIDE_KEYS.map((key) => key.toLowerCase()))
+  const hits: string[] = []
+  for (const key of Object.keys(sections)) {
+    if (reservedSet.has(key.trim().toLowerCase())) {
+      hits.push(key)
+    }
+  }
+  return hits
+}
+
+function assertNoReservedKeys(sections: Record<string, unknown>): void {
+  const hits = findReservedKeys(sections)
+  if (hits.length > 0) {
+    throw new PromptOverrideReservedKeyError(hits)
+  }
+}
+
+export class PromptOverrideReservedKeyError extends Error {
+  readonly code = 'reserved_key'
+  constructor(public readonly keys: readonly string[]) {
+    super(
+      `Prompt override includes reserved policy keys: ${keys.join(', ')}. ` +
+        `Policy fields (${RESERVED_OVERRIDE_KEYS.join(', ')}) are never editable via prompt overrides.`,
+    )
+    this.name = 'PromptOverrideReservedKeyError'
+  }
+}
+
+/**
+ * Convenience wrapper: composes the full system prompt for a legacy agent that
+ * ships a single-string `systemPrompt`. Returns the base unchanged when no
+ * override is present. When an override is present, the base is treated as the
+ * `role` section and overrides are layered via {@link applyPromptOverride}.
+ */
+export function composeSystemPromptWithOverride(
+  baseSystemPrompt: string,
+  override: PromptOverrideInput | null | undefined,
+): string {
+  if (!override?.sections || Object.keys(override.sections).length === 0) {
+    return baseSystemPrompt
+  }
+  const template: PromptTemplate = {
+    id: 'legacy-system-prompt',
+    sections: [
+      { name: 'role', content: baseSystemPrompt },
+      { name: 'scope', content: '' },
+      { name: 'data', content: '' },
+      { name: 'tools', content: '' },
+      { name: 'attachments', content: '' },
+      { name: 'mutationPolicy', content: '' },
+      { name: 'responseStyle', content: '' },
+    ],
+  }
+  const applied = applyPromptOverride(template, override)
+  return applied.systemPrompt
+}

package/src/modules/ai_assistant/lib/schema-utils.ts

@@ -44,8 +44,13 @@ export function jsonSchemaToZod(jsonSchema: Record<string, unknown>): ZodType {
     const required = (jsonSchema.required as string[]) || []
     const additionalProperties = jsonSchema.additionalProperties
 
-    // Handle z.record() - objects with additionalProperties but no fixed properties
-    if (additionalProperties && (!properties || Object.keys(properties).length === 0)) {
+    // Handle z.record() - objects with additionalProperties but no fixed properties.
+    // Skip the record path when properties is present but empty — that is a
+    // no-arg object schema, not a dictionary. OpenAI requires `properties: {}`
+    // in the JSON Schema, and `z.object({})` produces that, whereas
+    // `z.record()` does not.
+    const hasFixedProperties = properties && Object.keys(properties).length > 0
+    if (additionalProperties && !hasFixedProperties && properties === undefined) {
       // This is a record/dictionary type - allow any properties
       if (typeof additionalProperties === 'object') {
         return z.record(z.string(), jsonSchemaToZod(additionalProperties as Record<string, unknown>))
@@ -127,6 +132,13 @@ export function toSafeZodSchema(schema: ZodType): ZodType {
     // Use Zod 4's toJSONSchema with unrepresentable: 'any' to handle Date types
     const jsonSchema = z.toJSONSchema(schema, { unrepresentable: 'any' }) as Record<string, unknown>
 
+    // OpenAI requires `properties` on object schemas. Empty passthrough objects
+    // (tools that take no args) roundtrip as `{ type: "object", additionalProperties: true }`
+    // without `properties`, which OpenAI rejects. Ensure `properties` is present.
+    if (jsonSchema.type === 'object' && !jsonSchema.properties) {
+      jsonSchema.properties = {}
+    }
+
     // Convert back to a simple Zod schema without Date types
     const safeSchema = jsonSchemaToZod(jsonSchema)
 

package/src/modules/ai_assistant/lib/tool-executor.ts

@@ -3,6 +3,20 @@ import { getToolRegistry } from './tool-registry'
 import { hasRequiredFeatures } from './auth'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 
+/**
+ * Strip empty strings from object values so LLM-generated `""` for optional
+ * fields becomes `undefined` (passes `.optional()` Zod validators).
+ */
+function sanitizeEmptyStrings(input: unknown): unknown {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return input
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+    if (typeof value === 'string' && value.trim() === '') continue
+    result[key] = value
+  }
+  return result
+}
+
 /**
  * Execute a tool with full context and ACL checks.
  */
@@ -41,8 +55,13 @@ export async function executeTool(
     }
   }
 
+  // LLMs often send empty strings for optional fields (e.g., `personId: ""`).
+  // Strip empty strings to `undefined` before Zod parsing so `.uuid().optional()`
+  // fields pass validation when the model meant "omit this field".
+  const sanitizedInput = sanitizeEmptyStrings(input)
+
   // Input validation
-  const parseResult = tool.inputSchema.safeParse(input)
+  const parseResult = tool.inputSchema.safeParse(sanitizedInput)
   if (!parseResult.success) {
     // Use any cast for Zod v4 compatibility
     const issues = (parseResult.error as any).issues ?? []
@@ -58,9 +77,12 @@ export async function executeTool(
     }
   }
 
-  // Execute tool
+  // Execute tool. Attach `tool` to the context so handlers that build an
+  // `AiToolExecutionContext` (e.g. via `createAiApiOperationRunner`) keep their
+  // route-gate coverage check working.
+  const handlerContext: McpToolContext = { ...context, tool }
   try {
-    const result = await tool.handler(parseResult.data, context)
+    const result = await tool.handler(parseResult.data, handlerContext)
     return { success: true, result }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)

package/src/modules/ai_assistant/lib/tool-loader.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod'
 import type { SearchService } from '@open-mercato/search/service'
-import { registerMcpTool, getToolRegistry } from './tool-registry'
+import { registerMcpTool, getToolRegistry, toolRegistry, unregisterMcpTool } from './tool-registry'
+import {
+  applyToolOverrideMap,
+  composeToolOverrideMap,
+  type AiToolOverrideConfigEntry,
+} from './ai-overrides'
 import type { McpToolDefinition, McpToolContext } from './types'
 import { ToolSearchService } from './tool-search'
 
@@ -15,6 +20,27 @@ type ModuleAiTool = {
   handler: (input: any, ctx: any) => Promise<unknown>
 }
 
+/**
+ * Shape of a single entry inside `ai-tools.generated.ts`.
+ * Matches the structural contract emitted by
+ * `packages/cli/src/lib/generators/extensions/ai-tools.ts`.
+ */
+export type AiToolConfigEntry = {
+  moduleId: string
+  tools: unknown[]
+}
+
+function isModuleAiTool(value: unknown): value is ModuleAiTool {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Record<string, unknown>
+  return (
+    typeof candidate.name === 'string' &&
+    typeof candidate.description === 'string' &&
+    candidate.inputSchema !== undefined &&
+    typeof candidate.handler === 'function'
+  )
+}
+
 /**
  * Built-in context.whoami tool that returns the current authentication context.
  * This is useful for AI to understand its current tenant/org scope.
@@ -42,19 +68,131 @@ const contextWhoamiTool: McpToolDefinition = {
  *
  * @param moduleId - The module identifier (e.g., 'search', 'customers')
  * @param tools - Array of tool definitions from the module
+ *
+ * IMPORTANT: We register the full typed tool (spread) — never reconstruct a
+ * minimal `{ name, description, inputSchema, requiredFeatures, handler }`
+ * payload. Stripping fields like `isMutation`, `displayName`, `isBulk`,
+ * `loadBeforeRecord(s)` makes the agent settings UI report mutation tools
+ * as read-only and prevents the chat dispatcher's mutation interceptor
+ * from firing.
  */
 export function loadModuleTools(moduleId: string, tools: ModuleAiTool[]): void {
   for (const tool of tools) {
-    registerMcpTool(
-      {
-        name: tool.name,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-        requiredFeatures: tool.requiredFeatures,
-        handler: tool.handler,
-      } as McpToolDefinition,
-      { moduleId }
+    registerMcpTool(tool as McpToolDefinition, { moduleId })
+  }
+}
+
+/**
+ * Register the generated `aiToolConfigEntries` shape emitted by the
+ * `ai-tools.generated.ts` generator extension. Entries with an empty
+ * `tools` array stay silent (the generator already filters those out).
+ * Invalid tool objects are skipped with a warning instead of throwing.
+ *
+ * Returns the number of tools actually registered so callers can log it.
+ */
+export function registerGeneratedAiToolEntries(entries: AiToolConfigEntry[]): number {
+  let registered = 0
+  for (const entry of entries) {
+    if (!entry || typeof entry.moduleId !== 'string') continue
+    if (!Array.isArray(entry.tools) || entry.tools.length === 0) continue
+    for (const candidate of entry.tools) {
+      if (!isModuleAiTool(candidate)) {
+        console.warn(
+          `[MCP Tools] Skipping malformed AI tool in module "${entry.moduleId}"`
+        )
+        continue
+      }
+      // Register the full typed tool — see comment on `loadModuleTools`.
+      registerMcpTool(candidate as McpToolDefinition, { moduleId: entry.moduleId })
+      registered += 1
+    }
+  }
+  return registered
+}
+
+/**
+ * Apply the list of `aiToolOverrides` exports collected by the generator
+ * (one entry per module) to the live tool registry. Tools mapped to
+ * `null` are unregistered; tools mapped to a full definition replace the
+ * existing registration. Module load order controls precedence — last
+ * entry wins. The `modules.ts`-tier and programmatic overrides (set via
+ * {@link applyAiOverridesFromEnabledModules} and
+ * {@link applyAiToolOverrides}) supersede file-based entries.
+ *
+ * Safe to call when no override file is present (the entries array is
+ * empty); it is a no-op then.
+ */
+export function applyAiToolOverrideEntries(
+  entries: readonly AiToolOverrideConfigEntry[],
+): void {
+  const overrideMap = composeToolOverrideMap(entries)
+  if (Object.keys(overrideMap).length === 0) return
+  const baseTools = toolRegistry.getTools() as Map<string, McpToolDefinition>
+  const overridden = applyToolOverrideMap<McpToolDefinition>(baseTools, overrideMap)
+  for (const [name, value] of Object.entries(overrideMap)) {
+    if (value === null) {
+      unregisterMcpTool(name)
+      console.info(`[AI Overrides] Tool "${name}" disabled by override.`)
+      continue
+    }
+    const next = overridden.get(name)
+    if (!next) continue
+    // Re-register through the public path so moduleMap stays consistent.
+    registerMcpTool(next as McpToolDefinition, { moduleId: 'ai_overrides' })
+    console.info(`[AI Overrides] Tool "${name}" replaced by override.`)
+  }
+}
+
+/**
+ * Read `aiToolOverrideEntries` from `ai-tools.generated.ts` and apply
+ * them on top of the live tool registry. Safe to call when the file is
+ * missing (pre-generate builds, tests) — applies only the
+ * `modules.ts`-tier and programmatic overrides in that case.
+ */
+export async function loadGeneratedAiToolOverrides(): Promise<void> {
+  let entries: AiToolOverrideConfigEntry[] = []
+  try {
+    const mod = (await import(
+      '@/.mercato/generated/ai-tools.generated'
+    )) as { aiToolOverrideEntries?: unknown[] }
+    entries = Array.isArray(mod.aiToolOverrideEntries)
+      ? (mod.aiToolOverrideEntries as AiToolOverrideConfigEntry[])
+      : []
+  } catch {
+    // No override file generated.
+  }
+  applyAiToolOverrideEntries(entries)
+}
+
+/**
+ * Load the generated `ai-tools.generated.ts` file emitted by
+ * `yarn generate` and register every declared module tool through the
+ * existing `registerMcpTool` path. Safe to call when the generated file
+ * is missing (e.g., tests or pre-generate builds) — returns 0.
+ */
+export async function loadGeneratedModuleAiTools(): Promise<number> {
+  try {
+    const mod = (await import(
+      '@/.mercato/generated/ai-tools.generated'
+    )) as { aiToolConfigEntries?: AiToolConfigEntry[] }
+    const entries = Array.isArray(mod.aiToolConfigEntries)
+      ? mod.aiToolConfigEntries
+      : []
+    const count = registerGeneratedAiToolEntries(entries)
+    // Apply module-to-module + programmatic tool overrides AFTER the base
+    // registrations so disable / replace semantics work end-to-end.
+    try {
+      await loadGeneratedAiToolOverrides()
+    } catch (error) {
+      console.error('[AI Overrides] Failed to apply tool overrides:', error)
+    }
+    return count
+  } catch (error) {
+    console.error(
+      '[MCP Tools] Could not load ai-tools.generated.ts (module tools unavailable):',
+      error
     )
+    return 0
   }
 }
 
@@ -79,9 +217,17 @@ export async function loadAllModuleTools(): Promise<void> {
     console.error('[MCP Tools] Could not load Code Mode tools:', error)
   }
 
-  // Note: Auto-discovered module AI tools (from ai-tools.generated.ts) and
-  // legacy API discovery tools (find_api, call_api, discover_schema) are no
-  // longer loaded. Code Mode's search + execute tools cover all use cases.
+  // 3. Register module-contributed tools from ai-tools.generated.ts.
+  // Code Mode stays untouched; module tools are additive. Missing
+  // generated file is not fatal (pre-generate builds, tests).
+  try {
+    const moduleToolCount = await loadGeneratedModuleAiTools()
+    console.error(
+      `[MCP Tools] Registered ${moduleToolCount} module-contributed AI tools from ai-tools.generated.ts`
+    )
+  } catch (error) {
+    console.error('[MCP Tools] Could not load module AI tools:', error)
+  }
 }
 
 /**