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

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

@@ -0,0 +1,136 @@
+import {
+  applyPromptOverride,
+  composeSystemPromptWithOverride,
+  findReservedKeys,
+  PromptOverrideReservedKeyError,
+} from '../prompt-override-merge'
+import type { PromptTemplate } from '../prompt-composition-types'
+
+function makeTemplate(): PromptTemplate {
+  return {
+    id: 'test-template',
+    sections: [
+      { name: 'role', content: 'You are an assistant.' },
+      { name: 'scope', content: 'Answer questions only.' },
+      { name: 'data', content: 'Scoped to tenant.' },
+      { name: 'tools', content: 'Use read-only tools.' },
+      { name: 'attachments', content: 'Images accepted.' },
+      { name: 'mutationPolicy', content: 'Read-only.' },
+      { name: 'responseStyle', content: 'Terse, factual.' },
+    ],
+  }
+}
+
+describe('applyPromptOverride', () => {
+  it('is identity when override is empty', () => {
+    const template = makeTemplate()
+    const result = applyPromptOverride(template, { sections: {} })
+    expect(result.sections).toEqual(template.sections)
+    expect(result.systemPrompt).toContain('[ROLE]\nYou are an assistant.')
+    expect(result.systemPrompt).toContain('[RESPONSE STYLE]\nTerse, factual.')
+  })
+
+  it('is identity when override is null/undefined', () => {
+    const template = makeTemplate()
+    const nullResult = applyPromptOverride(template, null)
+    const undefinedResult = applyPromptOverride(template, undefined)
+    expect(nullResult.sections).toEqual(template.sections)
+    expect(undefinedResult.sections).toEqual(template.sections)
+  })
+
+  it('appends text to an existing canonical section preserving built-in text', () => {
+    const template = makeTemplate()
+    const result = applyPromptOverride(template, {
+      sections: { role: 'Be friendly.' },
+    })
+    const role = result.sections.find((s) => s.name === 'role')
+    expect(role?.content).toBe('You are an assistant.\n\nBe friendly.')
+    expect(result.systemPrompt).toContain('You are an assistant.\n\nBe friendly.')
+  })
+
+  it('appends to MUTATION POLICY via the pretty header key', () => {
+    const template = makeTemplate()
+    const result = applyPromptOverride(template, {
+      sections: { 'MUTATION POLICY': 'Strict.' },
+    })
+    const section = result.sections.find((s) => s.name === 'mutationPolicy')
+    expect(section?.content).toBe('Read-only.\n\nStrict.')
+  })
+
+  it('inserts a brand-new section after RESPONSE STYLE preserving canonical order', () => {
+    const template = makeTemplate()
+    const result = applyPromptOverride(template, {
+      sections: { 'Company Voice': 'Always use the first-person plural.' },
+    })
+    const names = result.sections.map((s) => s.name)
+    const canonicalOrder = [
+      'role',
+      'scope',
+      'data',
+      'tools',
+      'attachments',
+      'mutationPolicy',
+      'responseStyle',
+    ]
+    // Canonical sections appear in the expected order.
+    expect(names.slice(0, canonicalOrder.length)).toEqual(canonicalOrder)
+    // The new "overrides" section carrying the brand-new header lands after responseStyle.
+    expect(names[canonicalOrder.length]).toBe('overrides')
+    expect(result.systemPrompt).toMatch(/COMPANY VOICE/)
+    expect(result.systemPrompt).toContain('Always use the first-person plural.')
+    // And RESPONSE STYLE still appears before the new section.
+    const responseStyleIndex = result.systemPrompt.indexOf('[RESPONSE STYLE]')
+    const overridesIndex = result.systemPrompt.indexOf('[OVERRIDES]')
+    expect(responseStyleIndex).toBeGreaterThanOrEqual(0)
+    expect(overridesIndex).toBeGreaterThan(responseStyleIndex)
+  })
+
+  it('ignores empty / whitespace-only override values', () => {
+    const template = makeTemplate()
+    const result = applyPromptOverride(template, {
+      sections: { role: '   ', scope: '' },
+    })
+    expect(result.sections).toEqual(template.sections)
+  })
+
+  it('throws when a reserved policy key is present', () => {
+    const template = makeTemplate()
+    expect(() =>
+      applyPromptOverride(template, {
+        sections: { mutationPolicy: 'Allow writes', role: 'Be nice.' },
+      }),
+    ).toThrow(PromptOverrideReservedKeyError)
+  })
+
+  it('findReservedKeys returns matching keys case-insensitively', () => {
+    expect(findReservedKeys({ role: 'x' })).toEqual([])
+    expect(findReservedKeys({ mutationPolicy: 'x' })).toEqual(['mutationPolicy'])
+    expect(findReservedKeys({ READONLY: 'x' })).toEqual(['READONLY'])
+    expect(findReservedKeys({ AllowedTools: 'x', extra: 'y' })).toEqual(['AllowedTools'])
+    expect(findReservedKeys(null)).toEqual([])
+    expect(findReservedKeys(undefined)).toEqual([])
+  })
+})
+
+describe('composeSystemPromptWithOverride', () => {
+  it('returns base prompt when no override is present', () => {
+    const result = composeSystemPromptWithOverride('base prompt', null)
+    expect(result).toBe('base prompt')
+  })
+
+  it('layers a role-section override onto a plain-string base prompt', () => {
+    const result = composeSystemPromptWithOverride('You are a helpful bot.', {
+      sections: { role: 'Stay concise.' },
+    })
+    expect(result).toContain('[ROLE]\nYou are a helpful bot.\n\nStay concise.')
+  })
+
+  it('layers a brand-new section override onto a plain-string base prompt', () => {
+    const result = composeSystemPromptWithOverride('Base.', {
+      sections: { 'Tenant Voice': 'Use British English.' },
+    })
+    expect(result).toContain('Base.')
+    expect(result).toContain('TENANT VOICE')
+    expect(result).toContain('Use British English.')
+  })
+})

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

