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

package/src/modules/ai_assistant/__tests__/integration/ws-c-tool-pack-coverage.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Step 3.13 — Phase 1 WS-C integration tests (tool-pack coverage).
+ *
+ * Re-exercises the cross-cutting shape of the `search.*`, `attachments.*`, and
+ * `meta.*` packs through the agent runtime so we can assert the invariants
+ * that per-pack unit tests cannot:
+ *
+ *   - Every pack tool carries `requiredFeatures` (no unguarded read tool).
+ *   - Tenant context is enforced by search/attachments handlers before any
+ *     downstream resolve() call.
+ *   - `meta.list_agents` degrades gracefully on an empty registry and honors
+ *     RBAC filtering + super-admin bypass when wired through the same
+ *     `listAgents()` API used by the chat dispatcher.
+ *   - An agent that whitelists all three packs reaches the AI SDK with the
+ *     full tool map and no extras.
+ *
+ * Customer/catalog tool packs are covered by their per-pack unit tests under
+ * `packages/core/src/modules/{customers,catalog}/__tests__/ai-tools/`. Those
+ * tests already verify tenant isolation, not-found shape, includeRelated
+ * aggregates, search_products routing, and suggest_price_adjustment's
+ * `isMutation: false` + `currentPrice: null` fallback. Re-testing them here
+ * would require cross-package Jest plumbing the ai-assistant harness does not
+ * currently support — documented as a deliberate scoping choice; see
+ * `${run_folder}/step-3.13-checks.md`.
+ */
+
+import { z } from 'zod'
+import type { AiAgentDefinition } from '../../lib/ai-agent-definition'
+import type { AiToolDefinition } from '../../lib/types'
+
+const streamTextMock = jest.fn()
+
+jest.mock('ai', () => {
+  const actual = jest.requireActual('ai')
+  return {
+    ...actual,
+    streamText: (...args: unknown[]) => streamTextMock(...args),
+  }
+})
+
+const createModelMock = jest.fn(
+  (options: { modelId: string; apiKey: string }) => ({ id: options.modelId, apiKey: options.apiKey }),
+)
+const resolveApiKeyMock = jest.fn(() => 'test-api-key')
+
+jest.mock('@open-mercato/shared/lib/ai/llm-provider-registry', () => ({
+  llmProviderRegistry: {
+    resolveFirstConfigured: () => ({
+      id: 'test-provider',
+      defaultModel: 'provider-default-model',
+      resolveApiKey: resolveApiKeyMock,
+      createModel: createModelMock,
+    }),
+  },
+}))
+
+import {
+  resetAgentRegistryForTests,
+  seedAgentRegistryForTests,
+} from '../../lib/agent-registry'
+import { toolRegistry, registerMcpTool } from '../../lib/tool-registry'
+import { resolveAiAgentTools } from '../../lib/agent-tools'
+
+import searchAiTools from '../../ai-tools/search-pack'
+import attachmentsAiTools from '../../ai-tools/attachments-pack'
+import metaAiTools from '../../ai-tools/meta-pack'
+
+import { listAgents } from '../../lib/agent-registry'
+import { hasRequiredFeatures } from '../../lib/auth'
+
+function findTool(
+  pack: AiToolDefinition<any, any>[],
+  name: string,
+): AiToolDefinition<any, any> {
+  const tool = pack.find((entry) => entry.name === name)
+  if (!tool) throw new Error(`tool ${name} not registered in pack`)
+  return tool
+}
+
+function makeAgent(
+  overrides: Partial<AiAgentDefinition> & Pick<AiAgentDefinition, 'id' | 'moduleId'>,
+): AiAgentDefinition {
+  return {
+    label: `${overrides.id} label`,
+    description: `${overrides.id} description`,
+    systemPrompt: 'System prompt.',
+    allowedTools: [],
+    ...overrides,
+  }
+}
+
+function makeCtx(overrides: Partial<{
+  tenantId: string | null
+  organizationId: string | null
+  userId: string | null
+  userFeatures: string[]
+  isSuperAdmin: boolean
+  container: { resolve: (name: string) => unknown }
+}> = {}) {
+  return {
+    tenantId: 'tenant-a',
+    organizationId: 'org-a',
+    userId: 'user-a',
+    container: { resolve: jest.fn() },
+    userFeatures: ['ai_assistant.view'],
+    isSuperAdmin: false,
+    ...overrides,
+  }
+}
+
+describe('WS-C integration — tool-pack coverage', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+    streamTextMock.mockImplementation(() => ({
+      toTextStreamResponse: jest.fn(() => new Response('ok')),
+    }))
+  })
+
+  afterAll(() => {
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+  })
+
+  describe('every read tool across the three packs carries requiredFeatures', () => {
+    it('search pack', () => {
+      for (const tool of searchAiTools) {
+        expect(tool.requiredFeatures).toBeDefined()
+        expect((tool.requiredFeatures as string[]).length).toBeGreaterThan(0)
+      }
+    })
+
+    it('attachments pack', () => {
+      for (const tool of attachmentsAiTools) {
+        expect(tool.requiredFeatures).toBeDefined()
+        expect((tool.requiredFeatures as string[]).length).toBeGreaterThan(0)
+      }
+    })
+
+    it('meta pack', () => {
+      for (const tool of metaAiTools) {
+        expect(tool.requiredFeatures).toEqual(['ai_assistant.view'])
+      }
+    })
+  })
+
+  describe('search.hybrid_search — tenant context enforcement', () => {
+    const tool = findTool(searchAiTools, 'search.hybrid_search')
+
+    it('throws when tenantId is missing (short-circuits before any search)', async () => {
+      await expect(
+        tool.handler({ q: 'anything' }, makeCtx({ tenantId: null }) as any),
+      ).rejects.toThrow(/tenant/i)
+    })
+
+    it('propagates tenantId + organizationId to the search service call', async () => {
+      const searchMock = jest.fn().mockResolvedValue([])
+      const ctx = makeCtx({
+        container: {
+          resolve: (name: string) => {
+            if (name === 'searchService') return { search: searchMock }
+            throw new Error(`Unknown registration: ${name}`)
+          },
+        },
+      })
+
+      await tool.handler({ q: 'hello', limit: 10 }, ctx as any)
+
+      expect(searchMock).toHaveBeenCalledTimes(1)
+      const [query, options] = searchMock.mock.calls[0] as [string, Record<string, unknown>]
+      expect(query).toBe('hello')
+      expect(options.tenantId).toBe('tenant-a')
+      expect(options.organizationId).toBe('org-a')
+      expect(options.limit).toBe(10)
+    })
+  })
+
+  describe('attachments.list_record_attachments — tenant context enforcement', () => {
+    const tool = findTool(attachmentsAiTools, 'attachments.list_record_attachments')
+
+    it('throws when tenantId is missing', async () => {
+      await expect(
+        tool.handler(
+          { entityType: 'customers:customer_person_profile', recordId: 'r1' },
+          makeCtx({ tenantId: null }) as any,
+        ),
+      ).rejects.toThrow(/tenant/i)
+    })
+  })
+
+  describe('meta.list_agents — RBAC + empty-registry graceful path', () => {
+    const tool = findTool(metaAiTools, 'meta.list_agents')
+
+    it('returns { agents: [], total: 0 } when the registry is empty', async () => {
+      const result = (await tool.handler({}, makeCtx() as any)) as {
+        agents: unknown[]
+        total: number
+      }
+      expect(result.agents).toEqual([])
+      expect(result.total).toBe(0)
+    })
+
+    it('filters by requiredFeatures using the same matcher the chat runtime uses', async () => {
+      seedAgentRegistryForTests([
+        makeAgent({ id: 'catalog.reader', moduleId: 'catalog', requiredFeatures: ['catalog.products.view'] }),
+        makeAgent({ id: 'catalog.writer', moduleId: 'catalog', requiredFeatures: ['catalog.products.manage'] }),
+      ])
+      const ctx = makeCtx({ userFeatures: ['ai_assistant.view', 'catalog.products.view'] })
+      const result = (await tool.handler({}, ctx as any)) as {
+        agents: Array<{ id: string }>
+      }
+      expect(result.agents.map((a) => a.id)).toEqual(['catalog.reader'])
+
+      // Parity with the chat runtime: the dispatcher uses the same helper.
+      const allowed = listAgents().filter((agent) =>
+        hasRequiredFeatures(agent.requiredFeatures ?? [], ctx.userFeatures, ctx.isSuperAdmin),
+      )
+      expect(allowed.map((a) => a.id)).toEqual(['catalog.reader'])
+    })
+
+    it('super-admin bypass: every agent is returned regardless of requiredFeatures', async () => {
+      seedAgentRegistryForTests([
+        makeAgent({ id: 'x.a', moduleId: 'x', requiredFeatures: ['x.secret'] }),
+        makeAgent({ id: 'y.b', moduleId: 'y', requiredFeatures: ['y.secret'] }),
+      ])
+      const ctx = makeCtx({ userFeatures: [], isSuperAdmin: true })
+      const result = (await tool.handler({}, ctx as any)) as {
+        agents: Array<{ id: string }>
+      }
+      expect(result.agents.map((a) => a.id).sort()).toEqual(['x.a', 'y.b'])
+    })
+  })
+
+  describe('agent whitelisting three packs reaches the SDK with the full tool map + no extras', () => {
+    it('resolveAiAgentTools picks only whitelisted tools across packs', async () => {
+      // Register one tool from each pack under a fresh registry.
+      for (const tool of [
+        findTool(searchAiTools, 'search.hybrid_search'),
+        findTool(attachmentsAiTools, 'attachments.list_record_attachments'),
+        findTool(metaAiTools, 'meta.list_agents'),
+      ]) {
+        registerMcpTool(tool as never)
+      }
+      // Plus an extra tool the agent does NOT whitelist; MUST NOT appear.
+      registerMcpTool({
+        name: 'catalog.update_product',
+        description: 'write tool',
+        inputSchema: z.object({}),
+        handler: async () => ({}),
+        isMutation: true,
+        requiredFeatures: ['catalog.products.manage'],
+      })
+
+      seedAgentRegistryForTests([
+        makeAgent({
+          id: 'multi.reader',
+          moduleId: 'multi',
+          allowedTools: [
+            'search.hybrid_search',
+            'attachments.list_record_attachments',
+            'meta.list_agents',
+          ],
+        }),
+      ])
+
+      const resolved = await resolveAiAgentTools({
+        agentId: 'multi.reader',
+        authContext: {
+          tenantId: 'tenant-a',
+          organizationId: 'org-a',
+          userId: 'user-a',
+          features: ['*'],
+          isSuperAdmin: true,
+        },
+      })
+
+      const toolNames = Object.keys(resolved.tools).sort()
+      expect(toolNames).toEqual(
+        ['attachments__list_record_attachments', 'meta__list_agents', 'search__hybrid_search'].sort(),
+      )
+      expect(toolNames).not.toContain('catalog__update_product')
+    })
+  })
+})

