@open-mercato/ai-assistant 0.6.7-develop.6862.1.c11a64ce0a → 0.6.7

package/src/modules/ai_assistant/lib/__tests__/input-moderation-gate.test.ts

@@ -1,121 +0,0 @@
-import { extractLatestUserText, runInputModerationGate } from '../agent-runtime'
-import {
-  AiModerationBlockedError,
-  AiModerationUnavailableError,
-  type ModerationResult,
-  type ModerationService,
-} from '../moderation'
-
-function serviceReturning(result: ModerationResult): ModerationService {
-  return { checkInput: jest.fn(async () => result) }
-}
-function serviceThrowing(error: unknown): ModerationService {
-  return { checkInput: jest.fn(async () => { throw error }) }
-}
-
-const CLEAN: ModerationResult = { flagged: false, categories: { hate: { flagged: false, score: 0.01 } } }
-const FLAGGED: ModerationResult = { flagged: true, categories: { hate: { flagged: true, score: 0.98 } } }
-
-const base = {
-  supportsInputModeration: true,
-  userText: 'hello there',
-  resolveApiKey: () => 'sk-test' as string | null,
-  env: {} as Record<string, string | undefined>,
-}
-
-describe('extractLatestUserText', () => {
-  it('returns the text parts of the most recent user message', () => {
-    const messages = [
-      { role: 'user', parts: [{ type: 'text', text: 'first' }] },
-      { role: 'assistant', parts: [{ type: 'text', text: 'reply' }] },
-      { role: 'user', parts: [{ type: 'text', text: 'second' }, { type: 'text', text: 'line' }] },
-    ] as never
-    expect(extractLatestUserText(messages)).toBe('second\nline')
-  })
-
-  it('falls back to string content and returns empty when no user message', () => {
-    expect(extractLatestUserText([{ role: 'user', content: 'plain' }] as never)).toBe('plain')
-    expect(extractLatestUserText([{ role: 'assistant', parts: [{ type: 'text', text: 'x' }] }] as never)).toBe('')
-  })
-})
-
-describe('runInputModerationGate', () => {
-  it('skips entirely when policy resolves to off (no untrusted, no override, no env)', async () => {
-    const service = serviceReturning(FLAGGED)
-    await expect(runInputModerationGate({ ...base, service })).resolves.toBeUndefined()
-    expect(service.checkInput).not.toHaveBeenCalled()
-  })
-
-  it('skips when the provider does not support moderation, even on an enforced surface', async () => {
-    const service = serviceReturning(FLAGGED)
-    await expect(
-      runInputModerationGate({ ...base, untrustedInput: true, supportsInputModeration: false, service }),
-    ).resolves.toBeUndefined()
-    expect(service.checkInput).not.toHaveBeenCalled()
-  })
-
-  it('skips when the user text is empty', async () => {
-    const service = serviceReturning(FLAGGED)
-    await expect(
-      runInputModerationGate({ ...base, untrustedInput: true, userText: '   ', service }),
-    ).resolves.toBeUndefined()
-    expect(service.checkInput).not.toHaveBeenCalled()
-  })
-
-  it('passes clean input through on an enabled surface', async () => {
-    const service = serviceReturning(CLEAN)
-    await expect(
-      runInputModerationGate({ ...base, perAgentOverride: true, service }),
-    ).resolves.toBeUndefined()
-    expect(service.checkInput).toHaveBeenCalledTimes(1)
-  })
-
-  it('throws AiModerationBlockedError (with categories) on flagged input', async () => {
-    const service = serviceReturning(FLAGGED)
-    const error = await runInputModerationGate({ ...base, untrustedInput: true, service }).catch((e) => e)
-    expect(error).toBeInstanceOf(AiModerationBlockedError)
-    expect((error as AiModerationBlockedError).categories.hate.flagged).toBe(true)
-  })
-
-  it('runs the onFlagged side effect before throwing, and the throw still applies if it fails', async () => {
-    const service = serviceReturning(FLAGGED)
-    const onFlagged = jest.fn(async () => { throw new Error('db down') })
-    const error = await runInputModerationGate({ ...base, untrustedInput: true, service, onFlagged }).catch((e) => e)
-    expect(onFlagged).toHaveBeenCalledWith(FLAGGED.categories)
-    expect(error).toBeInstanceOf(AiModerationBlockedError)
-  })
-
-  it('fails CLOSED on an enforced surface when the endpoint is unavailable', async () => {
-    const service = serviceThrowing(new AiModerationUnavailableError('endpoint down'))
-    await expect(
-      runInputModerationGate({ ...base, untrustedInput: true, service }),
-    ).rejects.toBeInstanceOf(AiModerationUnavailableError)
-  })
-
-  it('fails OPEN on an opt-in (on) surface when the endpoint is unavailable', async () => {
-    const service = serviceThrowing(new AiModerationUnavailableError('endpoint down'))
-    await expect(
-      runInputModerationGate({ ...base, perAgentOverride: true, service }),
-    ).resolves.toBeUndefined()
-  })
-
-  it('fails CLOSED on enforced when the service is missing from the container', async () => {
-    await expect(
-      runInputModerationGate({ ...base, untrustedInput: true, service: null }),
-    ).rejects.toBeInstanceOf(AiModerationUnavailableError)
-  })
-
-  it('fails OPEN on opt-in when the API key is missing', async () => {
-    const service = serviceReturning(CLEAN)
-    await expect(
-      runInputModerationGate({ ...base, perAgentOverride: true, resolveApiKey: () => null, service }),
-    ).resolves.toBeUndefined()
-    expect(service.checkInput).not.toHaveBeenCalled()
-  })
-
-  it('does not resolve the API key on the common skip path (policy off)', async () => {
-    const resolveApiKey = jest.fn(() => 'sk-test' as string | null)
-    await expect(runInputModerationGate({ ...base, resolveApiKey, service: serviceReturning(CLEAN) })).resolves.toBeUndefined()
-    expect(resolveApiKey).not.toHaveBeenCalled()
-  })
-})

