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

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

@@ -0,0 +1,207 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import type { UIMessage } from 'ai'
+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 { loadAgentRegistry } from '../../../lib/agent-registry'
+import { checkAgentPolicy, type AgentPolicyDenyCode } from '../../../lib/agent-policy'
+import { runAiAgentText } from '../../../lib/agent-runtime'
+import { AgentPolicyError } from '../../../lib/agent-tools'
+
+const MAX_MESSAGES = 100
+
+const agentIdPattern = /^[a-z0-9_]+\.[a-z0-9_]+$/
+
+const chatMessageSchema = z.object({
+  role: z.enum(['user', 'assistant', 'system']),
+  content: z.string(),
+})
+
+const pageContextSchema = z
+  .object({
+    pageId: z.string().nullable().optional(),
+    entityType: z.string().nullable().optional(),
+    recordId: z.string().nullable().optional(),
+  })
+  .passthrough()
+
+const chatRequestSchema = z.object({
+  messages: z
+    .array(chatMessageSchema)
+    .min(1, 'messages must contain at least one message')
+    .max(MAX_MESSAGES, `messages must contain at most ${MAX_MESSAGES} entries`),
+  attachmentIds: z.array(z.string()).optional(),
+  debug: z.boolean().optional(),
+  pageContext: pageContextSchema.optional(),
+  /**
+   * Optional stable conversation id forwarded from `<AiChat>`. Bridged into
+   * the Step 5.6 `prepareMutation` idempotency hash so repeated turns within
+   * the same chat collapse onto the same pending action. Additive; omitted
+   * bodies continue to work as before.
+   */
+  conversationId: z.string().min(1).max(128).optional(),
+})
+
+export type AiChatRequest = z.infer<typeof chatRequestSchema>
+
+const agentQuerySchema = z.object({
+  agent: z
+    .string()
+    .regex(agentIdPattern, 'agent must match "<module>.<agent>" (lowercase, digits, underscores only)'),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'AI agent dispatcher',
+  methods: {
+    POST: {
+      operationId: 'aiAssistantChatAgent',
+      summary: 'Stream a chat turn for a registered AI agent',
+      description:
+        'Dispatches a chat turn to the focused AI agent identified by `?agent=<module>.<agent>`. ' +
+        'Enforces agent-level `requiredFeatures`, tool whitelisting, read-only / mutationPolicy, ' +
+        'execution-mode compatibility, and attachment media-type policy. The streaming response ' +
+        'body uses an AI SDK-compatible `text/event-stream` transport.',
+      query: agentQuerySchema,
+      requestBody: {
+        contentType: 'application/json',
+        description: 'Chat turn payload. `messages` is required; `attachmentIds`, `debug`, and `pageContext` are optional.',
+        schema: chatRequestSchema,
+      },
+      responses: [
+        { status: 200, description: 'Streaming text/event-stream response compatible with AI SDK chat transports.', mediaType: 'text/event-stream' },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid query param, malformed payload, or message count above the cap.' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks agent-level or tool-level required features.' },
+        { status: 404, description: 'Unknown agent id.' },
+        { status: 409, description: 'Agent/tool/execution-mode policy violation.' },
+        { status: 500, description: 'Internal runtime failure.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['ai_assistant.view'] },
+}
+
+function jsonError(
+  status: number,
+  message: string,
+  code: string,
+  extra?: Record<string, unknown>,
+): NextResponse {
+  return NextResponse.json({ error: message, code, ...(extra ?? {}) }, { status })
+}
+
+function statusForDenyCode(code: AgentPolicyDenyCode): number {
+  switch (code) {
+    case 'agent_unknown':
+      return 404
+    case 'agent_features_denied':
+    case 'tool_features_denied':
+      return 403
+    case 'tool_not_whitelisted':
+    case 'tool_unknown':
+    case 'mutation_blocked_by_readonly':
+    case 'mutation_blocked_by_policy':
+    case 'execution_mode_not_supported':
+      return 409
+    case 'attachment_type_not_accepted':
+      return 400
+    default:
+      return 409
+  }
+}
+
+export async function POST(req: NextRequest): Promise<Response> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return jsonError(401, 'Unauthorized', 'unauthenticated')
+  }
+
+  const requestUrl = new URL(req.url)
+  const queryResult = agentQuerySchema.safeParse({
+    agent: requestUrl.searchParams.get('agent') ?? undefined,
+  })
+  if (!queryResult.success) {
+    return jsonError(400, 'Invalid or missing "agent" query parameter.', 'validation_error', {
+      issues: queryResult.error.issues,
+    })
+  }
+  const agentId = queryResult.data.agent
+
+  let parsedBody: unknown
+  try {
+    parsedBody = await req.json()
+  } catch {
+    return jsonError(400, 'Request body must be valid JSON.', 'validation_error')
+  }
+
+  const bodyResult = chatRequestSchema.safeParse(parsedBody)
+  if (!bodyResult.success) {
+    return jsonError(400, 'Invalid request body.', 'validation_error', {
+      issues: bodyResult.error.issues,
+    })
+  }
+
+  try {
+    await loadAgentRegistry()
+
+    const container = await createRequestContainer()
+    const rbacService = container.resolve<RbacService>('rbacService')
+    const acl = await rbacService.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    const decision = checkAgentPolicy({
+      agentId,
+      authContext: {
+        userFeatures: acl.features,
+        isSuperAdmin: acl.isSuperAdmin,
+      },
+      requestedExecutionMode: 'chat',
+      // TODO(step-3.7): resolve attachmentIds -> media types via attachment-bridge
+      // once the attachment-to-model conversion bridge lands. Until then the
+      // policy gate skips attachment-type validation because media types are
+      // not known at dispatch time.
+      attachmentMediaTypes: undefined,
+    })
+
+    if (!decision.ok) {
+      return jsonError(statusForDenyCode(decision.code), decision.message, decision.code)
+    }
+
+    return await runAiAgentText({
+      agentId,
+      messages: bodyResult.data.messages as unknown as UIMessage[],
+      attachmentIds: bodyResult.data.attachmentIds,
+      pageContext: bodyResult.data.pageContext,
+      debug: bodyResult.data.debug,
+      conversationId: bodyResult.data.conversationId ?? null,
+      authContext: {
+        tenantId: auth.tenantId ?? null,
+        organizationId: auth.orgId ?? null,
+        userId: auth.sub,
+        features: acl.features,
+        isSuperAdmin: acl.isSuperAdmin,
+      },
+      container,
+    })
+  } catch (error) {
+    if (error instanceof AgentPolicyError) {
+      return jsonError(statusForDenyCode(error.code), error.message, error.code)
+    }
+    console.error('[AI Chat Agent] Dispatch failure:', error)
+    return jsonError(
+      500,
+      error instanceof Error ? error.message : 'Agent dispatch failed.',
+      'internal_error',
+    )
+  }
+}

package/src/modules/ai_assistant/api/ai/run-object/__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 runAiAgentObjectMock = 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', () => ({
+  runAiAgentObject: (...args: unknown[]) => runAiAgentObjectMock(...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(body: unknown): Request {
+  return new Request('http://localhost/api/ai_assistant/ai/run-object', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+}
+
+describe('POST /api/ai_assistant/ai/run-object', () => {
+  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
+      },
+    })
+    runAiAgentObjectMock.mockResolvedValue({
+      mode: 'generate',
+      object: { title: 'hello' },
+      finishReason: 'stop',
+      usage: { inputTokens: 10, outputTokens: 20 },
+    })
+  })
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore()
+  })
+
+  afterAll(() => {
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    authMock.mockResolvedValueOnce(null)
+
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.extract',
+        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 body fails zod validation (missing messages)', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.extract',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        output: { schemaName: 'Extract', schema: z.object({ title: z.string() }) },
+      }),
+    ])
+
+    const response = await POST(buildRequest({ agent: 'catalog.extract' }) 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 () => {
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.missing',
+        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: 'catalog.extract',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        requiredFeatures: ['catalog.extract.use'],
+        output: { schemaName: 'Extract', schema: z.object({ title: z.string() }) },
+      }),
+    ])
+
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.extract',
+        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 422 when a chat-mode agent is invoked via run-object', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.assistant',
+        moduleId: 'customers',
+      }),
+    ])
+
+    const response = await POST(
+      buildRequest({
+        agent: 'customers.assistant',
+        messages: [{ role: 'user', content: 'hi' }],
+      }) as any,
+    )
+
+    expect(response.status).toBe(422)
+    const json = await response.json()
+    expect(json.code).toBe('execution_mode_not_supported')
+  })
+
+  it('returns 200 and delegates to runAiAgentObject on success', async () => {
+    registerMcpTool(
+      makeTool({ name: 'catalog.read_product', requiredFeatures: ['catalog.products.view'] }),
+      { moduleId: 'catalog' },
+    )
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.extract',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        allowedTools: ['catalog.read_product'],
+        output: { schemaName: 'Extract', schema: z.object({ title: z.string() }) },
+      }),
+    ])
+
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.extract',
+        messages: [{ role: 'user', content: 'Generate a product title' }],
+        pageContext: { pageId: 'ai_assistant.playground' },
+      }) as any,
+    )
+
+    expect(response.status).toBe(200)
+    const json = await response.json()
+    expect(json).toEqual({
+      object: { title: 'hello' },
+      finishReason: 'stop',
+      usage: { inputTokens: 10, outputTokens: 20 },
+    })
+    expect(runAiAgentObjectMock).toHaveBeenCalledTimes(1)
+    const callArg = runAiAgentObjectMock.mock.calls[0][0] as {
+      agentId: string
+      input: unknown
+      pageContext?: { pageId?: string }
+      authContext: { userId: string; tenantId: string | null; organizationId: string | null }
+    }
+    expect(callArg.agentId).toBe('catalog.extract')
+    expect(callArg.pageContext).toEqual({ pageId: 'ai_assistant.playground' })
+    expect(callArg.authContext.userId).toBe('user-1')
+    expect(callArg.authContext.tenantId).toBe('tenant-1')
+    expect(callArg.authContext.organizationId).toBe('org-1')
+  })
+
+  it('returns 422 when the helper resolves to stream mode', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.extract',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        output: { schemaName: 'Extract', schema: z.object({ title: z.string() }) },
+      }),
+    ])
+    runAiAgentObjectMock.mockResolvedValueOnce({
+      mode: 'stream',
+      object: Promise.resolve({ title: 'hello' }),
+      partialObjectStream: (async function* () {})(),
+      textStream: (async function* () {})(),
+    })
+
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.extract',
+        messages: [{ role: 'user', content: 'hi' }],
+      }) as any,
+    )
+
+    expect(response.status).toBe(422)
+    const json = await response.json()
+    expect(json.code).toBe('execution_mode_not_supported')
+  })
+
+  it('maps AgentPolicyError thrown by the runtime to the canonical HTTP status', async () => {
+    const { AgentPolicyError } = await import('../../../../lib/agent-tools')
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.extract',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        output: { schemaName: 'Extract', schema: z.object({ title: z.string() }) },
+      }),
+    ])
+    runAiAgentObjectMock.mockRejectedValueOnce(
+      new AgentPolicyError('tool_not_whitelisted', 'Tool not whitelisted'),
+    )
+
+    const response = await POST(
+      buildRequest({
+        agent: 'catalog.extract',
+        messages: [{ role: 'user', content: 'hi' }],
+      }) as any,
+    )
+
+    expect(response.status).toBe(409)
+    const json = await response.json()
+    expect(json.code).toBe('tool_not_whitelisted')
+  })
+})

