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

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

@@ -0,0 +1,263 @@
+/**
+ * Step 5.16 — Phase 3 WS-D integration tests for the execution-budget
+ * (`maxSteps`) contract on `runAiAgentText` and `runAiAgentObject`.
+ *
+ * Pins the Step 3.4 / 3.5 `stopWhen: stepCountIs(agent.maxSteps)` plumbing:
+ *
+ *   - agent declares `maxSteps: n (n > 0)` → `stopWhen: stepCountIs(n)`
+ *   - agent omits `maxSteps` (or sets 0) → no `stopWhen` on the SDK args
+ *   - `runAiAgentObject` preserves the exact same precedence — object-mode
+ *     must not silently diverge from chat-mode (spec §1.5).
+ *
+ * The Step description also enumerates a "caller-passed stopWhen overrides
+ * the agent's maxSteps" scenario. The current `RunAiAgentTextInput` /
+ * `RunAiAgentObjectInput` shapes do NOT expose a per-call override surface
+ * (only `modelOverride`). Introducing a public `maxStepsOverride` field
+ * would require production code changes, and Step 5.16 is strictly
+ * additive-test-only ("No new production code in this Step"). That
+ * scenario is therefore documented as a deliberate gap in step-5.16-checks.md
+ * rather than forced through a test-only seam that would misrepresent the
+ * public contract.
+ *
+ * The AI SDK module is stubbed at the Jest module boundary. `streamText`,
+ * `generateObject`, `streamObject`, `convertToModelMessages`, and
+ * `stepCountIs` are all replaced by jest.fn()s so the test never hits a
+ * real provider. The provider registry is stubbed the same way as in
+ * `agent-runtime.test.ts`.
+ */
+
+const streamTextMock = jest.fn()
+const generateObjectMock = jest.fn()
+const streamObjectMock = jest.fn()
+const convertToModelMessagesMock = jest.fn((messages: unknown) => messages)
+const stepCountIsMock = jest.fn(
+  (count: number) => ({ __stopWhen: 'stepCount', count }) as const,
+)
+
+jest.mock('ai', () => {
+  const actual = jest.requireActual('ai')
+  return {
+    ...actual,
+    streamText: (...args: unknown[]) => streamTextMock(...args),
+    generateObject: (...args: unknown[]) => generateObjectMock(...args),
+    streamObject: (...args: unknown[]) => streamObjectMock(...args),
+    stepCountIs: (...args: unknown[]) => stepCountIsMock(...(args as [number])),
+    convertToModelMessages: (...args: unknown[]) => convertToModelMessagesMock(...args),
+  }
+})
+
+const createModelMock = jest.fn((options: { modelId: string; apiKey: string }) => ({
+  id: options.modelId,
+  apiKey: options.apiKey,
+}))
+const resolveApiKeyMock = jest.fn(() => 'test-api-key')
+
+jest.mock('@open-mercato/shared/lib/ai/llm-provider-registry', () => ({
+  llmProviderRegistry: {
+    resolveFirstConfigured: () => ({
+      id: 'test-provider',
+      defaultModel: 'provider-default-model',
+      resolveApiKey: resolveApiKeyMock,
+      createModel: createModelMock,
+    }),
+  },
+}))
+
+import { z } from 'zod'
+import type { AiAgentDefinition } from '../ai-agent-definition'
+import {
+  resetAgentRegistryForTests,
+  seedAgentRegistryForTests,
+} from '../agent-registry'
+import { toolRegistry } from '../tool-registry'
+import { runAiAgentObject, runAiAgentText } from '../agent-runtime'
+
+function makeAgent(
+  overrides: Partial<AiAgentDefinition> & Pick<AiAgentDefinition, 'id' | 'moduleId'>,
+): AiAgentDefinition {
+  return {
+    label: `${overrides.id} label`,
+    description: `${overrides.id} description`,
+    systemPrompt: 'System prompt base.',
+    allowedTools: [],
+    ...overrides,
+  }
+}
+
+const baseAuth = {
+  tenantId: 'tenant-1',
+  organizationId: 'org-1',
+  userId: 'user-1',
+  features: ['*'],
+  isSuperAdmin: true,
+}
+
+const baseMessages = [
+  { role: 'user' as const, id: 'm1', parts: [{ type: 'text' as const, text: 'hi' }] },
+]
+
+function fakeStreamResult(): {
+  toTextStreamResponse: jest.Mock
+  toUIMessageStreamResponse: jest.Mock
+} {
+  return {
+    toTextStreamResponse: jest.fn(
+      () =>
+        new Response('streamed', {
+          status: 200,
+          headers: { 'Content-Type': 'text/event-stream' },
+        }),
+    ),
+    toUIMessageStreamResponse: jest.fn(
+      () =>
+        new Response('streamed', {
+          status: 200,
+          headers: { 'Content-Type': 'text/event-stream' },
+        }),
+    ),
+  }
+}
+
+describe('Step 5.16 — runAiAgentText maxSteps budget (integration)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+    streamTextMock.mockImplementation(() => fakeStreamResult())
+  })
+  afterAll(() => {
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+  })
+
+  it('passes stopWhen: stepCountIs(agent.maxSteps) when maxSteps is a positive integer', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.account_assistant',
+        moduleId: 'customers',
+        maxSteps: 3,
+      }),
+    ])
+    await runAiAgentText({
+      agentId: 'customers.account_assistant',
+      messages: baseMessages as never,
+      authContext: baseAuth,
+    })
+    expect(stepCountIsMock).toHaveBeenCalledWith(3)
+    const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
+    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 3 })
+  })
+
+  it('applies default stopWhen: stepCountIs(10) when maxSteps is undefined (tool-call-enabling default)', async () => {
+    // PR #1593 (commit 5873fcee5) added a default of 10 when maxSteps is
+    // undefined — without stopWhen the AI SDK runs a single model call and
+    // never executes tool calls, which makes every tool-using query return
+    // an empty stream. The test pins that behavior.
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.account_assistant',
+        moduleId: 'customers',
+        // Explicit undefined — the default case for most agents.
+      }),
+    ])
+    await runAiAgentText({
+      agentId: 'customers.account_assistant',
+      messages: baseMessages as never,
+      authContext: baseAuth,
+    })
+    expect(stepCountIsMock).toHaveBeenCalledWith(10)
+    const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
+    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 10 })
+  })
+
+  it('falls back to default stopWhen: stepCountIs(10) when maxSteps is 0', async () => {
+    // Spec §1.4: maxSteps must be a positive integer; 0 is treated the same
+    // as undefined. Post-#1593 that means the default-10 guard kicks in so
+    // tool calls still work, instead of short-circuiting to a single model
+    // call.
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'customers.account_assistant',
+        moduleId: 'customers',
+        maxSteps: 0,
+      }),
+    ])
+    await runAiAgentText({
+      agentId: 'customers.account_assistant',
+      messages: baseMessages as never,
+      authContext: baseAuth,
+    })
+    expect(stepCountIsMock).toHaveBeenCalledWith(10)
+    const callArg = streamTextMock.mock.calls[0][0] as { stopWhen: unknown }
+    expect(callArg.stopWhen).toEqual({ __stopWhen: 'stepCount', count: 10 })
+  })
+})
+
+describe('Step 5.16 — runAiAgentObject maxSteps budget parity (integration)', () => {
+  const schema = z.object({ summary: z.string() })
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+    generateObjectMock.mockImplementation(async () => ({
+      object: { summary: 'stub' },
+      finishReason: 'stop',
+      usage: { inputTokens: 1, outputTokens: 1 },
+    }))
+  })
+  afterAll(() => {
+    resetAgentRegistryForTests()
+    toolRegistry.clear()
+  })
+
+  it('preserves agent.maxSteps → stopWhen on generateObject (object-mode parity)', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.merchandising_assistant',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        output: {
+          schemaName: 'MerchandisingProposal',
+          schema,
+          mode: 'generate',
+        } as never,
+        maxSteps: 4,
+      }),
+    ])
+    await runAiAgentObject({
+      agentId: 'catalog.merchandising_assistant',
+      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 })
+  })
+
+  it('omits stopWhen on generateObject when the agent declares no maxSteps', async () => {
+    seedAgentRegistryForTests([
+      makeAgent({
+        id: 'catalog.merchandising_assistant',
+        moduleId: 'catalog',
+        executionMode: 'object',
+        output: {
+          schemaName: 'MerchandisingProposal',
+          schema,
+          mode: 'generate',
+        } as never,
+      }),
+    ])
+    await runAiAgentObject({
+      agentId: 'catalog.merchandising_assistant',
+      input: 'draft title variants',
+      authContext: baseAuth,
+    })
+    expect(stepCountIsMock).not.toHaveBeenCalled()
+    const callArg = generateObjectMock.mock.calls[0][0] as { stopWhen?: unknown }
+    expect('stopWhen' in callArg).toBe(false)
+  })
+})

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