package/src/modules/ai_assistant/lib/__tests__/moderation-flag-recorder.test.ts

@@ -1,76 +0,0 @@
-import type { AwilixContainer } from 'awilix'
-
-const createMock = jest.fn()
-const emitMock = jest.fn()
-
-jest.mock('../../events', () => ({
-  emitAiAssistantEvent: (...args: unknown[]) => emitMock(...args),
-}))
-jest.mock('../../data/repositories/AiModerationFlagRepository', () => ({
-  AiModerationFlagRepository: jest.fn().mockImplementation(() => ({ create: createMock })),
-}))
-
-import { recordModerationFlag } from '../moderation-flag-recorder'
-
-function fakeContainer(): AwilixContainer {
-  return {
-    resolve: () => ({ fork: () => ({}) }),
-  } as unknown as AwilixContainer
-}
-
-const baseInput = {
-  tenantId: 'tenant-1',
-  organizationId: 'org-1',
-  agentId: 'customers.account_assistant',
-  userId: 'user-1',
-  providerId: 'openai',
-  modelId: 'gpt-5-mini',
-  categories: {
-    hate: { flagged: true, score: 0.97 },
-    violence: { flagged: false, score: 0.01 },
-  },
-}
-
-describe('recordModerationFlag', () => {
-  beforeEach(() => {
-    createMock.mockReset()
-    emitMock.mockReset()
-    createMock.mockResolvedValue({ id: 'flag-1' })
-    emitMock.mockResolvedValue(undefined)
-  })
-
-  it('persists the audit row and emits the event with only flagged categories', async () => {
-    await recordModerationFlag(baseInput, fakeContainer())
-    expect(createMock).toHaveBeenCalledWith(
-      expect.objectContaining({ tenantId: 'tenant-1', agentId: 'customers.account_assistant', providerId: 'openai' }),
-    )
-    expect(emitMock).toHaveBeenCalledWith(
-      'ai_assistant.moderation_flag.created',
-      expect.objectContaining({ id: 'flag-1', tenantId: 'tenant-1', categories: ['hate'] }),
-    )
-  })
-
-  it('skips entirely when tenantId is null (cannot tenant-scope the audit row)', async () => {
-    await recordModerationFlag({ ...baseInput, tenantId: null }, fakeContainer())
-    expect(createMock).not.toHaveBeenCalled()
-    expect(emitMock).not.toHaveBeenCalled()
-  })
-
-  it('skips when no container is available', async () => {
-    await recordModerationFlag(baseInput, undefined)
-    expect(createMock).not.toHaveBeenCalled()
-    expect(emitMock).not.toHaveBeenCalled()
-  })
-
-  it('swallows a persistence failure (never throws) and does not emit', async () => {
-    createMock.mockRejectedValue(new Error('db down'))
-    await expect(recordModerationFlag(baseInput, fakeContainer())).resolves.toBeUndefined()
-    expect(emitMock).not.toHaveBeenCalled()
-  })
-
-  it('swallows an emit failure after a successful persist (never throws)', async () => {
-    emitMock.mockRejectedValue(new Error('bus down'))
-    await expect(recordModerationFlag(baseInput, fakeContainer())).resolves.toBeUndefined()
-    expect(createMock).toHaveBeenCalledTimes(1)
-  })
-})

