@open-mercato/ai-assistant 0.6.1-develop.3291.1.6fad645fd0 → 0.6.1

package/src/modules/ai_assistant/lib/__tests__/agent-runtime-loop-phase0.test.ts

@@ -0,0 +1,439 @@
+/**
+ * Phase 0 unit tests for the agentic loop control surface.
+ *
+ * Covers:
+ * - resolveEffectiveLoopConfig — precedence chain (caller > agent.loop > legacyMaxSteps > wrapper default)
+ * - translateStopConditions — mapping of AiAgentLoopStopCondition to SDK helpers + hard stepCountIs fallback
+ * - mergeStepOverrides — security-critical tool-allowlist enforcement
+ * - assertLoopObjectModeCompatible — object-mode field rejection
+ *
+ * Phase 0 of spec 2026-04-28-ai-agents-agentic-loop-controls.
+ */
+
+const stepCountIsMock = jest.fn((count: number) => ({ __kind: 'stepCount', count }))
+const hasToolCallMock = jest.fn((name: string) => ({ __kind: 'hasToolCall', name }))
+
+jest.mock('ai', () => {
+  const actual = jest.requireActual('ai')
+  return {
+    ...actual,
+    stepCountIs: (count: number) => stepCountIsMock(count),
+    hasToolCall: (name: string) => hasToolCallMock(name),
+  }
+})
+
+import type { AiAgentDefinition } from '../ai-agent-definition'
+import type { PrepareStepResult, ToolSet } from 'ai'
+import {
+  resolveEffectiveLoopConfig,
+  translateStopConditions,
+  mergeStepOverrides,
+  buildWrapperPrepareStep,
+  assertLoopObjectModeCompatible,
+} from '../agent-runtime'
+import { AgentPolicyError } from '../agent-tools'
+
+function makeAgent(
+  overrides: Partial<AiAgentDefinition> & Pick<AiAgentDefinition, 'id' | 'moduleId'>,
+): AiAgentDefinition {
+  return {
+    label: `${overrides.id} label`,
+    description: `${overrides.id} description`,
+    systemPrompt: 'System prompt.',
+    allowedTools: [],
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// resolveEffectiveLoopConfig
+// ---------------------------------------------------------------------------
+
+describe('resolveEffectiveLoopConfig', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('returns wrapper default when agent has no loop config and no caller override', () => {
+    const agent = makeAgent({ id: 'mod.agent', moduleId: 'mod' })
+    const result = resolveEffectiveLoopConfig(agent, undefined, { maxSteps: 10 })
+    expect(result.maxSteps).toBe(10)
+  })
+
+  it('uses legacy agent.maxSteps when agent.loop is absent', () => {
+    const agent = makeAgent({ id: 'mod.agent', moduleId: 'mod', maxSteps: 5 })
+    const result = resolveEffectiveLoopConfig(agent, undefined, { maxSteps: 10 })
+    expect(result.maxSteps).toBe(5)
+  })
+
+  it('agent.loop wins over legacy maxSteps when both are present', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      maxSteps: 5,
+      loop: { maxSteps: 8 },
+    })
+    const result = resolveEffectiveLoopConfig(agent, undefined, { maxSteps: 10 })
+    expect(result.maxSteps).toBe(8)
+  })
+
+  it('caller loop override wins over agent.loop', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { maxSteps: 8 },
+    })
+    const result = resolveEffectiveLoopConfig(agent, { maxSteps: 3 }, { maxSteps: 10 })
+    expect(result.maxSteps).toBe(3)
+  })
+
+  it('caller loop preserves agent-level stopWhen when caller does not override it', () => {
+    const agentStop = { kind: 'hasToolCall' as const, toolName: 'mod.tool' }
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { stopWhen: agentStop },
+    })
+    const result = resolveEffectiveLoopConfig(agent, { maxSteps: 3 }, { maxSteps: 10 })
+    expect(result.stopWhen).toEqual(agentStop)
+    expect(result.maxSteps).toBe(3)
+  })
+
+  it('caller override replaces agent stopWhen when caller sets stopWhen', () => {
+    const agentStop = { kind: 'hasToolCall' as const, toolName: 'mod.tool' }
+    const callerStop = { kind: 'stepCount' as const, count: 2 }
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { stopWhen: agentStop },
+    })
+    const result = resolveEffectiveLoopConfig(agent, { stopWhen: callerStop }, { maxSteps: 10 })
+    expect(result.stopWhen).toEqual(callerStop)
+  })
+
+  it('legacy maxSteps is NOT applied when agent.loop is present (loop wins)', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      maxSteps: 99,
+      loop: { maxSteps: 7 },
+    })
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.maxSteps).toBe(7)
+  })
+
+  it('returns wrapper default maxSteps when no source provides maxSteps', () => {
+    const agent = makeAgent({ id: 'mod.agent', moduleId: 'mod' })
+    const result = resolveEffectiveLoopConfig(agent, undefined, { maxSteps: 10 })
+    expect(result.maxSteps).toBe(10)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// translateStopConditions
+// ---------------------------------------------------------------------------
+
+describe('translateStopConditions', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('always includes stepCountIs(maxSteps) as the final element', () => {
+    const result = translateStopConditions({ maxSteps: 5 })
+    expect(stepCountIsMock).toHaveBeenCalledWith(5)
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual({ __kind: 'stepCount', count: 5 })
+  })
+
+  it('defaults to maxSteps=10 when maxSteps is not set', () => {
+    translateStopConditions({})
+    expect(stepCountIsMock).toHaveBeenCalledWith(10)
+  })
+
+  it('maps kind:stepCount to stepCountIs', () => {
+    const result = translateStopConditions({
+      maxSteps: 10,
+      stopWhen: { kind: 'stepCount', count: 3 },
+    })
+    expect(stepCountIsMock).toHaveBeenCalledWith(3)
+    expect(result).toHaveLength(2)
+  })
+
+  it('maps kind:hasToolCall to hasToolCall', () => {
+    const result = translateStopConditions(
+      {
+        maxSteps: 10,
+        stopWhen: { kind: 'hasToolCall', toolName: 'mod.update' },
+      },
+      (name) => name.replace(/\./g, '__'),
+    )
+    expect(hasToolCallMock).toHaveBeenCalledWith('mod__update')
+    expect(result).toHaveLength(2)
+    expect(result[0]).toEqual({ __kind: 'hasToolCall', name: 'mod__update' })
+    expect(result[1]).toEqual({ __kind: 'stepCount', count: 10 })
+  })
+
+  it('passes kind:custom predicates through as-is', () => {
+    const customStop = jest.fn(() => false) as unknown as import('ai').StopCondition<Record<string, unknown>>
+    const result = translateStopConditions({
+      maxSteps: 10,
+      stopWhen: { kind: 'custom', stop: customStop },
+    })
+    expect(result[0]).toBe(customStop)
+    expect(result).toHaveLength(2)
+  })
+
+  it('handles an array of stopWhen conditions', () => {
+    const result = translateStopConditions({
+      maxSteps: 4,
+      stopWhen: [
+        { kind: 'hasToolCall', toolName: 'mod.a' },
+        { kind: 'hasToolCall', toolName: 'mod.b' },
+      ],
+    })
+    expect(hasToolCallMock).toHaveBeenCalledWith('mod.a')
+    expect(hasToolCallMock).toHaveBeenCalledWith('mod.b')
+    expect(result).toHaveLength(3)
+    expect(result[2]).toEqual({ __kind: 'stepCount', count: 4 })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// mergeStepOverrides
+// ---------------------------------------------------------------------------
+
+describe('mergeStepOverrides', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  const agent = makeAgent({
+    id: 'mod.agent',
+    moduleId: 'mod',
+    allowedTools: ['mod.read', 'mod.write'],
+  })
+
+  const wrappedRead = { execute: jest.fn(), description: 'read tool' }
+  const wrappedWrite = { execute: jest.fn(), description: 'write tool', isMutation: true }
+  const wrappedRegistry = {
+    mod__read: wrappedRead,
+    mod__write: wrappedWrite,
+  }
+
+  it('returns wrapperOverride unchanged when userOverride is null', () => {
+    const wrapper: PrepareStepResult<ToolSet> = { activeTools: ['mod__read'] }
+    expect(mergeStepOverrides(wrapper, null, agent, wrappedRegistry)).toBe(wrapper)
+  })
+
+  it('returns wrapperOverride unchanged when userOverride is undefined', () => {
+    const wrapper: PrepareStepResult<ToolSet> = { activeTools: ['mod__read'] }
+    expect(mergeStepOverrides(wrapper, undefined, agent, wrappedRegistry)).toBe(wrapper)
+  })
+
+  it('merges model from userOverride', () => {
+    const fakeModel = { id: 'gpt-5-mini' } as unknown as import('ai').LanguageModel
+    const result = mergeStepOverrides({}, { model: fakeModel }, agent, wrappedRegistry)
+    expect(result.model).toBe(fakeModel)
+  })
+
+  it('merges toolChoice from userOverride', () => {
+    const result = mergeStepOverrides({}, { toolChoice: 'none' }, agent, wrappedRegistry)
+    expect(result.toolChoice).toBe('none')
+  })
+
+  it('filters user activeTools to only those in agent.allowedTools (dotted names)', () => {
+    const result = mergeStepOverrides(
+      {},
+      { activeTools: ['mod.read', 'mod.write', 'outside.tool'] },
+      agent,
+      wrappedRegistry,
+    )
+    expect(result.activeTools).toEqual(['mod.read', 'mod.write'])
+  })
+
+  it('accepts already-sanitized activeTools and normalizes them back to dotted contract names', () => {
+    const result = mergeStepOverrides(
+      {},
+      { activeTools: ['mod__read', 'outside__tool'] },
+      agent,
+      wrappedRegistry,
+    )
+    expect(result.activeTools).toEqual(['mod.read'])
+  })
+
+  it('replaces user tools with wrapped counterparts from wrappedRegistry', () => {
+    const rawHandler = { execute: jest.fn() }
+    const result = mergeStepOverrides(
+      {},
+      { tools: { mod__read: rawHandler } as unknown as PrepareStepResult<ToolSet>['tools'] },
+      agent,
+      wrappedRegistry,
+    )
+    expect((result.tools as Record<string, unknown>)['mod__read']).toBe(wrappedRead)
+  })
+
+  it('drops user tools not present in wrappedRegistry with a warning', () => {
+    const consoleSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+    const rawHandler = { execute: jest.fn() }
+    const result = mergeStepOverrides(
+      {},
+      { tools: { unknown__tool: rawHandler } as unknown as PrepareStepResult<ToolSet>['tools'] },
+      agent,
+      wrappedRegistry,
+    )
+    expect((result.tools as Record<string, unknown>)['unknown__tool']).toBeUndefined()
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('unknown__tool'),
+    )
+    consoleSpy.mockRestore()
+  })
+
+  it('throws loop_violates_mutation_policy when user returns raw mutation handler', () => {
+    const { toolRegistry: registry } = jest.requireActual('../tool-registry') as {
+      toolRegistry: { getTool: (name: string) => unknown }
+    }
+    jest.spyOn(registry, 'getTool').mockImplementation((name: string) => {
+      if (name === 'mod.write') return { isMutation: true }
+      return undefined
+    })
+
+    const rawMutationHandler = { execute: jest.fn() }
+    expect(() =>
+      mergeStepOverrides(
+        {},
+        { tools: { mod__write: rawMutationHandler } as unknown as PrepareStepResult<ToolSet>['tools'] },
+        agent,
+        wrappedRegistry,
+      ),
+    ).toThrow(AgentPolicyError)
+
+    jest.restoreAllMocks()
+  })
+})
+
+describe('buildWrapperPrepareStep', () => {
+  const agent = makeAgent({
+    id: 'mod.agent',
+    moduleId: 'mod',
+    allowedTools: ['mod.read', 'mod.write'],
+  })
+  const wrappedRegistry = {
+    mod__read: { execute: jest.fn(), description: 'read tool' },
+    mod__write: { execute: jest.fn(), description: 'write tool' },
+  }
+
+  it('maps dotted activeTools from user prepareStep to SDK-safe tool keys', async () => {
+    const prepareStep = buildWrapperPrepareStep(
+      agent,
+      {
+        prepareStep: async () => ({ activeTools: ['mod.read', 'mod.write'] }),
+      },
+      wrappedRegistry,
+    )
+
+    const result = await prepareStep({
+      stepNumber: 0,
+      steps: [],
+      messages: [],
+      model: {} as never,
+    })
+
+    expect(result?.activeTools).toEqual(['mod__read', 'mod__write'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// assertLoopObjectModeCompatible
+// ---------------------------------------------------------------------------
+
+describe('assertLoopObjectModeCompatible', () => {
+  it('does not throw for object-safe loop fields', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({
+        maxSteps: 5,
+        budget: { maxTokens: 50000 },
+        onStepFinish: jest.fn(),
+        onStepStart: jest.fn(),
+        allowRuntimeOverride: true,
+      }),
+    ).not.toThrow()
+  })
+
+  it('throws loop_unsupported_in_object_mode for prepareStep', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ prepareStep: jest.fn() }),
+    ).toThrow(AgentPolicyError)
+    try {
+      assertLoopObjectModeCompatible({ prepareStep: jest.fn() })
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_unsupported_in_object_mode')
+    }
+  })
+
+  it('throws for repairToolCall', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ repairToolCall: jest.fn() }),
+    ).toThrow(AgentPolicyError)
+  })
+
+  it('throws for stopWhen', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ stopWhen: { kind: 'stepCount', count: 3 } }),
+    ).toThrow(AgentPolicyError)
+  })
+
+  it('throws for activeTools', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ activeTools: ['mod.read'] }),
+    ).toThrow(AgentPolicyError)
+  })
+
+  it('throws for toolChoice', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ toolChoice: 'none' }),
+    ).toThrow(AgentPolicyError)
+  })
+
+  it('mentions all unsupported fields in the error message', () => {
+    try {
+      assertLoopObjectModeCompatible({ prepareStep: jest.fn(), stopWhen: { kind: 'stepCount', count: 2 } })
+    } catch (error) {
+      expect((error as Error).message).toContain('prepareStep')
+      expect((error as Error).message).toContain('stopWhen')
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ai-agent-definition legacy maxSteps and loop field acceptance
+// ---------------------------------------------------------------------------
+
+describe('defineAiAgent loop field acceptance (Phase 0 BC)', () => {
+  it('legacy maxSteps is still accepted on AiAgentDefinition', () => {
+    const agent = makeAgent({ id: 'mod.agent', moduleId: 'mod', maxSteps: 5 })
+    expect(agent.maxSteps).toBe(5)
+  })
+
+  it('loop field is accepted on AiAgentDefinition', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { maxSteps: 7, stopWhen: { kind: 'hasToolCall', toolName: 'mod.update' } },
+    })
+    expect(agent.loop?.maxSteps).toBe(7)
+    const stopWhen = agent.loop?.stopWhen
+    expect(stopWhen).toEqual({ kind: 'hasToolCall', toolName: 'mod.update' })
+  })
+
+  it('loop and maxSteps can coexist (loop wins in resolveEffectiveLoopConfig)', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      maxSteps: 99,
+      loop: { maxSteps: 4 },
+    })
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.maxSteps).toBe(4)
+  })
+})

