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

package/src/modules/ai_assistant/cli.ts

@@ -1,14 +1,9 @@
 import type { ModuleCli } from '@open-mercato/shared/modules/registry'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-import { fileURLToPath } from 'node:url'
-import { dirname, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
 /**
  * Ensure app bootstrap is called before creating DI container.
- * Uses import.meta.url for runtime path resolution since @/ alias
- * doesn't work with dynamic imports (TypeScript path aliases are
- * compile-time only, not available to Node.js at runtime).
+ * Uses the shared generated-bootstrap loader so the command works both from
+ * the monorepo app and from standalone apps installed through npm packages.
  */
 async function ensureBootstrap(): Promise<void> {
   // First check if DI is already available
@@ -20,23 +15,9 @@ async function ensureBootstrap(): Promise<void> {
     // DI not available, need to bootstrap
   }
 
-  // Construct absolute path to bootstrap using import.meta.url
   try {
-    const __filename = fileURLToPath(import.meta.url)
-    const __dirname = dirname(__filename)
-    // From packages/ai-assistant/src/modules/ai_assistant/cli.ts
-    // to apps/mercato/src/bootstrap.ts:
-    // ai_assistant → modules → src → ai-assistant → packages → root (6 levels)
-    // then into apps/mercato/src/bootstrap.ts
-    const bootstrapPath = resolve(__dirname, '../../../../../../apps/mercato/src/bootstrap.ts')
-
-    // Dynamic import using file URL
-    const bootstrapUrl = pathToFileURL(bootstrapPath).href
-    const { bootstrap, isBootstrapped } = await import(bootstrapUrl)
-
-    if (!isBootstrapped()) {
-      bootstrap()
-    }
+    const { bootstrapFromAppRoot } = await import('@open-mercato/shared/lib/bootstrap/dynamicLoader')
+    await bootstrapFromAppRoot()
   } catch (error) {
     console.error('[MCP] Bootstrap failed:', error instanceof Error ? error.message : error)
     // Continue - some contexts may not have bootstrap available
@@ -271,4 +252,98 @@ const entityGraph: ModuleCli = {
   },
 }
 
-export default [mcpServe, mcpServeHttp, mcpDev, listTools, entityGraph]
+const runPendingActionCleanup: ModuleCli = {
+  command: 'run-pending-action-cleanup',
+  async run() {
+    await ensureBootstrap()
+    const container = await createRequestContainer()
+
+    const { runPendingActionCleanup: runCleanup } = await import(
+      './workers/ai-pending-action-cleanup'
+    )
+
+    const em = container.resolve<import('@mikro-orm/postgresql').EntityManager>('em')
+    const summary = await runCleanup({ em })
+
+    console.log('[ai-pending-action-cleanup] Sweep complete:', summary)
+  },
+}
+
+const testTools: ModuleCli = {
+  command: 'test-tools',
+  async run(rest) {
+    const args = parseArgs(rest)
+    const json = args.json === true || args.json === 'true'
+    const moduleFilter =
+      typeof args.module === 'string' && args.module.length > 0 ? args.module : null
+    const includeMutations = args['no-mutations'] !== true && args['no-mutations'] !== 'true'
+    const tenantId =
+      typeof args.tenant === 'string' && args.tenant.length > 0 ? args.tenant : null
+    const organizationId =
+      typeof args.org === 'string' && args.org.length > 0 ? args.org : null
+
+    await ensureBootstrap()
+    const { runToolTests } = await import('./lib/tool-test-runner')
+    const report = await runToolTests({
+      tenantId,
+      organizationId,
+      moduleFilter,
+      includeMutations,
+    })
+
+    if (json) {
+      // Wrap in markers so a Playwright spec (or any caller) can extract the
+      // JSON payload without being thrown off by bootstrap log lines emitted
+      // to stdout by other modules during DI container creation.
+      console.log('---TOOL_TEST_REPORT_BEGIN---')
+      console.log(JSON.stringify(report))
+      console.log('---TOOL_TEST_REPORT_END---')
+    } else {
+      console.log('')
+      console.log(
+        `AI tool test report — tenant=${report.tenantId ?? '<none>'} org=${
+          report.organizationId ?? '<none>'
+        }`,
+      )
+      console.log(
+        `total=${report.total} pass=${report.passed} fail=${report.failed} skip=${report.skipped}`,
+      )
+      const byModule = new Map<string, typeof report.records>()
+      for (const record of report.records) {
+        const list = byModule.get(record.module) ?? []
+        list.push(record)
+        byModule.set(record.module, list)
+      }
+      const sortedModules = Array.from(byModule.keys()).sort()
+      for (const moduleId of sortedModules) {
+        const list = byModule.get(moduleId)!
+        console.log('')
+        console.log(`${moduleId} (${list.length}):`)
+        for (const record of list) {
+          const marker =
+            record.status === 'pass' ? '✓' : record.status === 'fail' ? '✗' : '·'
+          const reason = record.reason ? ` — ${record.reason}` : ''
+          const mutation = record.isMutation ? ' [mutation]' : ''
+          console.log(
+            `  ${marker} ${record.tool}${mutation} (${record.durationMs}ms)${reason}`,
+          )
+        }
+      }
+      console.log('')
+    }
+
+    if (report.failed > 0) {
+      process.exitCode = 1
+    }
+  },
+}
+
+export default [
+  mcpServe,
+  mcpServeHttp,
+  mcpDev,
+  listTools,
+  entityGraph,
+  runPendingActionCleanup,
+  testTools,
+]

package/src/modules/ai_assistant/data/__tests__/schema-unique-indexes.test.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs'
+
+const migrationCases = [
+  {
+    file: 'Migration20260419100521.ts',
+    orgIndex: 'create unique index "ai_agent_prompt_overrides_tenant_org_agent_version_uq"',
+    tenantIndex:
+      'create unique index "ai_agent_prompt_overrides_tenant_agent_version_null_org_uq"',
+  },
+  {
+    file: 'Migration20260419132948.ts',
+    orgIndex:
+      'create unique index "ai_agent_mutation_policy_overrides_tenant_org_agent_uq"',
+    tenantIndex:
+      'create unique index "ai_agent_mutation_policy_overrides_tenant_agent_null_org_uq"',
+  },
+  {
+    file: 'Migration20260419134235.ts',
+    orgIndex: 'create unique index "ai_pending_actions_tenant_org_idempotency_uq"',
+    tenantIndex: 'create unique index "ai_pending_actions_tenant_idem_null_org_uq"',
+  },
+]
+
+describe('AI assistant nullable organization unique indexes', () => {
+  it.each(migrationCases)(
+    '$file uses partial unique indexes for org and tenant-wide rows',
+    ({ file, orgIndex, tenantIndex }) => {
+      const source = readFileSync(
+        new URL(`../../migrations/${file}`, import.meta.url),
+        'utf8',
+      )
+
+      expect(source).toContain(orgIndex)
+      expect(source).toContain('where "organization_id" is not null')
+      expect(source).toContain(tenantIndex)
+      expect(source).toContain('where "organization_id" is null')
+      expect(source).not.toContain(' add constraint ')
+    },
+  )
+
+  it('keeps the module snapshot aligned with partial unique indexes', () => {
+    const snapshot = JSON.parse(
+      readFileSync(
+        new URL('../../migrations/.snapshot-open-mercato.json', import.meta.url),
+        'utf8',
+      ),
+    ) as {
+      tables: Array<{ name: string; indexes: Array<{ keyName: string; expression?: string }> }>
+    }
+
+    const indexes = new Map<string, string>()
+    for (const table of snapshot.tables) {
+      for (const index of table.indexes) {
+        if (index.expression) indexes.set(index.keyName, index.expression)
+      }
+    }
+
+    for (const { orgIndex, tenantIndex } of migrationCases) {
+      const orgIndexName = orgIndex.match(/"([^"]+)"/)?.[1]
+      const tenantIndexName = tenantIndex.match(/"([^"]+)"/)?.[1]
+      expect(orgIndexName ? indexes.get(orgIndexName) : undefined).toContain(
+        'where "organization_id" is not null',
+      )
+      expect(tenantIndexName ? indexes.get(tenantIndexName) : undefined).toContain(
+        'where "organization_id" is null',
+      )
+    }
+  })
+})

