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

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

@@ -0,0 +1,218 @@
+/**
+ * Step 3.8 — `meta.*` tool pack unit tests.
+ *
+ * Covers `list_agents` empty-registry graceful case, RBAC filtering,
+ * super-admin bypass, `describe_agent` not-found / forbidden / happy,
+ * and the `output.schema` JSON-Schema fallback.
+ */
+import { z } from 'zod'
+import type { AiAgentDefinition } from '../../lib/ai-agent-definition'
+import {
+  resetAgentRegistryForTests,
+  seedAgentRegistryForTests,
+} from '../../lib/agent-registry'
+import metaAiTools from '../meta-pack'
+
+function findTool(name: string) {
+  const tool = metaAiTools.find((entry) => entry.name === name)
+  if (!tool) throw new Error(`tool ${name} missing`)
+  return tool
+}
+
+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 makeCtx(overrides: Partial<{
+  tenantId: string | null
+  organizationId: string | null
+  userId: string | null
+  userFeatures: string[]
+  isSuperAdmin: boolean
+}> = {}) {
+  return {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    userId: 'user-1',
+    container: { resolve: jest.fn() },
+    userFeatures: ['ai_assistant.view'],
+    isSuperAdmin: false,
+    ...overrides,
+  }
+}
+
+describe('meta.list_agents', () => {
+  const tool = findTool('meta.list_agents')
+
+  beforeEach(() => {
+    resetAgentRegistryForTests()
+  })
+
+  afterAll(() => {
+    resetAgentRegistryForTests()
+  })
+
+  it('returns an empty array when the registry is empty (never throws)', async () => {
+    const ctx = makeCtx()
+    const result = (await tool.handler({}, ctx as any)) as Record<string, unknown>
+    expect(result.agents).toEqual([])
+    expect(result.total).toBe(0)
+  })
+
+  it('filters by requiredFeatures based on the caller user features', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({ id: 'catalog.read', moduleId: 'catalog', requiredFeatures: ['catalog.view'] }),
+      makeAgent({ id: 'catalog.write', moduleId: 'catalog', requiredFeatures: ['catalog.manage'] }),
+      makeAgent({ id: 'customers.read', moduleId: 'customers' }),
+    ])
+    const ctx = makeCtx({ userFeatures: ['catalog.view', 'ai_assistant.view'] })
+    const result = (await tool.handler({}, ctx as any)) as Record<string, unknown>
+    const agents = result.agents as Array<Record<string, unknown>>
+    const ids = agents.map((agent) => agent.id).sort()
+    expect(ids).toEqual(['catalog.read', 'customers.read'])
+  })
+
+  it('super-admin sees every agent regardless of requiredFeatures', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({ id: 'catalog.admin', moduleId: 'catalog', requiredFeatures: ['catalog.admin_only'] }),
+      makeAgent({ id: 'customers.mgr', moduleId: 'customers', requiredFeatures: ['customers.manage'] }),
+    ])
+    const ctx = makeCtx({ userFeatures: [], isSuperAdmin: true })
+    const result = (await tool.handler({}, ctx as any)) as Record<string, unknown>
+    const agents = result.agents as Array<Record<string, unknown>>
+    expect(agents.map((agent) => agent.id).sort()).toEqual(['catalog.admin', 'customers.mgr'])
+  })
+
+  it('filters by moduleId when provided', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({ id: 'catalog.a', moduleId: 'catalog' }),
+      makeAgent({ id: 'customers.a', moduleId: 'customers' }),
+    ])
+    const ctx = makeCtx({ userFeatures: ['*'] })
+    const result = (await tool.handler({ moduleId: 'customers' }, ctx as any)) as Record<string, unknown>
+    const agents = result.agents as Array<Record<string, unknown>>
+    expect(agents.map((agent) => agent.id)).toEqual(['customers.a'])
+  })
+})
+
+describe('meta.describe_agent', () => {
+  const tool = findTool('meta.describe_agent')
+
+  beforeEach(() => {
+    resetAgentRegistryForTests()
+  })
+
+  afterAll(() => {
+    resetAgentRegistryForTests()
+  })
+
+  it('returns { agent: null, reason: "not_found" } when the id is unknown', async () => {
+    const ctx = makeCtx()
+    const result = (await tool.handler({ agentId: 'no.such.agent' }, ctx as any)) as Record<string, unknown>
+    expect(result.agent).toBeNull()
+    expect(result.reason).toBe('not_found')
+  })
+
+  it('returns { agent: null, reason: "forbidden" } when RBAC denies access', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.private',
+        moduleId: 'catalog',
+        requiredFeatures: ['catalog.private_feature'],
+      }),
+    ])
+    const ctx = makeCtx({ userFeatures: ['ai_assistant.view'] })
+    const result = (await tool.handler({ agentId: 'catalog.private' }, ctx as any)) as Record<string, unknown>
+    expect(result.agent).toBeNull()
+    expect(result.reason).toBe('forbidden')
+  })
+
+  it('returns a serialized description with JSON-Schema output when representable', async () => {
+    const schema = z.object({
+      title: z.string(),
+      price: z.number(),
+    })
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.merch',
+        moduleId: 'catalog',
+        description: 'Merchandising helper',
+        allowedTools: ['search.hybrid_search', 'catalog.get_product_bundle'],
+        executionMode: 'object',
+        readOnly: true,
+        mutationPolicy: 'read-only',
+        acceptedMediaTypes: ['image', 'pdf'],
+        maxSteps: 6,
+        output: { schemaName: 'MerchProposal', schema, mode: 'generate' },
+        keywords: ['catalog', 'merch'],
+        domain: 'catalog',
+      }),
+    ])
+    const ctx = makeCtx({ userFeatures: ['ai_assistant.view'] })
+    const result = (await tool.handler({ agentId: 'catalog.merch' }, ctx as any)) as Record<string, unknown>
+    const agent = result.agent as Record<string, unknown>
+    expect(agent.id).toBe('catalog.merch')
+    expect(agent.executionMode).toBe('object')
+    expect(agent.allowedTools).toEqual(['search.hybrid_search', 'catalog.get_product_bundle'])
+    expect(agent.readOnly).toBe(true)
+    expect(agent.acceptedMediaTypes).toEqual(['image', 'pdf'])
+    const output = agent.output as Record<string, unknown>
+    expect(output.schemaName).toBe('MerchProposal')
+    expect(output.jsonSchema).toBeDefined()
+    const prompt = agent.prompt as Record<string, unknown>
+    expect(prompt.systemPrompt).toBe('You are a test agent.')
+    expect(prompt.hasDynamicPageContext).toBe(false)
+  })
+
+  it('still returns the agent when output.schema is non-serializable — falls back to a note', async () => {
+    const brokenSchema = { _def: { typeName: 'ZodUnknown' } } as unknown as z.ZodType
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.broken',
+        moduleId: 'catalog',
+        output: { schemaName: 'Broken', schema: brokenSchema },
+      }),
+    ])
+    const ctx = makeCtx({ userFeatures: ['ai_assistant.view'] })
+    const result = (await tool.handler({ agentId: 'catalog.broken' }, ctx as any)) as Record<string, unknown>
+    const agent = result.agent as Record<string, unknown>
+    const output = agent.output as Record<string, unknown>
+    expect(output.schemaName).toBe('Broken')
+    const hasJsonSchema = Object.prototype.hasOwnProperty.call(output, 'jsonSchema')
+    const hasNote = Object.prototype.hasOwnProperty.call(output, 'note')
+    expect(hasJsonSchema || hasNote).toBe(true)
+  })
+
+  it('hasPageContextResolver reflects whether the agent declared a resolvePageContext callback', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.page',
+        moduleId: 'catalog',
+        resolvePageContext: async () => 'context',
+      }),
+    ])
+    const ctx = makeCtx({ userFeatures: ['ai_assistant.view'] })
+    const result = (await tool.handler({ agentId: 'catalog.page' }, ctx as any)) as Record<string, unknown>
+    const agent = result.agent as Record<string, unknown>
+    expect(agent.hasPageContextResolver).toBe(true)
+    const prompt = agent.prompt as Record<string, unknown>
+    expect(prompt.hasDynamicPageContext).toBe(true)
+  })
+})
+
+describe('meta-pack tool surface', () => {
+  it('exports the two read-only meta tools', () => {
+    const names = metaAiTools.map((tool) => tool.name)
+    expect(names).toEqual(['meta.list_agents', 'meta.describe_agent'])
+    for (const tool of metaAiTools) {
+      expect(tool.isMutation).not.toBe(true)
+      expect(tool.requiredFeatures).toEqual(['ai_assistant.view'])
+    }
+  })
+})

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