package/src/modules/ai_assistant/lib/__tests__/agent-runtime-loop-phase1.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Phase 1 unit tests for per-call loop overrides on runAiAgentText /
+ * runAiAgentObject.
+ *
+ * Covers:
+ * - Caller override is accepted when allowRuntimeOverride is true (default).
+ * - AgentPolicyError loop_runtime_override_disabled when agent opts out.
+ * - Object-mode loop subset: chat-only fields throw loop_unsupported_in_object_mode.
+ * - resolveEffectiveLoopConfig caller precedence with gating.
+ *
+ * Phase 1 of spec 2026-04-28-ai-agents-agentic-loop-controls.
+ */
+
+const stepCountIsMock = jest.fn((count: number) => ({ __kind: 'stepCount', count }))
+
+jest.mock('ai', () => {
+  const actual = jest.requireActual('ai')
+  return {
+    ...actual,
+    stepCountIs: (count: number) => stepCountIsMock(count),
+  }
+})
+
+import type { AiAgentDefinition, AiAgentLoopConfig } from '../ai-agent-definition'
+import {
+  resolveEffectiveLoopConfig,
+  assertLoopObjectModeCompatible,
+} from '../agent-runtime'
+import { AgentPolicyError } from '../agent-tools'
+
+function makeAgent(
+  overrides: Partial<AiAgentDefinition> & Pick<AiAgentDefinition, 'id' | 'moduleId'>,
+): AiAgentDefinition {
+  return {
+    label: `${overrides.id} label`,
+    description: `${overrides.id} description`,
+    systemPrompt: 'System prompt.',
+    allowedTools: [],
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-call loop override gating
+// ---------------------------------------------------------------------------
+
+describe('Phase 1: caller loop override gating (loop_runtime_override_disabled)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('accepts per-call loop override when agent has no allowRuntimeOverride set (default true)', () => {
+    const agent = makeAgent({ id: 'mod.agent', moduleId: 'mod' })
+    expect(() =>
+      resolveEffectiveLoopConfig(agent, { maxSteps: 3 }),
+    ).not.toThrow()
+  })
+
+  it('accepts per-call loop override when agent explicitly sets allowRuntimeOverride: true', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { allowRuntimeOverride: true, maxSteps: 8 },
+    })
+    expect(() =>
+      resolveEffectiveLoopConfig(agent, { maxSteps: 3 }),
+    ).not.toThrow()
+    const result = resolveEffectiveLoopConfig(agent, { maxSteps: 3 })
+    expect(result.maxSteps).toBe(3)
+  })
+
+  it('throws loop_runtime_override_disabled when agent sets allowRuntimeOverride: false', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { allowRuntimeOverride: false, maxSteps: 8 },
+    })
+    expect(() =>
+      resolveEffectiveLoopConfig(agent, { maxSteps: 3 }),
+    ).toThrow(AgentPolicyError)
+
+    try {
+      resolveEffectiveLoopConfig(agent, { maxSteps: 3 })
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_runtime_override_disabled')
+      expect((error as AgentPolicyError).message).toContain('mod.agent')
+    }
+  })
+
+  it('does NOT throw when allowRuntimeOverride: false but no caller loop is supplied', () => {
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { allowRuntimeOverride: false, maxSteps: 8 },
+    })
+    expect(() =>
+      resolveEffectiveLoopConfig(agent, undefined),
+    ).not.toThrow()
+    const result = resolveEffectiveLoopConfig(agent, undefined)
+    expect(result.maxSteps).toBe(8)
+  })
+
+  it('caller loop fields override agent loop fields selectively', () => {
+    const agentStop = { kind: 'hasToolCall' as const, toolName: 'mod.update' }
+    const agent = makeAgent({
+      id: 'mod.agent',
+      moduleId: 'mod',
+      loop: { maxSteps: 8, stopWhen: agentStop },
+    })
+    const result = resolveEffectiveLoopConfig(agent, { maxSteps: 3 })
+    expect(result.maxSteps).toBe(3)
+    expect(result.stopWhen).toEqual(agentStop)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Object-mode loop subset
+// ---------------------------------------------------------------------------
+
+describe('Phase 1: object-mode loop subset enforcement', () => {
+  it('accepts maxSteps in object mode', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ maxSteps: 3 }),
+    ).not.toThrow()
+  })
+
+  it('accepts budget in object mode', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ budget: { maxTokens: 50000 } }),
+    ).not.toThrow()
+  })
+
+  it('accepts onStepFinish in object mode', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ onStepFinish: jest.fn() }),
+    ).not.toThrow()
+  })
+
+  it('accepts onStepStart in object mode', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ onStepStart: jest.fn() }),
+    ).not.toThrow()
+  })
+
+  it('accepts allowRuntimeOverride in object mode', () => {
+    expect(() =>
+      assertLoopObjectModeCompatible({ allowRuntimeOverride: true }),
+    ).not.toThrow()
+  })
+
+  it('rejects prepareStep with loop_unsupported_in_object_mode', () => {
+    try {
+      assertLoopObjectModeCompatible({ prepareStep: jest.fn() })
+      fail('Expected AgentPolicyError')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_unsupported_in_object_mode')
+    }
+  })
+
+  it('rejects stopWhen with loop_unsupported_in_object_mode', () => {
+    try {
+      assertLoopObjectModeCompatible({ stopWhen: { kind: 'stepCount', count: 2 } })
+      fail('Expected AgentPolicyError')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_unsupported_in_object_mode')
+    }
+  })
+
+  it('rejects repairToolCall with loop_unsupported_in_object_mode', () => {
+    try {
+      assertLoopObjectModeCompatible({ repairToolCall: jest.fn() })
+      fail('Expected AgentPolicyError')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_unsupported_in_object_mode')
+    }
+  })
+
+  it('rejects activeTools with loop_unsupported_in_object_mode', () => {
+    try {
+      assertLoopObjectModeCompatible({ activeTools: ['mod.read'] })
+      fail('Expected AgentPolicyError')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_unsupported_in_object_mode')
+    }
+  })
+
+  it('rejects toolChoice with loop_unsupported_in_object_mode', () => {
+    try {
+      assertLoopObjectModeCompatible({ toolChoice: 'auto' })
+      fail('Expected AgentPolicyError')
+    } catch (error) {
+      expect(error).toBeInstanceOf(AgentPolicyError)
+      expect((error as AgentPolicyError).code).toBe('loop_unsupported_in_object_mode')
+    }
+  })
+
+  it('lists all unsupported fields in the error message when multiple are set', () => {
+    try {
+      assertLoopObjectModeCompatible({
+        prepareStep: jest.fn(),
+        stopWhen: { kind: 'stepCount', count: 1 },
+        activeTools: ['mod.read'],
+      })
+      fail('Expected AgentPolicyError')
+    } catch (error) {
+      const message = (error as Error).message
+      expect(message).toContain('prepareStep')
+      expect(message).toContain('stopWhen')
+      expect(message).toContain('activeTools')
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// AgentPolicyDenyCode exhaustiveness check
+// ---------------------------------------------------------------------------
+
+describe('Phase 1: AgentPolicyDenyCode has loop override codes', () => {
+  it('AgentPolicyError can be constructed with loop_runtime_override_disabled', () => {
+    const error = new AgentPolicyError('loop_runtime_override_disabled', 'test')
+    expect(error.code).toBe('loop_runtime_override_disabled')
+  })
+
+  it('AgentPolicyError can be constructed with loop_unsupported_in_object_mode', () => {
+    const error = new AgentPolicyError('loop_unsupported_in_object_mode', 'test')
+    expect(error.code).toBe('loop_unsupported_in_object_mode')
+  })
+
+  it('AgentPolicyError can be constructed with loop_violates_mutation_policy', () => {
+    const error = new AgentPolicyError('loop_violates_mutation_policy', 'test')
+    expect(error.code).toBe('loop_violates_mutation_policy')
+  })
+
+  it('AgentPolicyError can be constructed with loop_active_tools_outside_allowlist', () => {
+    const error = new AgentPolicyError('loop_active_tools_outside_allowlist', 'test')
+    expect(error.code).toBe('loop_active_tools_outside_allowlist')
+  })
+})