@@ -0,0 +1,125 @@
+import { z } from 'zod'
+import {
+  registerGeneratedAiToolEntries,
+  type AiToolConfigEntry,
+} from '../tool-loader'
+import { toolRegistry } from '../tool-registry'
+import { convertMcpToolsToAiSdk } from '../mcp-tool-adapter'
+import type { InProcessMcpClient, ToolInfoWithSchema } from '../in-process-client'
+
+function makeTool(name: string) {
+  return {
+    name,
+    description: `Tool ${name}`,
+    inputSchema: z.object({ q: z.string() }),
+    requiredFeatures: [`${name}.view`],
+    handler: async (input: { q: string }) => ({ echo: input.q, name }),
+  }
+}
+
+describe('registerGeneratedAiToolEntries', () => {
+  beforeEach(() => {
+    toolRegistry.clear()
+  })
+
+  afterAll(() => {
+    toolRegistry.clear()
+  })
+
+  it('registers tools from modules that populate ai-tools.ts', () => {
+    const entries: AiToolConfigEntry[] = [
+      { moduleId: 'search', tools: [makeTool('search_query'), makeTool('search_status')] },
+    ]
+
+    const registered = registerGeneratedAiToolEntries(entries)
+
+    expect(registered).toBe(2)
+    expect(toolRegistry.listToolsByModule('search')).toEqual([
+      'search_query',
+      'search_status',
+    ])
+    expect(toolRegistry.getTool('search_query')?.requiredFeatures).toEqual(['search_query.view'])
+  })
+
+  it('stays silent for modules without an ai-tools.ts (empty or missing tools)', () => {
+    const entries: AiToolConfigEntry[] = [
+      { moduleId: 'auth', tools: [] },
+      { moduleId: 'catalog', tools: undefined as unknown as unknown[] },
+    ]
+
+    const registered = registerGeneratedAiToolEntries(entries)
+
+    expect(registered).toBe(0)
+    expect(toolRegistry.listToolNames()).toEqual([])
+  })
+
+  it('is idempotent — re-running does not duplicate registrations', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const entries: AiToolConfigEntry[] = [
+      { moduleId: 'search', tools: [makeTool('search_query')] },
+    ]
+
+    registerGeneratedAiToolEntries(entries)
+    registerGeneratedAiToolEntries(entries)
+
+    expect(toolRegistry.listToolsByModule('search')).toEqual(['search_query'])
+    expect(toolRegistry.listToolNames()).toEqual(['search_query'])
+    warnSpy.mockRestore()
+  })
+
+  it('skips malformed tool objects instead of throwing', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const entries: AiToolConfigEntry[] = [
+      {
+        moduleId: 'broken',
+        tools: [
+          { name: 'missing_handler', description: 'x', inputSchema: z.object({}) } as unknown,
+          null as unknown,
+          makeTool('ok_tool'),
+        ],
+      },
+    ]
+
+    const registered = registerGeneratedAiToolEntries(entries)
+
+    expect(registered).toBe(1)
+    expect(toolRegistry.getTool('ok_tool')).toBeDefined()
+    expect(toolRegistry.getTool('missing_handler')).toBeUndefined()
+    warnSpy.mockRestore()
+  })
+
+  it('keeps tools resolvable through mcp-tool-adapter with identical shape', async () => {
+    const entries: AiToolConfigEntry[] = [
+      { moduleId: 'search', tools: [makeTool('search_query')] },
+    ]
+    registerGeneratedAiToolEntries(entries)
+
+    const registered = toolRegistry.getTool('search_query')
+    expect(registered).toBeDefined()
+    if (!registered) return
+
+    const mcpTools: ToolInfoWithSchema[] = [
+      {
+        name: registered.name,
+        description: registered.description,
+        inputSchema: registered.inputSchema,
+      },
+    ]
+
+    const callToolMock = jest.fn(async () => ({ success: true, result: { ok: true } }))
+    const fakeClient = { callTool: callToolMock } as unknown as InProcessMcpClient
+
+    const aiSdkTools = convertMcpToolsToAiSdk(fakeClient, mcpTools)
+
+    expect(Object.keys(aiSdkTools)).toEqual(['search_query'])
+    const adapted = aiSdkTools.search_query as unknown as {
+      description: string
+      execute: (args: unknown) => Promise<string>
+    }
+    expect(adapted.description).toBe(registered.description)
+
+    const out = await adapted.execute({ q: 'hello' })
+    expect(callToolMock).toHaveBeenCalledWith('search_query', { q: 'hello' })
+    expect(out).toContain('"ok": true')
+  })
+})