@@ -0,0 +1,192 @@
+/**
+ * Step 3.8 — `search.*` tool pack unit tests.
+ *
+ * Covers `search.hybrid_search` happy path and `search.get_record_context`
+ * happy / miss / tenant isolation.
+ */
+import searchAiTools from '../search-pack'
+
+type SearchCall = {
+  query: string
+  options: Record<string, unknown>
+}
+
+type ToolContext = {
+  tenantId: string | null
+  organizationId: string | null
+  userId: string | null
+  container: { resolve: (name: string) => unknown }
+  userFeatures: string[]
+  isSuperAdmin: boolean
+}
+
+function findTool(name: string) {
+  const tool = searchAiTools.find((entry) => entry.name === name)
+  if (!tool) throw new Error(`tool ${name} missing`)
+  return tool
+}
+
+function makeCtx(overrides: Partial<ToolContext> = {}): ToolContext {
+  const container = {
+    resolve: jest.fn(),
+  }
+  return {
+    tenantId: 'tenant-1',
+    organizationId: 'org-1',
+    userId: 'user-1',
+    container,
+    userFeatures: ['search.view'],
+    isSuperAdmin: false,
+    ...overrides,
+  }
+}
+
+function makeSearchService(results: unknown[]): {
+  service: { search: (query: string, options: Record<string, unknown>) => Promise<unknown[]> }
+  calls: SearchCall[]
+} {
+  const calls: SearchCall[] = []
+  return {
+    calls,
+    service: {
+      search: async (query: string, options: Record<string, unknown>) => {
+        calls.push({ query, options })
+        return results
+      },
+    },
+  }
+}
+
+describe('search.hybrid_search', () => {
+  const tool = findTool('search.hybrid_search')
+
+  it('passes tenant + organization scope and limits through to SearchService', async () => {
+    const { service, calls } = makeSearchService([
+      {
+        entityId: 'catalog:product',
+        recordId: 'rec-1',
+        score: 0.9,
+        source: 'fulltext',
+        presenter: { title: 'Product A' },
+      },
+    ])
+    const ctx = makeCtx()
+    ;(ctx.container.resolve as jest.Mock).mockImplementation((name: string) => {
+      if (name === 'searchService') return service
+      throw new Error(`unexpected resolve ${name}`)
+    })
+    const result = (await tool.handler(
+      { q: 'widget', limit: 10, strategies: ['fulltext', 'vector'], entityTypes: ['catalog:product'] },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(calls).toHaveLength(1)
+    expect(calls[0].query).toBe('widget')
+    expect(calls[0].options).toMatchObject({
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      limit: 10,
+      strategies: ['fulltext', 'vector'],
+      entityTypes: ['catalog:product'],
+    })
+    expect(result.totalResults).toBe(1)
+    expect(result.strategiesUsed).toEqual(['fulltext'])
+  })
+
+  it('defaults limit to 20 when omitted', async () => {
+    const { service, calls } = makeSearchService([])
+    const ctx = makeCtx()
+    ;(ctx.container.resolve as jest.Mock).mockReturnValue(service)
+    await tool.handler({ q: 'hello' }, ctx as any)
+    expect(calls[0].options.limit).toBe(20)
+  })
+
+  it('throws when tenant context is missing', async () => {
+    const ctx = makeCtx({ tenantId: null })
+    ;(ctx.container.resolve as jest.Mock).mockReturnValue({ search: jest.fn() })
+    await expect(tool.handler({ q: 'x' }, ctx as any)).rejects.toThrow(/Tenant context/)
+  })
+})
+
+describe('search.get_record_context', () => {
+  const tool = findTool('search.get_record_context')
+
+  it('returns the matching hit with presenter/url/links', async () => {
+    const match = {
+      entityId: 'catalog:product',
+      recordId: 'rec-42',
+      score: 1,
+      source: 'fulltext',
+      presenter: { title: 'Widget' },
+      url: '/backend/catalog/catalog/products/rec-42',
+      links: [{ href: '/backend/catalog/catalog/products/rec-42', label: 'Open', kind: 'primary' }],
+    }
+    const { service, calls } = makeSearchService([
+      { entityId: 'catalog:product', recordId: 'rec-99', score: 0.5, source: 'fulltext' },
+      match,
+    ])
+    const ctx = makeCtx()
+    ;(ctx.container.resolve as jest.Mock).mockReturnValue(service)
+    const result = (await tool.handler(
+      { entityId: 'catalog:product', recordId: 'rec-42' },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(calls[0].query).toBe('rec-42')
+    expect(calls[0].options).toMatchObject({
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      limit: 5,
+      entityTypes: ['catalog:product'],
+    })
+    expect(result.found).toBe(true)
+    expect(result.recordId).toBe('rec-42')
+    expect(result.presenter).toEqual(match.presenter)
+    expect(result.url).toBe(match.url)
+    expect(result.links).toEqual(match.links)
+  })
+
+  it('returns { found: false } when no hit matches the recordId', async () => {
+    const { service } = makeSearchService([
+      { entityId: 'catalog:product', recordId: 'other', score: 0.2, source: 'fulltext' },
+    ])
+    const ctx = makeCtx()
+    ;(ctx.container.resolve as jest.Mock).mockReturnValue(service)
+    const result = (await tool.handler(
+      { entityId: 'catalog:product', recordId: 'missing' },
+      ctx as any,
+    )) as Record<string, unknown>
+    expect(result.found).toBe(false)
+    expect(result.recordId).toBe('missing')
+  })
+
+  it('passes the caller tenant/org and never leaks another tenant', async () => {
+    const { service, calls } = makeSearchService([])
+    const ctx = makeCtx({ tenantId: 'tenant-A', organizationId: 'org-A' })
+    ;(ctx.container.resolve as jest.Mock).mockReturnValue(service)
+    await tool.handler({ entityId: 'x:y', recordId: 'z' }, ctx as any)
+    expect(calls[0].options).toMatchObject({
+      tenantId: 'tenant-A',
+      organizationId: 'org-A',
+    })
+    expect(calls[0].options).not.toHaveProperty('bypassTenantScope')
+  })
+
+  it('throws when tenant context is missing', async () => {
+    const ctx = makeCtx({ tenantId: null })
+    ;(ctx.container.resolve as jest.Mock).mockReturnValue({ search: jest.fn() })
+    await expect(
+      tool.handler({ entityId: 'x:y', recordId: 'z' }, ctx as any),
+    ).rejects.toThrow(/Tenant context/)
+  })
+})
+
+describe('search-pack tool surface', () => {
+  it('exports exactly the expected tool names and shapes', () => {
+    const names = searchAiTools.map((tool) => tool.name)
+    expect(names).toEqual(['search.hybrid_search', 'search.get_record_context'])
+    for (const tool of searchAiTools) {
+      expect(typeof tool.description).toBe('string')
+      expect(tool.isMutation).not.toBe(true)
+      expect(tool.requiredFeatures).toContain('search.view')
+    }
+  })
+})

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

@@ -0,0 +1,269 @@
+/**
+ * General-purpose `attachments.*` tool pack (Phase 1 WS-C, Step 3.8).
+ *
+ * Read-only tools return metadata + optional extracted text; the
+ * attachment-to-model bridge (Step 3.7) owns raw bytes / signed URLs.
+ * The transfer tool is the only mutation — agents with `readOnly: true`
+ * are already filtered by the Step 3.2 policy gate.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { z } from 'zod'
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { defineAiTool } from '../lib/ai-tool-definition'
+import type { AiToolDefinition } from '../lib/types'
+
+type AttachmentMetadataModule = {
+  readAttachmentMetadata: (raw: unknown) => {
+    tags?: string[]
+    assignments?: Array<{ type: string; id: string; href?: string | null; label?: string | null }>
+  }
+  mergeAttachmentMetadata: (
+    raw: unknown,
+    patch: { assignments?: unknown; tags?: unknown },
+  ) => Record<string, unknown>
+}
+
+type AttachmentEntityModule = {
+  Attachment: new () => unknown
+}
+
+async function loadAttachmentEntity(): Promise<AttachmentEntityModule['Attachment']> {
+  const mod = (await import(
+    '@open-mercato/core/modules/attachments/data/entities'
+  )) as AttachmentEntityModule
+  return mod.Attachment
+}
+
+async function loadAttachmentMetadata(): Promise<AttachmentMetadataModule> {
+  const mod = (await import(
+    '@open-mercato/core/modules/attachments/lib/metadata'
+  )) as AttachmentMetadataModule
+  return mod
+}
+
+type AttachmentRow = {
+  id: string
+  entityId: string
+  recordId: string
+  fileName: string
+  mimeType: string
+  fileSize: number
+  storageMetadata?: Record<string, unknown> | null
+  url?: string
+  content?: string | null
+  tenantId?: string | null
+  organizationId?: string | null
+  partitionCode?: string
+  createdAt?: Date
+}
+
+function assertTenantScope(ctx: { tenantId: string | null }): string {
+  if (!ctx.tenantId) {
+    throw new Error('Tenant context is required for attachments tools')
+  }
+  return ctx.tenantId
+}
+
+function resolveEm(ctx: {
+  container: { resolve: <T = unknown>(name: string) => T }
+}): EntityManager {
+  return ctx.container.resolve<EntityManager>('em')
+}
+
+const listInput = z.object({
+  entityType: z.string().min(1).describe('Entity identifier (e.g. "customers:customer_person_profile").'),
+  recordId: z.string().min(1).describe('Record identifier within that entity.'),
+})
+
+const listRecordAttachmentsTool = defineAiTool({
+  name: 'attachments.list_record_attachments',
+  displayName: 'List record attachments',
+  description:
+    'List attachments bound to a record, scoped to the caller tenant and organization. Returns metadata only (no bytes, no signed URL).',
+  inputSchema: listInput,
+  requiredFeatures: ['attachments.view'],
+  tags: ['read', 'attachments'],
+  handler: async (rawInput, ctx) => {
+    const tenantId = assertTenantScope(ctx)
+    const input = listInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const Attachment = await loadAttachmentEntity()
+    const where: Record<string, unknown> = {
+      entityId: input.entityType,
+      recordId: input.recordId,
+      tenantId,
+    }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    const rows = (await findWithDecryption<AttachmentRow>(
+      em,
+      Attachment as unknown as new () => AttachmentRow,
+      where,
+      { orderBy: { createdAt: 'desc' } as any },
+      { tenantId, organizationId: ctx.organizationId },
+    )) as AttachmentRow[]
+    return {
+      entityType: input.entityType,
+      recordId: input.recordId,
+      total: rows.length,
+      items: rows.map((row) => ({
+        id: row.id,
+        entityType: row.entityId,
+        recordId: row.recordId,
+        fileName: row.fileName,
+        mediaType: row.mimeType,
+        size: row.fileSize,
+        partitionCode: row.partitionCode,
+        createdAt: row.createdAt ? new Date(row.createdAt).toISOString() : null,
+      })),
+    }
+  },
+})
+
+const readInput = z.object({
+  attachmentId: z.string().uuid().describe('Attachment identifier.'),
+  includeExtractedText: z
+    .boolean()
+    .optional()
+    .describe('When true, include the stored extracted / OCR text if present (default false).'),
+})
+
+const readAttachmentTool = defineAiTool({
+  name: 'attachments.read_attachment',
+  displayName: 'Read attachment metadata',
+  description:
+    'Return attachment metadata, tags, assignments, and optionally the stored extracted text. Never returns raw bytes or signed URLs.',
+  inputSchema: readInput,
+  requiredFeatures: ['attachments.view'],
+  tags: ['read', 'attachments'],
+  handler: async (rawInput, ctx) => {
+    const tenantId = assertTenantScope(ctx)
+    const input = readInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const Attachment = await loadAttachmentEntity()
+    const { readAttachmentMetadata } = await loadAttachmentMetadata()
+    const where: Record<string, unknown> = { id: input.attachmentId, tenantId }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    const row = (await findOneWithDecryption<AttachmentRow>(
+      em,
+      Attachment as unknown as new () => AttachmentRow,
+      where,
+      undefined,
+      { tenantId, organizationId: ctx.organizationId },
+    )) as AttachmentRow | null
+    if (!row) {
+      return { found: false as const, attachmentId: input.attachmentId }
+    }
+    const metadata = readAttachmentMetadata(row.storageMetadata)
+    return {
+      found: true as const,
+      id: row.id,
+      entityType: row.entityId,
+      recordId: row.recordId,
+      fileName: row.fileName,
+      mediaType: row.mimeType,
+      size: row.fileSize,
+      partitionCode: row.partitionCode,
+      createdAt: row.createdAt ? new Date(row.createdAt).toISOString() : null,
+      tags: metadata.tags ?? [],
+      assignments: metadata.assignments ?? [],
+      extractedText:
+        input.includeExtractedText === true && typeof row.content === 'string' ? row.content : null,
+      hasExtractedText: typeof row.content === 'string' && row.content.length > 0,
+    }
+  },
+})
+
+const transferInput = z.object({
+  fromEntityType: z.string().min(1).describe('Current entity type of the source attachments.'),
+  fromRecordId: z.string().min(1).describe('Current record id the attachments are bound to.'),
+  toEntityType: z.string().min(1).describe('Target entity type (must match the source).'),
+  toRecordId: z.string().min(1).describe('Target record id to re-bind the attachments to.'),
+  attachmentIds: z
+    .array(z.string().uuid())
+    .min(1)
+    .max(100)
+    .optional()
+    .describe('Optional subset; defaults to every attachment on the source record.'),
+})
+
+const transferRecordAttachmentsTool = defineAiTool({
+  name: 'attachments.transfer_record_attachments',
+  displayName: 'Transfer record attachments',
+  description:
+    'Move uploaded files from a temporary/draft record to a saved record. Mutation tool — agents with readOnly=true are blocked by the policy gate.',
+  inputSchema: transferInput,
+  isMutation: true,
+  requiredFeatures: ['attachments.manage'],
+  tags: ['write', 'attachments'],
+  handler: async (rawInput, ctx) => {
+    const tenantId = assertTenantScope(ctx)
+    const input = transferInput.parse(rawInput)
+    if (input.fromEntityType !== input.toEntityType) {
+      throw new Error(
+        'attachments.transfer_record_attachments requires fromEntityType and toEntityType to match',
+      )
+    }
+    const em = resolveEm(ctx)
+    const Attachment = await loadAttachmentEntity()
+    const { readAttachmentMetadata, mergeAttachmentMetadata } = await loadAttachmentMetadata()
+    const where: Record<string, unknown> = {
+      entityId: input.fromEntityType,
+      recordId: input.fromRecordId,
+      tenantId,
+    }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    if (input.attachmentIds && input.attachmentIds.length > 0) {
+      where.id = { $in: input.attachmentIds }
+    }
+    const rows = (await findWithDecryption<AttachmentRow>(
+      em,
+      Attachment as unknown as new () => AttachmentRow,
+      where,
+      undefined,
+      { tenantId, organizationId: ctx.organizationId },
+    )) as AttachmentRow[]
+    if (!rows.length) {
+      return {
+        transferred: 0,
+        fromEntityType: input.fromEntityType,
+        fromRecordId: input.fromRecordId,
+        toEntityType: input.toEntityType,
+        toRecordId: input.toRecordId,
+      }
+    }
+    for (const row of rows) {
+      const previousRecordId = row.recordId
+      row.recordId = input.toRecordId
+      const metadata = readAttachmentMetadata(row.storageMetadata)
+      const nextAssignments =
+        metadata.assignments?.map((assignment) => {
+          const matchesType = assignment.type === input.fromEntityType
+          const matchesRecord = assignment.id === previousRecordId
+          if (matchesType && matchesRecord) {
+            return { ...assignment, id: input.toRecordId }
+          }
+          return assignment
+        }) ?? []
+      row.storageMetadata = mergeAttachmentMetadata(row.storageMetadata, {
+        assignments: nextAssignments,
+      })
+    }
+    await em.persist(rows).flush()
+    return {
+      transferred: rows.length,
+      fromEntityType: input.fromEntityType,
+      fromRecordId: input.fromRecordId,
+      toEntityType: input.toEntityType,
+      toRecordId: input.toRecordId,
+      attachmentIds: rows.map((row) => row.id),
+    }
+  },
+})
+
+export const attachmentsAiTools: AiToolDefinition<any, any>[] = [
+  listRecordAttachmentsTool,
+  readAttachmentTool,
+  transferRecordAttachmentsTool,
+]
+
+export default attachmentsAiTools