package/src/modules/ai_assistant/lib/__tests__/moderation-policy.test.ts

@@ -1,86 +0,0 @@
-import {
-  isModerationActive,
-  resolveModerationPolicy,
-  shouldFailClosed,
-} from '../moderation-policy'
-
-describe('resolveModerationPolicy — 5-step precedence', () => {
-  it('1. untrustedInput wins over everything → enforced', () => {
-    expect(
-      resolveModerationPolicy({
-        untrustedInput: true,
-        perAgentOverride: false,
-        tenantWideOverride: false,
-        env: { OM_AI_INPUT_MODERATION: 'false' },
-      }),
-    ).toBe('enforced')
-  })
-
-  it('2. per-agent override wins over tenant-wide + env', () => {
-    expect(
-      resolveModerationPolicy({
-        perAgentOverride: true,
-        tenantWideOverride: false,
-        env: { OM_AI_INPUT_MODERATION: 'false' },
-      }),
-    ).toBe('on')
-    expect(
-      resolveModerationPolicy({
-        perAgentOverride: false,
-        tenantWideOverride: true,
-        env: { OM_AI_INPUT_MODERATION: 'true' },
-      }),
-    ).toBe('off')
-  })
-
-  it('3. tenant-wide override wins over env when per-agent is inherit', () => {
-    expect(
-      resolveModerationPolicy({
-        perAgentOverride: null,
-        tenantWideOverride: true,
-        env: { OM_AI_INPUT_MODERATION: 'false' },
-      }),
-    ).toBe('on')
-    expect(
-      resolveModerationPolicy({
-        perAgentOverride: undefined,
-        tenantWideOverride: false,
-        env: { OM_AI_INPUT_MODERATION: 'true' },
-      }),
-    ).toBe('off')
-  })
-
-  it('4. env default applies when both overrides inherit', () => {
-    expect(
-      resolveModerationPolicy({ perAgentOverride: null, tenantWideOverride: null, env: { OM_AI_INPUT_MODERATION: 'true' } }),
-    ).toBe('on')
-    expect(
-      resolveModerationPolicy({ env: { OM_AI_INPUT_MODERATION: '1' } }),
-    ).toBe('on')
-  })
-
-  it('5. defaults to off when nothing is set', () => {
-    expect(resolveModerationPolicy({ env: {} })).toBe('off')
-    expect(resolveModerationPolicy({ perAgentOverride: null, tenantWideOverride: null, env: {} })).toBe('off')
-  })
-
-  it('treats untrustedInput=false the same as unset (falls through)', () => {
-    expect(
-      resolveModerationPolicy({ untrustedInput: false, tenantWideOverride: true, env: {} }),
-    ).toBe('on')
-  })
-})
-
-describe('moderation policy helpers', () => {
-  it('isModerationActive is true for enforced and on, false for off', () => {
-    expect(isModerationActive('enforced')).toBe(true)
-    expect(isModerationActive('on')).toBe(true)
-    expect(isModerationActive('off')).toBe(false)
-  })
-
-  it('shouldFailClosed is true only for enforced (opt-in on fails open)', () => {
-    expect(shouldFailClosed('enforced')).toBe(true)
-    expect(shouldFailClosed('on')).toBe(false)
-    expect(shouldFailClosed('off')).toBe(false)
-  })
-})

