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

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

@@ -0,0 +1,359 @@
+/**
+ * Phase 3 unit tests for BudgetEnforcer, kill-switch, and env shorthands.
+ *
+ * Covers:
+ * - BudgetEnforcer.hasActiveBudget: true only when at least one budget axis is set.
+ * - BudgetEnforcer.wire: returns original userOnStepFinish unchanged when no budget.
+ * - BudgetEnforcer.wire: wraps onStepFinish when budget is active (tracks usage).
+ * - BudgetEnforcer aborts after maxToolCalls exceeded.
+ * - BudgetEnforcer aborts after maxTokens exceeded.
+ * - BudgetEnforcer aborts via wall-clock timeout.
+ * - resolveEffectiveLoopConfig reads <MODULE>_AI_LOOP_MAX_STEPS env shorthand.
+ * - resolveEffectiveLoopConfig reads <MODULE>_AI_LOOP_MAX_WALL_CLOCK_MS env shorthand.
+ * - resolveEffectiveLoopConfig reads <MODULE>_AI_LOOP_MAX_TOKENS env shorthand.
+ * - kill-switch: when loop.disabled = true is injected via caller loop, stopWhen is stepCountIs(1).
+ *
+ * Phase 3 of spec 2026-04-28-ai-agents-agentic-loop-controls.
+ */
+
+import type { AiAgentLoopConfig, AiAgentDefinition } from '../ai-agent-definition'
+import { BudgetEnforcer, resolveEffectiveLoopConfig } from '../agent-runtime'
+
+describe('Phase 3: BudgetEnforcer', () => {
+  describe('hasActiveBudget', () => {
+    it('returns false when budget is undefined', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer(undefined, ac)
+      expect(enforcer.hasActiveBudget).toBe(false)
+    })
+
+    it('returns false when budget is an empty object', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({}, ac)
+      expect(enforcer.hasActiveBudget).toBe(false)
+    })
+
+    it('returns true when maxToolCalls is set', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 5 }, ac)
+      expect(enforcer.hasActiveBudget).toBe(true)
+    })
+
+    it('returns true when maxWallClockMs is set', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxWallClockMs: 10_000 }, ac)
+      expect(enforcer.hasActiveBudget).toBe(true)
+    })
+
+    it('returns true when maxTokens is set', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxTokens: 50_000 }, ac)
+      expect(enforcer.hasActiveBudget).toBe(true)
+    })
+  })
+
+  describe('wire()', () => {
+    it('returns the original userOnStepFinish unchanged when no active budget', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer(undefined, ac)
+      const userFn = jest.fn()
+      const wired = enforcer.wire(userFn)
+      expect(wired).toBe(userFn)
+    })
+
+    it('returns the original undefined unchanged when no active budget', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({}, ac)
+      const wired = enforcer.wire(undefined)
+      expect(wired).toBeUndefined()
+    })
+
+    it('returns a wrapper function (not the original) when budget is active', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 5 }, ac)
+      const userFn = jest.fn()
+      const wired = enforcer.wire(userFn)
+      expect(wired).not.toBe(userFn)
+      expect(typeof wired).toBe('function')
+    })
+
+    it('invokes userOnStepFinish when budget is active and limits not yet exceeded', async () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 5 }, ac)
+      const userFn = jest.fn().mockResolvedValue(undefined)
+      const wired = enforcer.wire(userFn)!
+
+      const fakeEvent = {
+        usage: { inputTokens: 10, outputTokens: 20 },
+        toolCalls: [{}],
+      }
+
+      await wired(fakeEvent as never)
+
+      expect(userFn).toHaveBeenCalledWith(fakeEvent)
+      expect(ac.signal.aborted).toBe(false)
+    })
+
+    it('does NOT invoke userOnStepFinish after abort signal fires', async () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 1 }, ac)
+      const userFn = jest.fn().mockResolvedValue(undefined)
+      const wired = enforcer.wire(userFn)!
+
+      const firstEvent = { usage: { inputTokens: 5, outputTokens: 5 }, toolCalls: [{}] }
+      await wired(firstEvent as never)
+      expect(ac.signal.aborted).toBe(true)
+      expect(enforcer.abortReason).toBe('budget-tool-calls')
+
+      userFn.mockClear()
+      const secondEvent = { usage: { inputTokens: 5, outputTokens: 5 }, toolCalls: [{}] }
+      await wired(secondEvent as never)
+
+      expect(userFn).toHaveBeenCalledWith(secondEvent)
+    })
+  })
+
+  describe('maxToolCalls enforcement', () => {
+    it('aborts after the tool-call limit is reached', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 2 }, ac)
+
+      enforcer.recordStep({ toolCalls: 1 })
+      expect(ac.signal.aborted).toBe(false)
+
+      enforcer.recordStep({ toolCalls: 1 })
+      expect(ac.signal.aborted).toBe(true)
+      expect(enforcer.abortReason).toBe('budget-tool-calls')
+    })
+
+    it('aborts when a single step exceeds the tool-call limit', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 1 }, ac)
+
+      enforcer.recordStep({ toolCalls: 3 })
+      expect(ac.signal.aborted).toBe(true)
+      expect(enforcer.abortReason).toBe('budget-tool-calls')
+    })
+
+    it('does not double-abort when already aborted', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 1 }, ac)
+
+      enforcer.recordStep({ toolCalls: 2 })
+      const firstReason = enforcer.abortReason
+
+      enforcer.recordStep({ toolCalls: 5 })
+      expect(enforcer.abortReason).toBe(firstReason)
+    })
+  })
+
+  describe('maxTokens enforcement', () => {
+    it('aborts after token accumulation reaches the limit', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxTokens: 100 }, ac)
+
+      enforcer.recordStep({ inputTokens: 40, outputTokens: 40 })
+      expect(ac.signal.aborted).toBe(false)
+
+      enforcer.recordStep({ inputTokens: 10, outputTokens: 11 })
+      expect(ac.signal.aborted).toBe(true)
+      expect(enforcer.abortReason).toBe('budget-tokens')
+    })
+
+    it('counts both inputTokens and outputTokens', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxTokens: 30 }, ac)
+
+      enforcer.recordStep({ inputTokens: 15, outputTokens: 15 })
+      expect(ac.signal.aborted).toBe(true)
+      expect(enforcer.abortReason).toBe('budget-tokens')
+    })
+
+    it('skips tokensUsed accumulation when no tokens supplied', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxTokens: 10 }, ac)
+
+      enforcer.recordStep({})
+      expect(ac.signal.aborted).toBe(false)
+    })
+  })
+
+  describe('maxWallClockMs enforcement', () => {
+    it('aborts via checkLimits when elapsed time exceeds the wall-clock limit', async () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxWallClockMs: 1 }, ac)
+
+      await new Promise<void>((resolve) => setTimeout(resolve, 5))
+
+      enforcer.recordStep({})
+      expect(ac.signal.aborted).toBe(true)
+      expect(enforcer.abortReason).toBe('budget-wall-clock')
+    })
+
+    it('does not abort within the wall-clock window', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxWallClockMs: 30_000 }, ac)
+
+      enforcer.recordStep({})
+      expect(ac.signal.aborted).toBe(false)
+    })
+  })
+
+  describe('abortReason tracking', () => {
+    it('starts as null', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 5 }, ac)
+      expect(enforcer.abortReason).toBeNull()
+    })
+
+    it('is set to budget-tool-calls on tool-call abort', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxToolCalls: 1 }, ac)
+      enforcer.recordStep({ toolCalls: 2 })
+      expect(enforcer.abortReason).toBe('budget-tool-calls')
+    })
+
+    it('is set to budget-tokens on token abort', () => {
+      const ac = new AbortController()
+      const enforcer = new BudgetEnforcer({ maxTokens: 1 }, ac)
+      enforcer.recordStep({ inputTokens: 5 })
+      expect(enforcer.abortReason).toBe('budget-tokens')
+    })
+  })
+})
+
+describe('Phase 3: resolveEffectiveLoopConfig — env shorthands', () => {
+  const savedEnv: Record<string, string | undefined> = {}
+
+  function setEnv(key: string, value: string) {
+    savedEnv[key] = process.env[key]
+    process.env[key] = value
+  }
+
+  function restoreEnv(key: string) {
+    if (savedEnv[key] === undefined) {
+      delete process.env[key]
+    } else {
+      process.env[key] = savedEnv[key]
+    }
+  }
+
+  function makeAgent(moduleId: string): AiAgentDefinition {
+    return {
+      id: `${moduleId}.agent`,
+      moduleId,
+      label: 'Test agent',
+      description: 'Test',
+      systemPrompt: 'Prompt.',
+      allowedTools: [],
+    }
+  }
+
+  afterEach(() => {
+    Object.keys(savedEnv).forEach((key) => restoreEnv(key))
+    Object.keys(savedEnv).forEach((key) => delete savedEnv[key])
+  })
+
+  it('reads <MODULE>_AI_LOOP_MAX_STEPS and maps to maxSteps', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_STEPS', '7')
+    const agent = makeAgent('mymod')
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.maxSteps).toBe(7)
+  })
+
+  it('env MAX_STEPS overrides agent.loop.maxSteps', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_STEPS', '3')
+    const agent: AiAgentDefinition = { ...makeAgent('mymod'), loop: { maxSteps: 10 } }
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.maxSteps).toBe(3)
+  })
+
+  it('caller loop override wins over env MAX_STEPS', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_STEPS', '3')
+    const agent = makeAgent('mymod')
+    const result = resolveEffectiveLoopConfig(agent, { maxSteps: 12 })
+    expect(result.maxSteps).toBe(12)
+  })
+
+  it('reads <MODULE>_AI_LOOP_MAX_WALL_CLOCK_MS and maps to budget.maxWallClockMs', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_WALL_CLOCK_MS', '20000')
+    const agent = makeAgent('mymod')
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.budget?.maxWallClockMs).toBe(20000)
+  })
+
+  it('reads <MODULE>_AI_LOOP_MAX_TOKENS and maps to budget.maxTokens', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_TOKENS', '80000')
+    const agent = makeAgent('mymod')
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.budget?.maxTokens).toBe(80000)
+  })
+
+  it('merges env budget into agent.loop.budget (env wins per axis)', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_TOKENS', '40000')
+    const agent: AiAgentDefinition = {
+      ...makeAgent('mymod'),
+      loop: { budget: { maxToolCalls: 5, maxTokens: 100_000 } },
+    }
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.budget?.maxToolCalls).toBe(5)
+    expect(result.budget?.maxTokens).toBe(40000)
+  })
+
+  it('ignores malformed (non-numeric) env values, falling back to wrapper default', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_STEPS', 'not-a-number')
+    const agent = makeAgent('mymod')
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.maxSteps).toBe(10)
+  })
+
+  it('ignores zero and negative env values, falling back to wrapper default', () => {
+    setEnv('MYMOD_AI_LOOP_MAX_STEPS', '0')
+    const agent = makeAgent('mymod')
+    const result = resolveEffectiveLoopConfig(agent)
+    expect(result.maxSteps).toBe(10)
+  })
+})
+
+describe('Phase 3: kill-switch via caller loop.disabled', () => {
+  function makeAgent(overrides: Partial<AiAgentDefinition> = {}): AiAgentDefinition {
+    return {
+      id: 'mod.agent',
+      moduleId: 'mod',
+      label: 'Test agent',
+      description: 'Test',
+      systemPrompt: 'Prompt.',
+      allowedTools: [],
+      ...overrides,
+    }
+  }
+
+  it('when caller passes loop.disabled = true, maxSteps is forced to 1', () => {
+    const agent: AiAgentDefinition = {
+      ...makeAgent(),
+      loop: { maxSteps: 10 },
+    }
+    const result = resolveEffectiveLoopConfig(agent, { disabled: true } as Partial<AiAgentLoopConfig>)
+    expect((result as Record<string, unknown>).disabled).toBe(true)
+    expect((result as Record<string, unknown>).maxSteps).toBe(1)
+  })
+
+  it('when loop.disabled is false, maxSteps is not forced', () => {
+    const agent: AiAgentDefinition = {
+      ...makeAgent(),
+      loop: { maxSteps: 8 },
+    }
+    const result = resolveEffectiveLoopConfig(agent, { disabled: false } as Partial<AiAgentLoopConfig>)
+    expect((result as Record<string, unknown>).maxSteps).toBe(8)
+  })
+
+  it('when agent.loop.disabled = true (via override), maxSteps is forced to 1', () => {
+    const agent: AiAgentDefinition = {
+      ...makeAgent(),
+      loop: { maxSteps: 5, disabled: true } as AiAgentLoopConfig,
+    }
+    const result = resolveEffectiveLoopConfig(agent)
+    expect((result as Record<string, unknown>).disabled).toBe(true)
+    expect((result as Record<string, unknown>).maxSteps).toBe(1)
+  })
+})

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