@@ -0,0 +1,183 @@
+/**
+ * Step 5.16 — Phase 3 WS-D integration tests for the shared AI model
+ * factory (Step 5.1).
+ *
+ * Pins the full four-layer resolution chain against a provider-registry
+ * shim that mirrors the real `LlmProviderRegistry.resolveFirstConfigured`
+ * contract. The factory is stateless and re-reads env + registry on every
+ * `resolveModel` call, so we drive each scenario from the dep-injected
+ * `env` + `registry` fields (the Step 5.1 test seam) rather than mutating
+ * `process.env` on the shared test run. This keeps the test hermetic and
+ * the env cleanup trivial.
+ *
+ * Scenarios (per Step 5.16 spec):
+ *   - callerOverride non-empty  → wins over env + agent default + provider
+ *   - env `<MODULE>_AI_MODEL`   → wins over agent default + provider default
+ *   - agentDefaultModel         → wins over provider default
+ *   - provider default          → chosen last
+ *   - no provider registered    → throws `AiModelFactoryError`
+ *                                 `code: 'no_provider_configured'`
+ *   - moduleId: undefined       → env-override lookup skipped (regression)
+ *   - empty-string callerOverride → falls through to env, not override
+ *
+ * Fixture rule: every test constructs its own provider + env shim, so no
+ * ordering coupling exists between scenarios.
+ */
+import type { AwilixContainer } from 'awilix'
+import {
+  AiModelFactoryError,
+  createModelFactory,
+  type CreateModelFactoryDependencies,
+} from '../model-factory'
+
+type FakeProvider = {
+  id: string
+  defaultModel: string
+  resolveApiKey: () => string | null
+  createModel: (options: { modelId: string; apiKey: string }) => unknown
+}
+
+function makeProvider(overrides: Partial<FakeProvider> = {}): FakeProvider {
+  return {
+    id: overrides.id ?? 'test-provider',
+    defaultModel: overrides.defaultModel ?? 'provider-default-model',
+    resolveApiKey: overrides.resolveApiKey ?? (() => 'test-api-key'),
+    createModel:
+      overrides.createModel ??
+      ((options: { modelId: string; apiKey: string }) => ({
+        kind: 'fake-model',
+        modelId: options.modelId,
+        apiKey: options.apiKey,
+      })),
+  }
+}
+
+function makeDeps(
+  provider: FakeProvider | null,
+  env: Record<string, string | undefined> = {},
+): CreateModelFactoryDependencies {
+  return {
+    registry: {
+      resolveFirstConfigured: () =>
+        provider as unknown as ReturnType<
+          NonNullable<CreateModelFactoryDependencies['registry']>['resolveFirstConfigured']
+        >,
+    },
+    env,
+  }
+}
+
+const fakeContainer = {} as unknown as AwilixContainer
+
+describe('Step 5.16 — model factory fallback chain (integration)', () => {
+  it('callerOverride wins over env + agentDefaultModel + provider default', () => {
+    const provider = makeProvider({ defaultModel: 'provider-default' })
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned' }
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned',
+      callerOverride: 'caller-wins',
+    })
+    expect(resolution.source).toBe('caller_override')
+    expect(resolution.modelId).toBe('caller-wins')
+    // Verify the model plumbing received the resolved id (not a later layer).
+    expect(resolution.model).toMatchObject({
+      kind: 'fake-model',
+      modelId: 'caller-wins',
+      apiKey: 'test-api-key',
+    })
+  })
+
+  it('env <MODULE>_AI_MODEL wins over agentDefaultModel + provider default when moduleId is set', () => {
+    const provider = makeProvider({ defaultModel: 'provider-default' })
+    const env = { CATALOG_AI_MODEL: 'catalog-env-model' }
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'catalog',
+      agentDefaultModel: 'agent-pinned',
+    })
+    expect(resolution.source).toBe('module_env')
+    expect(resolution.modelId).toBe('catalog-env-model')
+  })
+
+  it('agentDefaultModel wins over provider default when callerOverride + env are absent', () => {
+    const provider = makeProvider({ defaultModel: 'provider-default' })
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, {}))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned',
+    })
+    expect(resolution.source).toBe('agent_default')
+    expect(resolution.modelId).toBe('agent-pinned')
+  })
+
+  it('provider default is chosen last when no other source applies', () => {
+    const provider = makeProvider({ defaultModel: 'provider-last-resort' })
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, {}))
+    const resolution = factory.resolveModel({})
+    expect(resolution.source).toBe('provider_default')
+    expect(resolution.modelId).toBe('provider-last-resort')
+  })
+
+  it('throws AiModelFactoryError with code "no_provider_configured" when no provider is registered', () => {
+    const factory = createModelFactory(fakeContainer, makeDeps(null))
+    expect(() => factory.resolveModel({})).toThrow(AiModelFactoryError)
+    try {
+      factory.resolveModel({})
+      fail('expected AiModelFactoryError')
+    } catch (err) {
+      expect(err).toBeInstanceOf(AiModelFactoryError)
+      const typed = err as AiModelFactoryError
+      expect(typed.code).toBe('no_provider_configured')
+      expect(typed.message).toMatch(/No LLM provider is configured/i)
+    }
+  })
+
+  it('moduleId: undefined skips the env-override lookup (regression)', () => {
+    // Even if a `<MODULE>_AI_MODEL` env var exists in the environment, the
+    // factory does NOT construct a module-scoped env var name when moduleId
+    // is undefined — it falls straight through to agentDefaultModel /
+    // provider default. This guards against a past bug where `String(undefined)`
+    // yielded the literal env name `"UNDEFINED_AI_MODEL"`.
+    const provider = makeProvider({ defaultModel: 'provider-default' })
+    const env = {
+      INBOX_OPS_AI_MODEL: 'should-be-ignored',
+      UNDEFINED_AI_MODEL: 'also-ignored',
+    }
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, env))
+    const resolution = factory.resolveModel({
+      agentDefaultModel: 'agent-pinned',
+    })
+    expect(resolution.source).toBe('agent_default')
+    expect(resolution.modelId).toBe('agent-pinned')
+  })
+
+  it('empty-string callerOverride falls through to env, not treated as override', () => {
+    const provider = makeProvider({ defaultModel: 'provider-default' })
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned' }
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned',
+      callerOverride: '',
+    })
+    expect(resolution.source).toBe('module_env')
+    expect(resolution.modelId).toBe('env-pinned')
+  })
+
+  it('whitespace-only callerOverride is treated the same as empty (falls through)', () => {
+    // Defense-in-depth: a caller passing `"   "` (e.g. from a UI text input)
+    // should not bypass lower-priority layers.
+    const provider = makeProvider({ defaultModel: 'provider-default' })
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned' }
+    const factory = createModelFactory(fakeContainer, makeDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned',
+      callerOverride: '   ',
+    })
+    expect(resolution.source).toBe('module_env')
+    expect(resolution.modelId).toBe('env-pinned')
+  })
+})

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