package/src/modules/ai_assistant/lib/__tests__/moderation.test.ts

@@ -1,114 +0,0 @@
-import {
-  AiModerationUnavailableError,
-  createModerationService,
-  DEFAULT_MODERATION_MODEL,
-} from '../moderation'
-
-function jsonResponse(body: unknown, status = 200): Response {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    json: async () => body,
-  } as unknown as Response
-}
-
-function moderationBody(flagged: boolean): unknown {
-  return {
-    results: [
-      {
-        flagged,
-        categories: { hate: flagged, violence: false },
-        category_scores: { hate: flagged ? 0.97 : 0.01, violence: 0.002 },
-      },
-    ],
-  }
-}
-
-describe('createModerationService.checkInput', () => {
-  const service = createModerationService()
-  let fetchSpy: jest.SpyInstance
-
-  beforeEach(() => {
-    fetchSpy = jest.spyOn(globalThis, 'fetch')
-  })
-  afterEach(() => {
-    fetchSpy.mockRestore()
-  })
-
-  it('returns flagged=false with mapped categories for clean input', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse(moderationBody(false)))
-    const result = await service.checkInput({ text: 'hello', apiKey: 'sk-test' })
-    expect(result.flagged).toBe(false)
-    expect(result.categories.hate).toEqual({ flagged: false, score: 0.01 })
-    expect(result.categories.violence).toEqual({ flagged: false, score: 0.002 })
-    expect(fetchSpy).toHaveBeenCalledTimes(1)
-  })
-
-  it('returns flagged=true with category flags + scores for flagged input', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse(moderationBody(true)))
-    const result = await service.checkInput({ text: 'bad', apiKey: 'sk-test' })
-    expect(result.flagged).toBe(true)
-    expect(result.categories.hate).toEqual({ flagged: true, score: 0.97 })
-  })
-
-  it('sends the configured model + base URL and bearer auth', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse(moderationBody(false)))
-    await service.checkInput({
-      text: 'hi',
-      apiKey: 'sk-secret',
-      baseURL: 'https://proxy.example.com/v1/',
-      model: 'omni-moderation-2026',
-    })
-    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit]
-    expect(url).toBe('https://proxy.example.com/v1/moderations')
-    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer sk-secret')
-    expect(JSON.parse(init.body as string)).toEqual({ model: 'omni-moderation-2026', input: 'hi' })
-  })
-
-  it('defaults to omni-moderation-latest when no model is supplied', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse(moderationBody(false)))
-    await service.checkInput({ text: 'hi', apiKey: 'sk-test' })
-    const init = fetchSpy.mock.calls[0][1] as RequestInit
-    expect(JSON.parse(init.body as string).model).toBe(DEFAULT_MODERATION_MODEL)
-  })
-
-  it('retries once on a 5xx and succeeds', async () => {
-    fetchSpy
-      .mockResolvedValueOnce(jsonResponse({ error: 'boom' }, 503))
-      .mockResolvedValueOnce(jsonResponse(moderationBody(false)))
-    const result = await service.checkInput({ text: 'hi', apiKey: 'sk-test' })
-    expect(result.flagged).toBe(false)
-    expect(fetchSpy).toHaveBeenCalledTimes(2)
-  })
-
-  it('throws AiModerationUnavailableError after a 5xx on both attempts', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse({ error: 'boom' }, 500))
-    await expect(service.checkInput({ text: 'hi', apiKey: 'sk-test' })).rejects.toBeInstanceOf(
-      AiModerationUnavailableError,
-    )
-    expect(fetchSpy).toHaveBeenCalledTimes(2)
-  })
-
-  it('throws AiModerationUnavailableError on repeated network/timeout errors', async () => {
-    fetchSpy.mockRejectedValue(new Error('AbortError: timed out'))
-    await expect(service.checkInput({ text: 'hi', apiKey: 'sk-test' })).rejects.toBeInstanceOf(
-      AiModerationUnavailableError,
-    )
-    expect(fetchSpy).toHaveBeenCalledTimes(2)
-  })
-
-  it('does not retry a 4xx (credential/config error) and fails closed', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse({ error: 'unauthorized' }, 401))
-    await expect(service.checkInput({ text: 'hi', apiKey: 'bad' })).rejects.toBeInstanceOf(
-      AiModerationUnavailableError,
-    )
-    expect(fetchSpy).toHaveBeenCalledTimes(1)
-  })
-
-  it('throws AiModerationUnavailableError when the response schema is unexpected', async () => {
-    fetchSpy.mockResolvedValue(jsonResponse({ unexpected: true }))
-    await expect(service.checkInput({ text: 'hi', apiKey: 'sk-test' })).rejects.toBeInstanceOf(
-      AiModerationUnavailableError,
-    )
-  })
-})