@@ -286,7 +286,7 @@ describe('Phase 4a — runtime model override hydration in agent-runtime', () =>
       expect(getDefaultMock).not.toHaveBeenCalled()
     })
 
-    it('suppresses both overrides when allowRuntimeModelOverride is false', async () => {
+    it('suppresses both overrides when allowRuntimeOverride is false', async () => {
       getDefaultMock.mockResolvedValue({
         providerId: null,
         modelId: 'tenant-model-should-be-suppressed',
@@ -297,7 +297,7 @@ describe('Phase 4a — runtime model override hydration in agent-runtime', () =>
           id: 'customers.assistant',
           moduleId: 'customers',
           defaultModel: 'pinned-agent-model',
-          allowRuntimeModelOverride: false,
+          allowRuntimeOverride: false,
         }),
       ])
 

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

@@ -187,7 +187,8 @@ describe('runAiAgentText', () => {
 
     expect(stepCountIsMock).toHaveBeenCalledWith(5)
     const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
-    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 5 })
+    // Phase 2: stopWhen is now always an array from translateStopConditions
+    expect(callArg.stopWhen).toEqual([{ __stopWhen: 'stepCount', count: 5 }])
   })
 
   it('lets modelOverride win over agent.defaultModel', async () => {

package/src/modules/ai_assistant/lib/__tests__/max-steps-budget.integration.test.ts

@@ -145,7 +145,7 @@ describe('Step 5.16 — runAiAgentText maxSteps budget (integration)', () => {
     })
     expect(stepCountIsMock).toHaveBeenCalledWith(3)
     const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
-    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 3 })
+    expect(callArg.stopWhen).toEqual([{ __stopWhen: 'stepCount', count: 3 }])
   })
 
   it('applies default stopWhen: stepCountIs(10) when maxSteps is undefined (tool-call-enabling default)', async () => {
@@ -167,7 +167,7 @@ describe('Step 5.16 — runAiAgentText maxSteps budget (integration)', () => {
     })
     expect(stepCountIsMock).toHaveBeenCalledWith(10)
     const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
-    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 10 })
+    expect(callArg.stopWhen).toEqual([{ __stopWhen: 'stepCount', count: 10 }])
   })
 
   it('falls back to default stopWhen: stepCountIs(10) when maxSteps is 0', async () => {
@@ -189,7 +189,7 @@ describe('Step 5.16 — runAiAgentText maxSteps budget (integration)', () => {
     })
     expect(stepCountIsMock).toHaveBeenCalledWith(10)
     const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
-    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 10 })
+    expect(callArg.stopWhen).toEqual([{ __stopWhen: 'stepCount', count: 10 }])
   })
 })
 