@@ -0,0 +1,168 @@
+import type { AwilixContainer } from 'awilix'
+import {
+  AiModelFactoryError,
+  createModelFactory,
+  type AiModelFactoryInput,
+  type CreateModelFactoryDependencies,
+} from '../model-factory'
+
+function makeProvider(overrides: Partial<{
+  id: string
+  defaultModel: string
+  resolveApiKey: () => string | null
+  createModel: (options: { modelId: string; apiKey: string }) => unknown
+}> = {}) {
+  const createModel =
+    overrides.createModel ??
+    ((options: { modelId: string; apiKey: string }) => ({
+      kind: 'fake-model',
+      modelId: options.modelId,
+      apiKey: options.apiKey,
+    }))
+  return {
+    id: overrides.id ?? 'test-provider',
+    defaultModel: overrides.defaultModel ?? 'provider-default-model',
+    resolveApiKey: overrides.resolveApiKey ?? (() => 'test-api-key'),
+    createModel,
+  }
+}
+
+function makeFactoryDeps(
+  provider: ReturnType<typeof makeProvider> | null,
+  env: Record<string, string | undefined> = {},
+): CreateModelFactoryDependencies {
+  return {
+    registry: {
+      resolveFirstConfigured: () =>
+        provider as unknown as ReturnType<
+          NonNullable<CreateModelFactoryDependencies['registry']>['resolveFirstConfigured']
+        >,
+    },
+    env,
+  }
+}
+
+const fakeContainer = {} as unknown as AwilixContainer
+
+describe('createModelFactory', () => {
+  it('returns the provider default when no override is supplied', () => {
+    const provider = makeProvider()
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider))
+    const resolution = factory.resolveModel({})
+    expect(resolution.source).toBe('provider_default')
+    expect(resolution.modelId).toBe('provider-default-model')
+    expect(resolution.providerId).toBe('test-provider')
+    expect(resolution.model).toMatchObject({
+      kind: 'fake-model',
+      modelId: 'provider-default-model',
+      apiKey: 'test-api-key',
+    })
+  })
+
+  it('prefers agentDefaultModel over provider default', () => {
+    const provider = makeProvider()
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider))
+    const resolution = factory.resolveModel({ agentDefaultModel: 'agent-pinned-model' })
+    expect(resolution.source).toBe('agent_default')
+    expect(resolution.modelId).toBe('agent-pinned-model')
+  })
+
+  it('prefers <MODULE>_AI_MODEL env override over agent default', () => {
+    const provider = makeProvider()
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned-model' }
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned-model',
+    })
+    expect(resolution.source).toBe('module_env')
+    expect(resolution.modelId).toBe('env-pinned-model')
+  })
+
+  it('uppercases moduleId when deriving the env var name', () => {
+    const provider = makeProvider()
+    const env = { INBOX_OPS_AI_MODEL: 'from-env' }
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider, env))
+    const resolution = factory.resolveModel({ moduleId: 'inbox_ops' })
+    expect(resolution.modelId).toBe('from-env')
+  })
+
+  it('prefers non-empty callerOverride over every other source', () => {
+    const provider = makeProvider()
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned-model' }
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned-model',
+      callerOverride: 'caller-wins',
+    })
+    expect(resolution.source).toBe('caller_override')
+    expect(resolution.modelId).toBe('caller-wins')
+  })
+
+  it('treats empty callerOverride as "no override" and falls through to env', () => {
+    const provider = makeProvider()
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned-model' }
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider, env))
+    const resolution = factory.resolveModel({
+      moduleId: 'inbox_ops',
+      agentDefaultModel: 'agent-pinned-model',
+      callerOverride: '   ',
+    })
+    expect(resolution.source).toBe('module_env')
+    expect(resolution.modelId).toBe('env-pinned-model')
+  })
+
+  it('skips env-override lookup when moduleId is undefined (does not crash)', () => {
+    const provider = makeProvider()
+    // Even if an `_AI_MODEL` var is present, an absent moduleId means no
+    // module-scoped env var name can be constructed, so the lookup is skipped.
+    const env = { INBOX_OPS_AI_MODEL: 'env-pinned-model' }
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider, env))
+    const resolution = factory.resolveModel({
+      agentDefaultModel: 'agent-pinned-model',
+    } satisfies AiModelFactoryInput)
+    expect(resolution.source).toBe('agent_default')
+    expect(resolution.modelId).toBe('agent-pinned-model')
+  })
+
+  it('throws AiModelFactoryError with code "no_provider_configured" when no provider is configured', () => {
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(null))
+    try {
+      factory.resolveModel({})
+      fail('expected AiModelFactoryError')
+    } catch (err) {
+      expect(err).toBeInstanceOf(AiModelFactoryError)
+      const typed = err as AiModelFactoryError
+      expect(typed.code).toBe('no_provider_configured')
+      expect(typed.message).toMatch(/No LLM provider is configured/i)
+    }
+  })
+
+  it('throws AiModelFactoryError with code "api_key_missing" when the provider returns no key', () => {
+    const provider = makeProvider({ resolveApiKey: () => null })
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider))
+    try {
+      factory.resolveModel({})
+      fail('expected AiModelFactoryError')
+    } catch (err) {
+      expect(err).toBeInstanceOf(AiModelFactoryError)
+      expect((err as AiModelFactoryError).code).toBe('api_key_missing')
+    }
+  })
+
+  it('passes the resolved modelId and apiKey through to provider.createModel', () => {
+    const createModel = jest.fn((options: { modelId: string; apiKey: string }) => ({
+      spy: true,
+      ...options,
+    }))
+    const provider = makeProvider({ createModel })
+    const env = { CATALOG_AI_MODEL: 'catalog-env-model' }
+    const factory = createModelFactory(fakeContainer, makeFactoryDeps(provider, env))
+    factory.resolveModel({ moduleId: 'catalog' })
+    expect(createModel).toHaveBeenCalledWith({
+      modelId: 'catalog-env-model',
+      apiKey: 'test-api-key',
+    })
+  })
+})