package/src/modules/ai_assistant/lib/moderation-flag-recorder.ts

@@ -1,75 +0,0 @@
-import type { AwilixContainer } from 'awilix'
-import type { EntityManager } from '@mikro-orm/postgresql'
-import { createLogger } from '@open-mercato/shared/lib/logger'
-import { AiModerationFlagRepository } from '../data/repositories/AiModerationFlagRepository'
-import { emitAiAssistantEvent } from '../events'
-import type { ModerationCategoryResult } from './moderation'
-
-const logger = createLogger('ai_assistant')
-
-export interface RecordModerationFlagInput {
-  tenantId: string | null
-  organizationId: string | null
-  agentId: string
-  userId: string
-  providerId: string
-  modelId: string
-  categories: Record<string, ModerationCategoryResult>
-}
-
-/**
- * Persists one `ai_moderation_flags` audit row and emits
- * `ai_assistant.moderation_flag.created`, best-effort.
- *
- * SAFETY CONTRACT: this MUST NEVER throw — the moderation rejection is the
- * primary effect and is thrown by the gate regardless. A missing tenant scope
- * (e.g. a system-scope caller) means the row cannot be tenant-scoped, so the
- * audit write is skipped. Any persistence/emit failure is logged and
- * swallowed so the user still receives the rejection.
- *
- * Spec `2026-06-04-ai-input-moderation-and-safety-identifiers`.
- */
-export async function recordModerationFlag(
-  input: RecordModerationFlagInput,
-  container: AwilixContainer | undefined,
-): Promise<void> {
-  if (!container) return
-  if (!input.tenantId) return
-
-  let createdId: string | null = null
-  try {
-    const em = container.resolve<EntityManager>('em')
-    const repo = new AiModerationFlagRepository(em.fork())
-    const flag = await repo.create({
-      tenantId: input.tenantId,
-      organizationId: input.organizationId,
-      agentId: input.agentId,
-      userId: input.userId,
-      providerId: input.providerId,
-      modelId: input.modelId,
-      categories: input.categories,
-    })
-    createdId = flag.id
-  } catch (error) {
-    logger.error('Failed to persist moderation flag (rejection still applies)', { err: error })
-    return
-  }
-
-  // Emit AFTER a successful write, detached so a failed emit never retroactively
-  // fails the audit insert.
-  try {
-    const flaggedCategories = Object.entries(input.categories)
-      .filter(([, value]) => value.flagged)
-      .map(([name]) => name)
-    await emitAiAssistantEvent('ai_assistant.moderation_flag.created', {
-      id: createdId,
-      tenantId: input.tenantId,
-      organizationId: input.organizationId,
-      agentId: input.agentId,
-      userId: input.userId,
-      categories: flaggedCategories,
-    })
-  } catch (error) {
-    logger.error('Failed to emit moderation_flag.created (audit row persisted)', { err: error })
-  }
-}