@@ -211,7 +211,7 @@ describe('Step 5.16 — runAiAgentObject maxSteps budget parity (integration)',
     toolRegistry.clear()
   })
 
-  it('preserves agent.maxSteps → stopWhen on generateObject (object-mode parity)', async () => {
+  it('preserves agent.maxSteps on generateObject (object-mode parity)', async () => {
     seedAgentRegistryForTests([
       makeAgent({
         id: 'catalog.merchandising_assistant',
@@ -230,15 +230,14 @@ describe('Step 5.16 — runAiAgentObject maxSteps budget parity (integration)',
       input: 'draft title variants',
       authContext: baseAuth,
     })
-    expect(stepCountIsMock).toHaveBeenCalledWith(4)
-    // runAiAgentObject augments the generateObject args dynamically — the
-    // typed SDK surface ignores stopWhen but we MUST still forward it so
-    // providers that honor it behave identically across chat / object.
-    const callArg = generateObjectMock.mock.calls[0][0] as { stopWhen?: unknown }
-    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 4 })
+    // Object mode does not call stepCountIs — ai-sdk's generateObject / streamObject
+    // signature dropped stopWhen support in 6.0.177, so the runtime forwards
+    // only maxSteps for providers that honour it.
+    const callArg = generateObjectMock.mock.calls[0][0] as { maxSteps?: number; stopWhen?: unknown }
+    expect(callArg.maxSteps).toBe(4)
   })
 
-  it('omits stopWhen on generateObject when the agent declares no maxSteps', async () => {
+  it('omits maxSteps on generateObject when the agent declares no maxSteps', async () => {
     seedAgentRegistryForTests([
       makeAgent({
         id: 'catalog.merchandising_assistant',
@@ -257,7 +256,7 @@ describe('Step 5.16 — runAiAgentObject maxSteps budget parity (integration)',
       authContext: baseAuth,
     })
     expect(stepCountIsMock).not.toHaveBeenCalled()
-    const callArg = generateObjectMock.mock.calls[0][0] as { stopWhen?: unknown }
-    expect('stopWhen' in callArg).toBe(false)
+    const callArg = generateObjectMock.mock.calls[0][0] as { maxSteps?: unknown }
+    expect(callArg.maxSteps).toBeUndefined()
   })
 })

package/src/modules/ai_assistant/lib/__tests__/model-factory.test.ts

@@ -382,7 +382,7 @@ describe('createModelFactory', () => {
       expect(resolution.source).toBe('env_default')
     })
 
-    it('falls through when OM_AI_PROVIDER is registered but unconfigured', () => {
+    it('falls through when only OM_AI_PROVIDER is registered but unconfigured', () => {
       const anthropic = makeProvider({ id: 'anthropic', isConfigured: () => true })
       const openai = makeProvider({ id: 'openai', isConfigured: () => false })
       const { registry } = makeMultiProviderRegistry([anthropic, openai])
@@ -390,13 +390,26 @@ describe('createModelFactory', () => {
         registry,
         env: {
           OM_AI_PROVIDER: 'openai',
-          OM_AI_MODEL: 'gpt-5-mini',
         },
       })
       const resolution = factory.resolveModel({})
       expect(resolution.providerId).toBe('anthropic')
-      expect(resolution.modelId).toBe('gpt-5-mini')
-      expect(resolution.source).toBe('env_default')
+      expect(resolution.modelId).toBe('provider-default-model')
+      expect(resolution.source).toBe('provider_default')
+    })
+
+    it('does not mix an OM_AI_PROVIDER/OM_AI_MODEL pair into a different configured provider', () => {
+      const anthropic = makeProvider({ id: 'anthropic', isConfigured: () => false })
+      const openai = makeProvider({ id: 'openai', isConfigured: () => true })
+      const { registry } = makeMultiProviderRegistry([anthropic, openai])
+      const factory = createModelFactory(fakeContainer, {
+        registry,
+        env: {
+          OM_AI_PROVIDER: 'anthropic',
+          OM_AI_MODEL: 'claude-sonnet-4-20250514',
+        },
+      })
+      expect(() => factory.resolveModel({})).toThrow(AiModelFactoryError)
     })
 
     it('slash-qualified OM_AI_MODEL resets the provider for that resolution', () => {
@@ -594,6 +607,31 @@ describe('createModelFactory', () => {
       expect(resolution.source).toBe('agent_default')
     })
 
+    it('does not send a slash-qualified agent default model to a fallback provider', () => {
+      const anthropic = makeProvider({ id: 'anthropic', isConfigured: () => false })
+      const openai = makeProvider({ id: 'openai', isConfigured: () => true })
+      const { registry } = makeMultiProviderRegistry([anthropic, openai])
+      const factory = createModelFactory(fakeContainer, { registry, env: {} })
+      expect(() =>
+        factory.resolveModel({
+          agentDefaultModel: 'anthropic/claude-sonnet-4-20250514',
+        }),
+      ).toThrow(AiModelFactoryError)
+    })
+
+    it('does not send an agent default provider/model pair to a fallback provider', () => {
+      const anthropic = makeProvider({ id: 'anthropic', isConfigured: () => false })
+      const openai = makeProvider({ id: 'openai', isConfigured: () => true })
+      const { registry } = makeMultiProviderRegistry([anthropic, openai])
+      const factory = createModelFactory(fakeContainer, { registry, env: {} })
+      expect(() =>
+        factory.resolveModel({
+          agentDefaultProvider: 'anthropic',
+          agentDefaultModel: 'claude-sonnet-4-20250514',
+        }),
+      ).toThrow(AiModelFactoryError)
+    })
+
     it('slash-qualified OM_AI_<MODULE>_MODEL provides both provider hint and model id', () => {
       const anthropic = makeProvider({ id: 'anthropic' })
       const openai = makeProvider({ id: 'openai', defaultModel: 'gpt-4o-mini' })
@@ -833,7 +871,7 @@ describe('parseSlashShorthand', () => {
   })
 })
 
-describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverride', () => {
+describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeOverride (renamed from allowRuntimeModelOverride)', () => {
   function makeMultiRegistry(providers: FakeProvider[]): AiModelFactoryRegistry {
     return {
       resolveFirstConfigured: (options) => {
@@ -887,11 +925,11 @@ describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverrid
     expect(resolution.providerId).toBe('openai')
   })
 
-  it('allowRuntimeModelOverride: false skips requestOverride (step 1)', () => {
+  it('allowRuntimeOverride: false skips requestOverride (step 1)', () => {
     const provider = makeProvider()
     const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
     const resolution = factory.resolveModel({
-      allowRuntimeModelOverride: false,
+      allowRuntimeOverride: false,
       requestOverride: { modelId: 'blocked-model' },
       agentDefaultModel: 'agent-wins',
     })
@@ -899,11 +937,11 @@ describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverrid
     expect(resolution.modelId).toBe('agent-wins')
   })
 
-  it('allowRuntimeModelOverride: false skips tenantOverride (step 3)', () => {
+  it('allowRuntimeOverride: false skips tenantOverride (step 3)', () => {
     const provider = makeProvider()
     const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
     const resolution = factory.resolveModel({
-      allowRuntimeModelOverride: false,
+      allowRuntimeOverride: false,
       tenantOverride: { modelId: 'blocked-tenant-model' },
       agentDefaultModel: 'agent-wins',
     })
@@ -911,11 +949,11 @@ describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverrid
     expect(resolution.modelId).toBe('agent-wins')
   })
 
-  it('allowRuntimeModelOverride: false still honors callerOverride (step 2)', () => {
+  it('allowRuntimeOverride: false still honors callerOverride (step 2)', () => {
     const provider = makeProvider()
     const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
     const resolution = factory.resolveModel({
-      allowRuntimeModelOverride: false,
+      allowRuntimeOverride: false,
       callerOverride: 'caller-still-wins',
       tenantOverride: { modelId: 'blocked' },
     })
@@ -923,7 +961,7 @@ describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverrid
     expect(resolution.modelId).toBe('caller-still-wins')
   })
 
-  it('allowRuntimeModelOverride: true (default) honors tenantOverride', () => {
+  it('allowRuntimeOverride: true (default) honors tenantOverride', () => {
     const provider = makeProvider()
     const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
     const resolution = factory.resolveModel({
@@ -952,11 +990,11 @@ describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverrid
     expect(resolution.baseURL).toBe('https://tenant.example.com/v1')
   })
 
-  it('allowRuntimeModelOverride: false suppresses requestOverride baseURL', () => {
+  it('allowRuntimeOverride: false suppresses requestOverride baseURL', () => {
     const provider = makeProvider()
     const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
     const resolution = factory.resolveModel({
-      allowRuntimeModelOverride: false,
+      allowRuntimeOverride: false,
       requestOverride: { baseURL: 'https://blocked.example.com/v1' },
     })
     expect(resolution.baseURL).toBeUndefined()
@@ -1126,4 +1164,29 @@ describe('Phase 4a — tenantOverride, requestOverride, allowRuntimeModelOverrid
       expect(resolution.allowlistFallback).toBeDefined()
     })
   })
+
+  it('deprecated allowRuntimeModelOverride alias: false skips requestOverride (backward compat)', () => {
+    const provider = makeProvider()
+    const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
+    const resolution = factory.resolveModel({
+      allowRuntimeModelOverride: false,
+      requestOverride: { modelId: 'blocked-model' },
+      agentDefaultModel: 'agent-wins',
+    })
+    expect(resolution.source).toBe('agent_default')
+    expect(resolution.modelId).toBe('agent-wins')
+  })
+
+  it('allowRuntimeOverride wins over deprecated allowRuntimeModelOverride when both present', () => {
+    const provider = makeProvider()
+    const factory = createModelFactory({} as AwilixContainer, makeFactoryDeps(provider))
+    const resolution = factory.resolveModel({
+      allowRuntimeOverride: true,
+      allowRuntimeModelOverride: false,
+      requestOverride: { modelId: 'override-model' },
+      agentDefaultModel: 'agent-default',
+    })
+    expect(resolution.source).toBe('request_override')
+    expect(resolution.modelId).toBe('override-model')
+  })
 })

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

@@ -18,6 +18,15 @@ export type AgentPolicyDenyCode =
   | 'mutation_blocked_by_policy'
   | 'execution_mode_not_supported'
   | 'attachment_type_not_accepted'
+  // Loop policy codes — Phase 0 of spec 2026-04-28-ai-agents-agentic-loop-controls
+  /** Object-mode rejects loop primitives that the SDK ignores for generateObject. */
+  | 'loop_unsupported_in_object_mode'
+  /** User prepareStep returned a tools map with a raw (unwrapped) mutation handler. */
+  | 'loop_violates_mutation_policy'
+  /** loop.activeTools contained names outside agent.allowedTools (thrown for caller-supplied overrides; warning-only for agent-declared). */
+  | 'loop_active_tools_outside_allowlist'
+  /** agent.loop.allowRuntimeOverride is false and a per-call loop override was supplied. */
+  | 'loop_runtime_override_disabled'
 
 export type AgentPolicyDecision =
   | { ok: true; agent: AiAgentDefinition; tool?: AiToolDefinition }