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

package/src/modules/ai_assistant/data/repositories/AiAgentPromptOverrideRepository.ts

@@ -0,0 +1,132 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  findOneWithDecryption,
+  findWithDecryption,
+} from '@open-mercato/shared/lib/encryption/find'
+import { AiAgentPromptOverride } from '../entities'
+
+export interface AiAgentPromptOverrideContext {
+  tenantId: string
+  organizationId?: string | null
+  userId?: string | null
+}
+
+export interface AiAgentPromptOverrideInput {
+  agentId: string
+  sections: Record<string, string>
+  notes?: string | null
+}
+
+/**
+ * Versioned prompt-override repository (Step 5.3).
+ *
+ * Every write produces a new row with a monotonically-increasing `version`
+ * scoped to `(tenantId, organizationId, agentId)`. We allocate the next
+ * version inside a transaction so two concurrent writers cannot collide on
+ * the same version number.
+ *
+ * Reads ALWAYS go through `findOneWithDecryption` / `findWithDecryption` —
+ * the `sections` column isn't encrypted today, but the repo sticks to the
+ * shared encrypted-read helpers so future GDPR-flagged columns are handled
+ * automatically.
+ */
+export class AiAgentPromptOverrideRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  async getLatest(
+    agentId: string,
+    ctx: AiAgentPromptOverrideContext,
+  ): Promise<AiAgentPromptOverride | null> {
+    if (!agentId || !ctx?.tenantId) return null
+    const row = await findOneWithDecryption<AiAgentPromptOverride>(
+      this.em,
+      AiAgentPromptOverride,
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId,
+      } as any,
+      { orderBy: { version: 'desc' } as any },
+      { tenantId: ctx.tenantId ?? null, organizationId: ctx.organizationId ?? null },
+    )
+    return row ?? null
+  }
+
+  async listVersions(
+    agentId: string,
+    ctx: AiAgentPromptOverrideContext,
+    limit: number = 10,
+  ): Promise<AiAgentPromptOverride[]> {
+    if (!agentId || !ctx?.tenantId) return []
+    const capped = Math.max(1, Math.min(Math.floor(limit), 100))
+    const rows = await findWithDecryption<AiAgentPromptOverride>(
+      this.em,
+      AiAgentPromptOverride,
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId,
+      } as any,
+      {
+        orderBy: { version: 'desc' } as any,
+        limit: capped,
+      },
+      { tenantId: ctx.tenantId ?? null, organizationId: ctx.organizationId ?? null },
+    )
+    return rows
+  }
+
+  async save(
+    input: AiAgentPromptOverrideInput,
+    ctx: AiAgentPromptOverrideContext,
+  ): Promise<AiAgentPromptOverride> {
+    if (!ctx?.tenantId) {
+      throw new Error('AiAgentPromptOverrideRepository.save requires tenantId')
+    }
+    if (!input?.agentId) {
+      throw new Error('AiAgentPromptOverrideRepository.save requires agentId')
+    }
+    const sanitizedSections = sanitizeSections(input.sections)
+    return this.em.transactional(async (tx) => {
+      const latest = await findOneWithDecryption<AiAgentPromptOverride>(
+        tx as unknown as EntityManager,
+        AiAgentPromptOverride,
+        {
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId ?? null,
+          agentId: input.agentId,
+        } as any,
+        { orderBy: { version: 'desc' } as any },
+        { tenantId: ctx.tenantId ?? null, organizationId: ctx.organizationId ?? null },
+      )
+      const nextVersion = (latest?.version ?? 0) + 1
+      const row = tx.create(AiAgentPromptOverride, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId: input.agentId,
+        version: nextVersion,
+        sections: sanitizedSections,
+        notes: input.notes ?? null,
+        createdByUserId: ctx.userId ?? null,
+      } as unknown as AiAgentPromptOverride)
+      await tx.persist(row).flush()
+      return row
+    })
+  }
+}
+
+function sanitizeSections(
+  sections: Record<string, string> | null | undefined,
+): Record<string, string> {
+  if (!sections || typeof sections !== 'object') return {}
+  const out: Record<string, string> = {}
+  for (const [key, value] of Object.entries(sections)) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (!trimmed) continue
+    out[key] = value
+  }
+  return out
+}
+
+export default AiAgentPromptOverrideRepository

package/src/modules/ai_assistant/data/repositories/AiPendingActionRepository.ts