package/src/modules/ai_assistant/lib/moderation-policy.ts

@@ -1,77 +0,0 @@
-/**
- * Input-moderation policy resolution.
- *
- * Resolves the effective moderation policy for an agent turn using a fixed
- * precedence (first match wins):
- *
- *   1. `agentDef.untrustedInput === true` → `enforced` (tenant cannot disable).
- *   2. Per-agent tenant override (`ai_agent_runtime_overrides` row with an
- *      `agent_id`) `input_moderation` → `on` / `off`.
- *   3. Tenant-wide override (row with `agent_id = NULL`) `input_moderation` →
- *      `on` / `off`.
- *   4. Env default `OM_AI_INPUT_MODERATION` (parsed via `parseBooleanWithDefault`)
- *      → `on` / `off`.
- *   5. Default `off`.
- *
- * Steps 4 and 5 collapse into `parseBooleanWithDefault(env, false)`.
- *
- * @see .ai/specs/2026-06-04-ai-input-moderation-and-safety-identifiers.md
- */
-
-import type { EnvLookup } from '@open-mercato/shared/lib/ai/llm-provider'
-import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
-
-/** Effective runtime moderation policy for a turn. */
-export type ModerationPolicy = 'enforced' | 'on' | 'off'
-
-/** The per-agent display state shown in settings (adds `inherit`). */
-export type ModerationPolicyDisplay = 'enforced' | 'on' | 'off' | 'inherit'
-
-export interface ResolveModerationPolicyInput {
-  /** Whether the agent definition marks this surface as untrusted. */
-  untrustedInput?: boolean
-  /**
-   * `input_moderation` from the agent-scoped tenant override row, or
-   * `null`/`undefined` when the row is absent or leaves it unset (inherit).
-   */
-  perAgentOverride?: boolean | null
-  /**
-   * `input_moderation` from the tenant-wide override row (`agent_id = NULL`),
-   * or `null`/`undefined` when absent/unset (inherit).
-   */
-  tenantWideOverride?: boolean | null
-  /** Env lookup; reads `OM_AI_INPUT_MODERATION`. Defaults to `process.env`. */
-  env?: EnvLookup
-}
-
-/**
- * Resolves the effective moderation policy following the 5-step precedence.
- * Pure and synchronous — the runtime hydrates the override values from the DB
- * before calling this.
- */
-export function resolveModerationPolicy(input: ResolveModerationPolicyInput): ModerationPolicy {
-  if (input.untrustedInput === true) return 'enforced'
-  if (input.perAgentOverride !== null && input.perAgentOverride !== undefined) {
-    return input.perAgentOverride ? 'on' : 'off'
-  }
-  if (input.tenantWideOverride !== null && input.tenantWideOverride !== undefined) {
-    return input.tenantWideOverride ? 'on' : 'off'
-  }
-  const env = input.env ?? process.env
-  return parseBooleanWithDefault(env.OM_AI_INPUT_MODERATION, false) ? 'on' : 'off'
-}
-
-/** Whether a resolved policy should run the moderation gate for the turn. */
-export function isModerationActive(policy: ModerationPolicy): boolean {
-  return policy === 'enforced' || policy === 'on'
-}
-
-/**
- * Whether an *unavailable* moderation check (endpoint outage) should fail
- * closed (reject the turn) rather than fail open (allow it through). Per spec:
- * only `enforced` (untrusted) surfaces fail closed; opt-in `on` surfaces prefer
- * availability and fail open. Both paths log. (`off` never reaches the gate.)
- */
-export function shouldFailClosed(policy: ModerationPolicy): boolean {
-  return policy === 'enforced'
-}