package/src/modules/ai_assistant/ai-tools/__tests__/attachments-pack.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Step 3.8 — `attachments.*` tool pack unit tests.
+ *
+ * Covers list happy/empty, read with/without extracted text, tenant
+ * isolation on reads, transfer happy path, and the mutation flag on
+ * `attachments.transfer_record_attachments`.
+ */
+const findWithDecryptionMock = jest.fn()
+const findOneWithDecryptionMock = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findWithDecryption: (...args: unknown[]) => findWithDecryptionMock(...args),
+  findOneWithDecryption: (...args: unknown[]) => findOneWithDecryptionMock(...args),
+}))
+
+jest.mock('@open-mercato/core/modules/attachments/data/entities', () => ({
+  Attachment: class AttachmentStub {},
+}))
+
+jest.mock('@open-mercato/core/modules/attachments/lib/metadata', () => ({
+  readAttachmentMetadata: (raw: unknown) => {
+    if (!raw || typeof raw !== 'object') return { tags: [], assignments: [] }
+    const value = raw as Record<string, unknown>
+    return {
+      tags: Array.isArray(value.tags) ? (value.tags as string[]) : [],
+      assignments: Array.isArray(value.assignments)
+        ? (value.assignments as Array<Record<string, unknown>>)
+        : [],
+    }
+  },
+  mergeAttachmentMetadata: (raw: unknown, patch: Record<string, unknown>) => {
+    const base =
+      raw && typeof raw === 'object' ? ({ ...(raw as Record<string, unknown>) }) : ({} as Record<string, unknown>)
+    return { ...base, ...patch }
+  },
+}))
+
+import attachmentsAiTools from '../attachments-pack'
+
+function findTool(name: string) {
+  const tool = attachmentsAiTools.find((entry) => entry.name === name)
+  if (!tool) throw new Error(`tool ${name} missing`)
+  return tool
+}
+
+type Ctx = {
+  tenantId: string | null
+  organizationId: string | null
+  userId: string | null
+  container: { resolve: (name: string) => unknown }
+  userFeatures: string[]
+  isSuperAdmin: boolean
+}
+
+function makeCtx(overrides: Partial<Ctx> = {}): {
+  ctx: Ctx
+  em: { persist: jest.Mock; flush: jest.Mock }
+} {
+  const em: any = {
+    persist: jest.fn(function (this: any) {
+      return em
+    }),
+    flush: jest.fn().mockResolvedValue(undefined),
+  }
+  const container = {
+    resolve: jest.fn((name: string) => {
+      if (name === 'em') return em
+      throw new Error(`unexpected resolve ${name}`)
+    }),
+  }
+  const ctx: Ctx = {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    userId: 'user-1',
+    container,
+    userFeatures: ['attachments.view', 'attachments.manage'],
+    isSuperAdmin: false,
+    ...overrides,
+  }
+  return { ctx, em }
+}
+
+function makeRow(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 'att-1',
+    entityId: 'customers:customer_person_profile',
+    recordId: 'person-1',
+    fileName: 'passport.pdf',
+    mimeType: 'application/pdf',
+    fileSize: 2048,
+    partitionCode: 'default',
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    storageMetadata: null,
+    content: null,
+    createdAt: new Date('2026-04-18T10:00:00Z'),
+    ...overrides,
+  }
+}
+
+beforeEach(() => {
+  findWithDecryptionMock.mockReset()
+  findOneWithDecryptionMock.mockReset()
+})
+
+describe('attachments.list_record_attachments', () => {
+  const tool = findTool('attachments.list_record_attachments')
+
+  it('returns metadata-only items scoped by tenant + organization', async () => {
+    findWithDecryptionMock.mockResolvedValue([
+      makeRow(),
+      makeRow({ id: 'att-2', fileName: 'photo.jpg', mimeType: 'image/jpeg', fileSize: 512 }),
+    ])
+    const { ctx } = makeCtx()
+    const result = (await tool.handler(
+      { entityType: 'customers:customer_person_profile', recordId: 'person-1' },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(findWithDecryptionMock).toHaveBeenCalledTimes(1)
+    const callArgs = findWithDecryptionMock.mock.calls[0]
+    expect(callArgs[2]).toMatchObject({
+      entityId: 'customers:customer_person_profile',
+      recordId: 'person-1',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+    })
+    expect(result.total).toBe(2)
+    const items = result.items as Array<Record<string, unknown>>
+    expect(items[0]).toMatchObject({
+      id: 'att-1',
+      fileName: 'passport.pdf',
+      mediaType: 'application/pdf',
+      size: 2048,
+    })
+    expect(items[0]).not.toHaveProperty('url')
+    expect(items[0]).not.toHaveProperty('signedUrl')
+  })
+
+  it('handles empty record gracefully', async () => {
+    findWithDecryptionMock.mockResolvedValue([])
+    const { ctx } = makeCtx()
+    const result = (await tool.handler(
+      { entityType: 'customers:customer_person_profile', recordId: 'nobody' },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(result.total).toBe(0)
+    expect(result.items).toEqual([])
+  })
+
+  it('throws when tenant context is missing', async () => {
+    const { ctx } = makeCtx({ tenantId: null })
+    await expect(
+      tool.handler(
+        { entityType: 'customers:customer_person_profile', recordId: 'person-1' },
+        ctx as any,
+      ),
+    ).rejects.toThrow(/Tenant context/)
+  })
+})
+
+describe('attachments.read_attachment', () => {
+  const tool = findTool('attachments.read_attachment')
+
+  it('returns extracted text only when includeExtractedText is true', async () => {
+    const row = makeRow({ content: 'OCR TEXT HERE', id: 'att-77' })
+    findOneWithDecryptionMock.mockResolvedValueOnce(row).mockResolvedValueOnce(row)
+    const { ctx } = makeCtx()
+    const withoutText = (await tool.handler(
+      { attachmentId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8' },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(withoutText.found).toBe(true)
+    expect(withoutText.hasExtractedText).toBe(true)
+    expect(withoutText.extractedText).toBeNull()
+
+    const withText = (await tool.handler(
+      { attachmentId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8', includeExtractedText: true },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(withText.extractedText).toBe('OCR TEXT HERE')
+  })
+
+  it('returns { found: false } when the attachment is not visible to the tenant', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(null)
+    const { ctx } = makeCtx()
+    const result = (await tool.handler(
+      { attachmentId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8' },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(result.found).toBe(false)
+  })
+
+  it('always scopes the query by tenantId (and organization when set)', async () => {
+    findOneWithDecryptionMock.mockResolvedValue(null)
+    const { ctx } = makeCtx({ tenantId: 'tenant-X', organizationId: 'org-X' })
+    await tool.handler(
+      { attachmentId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8' },
+      ctx as any,
+    )
+    const args = findOneWithDecryptionMock.mock.calls[0]
+    expect(args[2]).toMatchObject({
+      id: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+      tenantId: 'tenant-X',
+      organizationId: 'org-X',
+    })
+  })
+})
+
+describe('attachments.transfer_record_attachments', () => {
+  const tool = findTool('attachments.transfer_record_attachments')
+
+  it('declares isMutation=true', () => {
+    expect(tool.isMutation).toBe(true)
+  })
+
+  it('requires attachments.manage feature', () => {
+    expect(tool.requiredFeatures).toEqual(['attachments.manage'])
+  })
+
+  it('moves matching attachments to the target record and persists', async () => {
+    const row = makeRow({
+      id: 'att-1',
+      recordId: 'draft-1',
+      storageMetadata: {
+        assignments: [
+          { type: 'customers:customer_person_profile', id: 'draft-1' },
+        ],
+      },
+    })
+    findWithDecryptionMock.mockResolvedValue([row])
+    const { ctx, em } = makeCtx()
+    const result = (await tool.handler(
+      {
+        fromEntityType: 'customers:customer_person_profile',
+        fromRecordId: 'draft-1',
+        toEntityType: 'customers:customer_person_profile',
+        toRecordId: 'person-9',
+      },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(result.transferred).toBe(1)
+    expect((row as Record<string, unknown>).recordId).toBe('person-9')
+    const metadata = (row as Record<string, unknown>).storageMetadata as {
+      assignments: Array<{ type: string; id: string }>
+    }
+    expect(metadata.assignments[0]).toMatchObject({
+      type: 'customers:customer_person_profile',
+      id: 'person-9',
+    })
+    expect(em.persist).toHaveBeenCalledWith([row])
+    expect(em.flush).toHaveBeenCalled()
+  })
+
+  it('returns transferred: 0 when no matching attachments exist', async () => {
+    findWithDecryptionMock.mockResolvedValue([])
+    const { ctx, em } = makeCtx()
+    const result = (await tool.handler(
+      {
+        fromEntityType: 'customers:customer_person_profile',
+        fromRecordId: 'draft-x',
+        toEntityType: 'customers:customer_person_profile',
+        toRecordId: 'person-9',
+      },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(result.transferred).toBe(0)
+    expect(em.persist).not.toHaveBeenCalled()
+    expect(em.flush).not.toHaveBeenCalled()
+  })
+
+  it('rejects cross-entity transfers', async () => {
+    const { ctx } = makeCtx()
+    await expect(
+      tool.handler(
+        {
+          fromEntityType: 'a:b',
+          fromRecordId: 'r1',
+          toEntityType: 'c:d',
+          toRecordId: 'r2',
+        },
+        ctx as any,
+      ),
+    ).rejects.toThrow(/fromEntityType and toEntityType to match/)
+  })
+
+  it('respects caller tenant + organization when querying', async () => {
+    findWithDecryptionMock.mockResolvedValue([])
+    const { ctx } = makeCtx({ tenantId: 'tenant-Z', organizationId: 'org-Z' })
+    await tool.handler(
+      {
+        fromEntityType: 'x:y',
+        fromRecordId: 'r1',
+        toEntityType: 'x:y',
+        toRecordId: 'r2',
+      },
+      ctx as any,
+    )
+    const args = findWithDecryptionMock.mock.calls[0]
+    expect(args[2]).toMatchObject({
+      entityId: 'x:y',
+      recordId: 'r1',
+      tenantId: 'tenant-Z',
+      organizationId: 'org-Z',
+    })
+  })
+})
+
+describe('attachments-pack tool surface', () => {
+  it('exports the three expected tools with correct flags', () => {
+    const names = attachmentsAiTools.map((tool) => tool.name)
+    expect(names).toEqual([
+      'attachments.list_record_attachments',
+      'attachments.read_attachment',
+      'attachments.transfer_record_attachments',
+    ])
+    const readOnly = attachmentsAiTools.filter((tool) => tool.isMutation !== true)
+    expect(readOnly.map((tool) => tool.name)).toEqual([
+      'attachments.list_record_attachments',
+      'attachments.read_attachment',
+    ])
+  })
+})