package/src/modules/ai_assistant/lib/agent-policy.ts

@@ -0,0 +1,270 @@
+import { getAgent } from './agent-registry'
+import { hasRequiredFeatures } from './auth'
+import { toolRegistry } from './tool-registry'
+import type {
+  AiAgentAcceptedMediaType,
+  AiAgentDefinition,
+  AiAgentMutationPolicy,
+} from './ai-agent-definition'
+import type { AiToolDefinition } from './types'
+
+export type AgentPolicyDenyCode =
+  | 'agent_unknown'
+  | 'agent_features_denied'
+  | 'tool_not_whitelisted'
+  | 'tool_unknown'
+  | 'tool_features_denied'
+  | 'mutation_blocked_by_readonly'
+  | 'mutation_blocked_by_policy'
+  | 'execution_mode_not_supported'
+  | 'attachment_type_not_accepted'
+
+export type AgentPolicyDecision =
+  | { ok: true; agent: AiAgentDefinition; tool?: AiToolDefinition }
+  | { ok: false; code: AgentPolicyDenyCode; message: string }
+
+export interface AgentPolicyAuthContext {
+  userFeatures: string[]
+  isSuperAdmin: boolean
+}
+
+export interface AgentPolicyCheckInput {
+  agentId: string
+  authContext: AgentPolicyAuthContext
+  toolName?: string
+  attachmentMediaTypes?: string[]
+  requestedExecutionMode?: 'chat' | 'object'
+  /**
+   * Optional tenant-scoped downgrade for the agent's code-declared
+   * `mutationPolicy`. When supplied, the effective policy is the MOST
+   * RESTRICTIVE of `{ code-declared, override }` — escalation is never
+   * allowed through this channel (that is enforced at the route layer).
+   * Callers that omit this field get the exact pre-Step-5.4 behavior.
+   */
+  mutationPolicyOverride?: AiAgentMutationPolicy | null
+}
+
+/**
+ * Restrictiveness ranking of `AiAgentMutationPolicy` (most restrictive first).
+ * `read-only` blocks all mutation tools. `destructive-confirm-required` forces
+ * confirmation for every write (including non-destructive ones). `confirm-required`
+ * is the least restrictive policy — writes go through a single confirmation.
+ *
+ * This ordering is load-bearing for both the runtime's effective-policy
+ * computation AND the route-layer escalation guard. Changing the order is a
+ * security-sensitive change.
+ */
+const POLICY_RESTRICTIVENESS: Record<AiAgentMutationPolicy, number> = {
+  'read-only': 0,
+  'destructive-confirm-required': 1,
+  'confirm-required': 2,
+}
+
+export function isKnownMutationPolicy(value: unknown): value is AiAgentMutationPolicy {
+  return (
+    value === 'read-only' ||
+    value === 'confirm-required' ||
+    value === 'destructive-confirm-required'
+  )
+}
+
+/**
+ * Returns the effective mutation policy — the MOST RESTRICTIVE of
+ * `{ codeDeclared, override }`. Missing override → `codeDeclared`. A corrupt
+ * override value (unknown string from DB) is logged and falls back to
+ * `codeDeclared` so the system fails SAFE when a schema drift leaks through.
+ */
+export function resolveEffectiveMutationPolicy(
+  codeDeclared: AiAgentMutationPolicy | undefined,
+  override: AiAgentMutationPolicy | null | undefined,
+  agentId?: string,
+): AiAgentMutationPolicy {
+  const base: AiAgentMutationPolicy =
+    codeDeclared && isKnownMutationPolicy(codeDeclared) ? codeDeclared : 'read-only'
+  if (override === undefined || override === null) return base
+  if (!isKnownMutationPolicy(override)) {
+    console.warn(
+      `[AI Agents] Ignoring corrupt mutationPolicy override for agent "${agentId ?? '<unknown>'}": ${String(
+        override,
+      )}. Falling back to code-declared policy "${base}".`,
+    )
+    return base
+  }
+  const baseRank = POLICY_RESTRICTIVENESS[base]
+  const overrideRank = POLICY_RESTRICTIVENESS[override]
+  return overrideRank < baseRank ? override : base
+}
+
+/**
+ * Returns `true` when `candidate` would WIDEN `codeDeclared` — i.e. would
+ * grant the agent more mutation surface than its code declares. Used by the
+ * mutation-policy override route to reject escalation attempts with 400.
+ */
+export function isMutationPolicyEscalation(
+  codeDeclared: AiAgentMutationPolicy | undefined,
+  candidate: AiAgentMutationPolicy,
+): boolean {
+  const base: AiAgentMutationPolicy =
+    codeDeclared && isKnownMutationPolicy(codeDeclared) ? codeDeclared : 'read-only'
+  return POLICY_RESTRICTIVENESS[candidate] > POLICY_RESTRICTIVENESS[base]
+}
+
+function classifyMediaType(value: string): AiAgentAcceptedMediaType {
+  const normalized = value.trim().toLowerCase()
+  if (normalized.startsWith('image/')) return 'image'
+  if (normalized === 'application/pdf') return 'pdf'
+  return 'file'
+}
+
+function isAgentReadOnly(agent: AiAgentDefinition): boolean {
+  if (typeof agent.readOnly === 'boolean') return agent.readOnly
+  return true
+}
+
+/**
+ * Returns the effective mutation policy for a policy-check invocation — the
+ * most restrictive of `{ agent.mutationPolicy, input.mutationPolicyOverride }`.
+ * Pure-lookup helper; no I/O. Callers that need to know the same value outside
+ * of a policy check should use {@link resolveEffectiveMutationPolicy} directly.
+ */
+function resolvePolicyCheckMutationPolicy(
+  agent: AiAgentDefinition,
+  override: AiAgentMutationPolicy | null | undefined,
+): AiAgentMutationPolicy {
+  return resolveEffectiveMutationPolicy(agent.mutationPolicy, override, agent.id)
+}
+
+function hasAgentStructuredOutput(agent: AiAgentDefinition): boolean {
+  return Boolean(agent.output)
+}
+
+function agentExecutionMode(agent: AiAgentDefinition): 'chat' | 'object' {
+  return agent.executionMode ?? 'chat'
+}
+
+export function checkAgentPolicy(input: AgentPolicyCheckInput): AgentPolicyDecision {
+  const {
+    agentId,
+    authContext,
+    toolName,
+    attachmentMediaTypes,
+    requestedExecutionMode,
+    mutationPolicyOverride,
+  } = input
+
+  const agent = getAgent(agentId)
+  if (!agent) {
+    return {
+      ok: false,
+      code: 'agent_unknown',
+      message: `Agent "${agentId}" is not registered.`,
+    }
+  }
+
+  const agentFeatures = agent.requiredFeatures ?? []
+  if (
+    !hasRequiredFeatures(agentFeatures, authContext.userFeatures, authContext.isSuperAdmin)
+  ) {
+    return {
+      ok: false,
+      code: 'agent_features_denied',
+      message: `Access to agent "${agentId}" requires features: ${agentFeatures.join(', ')}`,
+    }
+  }
+
+  let resolvedTool: AiToolDefinition | undefined
+  if (typeof toolName === 'string') {
+    if (!agent.allowedTools.includes(toolName)) {
+      return {
+        ok: false,
+        code: 'tool_not_whitelisted',
+        message: `Tool "${toolName}" is not whitelisted for agent "${agentId}".`,
+      }
+    }
+
+    const toolRecord = toolRegistry.getTool(toolName) as AiToolDefinition | undefined
+    if (!toolRecord) {
+      return {
+        ok: false,
+        code: 'tool_unknown',
+        message: `Tool "${toolName}" is not registered in the tool registry.`,
+      }
+    }
+
+    const toolFeatures = toolRecord.requiredFeatures ?? []
+    if (
+      !hasRequiredFeatures(toolFeatures, authContext.userFeatures, authContext.isSuperAdmin)
+    ) {
+      return {
+        ok: false,
+        code: 'tool_features_denied',
+        message: `Access to tool "${toolName}" requires features: ${toolFeatures.join(', ')}`,
+      }
+    }
+
+    if (toolRecord.isMutation === true) {
+      if (isAgentReadOnly(agent)) {
+        return {
+          ok: false,
+          code: 'mutation_blocked_by_readonly',
+          message: `Mutation tool "${toolName}" cannot be executed by read-only agent "${agentId}".`,
+        }
+      }
+      const effectivePolicy = resolvePolicyCheckMutationPolicy(agent, mutationPolicyOverride)
+      if (effectivePolicy === 'read-only') {
+        return {
+          ok: false,
+          code: 'mutation_blocked_by_policy',
+          message: `Mutation tool "${toolName}" is blocked by agent "${agentId}" mutationPolicy=read-only.`,
+        }
+      }
+    }
+
+    resolvedTool = toolRecord
+  }
+
+  if (requestedExecutionMode) {
+    const declaredMode = agentExecutionMode(agent)
+    if (requestedExecutionMode === 'object') {
+      if (declaredMode !== 'object' && !hasAgentStructuredOutput(agent)) {
+        return {
+          ok: false,
+          code: 'execution_mode_not_supported',
+          message: `Agent "${agentId}" does not support execution mode "object" (no output schema declared).`,
+        }
+      }
+    } else if (requestedExecutionMode === 'chat') {
+      if (declaredMode === 'object' && hasAgentStructuredOutput(agent)) {
+        return {
+          ok: false,
+          code: 'execution_mode_not_supported',
+          message: `Agent "${agentId}" is declared as object-mode and cannot run via chat transport.`,
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(attachmentMediaTypes) && attachmentMediaTypes.length > 0) {
+    const accepted = agent.acceptedMediaTypes
+    if (!accepted || accepted.length === 0) {
+      return {
+        ok: false,
+        code: 'attachment_type_not_accepted',
+        message: `Agent "${agentId}" does not accept attachments.`,
+      }
+    }
+    const acceptedSet = new Set<AiAgentAcceptedMediaType>(accepted)
+    for (const raw of attachmentMediaTypes) {
+      const kind = classifyMediaType(raw)
+      if (!acceptedSet.has(kind)) {
+        return {
+          ok: false,
+          code: 'attachment_type_not_accepted',
+          message: `Agent "${agentId}" does not accept media type "${raw}" (classified as "${kind}").`,
+        }
+      }
+    }
+  }
+
+  return { ok: true, agent, tool: resolvedTool }
+}