@@ -0,0 +1,334 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  findOneWithDecryption,
+  findWithDecryption,
+} from '@open-mercato/shared/lib/encryption/find'
+import { AiPendingAction } from '../entities'
+import {
+  AI_PENDING_ACTION_ALLOWED_TRANSITIONS,
+  AiPendingActionStateError,
+  resolveAiPendingActionTtlSeconds,
+  type AiPendingActionExecutionResult,
+  type AiPendingActionFailedRecord,
+  type AiPendingActionFieldDiff,
+  type AiPendingActionQueueMode,
+  type AiPendingActionRecordDiff,
+  type AiPendingActionStatus,
+} from '../../lib/pending-action-types'
+
+export interface AiPendingActionContext {
+  tenantId: string
+  organizationId?: string | null
+  userId?: string | null
+}
+
+export interface AiPendingActionCreateInput {
+  agentId: string
+  toolName: string
+  idempotencyKey: string
+  createdByUserId: string
+  normalizedInput: Record<string, unknown>
+  conversationId?: string | null
+  targetEntityType?: string | null
+  targetRecordId?: string | null
+  fieldDiff?: AiPendingActionFieldDiff[]
+  records?: AiPendingActionRecordDiff[] | null
+  sideEffectsSummary?: string | null
+  recordVersion?: string | null
+  attachmentIds?: string[]
+  queueMode?: AiPendingActionQueueMode
+  /** Optional explicit TTL in seconds; overrides the env/default TTL. */
+  ttlSeconds?: number
+  /** Optional explicit `now` for deterministic tests. */
+  now?: Date
+}
+
+export interface AiPendingActionSetStatusExtra {
+  resolvedByUserId?: string | null
+  executionResult?: AiPendingActionExecutionResult | null
+  failedRecords?: AiPendingActionFailedRecord[] | null
+  /** Optional explicit `now` for deterministic tests. */
+  now?: Date
+}
+
+/**
+ * Persistent store for the Phase 3 WS-C mutation approval gate (Step 5.5).
+ *
+ * Responsibilities:
+ * - Create new pending rows with a TTL-derived `expiresAt`, honoring
+ *   idempotency within the window (same `idempotencyKey` returns the same
+ *   row as long as it is still `pending`; any terminal state mints a new row).
+ * - Tenant-scoped lookups for the confirm/cancel/reconnect routes and the
+ *   in-app UI's "open actions" list.
+ * - State-machine enforcement: `setStatus` rejects illegal transitions via
+ *   {@link AiPendingActionStateError}. The runtime callers translate this
+ *   to a 409 Conflict response.
+ * - `listExpired` for the cleanup worker (Step 5.12).
+ *
+ * Every read goes through `findOneWithDecryption` / `findWithDecryption`
+ * even though today no column is GDPR-flagged. This keeps the repo
+ * consistent with the rest of the module and preps for a future encrypted
+ * `normalizedInput` without a second refactor.
+ */
+export class AiPendingActionRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  async create(
+    input: AiPendingActionCreateInput,
+    ctx: AiPendingActionContext,
+  ): Promise<AiPendingAction> {
+    if (!ctx?.tenantId) {
+      throw new Error('AiPendingActionRepository.create requires tenantId')
+    }
+    if (!input?.agentId) {
+      throw new Error('AiPendingActionRepository.create requires agentId')
+    }
+    if (!input?.toolName) {
+      throw new Error('AiPendingActionRepository.create requires toolName')
+    }
+    if (!input?.idempotencyKey) {
+      throw new Error(
+        'AiPendingActionRepository.create requires idempotencyKey',
+      )
+    }
+    if (!input?.createdByUserId) {
+      throw new Error(
+        'AiPendingActionRepository.create requires createdByUserId',
+      )
+    }
+
+    const now = input.now ?? new Date()
+    const ttlSeconds = Math.max(
+      1,
+      Math.floor(
+        typeof input.ttlSeconds === 'number' && Number.isFinite(input.ttlSeconds)
+          ? input.ttlSeconds
+          : resolveAiPendingActionTtlSeconds(),
+      ),
+    )
+    const expiresAt = new Date(now.getTime() + ttlSeconds * 1000)
+
+    return this.em.transactional(async (tx) => {
+      const existing = await findOneWithDecryption<AiPendingAction>(
+        tx as unknown as EntityManager,
+        AiPendingAction,
+        {
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId ?? null,
+          idempotencyKey: input.idempotencyKey,
+        } as any,
+        { orderBy: { createdAt: 'desc' } as any },
+        {
+          tenantId: ctx.tenantId ?? null,
+          organizationId: ctx.organizationId ?? null,
+        },
+      )
+      if (existing && existing.status === 'pending') {
+        return existing
+      }
+      // Terminal stale row would collide on the unique
+      // `(tenantId, organizationId, idempotencyKey)` constraint when we
+      // try to insert a fresh one with the same hash — and that exact
+      // collision happens whenever the operator clicks "Fix with AI"
+      // and the model retries the SAME tool with the SAME args. Remove
+      // the stale row first so a retry can always proceed; success rows
+      // stay (they represent a real, applied change), and failed /
+      // cancelled / expired rows are cleared because they're blocking
+      // exactly the recovery flow they were created to enable.
+      if (
+        existing &&
+        (existing.status === 'failed' ||
+          existing.status === 'cancelled' ||
+          existing.status === 'expired')
+      ) {
+        await tx.remove(existing).flush()
+      }
+      const row = tx.create(AiPendingAction, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId: input.agentId,
+        toolName: input.toolName,
+        conversationId: input.conversationId ?? null,
+        targetEntityType: input.targetEntityType ?? null,
+        targetRecordId: input.targetRecordId ?? null,
+        normalizedInput: input.normalizedInput ?? {},
+        fieldDiff: Array.isArray(input.fieldDiff) ? input.fieldDiff : [],
+        records: normalizeRecords(input.records),
+        failedRecords: null,
+        sideEffectsSummary: input.sideEffectsSummary ?? null,
+        recordVersion: input.recordVersion ?? null,
+        attachmentIds: Array.isArray(input.attachmentIds)
+          ? input.attachmentIds
+          : [],
+        idempotencyKey: input.idempotencyKey,
+        createdByUserId: input.createdByUserId,
+        status: 'pending' as AiPendingActionStatus,
+        queueMode: (input.queueMode ?? 'inline') as AiPendingActionQueueMode,
+        executionResult: null,
+        createdAt: now,
+        expiresAt,
+        resolvedAt: null,
+        resolvedByUserId: null,
+      } as unknown as AiPendingAction)
+      await tx.persist(row).flush()
+      return row
+    })
+  }
+
+  async getById(
+    id: string,
+    ctx: AiPendingActionContext,
+  ): Promise<AiPendingAction | null> {
+    if (!id || !ctx?.tenantId) return null
+    const row = await findOneWithDecryption<AiPendingAction>(
+      this.em,
+      AiPendingAction,
+      {
+        id,
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+      } as any,
+      {},
+      {
+        tenantId: ctx.tenantId ?? null,
+        organizationId: ctx.organizationId ?? null,
+      },
+    )
+    return row ?? null
+  }
+
+  async listPendingForAgent(
+    agentId: string,
+    ctx: AiPendingActionContext,
+    limit: number = 50,
+  ): Promise<AiPendingAction[]> {
+    if (!agentId || !ctx?.tenantId) return []
+    const capped = Math.max(1, Math.min(Math.floor(limit), 200))
+    const rows = await findWithDecryption<AiPendingAction>(
+      this.em,
+      AiPendingAction,
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId,
+        status: 'pending',
+      } as any,
+      {
+        orderBy: { createdAt: 'desc' } as any,
+        limit: capped,
+      },
+      {
+        tenantId: ctx.tenantId ?? null,
+        organizationId: ctx.organizationId ?? null,
+      },
+    )
+    return rows
+  }
+
+  async setStatus(
+    id: string,
+    nextStatus: AiPendingActionStatus,
+    ctx: AiPendingActionContext,
+    extra?: AiPendingActionSetStatusExtra,
+  ): Promise<AiPendingAction> {
+    if (!ctx?.tenantId) {
+      throw new Error('AiPendingActionRepository.setStatus requires tenantId')
+    }
+    if (!id) {
+      throw new Error('AiPendingActionRepository.setStatus requires id')
+    }
+    return this.em.transactional(async (tx) => {
+      const existing = await findOneWithDecryption<AiPendingAction>(
+        tx as unknown as EntityManager,
+        AiPendingAction,
+        {
+          id,
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId ?? null,
+        } as any,
+        {},
+        {
+          tenantId: ctx.tenantId ?? null,
+          organizationId: ctx.organizationId ?? null,
+        },
+      )
+      if (!existing) {
+        throw new Error(`AiPendingAction not found: ${id}`)
+      }
+      if (existing.status === nextStatus) {
+        return existing
+      }
+      const allowed = AI_PENDING_ACTION_ALLOWED_TRANSITIONS[existing.status] ?? []
+      if (!allowed.includes(nextStatus)) {
+        throw new AiPendingActionStateError(existing.status, nextStatus)
+      }
+      const now = extra?.now ?? new Date()
+      existing.status = nextStatus
+      if (
+        nextStatus === 'confirmed' ||
+        nextStatus === 'cancelled' ||
+        nextStatus === 'expired' ||
+        nextStatus === 'failed'
+      ) {
+        existing.resolvedAt = existing.resolvedAt ?? now
+        if (extra && Object.prototype.hasOwnProperty.call(extra, 'resolvedByUserId')) {
+          existing.resolvedByUserId = extra.resolvedByUserId ?? null
+        } else if (nextStatus === 'expired') {
+          existing.resolvedByUserId = null
+        }
+      }
+      if (extra && Object.prototype.hasOwnProperty.call(extra, 'executionResult')) {
+        existing.executionResult = extra.executionResult ?? null
+      }
+      if (extra && Object.prototype.hasOwnProperty.call(extra, 'failedRecords')) {
+        existing.failedRecords = normalizeFailedRecords(extra.failedRecords)
+      }
+      await tx.persist(existing).flush()
+      return existing
+    })
+  }
+
+  async listExpired(
+    ctx: AiPendingActionContext,
+    now: Date,
+    limit: number = 100,
+  ): Promise<AiPendingAction[]> {
+    if (!ctx?.tenantId) return []
+    const capped = Math.max(1, Math.min(Math.floor(limit), 500))
+    const rows = await findWithDecryption<AiPendingAction>(
+      this.em,
+      AiPendingAction,
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        status: 'pending',
+        expiresAt: { $lt: now } as any,
+      } as any,
+      {
+        orderBy: { expiresAt: 'asc' } as any,
+        limit: capped,
+      },
+      {
+        tenantId: ctx.tenantId ?? null,
+        organizationId: ctx.organizationId ?? null,
+      },
+    )
+    return rows
+  }
+}
+
+function normalizeRecords(
+  records: AiPendingActionRecordDiff[] | null | undefined,
+): AiPendingActionRecordDiff[] | null {
+  if (!Array.isArray(records) || records.length === 0) return null
+  return records
+}
+
+function normalizeFailedRecords(
+  failed: AiPendingActionFailedRecord[] | null | undefined,
+): AiPendingActionFailedRecord[] | null {
+  if (!Array.isArray(failed) || failed.length === 0) return null
+  return failed
+}
+
+export default AiPendingActionRepository