package/src/modules/ai_assistant/data/entities/AiAgentMutationPolicyOverride.ts

@@ -0,0 +1,7 @@
+// Canonical entity class lives in `../entities.ts` (single-file aggregate, same
+// pattern as `packages/core/src/modules/customers/data/entities.ts`). This
+// thin re-export exists so call sites that prefer the by-name import path
+// (`.../entities/AiAgentMutationPolicyOverride`) keep working.
+
+export { AiAgentMutationPolicyOverride } from '../entities'
+export type { AiAgentMutationPolicyOverride as default } from '../entities'

package/src/modules/ai_assistant/data/entities/AiAgentPromptOverride.ts

@@ -0,0 +1,7 @@
+// Canonical entity class lives in `../entities.ts` (single-file aggregate, same
+// pattern as `packages/core/src/modules/customers/data/entities.ts`). This
+// thin re-export exists so call sites that prefer the by-name import path
+// (`.../entities/AiAgentPromptOverride`) keep working.
+
+export { AiAgentPromptOverride } from '../entities'
+export type { AiAgentPromptOverride as default } from '../entities'

package/src/modules/ai_assistant/data/entities/AiPendingAction.ts

@@ -0,0 +1,7 @@
+// Canonical entity class lives in `../entities.ts` (single-file aggregate, same
+// pattern as `packages/core/src/modules/customers/data/entities.ts`). This
+// thin re-export exists so call sites that prefer the by-name import path
+// (`.../entities/AiPendingAction`) keep working.
+
+export { AiPendingAction } from '../entities'
+export type { AiPendingAction as default } from '../entities'

