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

package/src/modules/ai_assistant/api/ai/agents/[agentId]/prompt-override/route.ts

@@ -0,0 +1,307 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { getAgent, loadAgentRegistry } from '../../../../../lib/agent-registry'
+import { hasRequiredFeatures } from '../../../../../lib/auth'
+import { AiAgentPromptOverrideRepository } from '../../../../../data/repositories/AiAgentPromptOverrideRepository'
+import type { AiAgentPromptOverride } from '../../../../../data/entities'
+import { findReservedKeys } from '../../../../../lib/prompt-override-merge'
+
+const agentIdPattern = /^[a-z0-9_]+\.[a-z0-9_]+$/
+
+const agentIdParamSchema = z.object({
+  agentId: z
+    .string()
+    .regex(agentIdPattern, 'agentId must match "<module>.<agent>" (lowercase, digits, underscores only)'),
+})
+
+const sectionsSchema = z.record(z.string(), z.string())
+
+/**
+ * Accept both `sections` (Step 5.3 canonical shape) and the Step 4.5
+ * placeholder `overrides` key so UI callers that haven't redeployed still
+ * work. `sections` wins when both are present.
+ */
+const promptOverrideRequestSchema = z
+  .object({
+    sections: sectionsSchema.optional(),
+    overrides: sectionsSchema.optional(),
+    notes: z.string().max(2000).optional(),
+  })
+  .refine((value) => value.sections !== undefined || value.overrides !== undefined, {
+    message: 'Body must include either `sections` or `overrides`.',
+  })
+
+export type AiPromptOverrideRequest = z.infer<typeof promptOverrideRequestSchema>
+
+const REQUIRED_FEATURE = 'ai_assistant.settings.manage'
+const HISTORY_LIMIT = 10
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'Versioned additive prompt-overrides for an AI agent',
+  methods: {
+    GET: {
+      operationId: 'aiAssistantGetPromptOverride',
+      summary: 'Read the latest prompt-section override for an agent plus recent version history.',
+      description:
+        'Returns `{ agentId, override, versions }` where `override` is the latest persisted ' +
+        'row (or `null`) and `versions` is the newest-first history capped at 10 rows. ' +
+        'Tenant-scoped; requires `ai_assistant.settings.manage`.',
+      responses: [
+        {
+          status: 200,
+          description: 'Latest override + recent version history.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid agent id.' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks `ai_assistant.settings.manage`.' },
+        { status: 404, description: 'Unknown agent id.' },
+      ],
+    },
+    POST: {
+      operationId: 'aiAssistantSavePromptOverride',
+      summary: 'Save a new prompt-section override version for the agent.',
+      description:
+        'Persists an additive `{ sections: Record<sectionId, text>, notes? }` override, allocating ' +
+        'the next monotonic version for `(tenant, org, agent)`. Reserved policy keys ' +
+        '(`mutationPolicy`, `readOnly`, `allowedTools`, `acceptedMediaTypes`) are rejected with ' +
+        '400 / `reserved_key`. Requires `ai_assistant.settings.manage`.',
+      requestBody: {
+        contentType: 'application/json',
+        description: 'Body: `{ sections: Record<string, string>, notes?: string }`.',
+        schema: promptOverrideRequestSchema,
+      },
+      responses: [
+        {
+          status: 200,
+          description: 'Override persisted. Returns `{ ok: true, version, updatedAt }`.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid agent id, malformed body, or reserved policy key.' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks `ai_assistant.settings.manage`.' },
+        { status: 404, description: 'Unknown agent id.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: [REQUIRED_FEATURE],
+}
+
+interface RouteContext {
+  params: Promise<{ agentId: string }>
+}
+
+function jsonError(
+  status: number,
+  message: string,
+  code: string,
+  extra?: Record<string, unknown>,
+): NextResponse {
+  return NextResponse.json({ error: message, code, ...(extra ?? {}) }, { status })
+}
+
+interface ResolvedAuth {
+  tenantId: string | null
+  organizationId: string | null
+  userId: string
+  isSuperAdmin: boolean
+  features: string[]
+  container: Awaited<ReturnType<typeof createRequestContainer>>
+  rbacService: RbacService
+}
+
+async function resolveAuthOrRespond(
+  req: NextRequest,
+): Promise<ResolvedAuth | NextResponse> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return jsonError(401, 'Unauthorized', 'unauthenticated')
+  }
+  const container = await createRequestContainer()
+  const rbacService = container.resolve<RbacService>('rbacService')
+  const acl = await rbacService.loadAcl(auth.sub, {
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId,
+  })
+  if (!hasRequiredFeatures([REQUIRED_FEATURE], acl.features, acl.isSuperAdmin, rbacService)) {
+    return jsonError(403, `Caller lacks required feature "${REQUIRED_FEATURE}".`, 'forbidden')
+  }
+  return {
+    tenantId: auth.tenantId ?? null,
+    organizationId: auth.orgId ?? null,
+    userId: auth.sub,
+    isSuperAdmin: acl.isSuperAdmin,
+    features: acl.features,
+    container,
+    rbacService,
+  }
+}
+
+function serializeOverride(row: AiAgentPromptOverride) {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    version: row.version,
+    sections: row.sections ?? {},
+    notes: row.notes ?? null,
+    createdByUserId: row.createdByUserId ?? null,
+    createdAt: row.createdAt?.toISOString?.() ?? new Date().toISOString(),
+    updatedAt: row.updatedAt?.toISOString?.() ?? new Date().toISOString(),
+  }
+}
+
+export async function GET(req: NextRequest, context: RouteContext): Promise<Response> {
+  const authResult = await resolveAuthOrRespond(req)
+  if (authResult instanceof NextResponse) return authResult
+
+  const rawParams = await context.params
+  const paramResult = agentIdParamSchema.safeParse(rawParams)
+  if (!paramResult.success) {
+    return jsonError(400, 'Invalid agent id.', 'validation_error', {
+      issues: paramResult.error.issues,
+    })
+  }
+
+  try {
+    await loadAgentRegistry()
+    const agent = getAgent(paramResult.data.agentId)
+    if (!agent) {
+      return jsonError(404, `Unknown agent "${paramResult.data.agentId}".`, 'agent_unknown')
+    }
+
+    if (!authResult.tenantId) {
+      return NextResponse.json({
+        agentId: agent.id,
+        override: null,
+        versions: [],
+      })
+    }
+
+    const em = authResult.container.resolve<EntityManager>('em')
+    const repo = new AiAgentPromptOverrideRepository(em)
+    const [latest, versions] = await Promise.all([
+      repo.getLatest(agent.id, {
+        tenantId: authResult.tenantId,
+        organizationId: authResult.organizationId,
+      }),
+      repo.listVersions(
+        agent.id,
+        {
+          tenantId: authResult.tenantId,
+          organizationId: authResult.organizationId,
+        },
+        HISTORY_LIMIT,
+      ),
+    ])
+
+    return NextResponse.json({
+      agentId: agent.id,
+      override: latest ? serializeOverride(latest) : null,
+      versions: versions.map(serializeOverride),
+    })
+  } catch (error) {
+    console.error('[AI Prompt Override GET] Failure:', error)
+    return jsonError(
+      500,
+      error instanceof Error ? error.message : 'Failed to load prompt override.',
+      'internal_error',
+    )
+  }
+}
+
+export async function POST(req: NextRequest, context: RouteContext): Promise<Response> {
+  const authResult = await resolveAuthOrRespond(req)
+  if (authResult instanceof NextResponse) return authResult
+
+  const rawParams = await context.params
+  const paramResult = agentIdParamSchema.safeParse(rawParams)
+  if (!paramResult.success) {
+    return jsonError(400, 'Invalid agent id.', 'validation_error', {
+      issues: paramResult.error.issues,
+    })
+  }
+
+  let parsedBody: unknown
+  try {
+    parsedBody = await req.json()
+  } catch {
+    return jsonError(400, 'Request body must be valid JSON.', 'validation_error')
+  }
+
+  const bodyResult = promptOverrideRequestSchema.safeParse(parsedBody)
+  if (!bodyResult.success) {
+    return jsonError(400, 'Invalid request body.', 'validation_error', {
+      issues: bodyResult.error.issues,
+    })
+  }
+
+  const sections = bodyResult.data.sections ?? bodyResult.data.overrides ?? {}
+  const reservedHits = findReservedKeys(sections)
+  if (reservedHits.length > 0) {
+    return jsonError(
+      400,
+      `Prompt override contains reserved policy keys: ${reservedHits.join(', ')}.`,
+      'reserved_key',
+      { reservedKeys: reservedHits },
+    )
+  }
+
+  try {
+    await loadAgentRegistry()
+    const agent = getAgent(paramResult.data.agentId)
+    if (!agent) {
+      return jsonError(404, `Unknown agent "${paramResult.data.agentId}".`, 'agent_unknown')
+    }
+
+    if (!authResult.tenantId) {
+      return jsonError(
+        400,
+        'Caller has no tenant context; cannot persist tenant-scoped prompt override.',
+        'tenant_required',
+      )
+    }
+
+    const em = authResult.container.resolve<EntityManager>('em')
+    const repo = new AiAgentPromptOverrideRepository(em)
+    const saved = await repo.save(
+      {
+        agentId: agent.id,
+        sections,
+        notes: bodyResult.data.notes ?? null,
+      },
+      {
+        tenantId: authResult.tenantId,
+        organizationId: authResult.organizationId,
+        userId: authResult.userId,
+      },
+    )
+
+    return NextResponse.json({
+      ok: true,
+      agentId: agent.id,
+      version: saved.version,
+      updatedAt: saved.updatedAt?.toISOString?.() ?? new Date().toISOString(),
+    })
+  } catch (error) {
+    console.error('[AI Prompt Override POST] Failure:', error)
+    return jsonError(
+      500,
+      error instanceof Error ? error.message : 'Failed to save prompt override.',
+      'internal_error',
+    )
+  }
+}

package/src/modules/ai_assistant/api/ai/agents/route.ts

@@ -0,0 +1,107 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
+import { listAgents, loadAgentRegistry } from '../../../lib/agent-registry'
+import { hasRequiredFeatures } from '../../../lib/auth'
+import { toolRegistry } from '../../../lib/tool-registry'
+import type { AiToolDefinition } from '../../../lib/types'
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'List AI agents the caller can invoke',
+  methods: {
+    GET: {
+      operationId: 'aiAssistantListAgents',
+      summary: 'List registered AI agents, filtered by the caller\'s features.',
+      description:
+        'Returns `{ agents: [...] }` — the subset of agents from `ai-agents.generated.ts` that the ' +
+        'authenticated caller can invoke based on each agent\'s `requiredFeatures`. Mirrors the ' +
+        '`meta.list_agents` tool handler so backoffice pages (e.g. the playground) can render an ' +
+        'agent picker without going through the MCP tool transport.',
+      responses: [
+        {
+          status: 200,
+          description: 'Accessible agent summaries.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 500, description: 'Internal failure while loading the agent registry.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['ai_assistant.view'] },
+}
+
+export async function GET(req: NextRequest) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return NextResponse.json({ error: 'Unauthorized', code: 'unauthenticated' }, { status: 401 })
+  }
+
+  try {
+    const container = await createRequestContainer()
+    const rbacService = container.resolve<RbacService>('rbacService')
+    const acl = await rbacService.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    // No LLM provider configured (no API keys set). The launcher uses the
+    // `aiConfigured` flag to show a setup prompt; explicit `<AiChat>` mounts
+    // and playground pages still see the full registry so they can show their
+    // own configuration prompts instead of silently disappearing.
+    const aiConfigured = llmProviderRegistry.resolveFirstConfigured() != null
+
+    await loadAgentRegistry()
+    const all = listAgents()
+    const accessible = all.filter((agent) =>
+      hasRequiredFeatures(agent.requiredFeatures, acl.features, acl.isSuperAdmin, rbacService),
+    )
+
+    const agents = accessible.map((agent) => {
+      const tools = agent.allowedTools.map((toolName) => {
+        const tool = toolRegistry.getTool(toolName) as AiToolDefinition | undefined
+        return {
+          name: toolName,
+          displayName: tool?.displayName ?? toolName,
+          isMutation: Boolean(tool?.isMutation),
+          registered: Boolean(tool),
+        }
+      })
+      return {
+        id: agent.id,
+        moduleId: agent.moduleId,
+        label: agent.label,
+        description: agent.description,
+        systemPrompt: agent.systemPrompt,
+        executionMode: agent.executionMode ?? 'chat',
+        mutationPolicy: agent.mutationPolicy ?? 'read-only',
+        readOnly: Boolean(agent.readOnly),
+        maxSteps: agent.maxSteps ?? null,
+        allowedTools: agent.allowedTools,
+        tools,
+        requiredFeatures: agent.requiredFeatures ?? [],
+        acceptedMediaTypes: agent.acceptedMediaTypes ?? [],
+        keywords: agent.keywords ?? [],
+        suggestions: agent.suggestions ?? [],
+        hasOutputSchema: Boolean(agent.output),
+      }
+    })
+
+    return NextResponse.json({ agents, total: agents.length, aiConfigured })
+  } catch (error) {
+    console.error('[AI Agents] Failed to list agents:', error)
+    return NextResponse.json(
+      { error: 'Failed to list agents', code: 'internal_error' },
+      { status: 500 },
+    )
+  }
+}

package/src/modules/ai_assistant/api/ai/chat/__tests__/route.test.ts

@@ -0,0 +1,282 @@
+import { z } from 'zod'
+import type { AiAgentDefinition } from '../../../../lib/ai-agent-definition'
+import type { AiToolDefinition } from '../../../../lib/types'
+import {
+  resetAgentRegistryForTests,
+  seedAgentRegistryForTests,
+} from '../../../../lib/agent-registry'
+import { toolRegistry, registerMcpTool } from '../../../../lib/tool-registry'
+
+const authMock = jest.fn()
+const loadAclMock = jest.fn()
+const createRequestContainerMock = jest.fn()
+const runAiAgentTextMock = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({
+  getAuthFromRequest: (...args: unknown[]) => authMock(...args),
+}))
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: (...args: unknown[]) => createRequestContainerMock(...args),
+}))
+
+jest.mock('../../../../lib/agent-runtime', () => ({
+  runAiAgentText: (...args: unknown[]) => runAiAgentTextMock(...args),
+}))
+
+import { POST } from '../route'
+
+function makeAgent(
+  overrides: Partial<AiAgentDefinition> & Pick<AiAgentDefinition, 'id' | 'moduleId'>,
+): AiAgentDefinition {
+  return {
+    label: `${overrides.id} label`,
+    description: `${overrides.id} description`,
+    systemPrompt: 'You are a test agent.',
+    allowedTools: [],
+    ...overrides,
+  }
+}
+
+function makeTool(
+  overrides: Partial<AiToolDefinition> & Pick<AiToolDefinition, 'name'>,
+): AiToolDefinition {
+  return {
+    description: `${overrides.name} description`,
+    inputSchema: z.object({}),
+    handler: async () => ({ ok: true }),
+    ...overrides,
+  }
+}
+
+function buildRequest(options: {
+  agent?: string | null
+  body?: unknown
+  bodyRaw?: string
+}): Request {
+  const url = new URL('http://localhost/api/ai/chat')
+  if (options.agent !== undefined && options.agent !== null) {
+    url.searchParams.set('agent', options.agent)
+  }
+  const init: RequestInit = { method: 'POST' }
+  if (options.bodyRaw !== undefined) {
+    init.body = options.bodyRaw
+  } else if (options.body !== undefined) {
+    init.body = JSON.stringify(options.body)
+    init.headers = { 'content-type': 'application/json' }
+  }
+  return new Request(url, init)
+}
+
+describe('POST /api/ai/chat', () => {
+  let consoleErrorSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    authMock.mockResolvedValue({
+      sub: 'user-1',
+      tenantId: 'tenant-1',
+      orgId: 'org-1',
+    })
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.view'], isSuperAdmin: false })
+    createRequestContainerMock.mockResolvedValue({
+      resolve: (name: string) => {
+        if (name === 'rbacService') return { loadAcl: loadAclMock }
+        return null
+      },
+    })
+    runAiAgentTextMock.mockResolvedValue(
+      new Response('data: {"type":"text","content":"ok"}\n\ndata: [DONE]\n\n', {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+      }),
+    )
+  })
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore()
+  })
+
+  afterAll(() => {
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    authMock.mockResolvedValueOnce(null)
+
+    const response = await POST(buildRequest({ agent: 'customers.assistant', body: { messages: [{ role: 'user', content: 'hi' }] } }) as any)
+
+    expect(response.status).toBe(401)
+    const json = await response.json()
+    expect(json.code).toBe('unauthenticated')
+  })
+
+  it('returns 400 when the agent query param is missing', async () => {
+    const response = await POST(buildRequest({ body: { messages: [{ role: 'user', content: 'hi' }] } }) as any)
+
+    expect(response.status).toBe(400)
+    const json = await response.json()
+    expect(json.code).toBe('validation_error')
+  })
+
+  it('returns 400 when the agent query param is malformed', async () => {
+    const response = await POST(buildRequest({ agent: 'BadAgent', body: { messages: [{ role: 'user', content: 'hi' }] } }) as any)
+
+    expect(response.status).toBe(400)
+    const json = await response.json()
+    expect(json.code).toBe('validation_error')
+  })
+
+  it('returns 400 when body fails zod validation (missing messages)', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({ id: 'customers.assistant', moduleId: 'customers' }),
+    ])
+
+    const response = await POST(buildRequest({ agent: 'customers.assistant', body: {} }) as any)
+
+    expect(response.status).toBe(400)
+    const json = await response.json()
+    expect(json.code).toBe('validation_error')
+  })
+
+  it('returns 400 when messages exceed the cap', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({ id: 'customers.assistant', moduleId: 'customers' }),
+    ])
+
+    const messages = Array.from({ length: 101 }, (_, index) => ({
+      role: 'user' as const,
+      content: `msg-${index}`,
+    }))
+
+    const response = await POST(buildRequest({ agent: 'customers.assistant', body: { messages } }) as any)
+
+    expect(response.status).toBe(400)
+    const json = await response.json()
+    expect(json.code).toBe('validation_error')
+  })
+
+  it('returns 404 for an unknown agent', async () => {
+    // registry intentionally empty
+    const response = await POST(
+      buildRequest({ agent: 'customers.missing', body: { messages: [{ role: 'user', content: 'hi' }] } }) as any,
+    )
+
+    expect(response.status).toBe(404)
+    const json = await response.json()
+    expect(json.code).toBe('agent_unknown')
+  })
+
+  it('returns 403 when the agent requires features the user lacks', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.assistant',
+        moduleId: 'customers',
+        requiredFeatures: ['customers.assistant.use'],
+      }),
+    ])
+    loadAclMock.mockResolvedValueOnce({ features: ['ai_assistant.view'], isSuperAdmin: false })
+
+    const response = await POST(
+      buildRequest({
+        agent: 'customers.assistant',
+        body: { messages: [{ role: 'user', content: 'hi' }] },
+      }) as any,
+    )
+
+    expect(response.status).toBe(403)
+    const json = await response.json()
+    expect(json.code).toBe('agent_features_denied')
+  })
+
+  it('returns 409 when an object-mode agent is invoked via chat transport', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.extract',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        output: { schema: z.object({ title: z.string() }) },
+      }),
+    ])
+
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.extract',
+        body: { messages: [{ role: 'user', content: 'hi' }] },
+      }) as any,
+    )
+
+    expect(response.status).toBe(409)
+    const json = await response.json()
+    expect(json.code).toBe('execution_mode_not_supported')
+  })
+
+  it('delegates to runAiAgentText with the resolved auth and body payload', async () => {
+    registerMcpTool(
+      makeTool({ name: 'customers.list_people', requiredFeatures: ['customers.people.view'] }),
+      { moduleId: 'customers' },
+    )
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.assistant',
+        moduleId: 'customers',
+        allowedTools: ['customers.list_people'],
+      }),
+    ])
+
+    const response = await POST(
+      buildRequest({
+        agent: 'customers.assistant',
+        body: {
+          messages: [{ role: 'user', content: 'Hello assistant' }],
+          debug: true,
+          pageContext: { pageId: 'customers.people' },
+        },
+      }) as any,
+    )
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+    expect(runAiAgentTextMock).toHaveBeenCalledTimes(1)
+    const callArg = runAiAgentTextMock.mock.calls[0][0] as {
+      agentId: string
+      messages: unknown
+      debug?: boolean
+      pageContext?: { pageId?: string }
+      authContext: { tenantId: string | null; organizationId: string | null; userId: string }
+      container: unknown
+    }
+    expect(callArg.agentId).toBe('customers.assistant')
+    expect(callArg.debug).toBe(true)
+    expect(callArg.pageContext).toEqual({ pageId: 'customers.people' })
+    expect(callArg.authContext.userId).toBe('user-1')
+    expect(callArg.authContext.tenantId).toBe('tenant-1')
+    expect(callArg.authContext.organizationId).toBe('org-1')
+    expect(callArg.container).toBeDefined()
+  })
+
+  it('maps AgentPolicyError thrown by the runtime to the canonical HTTP status', async () => {
+    const { AgentPolicyError } = await import('../../../../lib/agent-tools')
+    seedAgentRegistryForTests([
+      makeAgent({ id: 'customers.assistant', moduleId: 'customers' }),
+    ])
+    runAiAgentTextMock.mockRejectedValueOnce(
+      new AgentPolicyError('tool_not_whitelisted', 'Tool not whitelisted'),
+    )
+
+    const response = await POST(
+      buildRequest({
+        agent: 'customers.assistant',
+        body: { messages: [{ role: 'user', content: 'hi' }] },
+      }) as any,
+    )
+
+    expect(response.status).toBe(409)
+    const json = await response.json()
+    expect(json.code).toBe('tool_not_whitelisted')
+  })
+})