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

package/src/modules/ai_assistant/ai-tools/meta-pack.ts

@@ -0,0 +1,140 @@
+/**
+ * General-purpose `meta.*` tool pack (Phase 1 WS-C, Step 3.8).
+ *
+ * `list_agents` enumerates agents the caller can invoke; `describe_agent`
+ * returns a serializable description (Zod output schema → JSON-Schema when
+ * possible, otherwise a `non-serializable` marker). Both tools treat a
+ * missing agent registry as an empty list — the chat runtime must not
+ * crash if `ai-agents.generated.ts` has not been emitted yet.
+ */
+import { z } from 'zod'
+import type { AiAgentDefinition } from '../lib/ai-agent-definition'
+import { listAgents, getAgent } from '../lib/agent-registry'
+import { hasRequiredFeatures } from '../lib/auth'
+import { defineAiTool } from '../lib/ai-tool-definition'
+import type { AiToolDefinition } from '../lib/types'
+
+function summarizeAgent(agent: AiAgentDefinition): Record<string, unknown> {
+  return {
+    id: agent.id,
+    moduleId: agent.moduleId,
+    label: agent.label,
+    description: agent.description,
+    requiredFeatures: agent.requiredFeatures ?? [],
+    allowedTools: agent.allowedTools,
+    executionMode: agent.executionMode ?? 'chat',
+    mutationPolicy: agent.mutationPolicy ?? 'read-only',
+    readOnly: typeof agent.readOnly === 'boolean' ? agent.readOnly : true,
+    maxSteps: agent.maxSteps ?? null,
+    acceptedMediaTypes: agent.acceptedMediaTypes ?? [],
+    domain: agent.domain ?? null,
+    keywords: agent.keywords ?? [],
+    suggestions: agent.suggestions ?? [],
+    dataCapabilities: agent.dataCapabilities ?? null,
+    hasOutputSchema: Boolean(agent.output),
+    hasPageContextResolver: typeof agent.resolvePageContext === 'function',
+  }
+}
+
+function serializeStructuredOutput(
+  output: AiAgentDefinition['output'],
+): Record<string, unknown> | null {
+  if (!output) return null
+  try {
+    const jsonSchema = z.toJSONSchema(output.schema as unknown as z.ZodType, {
+      unrepresentable: 'any',
+    })
+    return {
+      schemaName: output.schemaName,
+      mode: output.mode ?? 'generate',
+      jsonSchema,
+    }
+  } catch (error) {
+    return {
+      schemaName: output.schemaName,
+      mode: output.mode ?? 'generate',
+      note: 'non-serializable',
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+function serializePrompt(agent: AiAgentDefinition): Record<string, unknown> {
+  return {
+    systemPrompt: agent.systemPrompt,
+    hasDynamicPageContext: typeof agent.resolvePageContext === 'function',
+  }
+}
+
+const listAgentsInput = z.object({
+  moduleId: z.string().optional().describe('Restrict results to one module id.'),
+})
+
+const listAgentsTool = defineAiTool({
+  name: 'meta.list_agents',
+  displayName: 'List agents',
+  description:
+    'List registered AI agents the caller can invoke. Filters by requiredFeatures RBAC; returns { agents: [] } if the registry is empty.',
+  inputSchema: listAgentsInput,
+  requiredFeatures: ['ai_assistant.view'],
+  tags: ['read', 'meta'],
+  handler: async (rawInput, ctx) => {
+    const input = listAgentsInput.parse(rawInput)
+    let all: AiAgentDefinition[] = []
+    try {
+      all = listAgents()
+    } catch {
+      all = []
+    }
+    const filtered = all.filter((agent) => {
+      if (input.moduleId && agent.moduleId !== input.moduleId) return false
+      const features = agent.requiredFeatures ?? []
+      return hasRequiredFeatures(features, ctx.userFeatures, ctx.isSuperAdmin)
+    })
+    return {
+      agents: filtered.map(summarizeAgent),
+      total: filtered.length,
+    }
+  },
+})
+
+const describeAgentInput = z.object({
+  agentId: z.string().min(1).describe('Agent id (e.g. "catalog.merchandising_assistant").'),
+})
+
+const describeAgentTool = defineAiTool({
+  name: 'meta.describe_agent',
+  displayName: 'Describe agent',
+  description:
+    'Return metadata, RBAC, allowed tools, execution mode, output schema (JSON-Schema when representable), and prompt shape for a single agent. Never throws — returns { agent: null, reason } if missing or forbidden.',
+  inputSchema: describeAgentInput,
+  requiredFeatures: ['ai_assistant.view'],
+  tags: ['read', 'meta'],
+  handler: async (rawInput, ctx) => {
+    const input = describeAgentInput.parse(rawInput)
+    let agent: AiAgentDefinition | undefined
+    try {
+      agent = getAgent(input.agentId)
+    } catch {
+      agent = undefined
+    }
+    if (!agent) {
+      return { agent: null, reason: 'not_found' as const }
+    }
+    const features = agent.requiredFeatures ?? []
+    if (!hasRequiredFeatures(features, ctx.userFeatures, ctx.isSuperAdmin)) {
+      return { agent: null, reason: 'forbidden' as const }
+    }
+    return {
+      agent: {
+        ...summarizeAgent(agent),
+        output: serializeStructuredOutput(agent.output),
+        prompt: serializePrompt(agent),
+      },
+    }
+  },
+})
+
+export const metaAiTools: AiToolDefinition<any, any>[] = [listAgentsTool, describeAgentTool]
+
+export default metaAiTools

package/src/modules/ai_assistant/ai-tools/search-pack.ts

@@ -0,0 +1,122 @@
+/**
+ * General-purpose `search.*` tool pack (Phase 1 WS-C, Step 3.8).
+ *
+ * These tools are discovered by the generator alongside any other module
+ * `ai-tools.ts`; they expose the existing `@open-mercato/search` runtime to
+ * agents that whitelist them via `allowedTools`.
+ */
+import { z } from 'zod'
+import type { SearchOptions, SearchResult, SearchStrategyId } from '@open-mercato/shared/modules/search'
+import { defineAiTool } from '../lib/ai-tool-definition'
+import type { AiToolDefinition } from '../lib/types'
+
+type SearchServiceLike = {
+  search: (query: string, options: SearchOptions) => Promise<SearchResult[]>
+}
+
+const hybridSearchInput = z.object({
+  q: z.string().min(1).describe('Search query text.'),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe('Maximum results (default 20, max 100).'),
+  strategies: z
+    .array(z.enum(['fulltext', 'vector', 'tokens']))
+    .optional()
+    .describe('Subset of strategies to run; defaults to the module defaults.'),
+  entityTypes: z
+    .array(z.string())
+    .optional()
+    .describe('Filter to specific entity ids (e.g. "catalog:product").'),
+})
+
+const hybridSearchTool = defineAiTool({
+  name: 'search.hybrid_search',
+  displayName: 'Hybrid search',
+  description:
+    'Run a global fulltext + vector + token search across enabled entities for the current tenant/organization.',
+  inputSchema: hybridSearchInput,
+  requiredFeatures: ['search.view'],
+  tags: ['read', 'search'],
+  handler: async (rawInput, ctx) => {
+    if (!ctx.tenantId) {
+      throw new Error('Tenant context is required for search.hybrid_search')
+    }
+    const input = hybridSearchInput.parse(rawInput)
+    const service = ctx.container.resolve<SearchServiceLike>('searchService')
+    const limit = input.limit ?? 20
+    const started = Date.now()
+    const results = await service.search(input.q, {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      limit,
+      strategies: input.strategies as SearchStrategyId[] | undefined,
+      entityTypes: input.entityTypes,
+    })
+    const timingMs = Date.now() - started
+    const strategiesUsed = Array.from(
+      new Set(results.map((result) => result.source).filter((id): id is SearchStrategyId => typeof id === 'string')),
+    )
+    return {
+      query: input.q,
+      totalResults: results.length,
+      results,
+      strategiesUsed,
+      timing: { ms: timingMs },
+    }
+  },
+})
+
+const getRecordContextInput = z.object({
+  entityId: z.string().min(1).describe('Entity identifier (e.g. "customers:customer_person_profile").'),
+  recordId: z.string().min(1).describe('Record primary key (UUID).'),
+})
+
+const getRecordContextTool = defineAiTool({
+  name: 'search.get_record_context',
+  displayName: 'Get record context',
+  description:
+    'Resolve presenter, links, and URL for a specific record by re-querying the search index. Returns { found: false } when no hit matches the recordId.',
+  inputSchema: getRecordContextInput,
+  requiredFeatures: ['search.view'],
+  tags: ['read', 'search'],
+  handler: async (rawInput, ctx) => {
+    if (!ctx.tenantId) {
+      throw new Error('Tenant context is required for search.get_record_context')
+    }
+    const input = getRecordContextInput.parse(rawInput)
+    const service = ctx.container.resolve<SearchServiceLike>('searchService')
+    const results = await service.search(input.recordId, {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      limit: 5,
+      entityTypes: [input.entityId],
+    })
+    const match = results.find((result) => result.recordId === input.recordId)
+    if (!match) {
+      return {
+        found: false as const,
+        entityId: input.entityId,
+        recordId: input.recordId,
+      }
+    }
+    return {
+      found: true as const,
+      entityId: match.entityId,
+      recordId: match.recordId,
+      presenter: match.presenter,
+      url: match.url,
+      links: match.links,
+      metadata: match.metadata,
+      source: match.source,
+      score: match.score,
+    }
+  },
+})
+
+export const searchAiTools: AiToolDefinition<any, any>[] = [hybridSearchTool, getRecordContextTool]
+
+export default searchAiTools

package/src/modules/ai_assistant/ai-tools.ts

@@ -0,0 +1,21 @@
+/**
+ * Module-root AI tools contribution for `ai_assistant` (Phase 1 WS-C, Step 3.8).
+ *
+ * The generator scans every module for a top-level `ai-tools.ts` and takes
+ * the `aiTools` (or `default`) export as the module contribution. This file
+ * aggregates the three general-purpose tool packs (`search.*`,
+ * `attachments.*`, `meta.*`) so they flow through the existing
+ * `ai-tools.generated.ts` pipeline without any new generator plumbing.
+ */
+import type { AiToolDefinition } from './lib/types'
+import searchAiTools from './ai-tools/search-pack'
+import attachmentsAiTools from './ai-tools/attachments-pack'
+import metaAiTools from './ai-tools/meta-pack'
+
+export const aiTools: AiToolDefinition<any, any>[] = [
+  ...searchAiTools,
+  ...attachmentsAiTools,
+  ...metaAiTools,
+]
+
+export default aiTools

package/src/modules/ai_assistant/api/ai/actions/[id]/__tests__/route.test.ts

@@ -0,0 +1,222 @@
+const authMock = jest.fn()
+const loadAclMock = jest.fn()
+const createRequestContainerMock = jest.fn()
+const repoGetByIdMock = 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('../../../../../data/repositories/AiPendingActionRepository', () => ({
+  AiPendingActionRepository: jest.fn().mockImplementation(() => ({
+    getById: repoGetByIdMock,
+  })),
+}))
+
+import { GET } from '../route'
+
+function buildRequest(): Request {
+  return new Request('http://localhost/api/ai_assistant/ai/actions/pa_123', {
+    method: 'GET',
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+function buildContext(id: string) {
+  return { params: Promise.resolve({ id }) }
+}
+
+function makeRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'pa_123',
+    agentId: 'catalog.merchandising_assistant',
+    toolName: 'catalog.update_product',
+    status: 'pending',
+    fieldDiff: [{ field: 'title', before: 'Old', after: 'New' }],
+    records: null,
+    failedRecords: null,
+    sideEffectsSummary: null,
+    attachmentIds: [],
+    targetEntityType: 'product',
+    targetRecordId: 'prod_1',
+    recordVersion: 'v1',
+    queueMode: 'inline',
+    executionResult: null,
+    createdAt: new Date('2026-04-18T10:00:00.000Z'),
+    expiresAt: new Date('2026-04-18T10:15:00.000Z'),
+    resolvedAt: null,
+    resolvedByUserId: null,
+    // server-internal fields — MUST NOT leak through the serializer
+    normalizedInput: { secret: 'do-not-leak' },
+    createdByUserId: 'user-1',
+    idempotencyKey: 'idem_abc',
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    ...overrides,
+  }
+}
+
+describe('GET /api/ai/actions/:id route (Step 5.7)', () => {
+  let consoleErrorSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    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,
+            hasAllFeatures: (required: string[], granted: string[]) =>
+              required.every((feature) => granted.includes(feature)),
+          }
+        }
+        if (name === 'em') {
+          return {}
+        }
+        return null
+      },
+    })
+  })
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    authMock.mockResolvedValueOnce(null)
+
+    const response = await GET(buildRequest() as any, buildContext('pa_123'))
+
+    expect(response.status).toBe(401)
+    // 401 envelope does include `code: 'unauthenticated'` in this module's
+    // routes (see chat/route.ts + prompt-override/route.ts). TC-AI-002
+    // only requires "status 401 — body shape not asserted", and this route
+    // follows the same shape. We still assert status only here to keep
+    // contract parity with TC-AI-002 and avoid pinning downstream envelope
+    // changes into this test.
+  })
+
+  it('happy path: tenant-matching id returns 200 + serialized row', async () => {
+    repoGetByIdMock.mockResolvedValueOnce(makeRow())
+
+    const response = await GET(buildRequest() as any, buildContext('pa_123'))
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body.id).toBe('pa_123')
+    expect(body.agentId).toBe('catalog.merchandising_assistant')
+    expect(body.status).toBe('pending')
+    expect(body.toolName).toBe('catalog.update_product')
+    expect(body.fieldDiff).toEqual([{ field: 'title', before: 'Old', after: 'New' }])
+    expect(body.createdAt).toBe('2026-04-18T10:00:00.000Z')
+    expect(body.expiresAt).toBe('2026-04-18T10:15:00.000Z')
+    expect(body.resolvedAt).toBeNull()
+    expect(body.resolvedByUserId).toBeNull()
+    expect(body.queueMode).toBe('inline')
+
+    // Repository was called with the tenant/org scope from the auth context.
+    expect(repoGetByIdMock).toHaveBeenCalledTimes(1)
+    expect(repoGetByIdMock).toHaveBeenCalledWith('pa_123', {
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      userId: 'user-1',
+    })
+  })
+
+  it('cross-tenant id returns 404 pending_action_not_found', async () => {
+    // Repository is tenant-scoped: getById returns null when the row belongs
+    // to a different tenant/org.
+    repoGetByIdMock.mockResolvedValueOnce(null)
+
+    const response = await GET(buildRequest() as any, buildContext('pa_from_other_tenant'))
+
+    expect(response.status).toBe(404)
+    const body = await response.json()
+    expect(body.code).toBe('pending_action_not_found')
+  })
+
+  it('returns 404 when the id is unknown (no row)', async () => {
+    repoGetByIdMock.mockResolvedValueOnce(null)
+
+    const response = await GET(buildRequest() as any, buildContext('pa_missing'))
+
+    expect(response.status).toBe(404)
+    const body = await response.json()
+    expect(body.code).toBe('pending_action_not_found')
+  })
+
+  it('returns 403 when the caller lacks ai_assistant.view', async () => {
+    loadAclMock.mockResolvedValueOnce({
+      features: ['catalog.view'],
+      isSuperAdmin: false,
+    })
+
+    const response = await GET(buildRequest() as any, buildContext('pa_123'))
+
+    expect(response.status).toBe(403)
+    const body = await response.json()
+    expect(body.code).toBe('forbidden')
+    expect(repoGetByIdMock).not.toHaveBeenCalled()
+  })
+
+  it('internal fields are never present in the response body', async () => {
+    repoGetByIdMock.mockResolvedValueOnce(makeRow())
+
+    const response = await GET(buildRequest() as any, buildContext('pa_123'))
+
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body).not.toHaveProperty('normalizedInput')
+    expect(body).not.toHaveProperty('createdByUserId')
+    expect(body).not.toHaveProperty('idempotencyKey')
+    expect(body).not.toHaveProperty('tenantId')
+    expect(body).not.toHaveProperty('organizationId')
+  })
+
+  it('returns 400 when the id param is empty', async () => {
+    const response = await GET(buildRequest() as any, buildContext(''))
+
+    expect(response.status).toBe(400)
+    const body = await response.json()
+    expect(body.code).toBe('validation_error')
+  })
+
+  it('returns 404 when the caller has no tenant scope', async () => {
+    authMock.mockResolvedValueOnce({
+      sub: 'user-1',
+      tenantId: null,
+      orgId: null,
+    })
+
+    const response = await GET(buildRequest() as any, buildContext('pa_123'))
+
+    expect(response.status).toBe(404)
+    const body = await response.json()
+    expect(body.code).toBe('pending_action_not_found')
+    expect(repoGetByIdMock).not.toHaveBeenCalled()
+  })
+
+  it('returns 500 when the repository throws', async () => {
+    repoGetByIdMock.mockRejectedValueOnce(new Error('db down'))
+
+    const response = await GET(buildRequest() as any, buildContext('pa_123'))
+
+    expect(response.status).toBe(500)
+    const body = await response.json()
+    expect(body.code).toBe('internal_error')
+  })
+})