package/src/modules/ai_assistant/api/ai/run-object/route.ts

@@ -0,0 +1,204 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import type { UIMessage } from 'ai'
+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 { loadAgentRegistry } from '../../../lib/agent-registry'
+import { checkAgentPolicy, type AgentPolicyDenyCode } from '../../../lib/agent-policy'
+import { runAiAgentObject } from '../../../lib/agent-runtime'
+import { AgentPolicyError } from '../../../lib/agent-tools'
+
+const MAX_MESSAGES = 100
+
+const agentIdPattern = /^[a-z0-9_]+\.[a-z0-9_]+$/
+
+const agentIdSchema = z
+  .string()
+  .regex(agentIdPattern, 'agent must match "<module>.<agent>" (lowercase, digits, underscores only)')
+
+const chatMessageSchema = z.object({
+  role: z.enum(['user', 'assistant', 'system']),
+  content: z.string(),
+})
+
+const pageContextSchema = z
+  .object({
+    pageId: z.string().optional(),
+    entityType: z.string().optional(),
+    recordId: z.string().optional(),
+  })
+  .passthrough()
+
+const runObjectRequestSchema = z.object({
+  agent: agentIdSchema,
+  messages: z
+    .array(chatMessageSchema)
+    .min(1, 'messages must contain at least one message')
+    .max(MAX_MESSAGES, `messages must contain at most ${MAX_MESSAGES} entries`),
+  attachmentIds: z.array(z.string()).optional(),
+  pageContext: pageContextSchema.optional(),
+  modelOverride: z.string().optional(),
+})
+
+export type AiRunObjectRequest = z.infer<typeof runObjectRequestSchema>
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'Run an AI agent in structured-output (object) mode',
+  methods: {
+    POST: {
+      operationId: 'aiAssistantRunObject',
+      summary: 'Run an object-mode AI agent and return the generated object',
+      description:
+        'Invokes `runAiAgentObject` server-side for the registered AI agent identified by `agent` ' +
+        '(matching "<module>.<agent>"). Enforces the same `requiredFeatures`, tool whitelisting, ' +
+        'mutationPolicy, and attachment media-type policy as the chat dispatcher, but additionally ' +
+        'requires the agent to declare `executionMode: "object"`. Returns the generated object in ' +
+        'a single JSON response (no streaming).',
+      requestBody: {
+        contentType: 'application/json',
+        description:
+          'Object-mode dispatch payload. `agent` and `messages` are required; `attachmentIds`, `pageContext`, and `modelOverride` are optional.',
+        schema: runObjectRequestSchema,
+      },
+      responses: [
+        {
+          status: 200,
+          description: 'Object-mode run completed; response body contains `{ object, usage?, finishReason? }`.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Malformed payload or message cap exceeded.' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks agent-level or tool-level required features.' },
+        { status: 404, description: 'Unknown agent id.' },
+        { status: 409, description: 'Agent/tool/execution-mode policy violation.' },
+        { status: 422, description: 'Agent does not support object-mode execution.' },
+        { status: 500, description: 'Internal runtime failure.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['ai_assistant.view'] },
+}
+
+function jsonError(
+  status: number,
+  message: string,
+  code: string,
+  extra?: Record<string, unknown>,
+): NextResponse {
+  return NextResponse.json({ error: message, code, ...(extra ?? {}) }, { status })
+}
+
+function statusForDenyCode(code: AgentPolicyDenyCode): number {
+  switch (code) {
+    case 'agent_unknown':
+      return 404
+    case 'agent_features_denied':
+    case 'tool_features_denied':
+      return 403
+    case 'execution_mode_not_supported':
+      return 422
+    case 'tool_not_whitelisted':
+    case 'tool_unknown':
+    case 'mutation_blocked_by_readonly':
+    case 'mutation_blocked_by_policy':
+      return 409
+    case 'attachment_type_not_accepted':
+      return 400
+    default:
+      return 409
+  }
+}
+
+export async function POST(req: NextRequest): Promise<Response> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return jsonError(401, 'Unauthorized', 'unauthenticated')
+  }
+
+  let parsedBody: unknown
+  try {
+    parsedBody = await req.json()
+  } catch {
+    return jsonError(400, 'Request body must be valid JSON.', 'validation_error')
+  }
+
+  const bodyResult = runObjectRequestSchema.safeParse(parsedBody)
+  if (!bodyResult.success) {
+    return jsonError(400, 'Invalid request body.', 'validation_error', {
+      issues: bodyResult.error.issues,
+    })
+  }
+
+  try {
+    await loadAgentRegistry()
+
+    const container = await createRequestContainer()
+    const rbacService = container.resolve<RbacService>('rbacService')
+    const acl = await rbacService.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    const decision = checkAgentPolicy({
+      agentId: bodyResult.data.agent,
+      authContext: {
+        userFeatures: acl.features,
+        isSuperAdmin: acl.isSuperAdmin,
+      },
+      requestedExecutionMode: 'object',
+      attachmentMediaTypes: undefined,
+    })
+
+    if (!decision.ok) {
+      return jsonError(statusForDenyCode(decision.code), decision.message, decision.code)
+    }
+
+    const result = await runAiAgentObject({
+      agentId: bodyResult.data.agent,
+      input: bodyResult.data.messages as unknown as UIMessage[],
+      attachmentIds: bodyResult.data.attachmentIds,
+      pageContext: bodyResult.data.pageContext,
+      modelOverride: bodyResult.data.modelOverride,
+      authContext: {
+        tenantId: auth.tenantId ?? null,
+        organizationId: auth.orgId ?? null,
+        userId: auth.sub,
+        features: acl.features,
+        isSuperAdmin: acl.isSuperAdmin,
+      },
+      container,
+    })
+
+    if (result.mode !== 'generate') {
+      return jsonError(
+        422,
+        'Streaming object-mode is not supported by the run-object HTTP route; agent must use generate mode.',
+        'execution_mode_not_supported',
+      )
+    }
+
+    return NextResponse.json({
+      object: result.object,
+      finishReason: result.finishReason,
+      usage: result.usage,
+    })
+  } catch (error) {
+    if (error instanceof AgentPolicyError) {
+      return jsonError(statusForDenyCode(error.code), error.message, error.code)
+    }
+    console.error('[AI Run Object] Dispatch failure:', error)
+    return jsonError(
+      500,
+      error instanceof Error ? error.message : 'Agent object dispatch failed.',
+      'internal_error',
+    )
+  }
+}