@open-mercato/ai-assistant 0.6.1-develop.3246.1.dbef9d7392 → 0.6.1-develop.3256.1.fe3dec2464

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

@@ -1,3 +1,4 @@
+import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
 import type { AiAgentDefinition, AiAgentExtension, AiAgentSuggestion } from './ai-agent-definition'
 import {
   applyAgentOverrideMap,
@@ -104,6 +105,24 @@ function applySuggestionPatch(
   return out
 }
 
+function validateAndNormalizeAgent(candidate: AiAgentDefinition): AiAgentDefinition {
+  const rawProvider = candidate.defaultProvider
+  if (typeof rawProvider !== 'string' || rawProvider.trim().length === 0) {
+    return candidate
+  }
+  const providerHint = rawProvider.trim()
+  const registered = llmProviderRegistry.get(providerHint)
+  if (!registered) {
+    console.warn(
+      `[AI Agents] Agent "${candidate.id}" declares defaultProvider "${providerHint}" which is not registered in llmProviderRegistry. ` +
+        `The agent will be registered with defaultProvider: undefined so the resolution chain still works. ` +
+        `Built-in provider ids: anthropic, google, openai, deepinfra, groq, together, fireworks, azure, litellm, ollama.`,
+    )
+    return { ...candidate, defaultProvider: undefined }
+  }
+  return candidate
+}
+
 function populateFromAgents(agents: unknown[]): void {
   for (const candidate of agents) {
     if (!isAiAgentDefinition(candidate)) {
@@ -116,7 +135,7 @@ function populateFromAgents(agents: unknown[]): void {
         `[AI Agents] Duplicate agent id "${candidate.id}" — already registered by module "${existing.moduleId}", conflicts with module "${candidate.moduleId}". Export \`aiAgentOverrides\` from your module's \`ai-agents.ts\` (or set it on the modules.ts entry) to replace an agent across modules.`
       )
     }
-    agentsById.set(candidate.id, candidate)
+    agentsById.set(candidate.id, validateAndNormalizeAgent(candidate))
   }
 }
 

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

@@ -1,3 +1,4 @@
+import { createContainer } from 'awilix'
 import type { AwilixContainer } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { LanguageModel, UIMessage } from 'ai'
@@ -9,8 +10,7 @@ import {
   streamText,
 } from 'ai'
 import type { ZodTypeAny } from 'zod'
-import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
-import { resolveAiProviderIdFromEnv } from '@open-mercato/shared/lib/ai/opencode-provider'
+import { createModelFactory } from './model-factory'
 import type {
   AiAgentDefinition,
   AiAgentPageContextInput,
@@ -30,6 +30,9 @@ import {
 } from './attachment-parts'
 import { AiAgentPromptOverrideRepository } from '../data/repositories/AiAgentPromptOverrideRepository'
 import { AiAgentMutationPolicyOverrideRepository } from '../data/repositories/AiAgentMutationPolicyOverrideRepository'
+import { AiAgentRuntimeOverrideRepository } from '../data/repositories/AiAgentRuntimeOverrideRepository'
+import { AiTenantModelAllowlistRepository } from '../data/repositories/AiTenantModelAllowlistRepository'
+import type { TenantAllowlistSnapshot } from './model-allowlist'
 import { composeSystemPromptWithOverride } from './prompt-override-merge'
 import { isKnownMutationPolicy } from './agent-policy'
 import type { AiAgentMutationPolicy } from './ai-agent-definition'
@@ -65,6 +68,36 @@ export interface RunAiAgentTextInput {
    * `agent.defaultModel` without inventing a new indirection layer.
    */
   modelOverride?: string
+  /**
+   * Optional request-time provider override. When non-empty, wins for the
+   * provider axis at the same priority as `modelOverride` for the model axis.
+   * A value that does not match any registered provider id is silently ignored.
+   *
+   * Phase 1 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  providerOverride?: string
+  /**
+   * Optional per-call base URL override. Wins over every other source in the
+   * baseURL resolution chain. Intended for programmatic callers only — the
+   * HTTP query-param baseUrl and the AI_RUNTIME_BASEURL_ALLOWLIST arrive in
+   * Phase 4a and MUST NOT be exposed here.
+   *
+   * Phase 2 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  baseUrlOverride?: string
+  /**
+   * Per-request HTTP dispatcher override (query params `?provider=`, `?model=`,
+   * `?baseUrl=`). Validated by the dispatcher route before being forwarded
+   * here. Wins over tenantOverride and all lower-priority sources when
+   * `agent.allowRuntimeModelOverride !== false`.
+   *
+   * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  requestOverride?: {
+    providerId?: string | null
+    modelId?: string | null
+    baseURL?: string | null
+  }
   /**
    * Optional DI container used by `resolvePageContext` callbacks. When omitted
    * and the agent declares a `resolvePageContext`, hydration is skipped with a
@@ -90,38 +123,61 @@ interface ResolvedAgentModel {
 function resolveAgentModel(
   agent: AiAgentDefinition,
   modelOverride: string | undefined,
+  providerOverride: string | undefined,
+  container: AwilixContainer | undefined,
+  baseUrlOverride?: string,
+  tenantOverride?: { providerId?: string | null; modelId?: string | null; baseURL?: string | null } | null,
+  requestOverride?: { providerId?: string | null; modelId?: string | null; baseURL?: string | null } | null,
+  tenantAllowlist?: TenantAllowlistSnapshot | null,
 ): ResolvedAgentModel {
-  const env = process.env
-  // Honor the operator-selected provider (new OM_AI_PROVIDER, with legacy
-  // OPENCODE_PROVIDER as the BC fallback) so deployments that have stale
-  // keys for other providers still hit the intended target.
-  const omProvider = (env.OM_AI_PROVIDER ?? '').trim()
-  const opencodeProvider = (env.OPENCODE_PROVIDER ?? '').trim()
-  const providerHint = omProvider.length > 0 || opencodeProvider.length > 0
-    ? [resolveAiProviderIdFromEnv(env)]
-    : undefined
-  const provider = llmProviderRegistry.resolveFirstConfigured(
-    providerHint ? { order: providerHint } : undefined,
-  )
-  if (!provider) {
-    throw new Error(
-      'No LLM provider is configured. Set OM_AI_PROVIDER (or the legacy OPENCODE_PROVIDER) plus a matching API key such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY, then restart the app. See https://docs.openmercato.com/framework/ai-assistant/overview.',
-    )
+  const effectiveContainer = container ?? createContainer()
+  const allowRuntimeModelOverride = agent.allowRuntimeModelOverride !== false
+  const resolution = createModelFactory(effectiveContainer).resolveModel({
+    moduleId: agent.moduleId,
+    agentDefaultModel: agent.defaultModel,
+    agentDefaultProvider: agent.defaultProvider,
+    agentDefaultBaseUrl: agent.defaultBaseUrl,
+    callerOverride: modelOverride,
+    providerOverride,
+    baseUrlOverride,
+    allowRuntimeModelOverride,
+    tenantOverride: tenantOverride ?? undefined,
+    requestOverride: requestOverride ?? undefined,
+    tenantAllowlist: tenantAllowlist ?? null,
+  })
+  return {
+    model: resolution.model as LanguageModel,
+    modelId: resolution.modelId,
+    providerId: resolution.providerId,
   }
-  const apiKey = provider.resolveApiKey()
-  if (!apiKey) {
-    throw new Error(
-      `LLM provider "${provider.id}" is advertised as configured but resolveApiKey() returned empty.`,
+}
+
+async function resolveTenantAllowlistSnapshot(
+  container: AwilixContainer | undefined,
+  tenantId: string | null,
+  organizationId: string | null,
+): Promise<TenantAllowlistSnapshot | null> {
+  if (!tenantId || !container) return null
+  let em: EntityManager | null = null
+  try {
+    em = container.resolve<EntityManager>('em')
+  } catch {
+    em = null
+  }
+  if (!em) return null
+  try {
+    const repo = new AiTenantModelAllowlistRepository(em)
+    return await repo.getSnapshot({
+      tenantId,
+      organizationId: organizationId ?? null,
+    })
+  } catch (error) {
+    console.warn(
+      '[AI Agents] Tenant allowlist lookup failed; falling back to env-only enforcement.',
+      error,
     )
+    return null
   }
-  const globalEnvModel = ((env.OM_AI_MODEL ?? env.OPENCODE_MODEL) ?? '').trim()
-  const modelId =
-    (modelOverride && modelOverride.trim().length > 0 ? modelOverride : undefined) ??
-    (globalEnvModel.length > 0 ? globalEnvModel : undefined) ??
-    agent.defaultModel ??
-    provider.defaultModel
-  const model = provider.createModel({ modelId, apiKey }) as LanguageModel
-  return { model, modelId, providerId: provider.id }
 }
 
 /**
@@ -264,6 +320,53 @@ async function resolveMutationPolicyOverride(
   }
 }
 
+/**
+ * Looks up the per-tenant AI runtime override (provider / model / baseURL) for
+ * the given agent (Phase 4a of spec
+ * `2026-04-27-ai-agents-provider-model-baseurl-overrides`).
+ *
+ * Mirrors the fail-open contract of {@link resolveMutationPolicyOverride}: any
+ * error — missing container, missing `em`, repository throw, missing migration
+ * — is logged at `warn` level and returns null so the model factory falls
+ * through to lower-priority sources. A chat turn MUST never fail on override
+ * lookup.
+ */
+async function resolveRuntimeModelOverride(
+  agentId: string,
+  container: AwilixContainer | undefined,
+  tenantId: string | null,
+  organizationId: string | null,
+): Promise<{ providerId?: string | null; modelId?: string | null; baseURL?: string | null } | null> {
+  if (!tenantId || !container) return null
+  let em: EntityManager | null = null
+  try {
+    em = container.resolve<EntityManager>('em')
+  } catch {
+    em = null
+  }
+  if (!em) return null
+  try {
+    const repo = new AiAgentRuntimeOverrideRepository(em)
+    const row = await repo.getDefault({
+      tenantId,
+      organizationId: organizationId ?? null,
+      agentId,
+    })
+    if (!row) return null
+    return {
+      providerId: row.providerId ?? null,
+      modelId: row.modelId ?? null,
+      baseURL: row.baseUrl ?? null,
+    }
+  } catch (error) {
+    console.warn(
+      `[AI Agents] Runtime model override lookup failed for agent "${agentId}"; falling back to lower-priority sources.`,
+      error,
+    )
+    return null
+  }
+}
+
 /**
  * Normalizes simple `{ role, content }` chat messages into the AI SDK
  * `UIMessage` shape that `convertToModelMessages` requires. When the
@@ -481,12 +584,25 @@ function appendRuntimeMutationPolicy(
  * invariant #7 still holds.
  */
 export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Response> {
-  const mutationPolicyOverride = await resolveMutationPolicyOverride(
-    input.agentId,
-    input.container,
-    input.authContext.tenantId,
-    input.authContext.organizationId,
-  )
+  const [mutationPolicyOverride, tenantRuntimeOverride, tenantAllowlistSnapshot] = await Promise.all([
+    resolveMutationPolicyOverride(
+      input.agentId,
+      input.container,
+      input.authContext.tenantId,
+      input.authContext.organizationId,
+    ),
+    resolveRuntimeModelOverride(
+      input.agentId,
+      input.container,
+      input.authContext.tenantId,
+      input.authContext.organizationId,
+    ),
+    resolveTenantAllowlistSnapshot(
+      input.container,
+      input.authContext.tenantId,
+      input.authContext.organizationId,
+    ),
+  ])
   const { agent, tools } = await resolveAiAgentTools({
     agentId: input.agentId,
     authContext: input.authContext,
@@ -517,7 +633,16 @@ export async function runAiAgentText(input: RunAiAgentTextInput): Promise<Respon
     mutationPolicyOverride,
   )
 
-  const { model } = resolveAgentModel(agent, input.modelOverride)
+  const { model } = resolveAgentModel(
+    agent,
+    input.modelOverride,
+    input.providerOverride,
+    input.container,
+    input.baseUrlOverride,
+    tenantRuntimeOverride,
+    input.requestOverride,
+    tenantAllowlistSnapshot,
+  )
   const normalizedMessages = ensureUiMessageShape(input.messages)
   const hydratedMessages = attachAttachmentsToMessages(normalizedMessages, resolvedAttachments)
   const modelMessages = await convertToModelMessages(hydratedMessages)
@@ -580,6 +705,35 @@ export interface RunAiAgentObjectInput<TSchema = ZodTypeAny> {
    */
   authContext: AiChatRequestContext
   modelOverride?: string
+  /**
+   * Optional request-time provider override. When non-empty, wins for the
+   * provider axis at the same priority as `modelOverride` for the model axis.
+   *
+   * Phase 1 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  providerOverride?: string
+  /**
+   * Optional per-call base URL override. Wins over every other source in the
+   * baseURL resolution chain. Intended for programmatic callers only — the
+   * HTTP query-param baseUrl and the AI_RUNTIME_BASEURL_ALLOWLIST arrive in
+   * Phase 4a and MUST NOT be exposed here.
+   *
+   * Phase 2 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  baseUrlOverride?: string
+  /**
+   * Per-request HTTP dispatcher override (query params `?provider=`, `?model=`,
+   * `?baseUrl=`). Validated by the dispatcher route before being forwarded
+   * here. Wins over tenantOverride and all lower-priority sources when
+   * `agent.allowRuntimeModelOverride !== false`.
+   *
+   * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  requestOverride?: {
+    providerId?: string | null
+    modelId?: string | null
+    baseURL?: string | null
+  }
   output?: RunAiAgentObjectOutputOverride<TSchema>
   debug?: boolean
   container?: AwilixContainer
@@ -662,12 +816,25 @@ function resolveStructuredOutput<TSchema>(
 export async function runAiAgentObject<TSchema = unknown>(
   input: RunAiAgentObjectInput<TSchema>,
 ): Promise<RunAiAgentObjectResult<TSchema>> {
-  const mutationPolicyOverride = await resolveMutationPolicyOverride(
-    input.agentId,
-    input.container,
-    input.authContext.tenantId,
-    input.authContext.organizationId,
-  )
+  const [mutationPolicyOverride, tenantRuntimeOverride, tenantAllowlistSnapshot] = await Promise.all([
+    resolveMutationPolicyOverride(
+      input.agentId,
+      input.container,
+      input.authContext.tenantId,
+      input.authContext.organizationId,
+    ),
+    resolveRuntimeModelOverride(
+      input.agentId,
+      input.container,
+      input.authContext.tenantId,
+      input.authContext.organizationId,
+    ),
+    resolveTenantAllowlistSnapshot(
+      input.container,
+      input.authContext.tenantId,
+      input.authContext.organizationId,
+    ),
+  ])
   const { agent, tools } = await resolveAiAgentTools({
     agentId: input.agentId,
     authContext: input.authContext,
@@ -700,7 +867,16 @@ export async function runAiAgentObject<TSchema = unknown>(
     mutationPolicyOverride,
   )
 
-  const { model } = resolveAgentModel(agent, input.modelOverride)
+  const { model } = resolveAgentModel(
+    agent,
+    input.modelOverride,
+    input.providerOverride,
+    input.container,
+    input.baseUrlOverride,
+    tenantRuntimeOverride,
+    input.requestOverride,
+    tenantAllowlistSnapshot,
+  )
   const normalizedMessages = ensureUiMessageShape(normalizeObjectMessages(input.input))
   const hydratedMessages = attachAttachmentsToMessages(
     normalizedMessages,

package/src/modules/ai_assistant/lib/ai-agent-definition.ts

@@ -46,7 +46,55 @@ export interface AiAgentDefinition {
   allowedTools: string[]
   suggestions?: AiAgentSuggestion[]
   executionMode?: AiAgentExecutionMode
+  /**
+   * Optional provider id this agent prefers (e.g. `'openai'`, `'anthropic'`).
+   * Must match a registered `LlmProvider.id`. When the named provider is
+   * registered but unconfigured at runtime the factory falls through
+   * transparently to the next configured provider.
+   *
+   * Phase 1 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  defaultProvider?: string
+  /**
+   * Optional model id fed through `createModelFactory` for this agent.
+   * Accepts either a plain model id (`claude-haiku-4-5-20251001`) or a
+   * slash-qualified `<provider>/<model>` shorthand (e.g. `openai/gpt-5-mini`).
+   * When the slash form is used the prefix must match a registered provider id;
+   * the registry-membership guard prevents mis-splitting model ids that already
+   * contain slashes (DeepInfra: `meta-llama/Llama-3.3-70B-Instruct-Turbo`).
+   *
+   * A higher-priority provider source still wins over the slash hint, but a
+   * lower-priority one cannot overwrite a slash-qualified model (cross-axis
+   * tie-break rule from spec §Phase-1).
+   *
+   * Phase 0 and Phase 1 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
   defaultModel?: string
+  /**
+   * Optional base URL this agent prefers for its chosen provider.
+   * Sits between the `<MODULE>_AI_BASE_URL` env (step 2 of the public 5-step
+   * baseURL hierarchy) and the preset env override (`baseURLEnvKeys`, step 4).
+   * Only honoured by adapters that support baseURL (Anthropic Messages-
+   * protocol relays, all OpenAI-compatible adapters, Google via
+   * @ai-sdk/google ≥3.0). See `packages/ai-assistant/AGENTS.md` →
+   * "baseURL override hierarchy" for the full numbered chain.
+   *
+   * Phase 2 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  defaultBaseUrl?: string
+  /**
+   * When false, per-request HTTP overrides (query params `provider`, `model`,
+   * `baseUrl`) and the per-tenant settings override stored in
+   * `ai_agent_runtime_overrides` are both suppressed. Steps 1 and 3 of the
+   * model-factory resolution chain are skipped for this agent.
+   *
+   * Default is `true` (permissive). Agents that pin a specific model for
+   * correctness reasons (e.g. a structured-output agent whose JSON-mode schema
+   * only works with one provider) should set this to `false`.
+   *
+   * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  allowRuntimeModelOverride?: boolean
   acceptedMediaTypes?: AiAgentAcceptedMediaType[]
   requiredFeatures?: string[]
   uiParts?: string[]

package/src/modules/ai_assistant/lib/baseurl-allowlist.ts

@@ -0,0 +1,64 @@
+/**
+ * `AI_RUNTIME_BASEURL_ALLOWLIST` guard helper.
+ *
+ * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`
+ * (R6 mitigation). An operator who wants to expose the `?baseUrl=` query
+ * parameter over HTTP MUST set this env var to a comma-separated list of
+ * allowed host patterns. When the env var is absent or empty, ANY non-empty
+ * `baseUrl` value received by the dispatcher is rejected with a typed 400
+ * error — ensuring that a misconfigured deployment cannot be tricked into
+ * forwarding API calls to an attacker-controlled endpoint.
+ *
+ * Host patterns use a simple glob: a leading `*` matches any subdomain.
+ * Examples:
+ *   `openrouter.ai`               — exact host
+ *   `*.openrouter.ai`             — any subdomain of openrouter.ai
+ *   `openrouter.ai,api.myproxy.io` — two hosts (comma-separated, no spaces)
+ *
+ * The comparison is case-insensitive and ignores the URL path/query —
+ * only the `hostname` portion of the submitted URL is checked.
+ */
+
+/**
+ * Returns the parsed allowlist from `AI_RUNTIME_BASEURL_ALLOWLIST`.
+ * An empty array means the allowlist is empty (reject all).
+ */
+export function readBaseurlAllowlist(env: Record<string, string | undefined> = process.env): string[] {
+  const raw = env.AI_RUNTIME_BASEURL_ALLOWLIST ?? ''
+  return raw
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter((entry) => entry.length > 0)
+}
+
+/**
+ * Returns true when `baseUrl` is permitted under the current allowlist.
+ *
+ * Rules:
+ *   - An empty `baseUrl` is always allowed (no override requested).
+ *   - When the allowlist is empty, any non-empty `baseUrl` is rejected.
+ *   - A pattern `*.example.com` matches `foo.example.com` but NOT `example.com`.
+ *   - A pattern `example.com` matches only `example.com` (exact, case-insensitive).
+ */
+export function isBaseurlAllowlisted(baseUrl: string, allowlist: string[]): boolean {
+  const trimmed = baseUrl.trim()
+  if (!trimmed) return true
+  if (allowlist.length === 0) return false
+
+  let parsedHostname: string
+  try {
+    parsedHostname = new URL(trimmed).hostname.toLowerCase()
+  } catch {
+    return false
+  }
+
+  for (const pattern of allowlist) {
+    if (pattern.startsWith('*.')) {
+      const suffix = pattern.slice(2)
+      if (parsedHostname.endsWith(`.${suffix}`)) return true
+    } else if (pattern === parsedHostname) {
+      return true
+    }
+  }
+  return false
+}

package/src/modules/ai_assistant/lib/llm-adapters/anthropic.ts

@@ -43,6 +43,13 @@ const DEFAULT_MODELS: readonly LlmModelInfo[] = [
 /**
  * Factory returning a fresh `AnthropicAdapter` instance. The adapter is
  * stateless — caller is free to reuse the returned object.
+ *
+ * `createModel` accepts an optional `baseURL` from {@link LlmCreateModelOptions}
+ * and forwards it to `createAnthropic({ apiKey, baseURL })`.
+ *
+ * baseURL only works for Anthropic Messages-protocol relays (Cloudflare AI
+ * Gateway in Anthropic mode, Helicone proxy). For OpenAI-format gateways,
+ * use the OpenAI / OpenRouter presets.
  */
 export function createAnthropicAdapter(): LlmProvider {
   const envKeys = ['ANTHROPIC_API_KEY', 'OPENCODE_ANTHROPIC_API_KEY'] as const
@@ -84,7 +91,10 @@ export function createAnthropicAdapter(): LlmProvider {
     },
 
     createModel(options: LlmCreateModelOptions): unknown {
-      const anthropic = createAnthropic({ apiKey: options.apiKey })
+      const anthropic = createAnthropic({
+        apiKey: options.apiKey,
+        ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+      })
       return anthropic(options.modelId)
     },
   }

package/src/modules/ai_assistant/lib/llm-adapters/google.ts

@@ -73,7 +73,10 @@ export function createGoogleAdapter(): LlmProvider {
     },
 
     createModel(options: LlmCreateModelOptions): unknown {
-      const google = createGoogleGenerativeAI({ apiKey: options.apiKey })
+      const google = createGoogleGenerativeAI({
+        apiKey: options.apiKey,
+        ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+      })
       return google(options.modelId)
     },
   }