package/src/modules/ai_assistant/data/entities.ts

@@ -0,0 +1,270 @@
+import { OptionalProps } from '@mikro-orm/core'
+import {
+  Entity,
+  Index,
+  PrimaryKey,
+  Property,
+} from '@mikro-orm/decorators/legacy'
+import type {
+  AiPendingActionExecutionResult,
+  AiPendingActionFailedRecord,
+  AiPendingActionFieldDiff,
+  AiPendingActionQueueMode,
+  AiPendingActionRecordDiff,
+  AiPendingActionStatus,
+} from '../lib/pending-action-types'
+
+/**
+ * Versioned additive prompt-override for a registered AI agent (Step 5.3).
+ *
+ * Each write creates a new row with `version = latest + 1`. Rows are never
+ * updated in place — history is preserved so operators can roll back by
+ * reading an earlier `version`. Column set is tenant/org-scoped per the
+ * standard Open Mercato RBAC contract.
+ *
+ * `sections` holds additive text keyed by prompt section id. The runtime
+ * composes the final `systemPrompt` via `composeSystemPromptWithOverride`
+ * (see `lib/prompt-override-merge.ts`), which NEVER replaces a built-in
+ * section — overrides are append-only by contract.
+ */
+@Entity({ tableName: 'ai_agent_prompt_overrides' })
+@Index({
+  name: 'ai_agent_prompt_overrides_tenant_org_agent_version_uq',
+  expression:
+    'create unique index "ai_agent_prompt_overrides_tenant_org_agent_version_uq" on "ai_agent_prompt_overrides" ("tenant_id", "organization_id", "agent_id", "version") where "organization_id" is not null',
+})
+@Index({
+  name: 'ai_agent_prompt_overrides_tenant_agent_version_null_org_uq',
+  expression:
+    'create unique index "ai_agent_prompt_overrides_tenant_agent_version_null_org_uq" on "ai_agent_prompt_overrides" ("tenant_id", "agent_id", "version") where "organization_id" is null',
+})
+@Index({
+  name: 'ai_agent_prompt_overrides_tenant_agent_idx',
+  properties: ['tenantId', 'agentId'],
+})
+@Index({
+  name: 'ai_agent_prompt_overrides_tenant_org_agent_version_idx',
+  expression:
+    'create index "ai_agent_prompt_overrides_tenant_org_agent_version_idx" on "ai_agent_prompt_overrides" ("tenant_id", "organization_id", "agent_id", "version" desc)',
+})
+export class AiAgentPromptOverride {
+  [OptionalProps]?: 'createdAt' | 'updatedAt' | 'organizationId' | 'createdByUserId' | 'notes'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'agent_id', type: 'text' })
+  agentId!: string
+
+  @Property({ name: 'version', type: 'int' })
+  version!: number
+
+  @Property({ name: 'sections', type: 'jsonb' })
+  sections!: Record<string, string>
+
+  @Property({ name: 'notes', type: 'text', nullable: true })
+  notes?: string | null
+
+  @Property({ name: 'created_by_user_id', type: 'uuid', nullable: true })
+  createdByUserId?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
+/**
+ * Persistent mutation-approval gate row backing the Phase 3 WS-C contract
+ * (spec §8 `AiPendingAction` + §9 confirm/cancel flow, Step 5.5).
+ *
+ * One row is created by `prepareMutation` (Step 5.6) whenever the runtime
+ * intercepts an `isMutation: true` tool call from a non-read-only agent.
+ * The row stores the normalized tool input, a precomputed `fieldDiff` (or
+ * per-record batch diff in `records[]`), the target record version, an
+ * `idempotencyKey` that dedupes double-submits within the TTL, and a
+ * `status` that walks the state machine defined in
+ * {@link AI_PENDING_ACTION_ALLOWED_TRANSITIONS}.
+ *
+ * The cleanup worker (Step 5.12) sweeps `status='pending' AND expiresAt < now`
+ * rows and transitions them to `expired`. The confirm route (Step 5.8)
+ * walks `pending → confirmed → executing → (failed | terminal success)`.
+ * Reads always flow through `findOneWithDecryption` /
+ * `findWithDecryption`, even though no column is GDPR-flagged today, so
+ * future encrypted columns (e.g. `normalizedInput`) are handled.
+ */
+@Entity({ tableName: 'ai_pending_actions' })
+@Index({
+  name: 'ai_pending_actions_tenant_org_idempotency_uq',
+  expression:
+    'create unique index "ai_pending_actions_tenant_org_idempotency_uq" on "ai_pending_actions" ("tenant_id", "organization_id", "idempotency_key") where "organization_id" is not null',
+})
+@Index({
+  name: 'ai_pending_actions_tenant_idem_null_org_uq',
+  expression:
+    'create unique index "ai_pending_actions_tenant_idem_null_org_uq" on "ai_pending_actions" ("tenant_id", "idempotency_key") where "organization_id" is null',
+})
+@Index({
+  name: 'ai_pending_actions_tenant_org_status_expires_idx',
+  properties: ['tenantId', 'organizationId', 'status', 'expiresAt'],
+})
+@Index({
+  name: 'ai_pending_actions_tenant_org_agent_status_idx',
+  properties: ['tenantId', 'organizationId', 'agentId', 'status'],
+})
+export class AiPendingAction {
+  [OptionalProps]?:
+    | 'createdAt'
+    | 'organizationId'
+    | 'conversationId'
+    | 'targetEntityType'
+    | 'targetRecordId'
+    | 'fieldDiff'
+    | 'records'
+    | 'failedRecords'
+    | 'sideEffectsSummary'
+    | 'recordVersion'
+    | 'attachmentIds'
+    | 'executionResult'
+    | 'resolvedAt'
+    | 'resolvedByUserId'
+    | 'queueMode'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'agent_id', type: 'text' })
+  agentId!: string
+
+  @Property({ name: 'tool_name', type: 'text' })
+  toolName!: string
+
+  @Property({ name: 'conversation_id', type: 'text', nullable: true })
+  conversationId?: string | null
+
+  @Property({ name: 'target_entity_type', type: 'text', nullable: true })
+  targetEntityType?: string | null
+
+  @Property({ name: 'target_record_id', type: 'text', nullable: true })
+  targetRecordId?: string | null
+
+  @Property({ name: 'normalized_input', type: 'jsonb' })
+  normalizedInput!: Record<string, unknown>
+
+  @Property({ name: 'field_diff', type: 'jsonb', default: [] })
+  fieldDiff: AiPendingActionFieldDiff[] = []
+
+  @Property({ name: 'records', type: 'jsonb', nullable: true })
+  records?: AiPendingActionRecordDiff[] | null
+
+  @Property({ name: 'failed_records', type: 'jsonb', nullable: true })
+  failedRecords?: AiPendingActionFailedRecord[] | null
+
+  @Property({ name: 'side_effects_summary', type: 'text', nullable: true })
+  sideEffectsSummary?: string | null
+
+  @Property({ name: 'record_version', type: 'text', nullable: true })
+  recordVersion?: string | null
+
+  @Property({ name: 'attachment_ids', type: 'jsonb', default: [] })
+  attachmentIds: string[] = []
+
+  @Property({ name: 'idempotency_key', type: 'text' })
+  idempotencyKey!: string
+
+  @Property({ name: 'created_by_user_id', type: 'uuid' })
+  createdByUserId!: string
+
+  @Property({ name: 'status', type: 'text' })
+  status!: AiPendingActionStatus
+
+  @Property({ name: 'queue_mode', type: 'text', default: 'inline' })
+  queueMode: AiPendingActionQueueMode = 'inline'
+
+  @Property({ name: 'execution_result', type: 'jsonb', nullable: true })
+  executionResult?: AiPendingActionExecutionResult | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'expires_at', type: Date })
+  expiresAt!: Date
+
+  @Property({ name: 'resolved_at', type: Date, nullable: true })
+  resolvedAt?: Date | null
+
+  @Property({ name: 'resolved_by_user_id', type: 'uuid', nullable: true })
+  resolvedByUserId?: string | null
+}
+
+/**
+ * Tenant-scoped override of an agent's declared `mutationPolicy` (Step 5.4).
+ *
+ * Unlike {@link AiAgentPromptOverride}, this surface is NOT versioned — it is
+ * a single-value policy switch per `(tenantId, organizationId, agentId)`. The
+ * runtime enforces the override as a DOWNGRADE only: the effective policy
+ * equals the MOST RESTRICTIVE of `{ code-declared, override }`. Escalation is
+ * a code-level change and is rejected at the route layer.
+ *
+ * Hierarchy (most restrictive → least): `read-only` < `destructive-confirm-required`
+ * < `confirm-required`. The route never allows an override to widen the
+ * code-declared policy.
+ */
+@Entity({ tableName: 'ai_agent_mutation_policy_overrides' })
+@Index({
+  name: 'ai_agent_mutation_policy_overrides_tenant_org_agent_uq',
+  expression:
+    'create unique index "ai_agent_mutation_policy_overrides_tenant_org_agent_uq" on "ai_agent_mutation_policy_overrides" ("tenant_id", "organization_id", "agent_id") where "organization_id" is not null',
+})
+@Index({
+  name: 'ai_agent_mutation_policy_overrides_tenant_agent_null_org_uq',
+  expression:
+    'create unique index "ai_agent_mutation_policy_overrides_tenant_agent_null_org_uq" on "ai_agent_mutation_policy_overrides" ("tenant_id", "agent_id") where "organization_id" is null',
+})
+@Index({
+  name: 'ai_agent_mutation_policy_overrides_tenant_agent_idx',
+  properties: ['tenantId', 'agentId'],
+})
+export class AiAgentMutationPolicyOverride {
+  [OptionalProps]?: 'createdAt' | 'updatedAt' | 'organizationId' | 'createdByUserId' | 'notes'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'agent_id', type: 'text' })
+  agentId!: string
+
+  @Property({ name: 'mutation_policy', type: 'text' })
+  mutationPolicy!: string
+
+  @Property({ name: 'notes', type: 'text', nullable: true })
+  notes?: string | null
+
+  @Property({ name: 'created_by_user_id', type: 'uuid', nullable: true })
+  createdByUserId?: string | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

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