package/src/modules/ai_assistant/data/repositories/__tests__/AiAgentMutationPolicyOverrideRepository.test.ts

@@ -0,0 +1,195 @@
+import { AiAgentMutationPolicyOverrideRepository } from '../AiAgentMutationPolicyOverrideRepository'
+import { AiAgentMutationPolicyOverride } from '../../entities'
+
+type Row = {
+  id: string
+  tenantId: string
+  organizationId: string | null
+  agentId: string
+  mutationPolicy: string
+  notes: string | null
+  createdByUserId: string | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+let idCounter = 0
+
+function mockEm() {
+  const store: Row[] = []
+
+  const find = async (_entity: unknown, where: any): Promise<Row[]> => {
+    return store.filter((row) => {
+      if (where?.agentId && row.agentId !== where.agentId) return false
+      if (where?.tenantId && row.tenantId !== where.tenantId) return false
+      if (where && 'organizationId' in where) {
+        const expected = where.organizationId ?? null
+        if ((row.organizationId ?? null) !== expected) return false
+      }
+      return true
+    })
+  }
+
+  const em: any = {
+    find,
+    findOne: async (_entity: unknown, where: any, options?: any) => {
+      const rows = await find(_entity, where, options)
+      return rows[0] ?? null
+    },
+    create: (_entity: unknown, data: any) => {
+      idCounter += 1
+      const row: Row = {
+        id: `row-${idCounter}`,
+        tenantId: data.tenantId,
+        organizationId: data.organizationId ?? null,
+        agentId: data.agentId,
+        mutationPolicy: data.mutationPolicy,
+        notes: data.notes ?? null,
+        createdByUserId: data.createdByUserId ?? null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      }
+      return row
+    },
+    persist: (row: Row) => {
+      em.__pendingPersist = row
+      return em
+    },
+    remove: (row: Row) => {
+      em.__pendingRemove = row
+      return em
+    },
+    flush: async () => {
+      if (em.__pendingPersist) {
+        const row = em.__pendingPersist as Row
+        const existingIndex = store.findIndex((r) => r.id === row.id)
+        if (existingIndex >= 0) store[existingIndex] = row
+        else store.push(row)
+        em.__pendingPersist = null
+      }
+      if (em.__pendingRemove) {
+        const row = em.__pendingRemove as Row
+        const index = store.findIndex((r) => r.id === row.id)
+        if (index >= 0) store.splice(index, 1)
+        em.__pendingRemove = null
+      }
+    },
+    transactional: async (fn: (tx: any) => Promise<unknown>) => fn(em),
+    __pendingPersist: null as Row | null,
+    __pendingRemove: null as Row | null,
+    __store: store,
+  }
+
+  return em
+}
+
+describe('AiAgentMutationPolicyOverrideRepository', () => {
+  it('set + get round-trip returns the persisted row', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+    const ctx = { tenantId: 't1', organizationId: null }
+
+    await repo.set(
+      { agentId: 'catalog.assistant', mutationPolicy: 'read-only', notes: 'lock it down' },
+      ctx,
+    )
+
+    const row = await repo.get('catalog.assistant', ctx)
+    expect(row).not.toBeNull()
+    expect(row!.mutationPolicy).toBe('read-only')
+    expect(row!.notes).toBe('lock it down')
+  })
+
+  it('set replaces the existing row (one override per tenant+org+agent)', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+    const ctx = { tenantId: 't1', organizationId: null }
+
+    await repo.set(
+      { agentId: 'catalog.assistant', mutationPolicy: 'read-only' },
+      ctx,
+    )
+    await repo.set(
+      { agentId: 'catalog.assistant', mutationPolicy: 'destructive-confirm-required' },
+      ctx,
+    )
+
+    const row = await repo.get('catalog.assistant', ctx)
+    expect(row).not.toBeNull()
+    expect(row!.mutationPolicy).toBe('destructive-confirm-required')
+    // Only one row exists for this tuple.
+    expect(em.__store.length).toBe(1)
+  })
+
+  it('clear returns null on subsequent get', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+    const ctx = { tenantId: 't1', organizationId: null }
+
+    await repo.set(
+      { agentId: 'catalog.assistant', mutationPolicy: 'read-only' },
+      ctx,
+    )
+    const cleared = await repo.clear('catalog.assistant', ctx)
+    expect(cleared).toBe(true)
+
+    const row = await repo.get('catalog.assistant', ctx)
+    expect(row).toBeNull()
+  })
+
+  it('clear returns false when no override exists', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+    const cleared = await repo.clear('catalog.assistant', {
+      tenantId: 't1',
+      organizationId: null,
+    })
+    expect(cleared).toBe(false)
+  })
+
+  it('scopes per tenant — get for a different tenant returns null', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+
+    await repo.set(
+      { agentId: 'catalog.assistant', mutationPolicy: 'read-only' },
+      { tenantId: 't1', organizationId: null },
+    )
+    const rowA = await repo.get('catalog.assistant', {
+      tenantId: 't1',
+      organizationId: null,
+    })
+    const rowB = await repo.get('catalog.assistant', {
+      tenantId: 't2',
+      organizationId: null,
+    })
+    expect(rowA?.mutationPolicy).toBe('read-only')
+    expect(rowB).toBeNull()
+  })
+
+  it('throws when tenantId is missing on set', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+    await expect(
+      repo.set(
+        { agentId: 'catalog.assistant', mutationPolicy: 'read-only' },
+        { tenantId: '', organizationId: null } as any,
+      ),
+    ).rejects.toThrow(/tenantId/)
+  })
+
+  it('returns an AiAgentMutationPolicyOverride-shaped payload', async () => {
+    const em = mockEm()
+    const repo = new AiAgentMutationPolicyOverrideRepository(em)
+    const saved = await repo.set(
+      { agentId: 'catalog.assistant', mutationPolicy: 'read-only', notes: 'note' },
+      { tenantId: 't1', organizationId: 'o1', userId: 'u1' },
+    )
+    expect(saved.agentId).toBe('catalog.assistant')
+    expect(saved.mutationPolicy).toBe('read-only')
+    expect(saved.organizationId).toBe('o1')
+    expect(saved.createdByUserId).toBe('u1')
+    expect(saved.notes).toBe('note')
+    void AiAgentMutationPolicyOverride
+  })
+})