@@ -0,0 +1,129 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import {
+  findOneWithDecryption,
+} from '@open-mercato/shared/lib/encryption/find'
+import { AiAgentMutationPolicyOverride } from '../entities'
+import type { AiAgentMutationPolicy } from '../../lib/ai-agent-definition'
+
+export interface AiAgentMutationPolicyOverrideContext {
+  tenantId: string
+  organizationId?: string | null
+  userId?: string | null
+}
+
+export interface AiAgentMutationPolicyOverrideInput {
+  agentId: string
+  mutationPolicy: AiAgentMutationPolicy
+  notes?: string | null
+}
+
+/**
+ * Single-value mutation-policy override repository (Step 5.4).
+ *
+ * Unlike the versioned prompt override, there is ONE current mutation-policy
+ * override per `(tenantId, organizationId, agentId)`. `set()` replaces the
+ * existing row (or inserts a new one) inside a transaction so concurrent
+ * writers cannot produce ghost rows. `clear()` deletes the row so the runtime
+ * falls back to the code-declared policy.
+ *
+ * Reads always go through `findOneWithDecryption` to stay consistent with the
+ * rest of the module even though `mutation_policy` isn't encrypted today.
+ */
+export class AiAgentMutationPolicyOverrideRepository {
+  constructor(private readonly em: EntityManager) {}
+
+  async get(
+    agentId: string,
+    ctx: AiAgentMutationPolicyOverrideContext,
+  ): Promise<AiAgentMutationPolicyOverride | null> {
+    if (!agentId || !ctx?.tenantId) return null
+    const row = await findOneWithDecryption<AiAgentMutationPolicyOverride>(
+      this.em,
+      AiAgentMutationPolicyOverride,
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId,
+      } as any,
+      {},
+      { tenantId: ctx.tenantId ?? null, organizationId: ctx.organizationId ?? null },
+    )
+    return row ?? null
+  }
+
+  async set(
+    input: AiAgentMutationPolicyOverrideInput,
+    ctx: AiAgentMutationPolicyOverrideContext,
+  ): Promise<AiAgentMutationPolicyOverride> {
+    if (!ctx?.tenantId) {
+      throw new Error('AiAgentMutationPolicyOverrideRepository.set requires tenantId')
+    }
+    if (!input?.agentId) {
+      throw new Error('AiAgentMutationPolicyOverrideRepository.set requires agentId')
+    }
+    const normalized = normalizeNotes(input.notes)
+    return this.em.transactional(async (tx) => {
+      const existing = await findOneWithDecryption<AiAgentMutationPolicyOverride>(
+        tx as unknown as EntityManager,
+        AiAgentMutationPolicyOverride,
+        {
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId ?? null,
+          agentId: input.agentId,
+        } as any,
+        {},
+        { tenantId: ctx.tenantId ?? null, organizationId: ctx.organizationId ?? null },
+      )
+      if (existing) {
+        existing.mutationPolicy = input.mutationPolicy
+        existing.notes = normalized
+        existing.createdByUserId = ctx.userId ?? existing.createdByUserId ?? null
+        existing.updatedAt = new Date()
+        await tx.persist(existing).flush()
+        return existing
+      }
+      const row = tx.create(AiAgentMutationPolicyOverride, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? null,
+        agentId: input.agentId,
+        mutationPolicy: input.mutationPolicy,
+        notes: normalized,
+        createdByUserId: ctx.userId ?? null,
+      } as unknown as AiAgentMutationPolicyOverride)
+      await tx.persist(row).flush()
+      return row
+    })
+  }
+
+  async clear(
+    agentId: string,
+    ctx: AiAgentMutationPolicyOverrideContext,
+  ): Promise<boolean> {
+    if (!agentId || !ctx?.tenantId) return false
+    return this.em.transactional(async (tx) => {
+      const existing = await findOneWithDecryption<AiAgentMutationPolicyOverride>(
+        tx as unknown as EntityManager,
+        AiAgentMutationPolicyOverride,
+        {
+          tenantId: ctx.tenantId,
+          organizationId: ctx.organizationId ?? null,
+          agentId,
+        } as any,
+        {},
+        { tenantId: ctx.tenantId ?? null, organizationId: ctx.organizationId ?? null },
+      )
+      if (!existing) return false
+      await tx.remove(existing).flush()
+      return true
+    })
+  }
+}
+
+function normalizeNotes(notes: string | null | undefined): string | null {
+  if (typeof notes !== 'string') return null
+  const trimmed = notes.trim()
+  if (!trimmed) return null
+  return notes
+}
+
+export default AiAgentMutationPolicyOverrideRepository