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

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

@@ -127,10 +127,14 @@ function toPolicyAuthContext(ctx: AiChatRequestContext): {
  * `^[a-zA-Z0-9_-]+$`; dots are replaced with double underscores (`__`).
  * Anthropic and Google accept both formats, so this is safe across providers.
  */
-function sanitizeToolNameForModel(name: string): string {
+export function sanitizeToolNameForModel(name: string): string {
   return name.replace(/\./g, '__')
 }
 
+export function desanitizeToolNameForDisplay(name: string): string {
+  return name.replace(/__/g, '.')
+}
+
 function formatToolResult(result: unknown): string {
   if (result === null || result === undefined) return 'No result returned'
   if (typeof result === 'string') return result

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

@@ -1,8 +1,246 @@
 import type { AwilixContainer } from 'awilix'
 import type { ZodTypeAny } from 'zod'
+import type {
+  PrepareStepFunction,
+  GenerateTextOnStepFinishCallback,
+  GenerateTextOnStepStartCallback,
+  GenerateTextOnToolCallStartCallback,
+  GenerateTextOnToolCallFinishCallback,
+  ToolCallRepairFunction,
+  StopCondition,
+  ToolChoice,
+  ToolSet,
+} from 'ai'
 
 export type AiAgentExecutionMode = 'chat' | 'object'
 
+/**
+ * Selects the underlying Vercel AI SDK dispatch strategy for this agent.
+ *
+ * - `'stream-text'` (default): the runtime calls `streamText(...)` directly on
+ *   every turn. All loop primitives are supported: `prepareStep`, `stopWhen`,
+ *   `repairToolCall`, `activeTools`, `toolChoice`.
+ *
+ * - `'tool-loop-agent'`: the runtime constructs a `ToolLoopAgent`
+ *   (`Experimental_Agent`) once and dispatches via `agent.generate(...)` /
+ *   `agent.stream(...)` per turn. The wrapper-owned `prepareStep` (security-
+ *   critical for mutation-approval) is supplied at construction via
+ *   `settings.prepareStep`. `stopWhen` is similarly wired at construction.
+ *   The `prepareCall` hook is used for per-turn narrowing of `model`, `tools`,
+ *   `stopWhen`, `activeTools`, and `providerOptions`; `prepareStep` is NOT in
+ *   its `Pick` list and MUST NOT be threaded through it.
+ *
+ *   Note: the current SDK version ships `experimental_repairToolCall` on
+ *   `ToolLoopAgentSettings`, so `repairToolCall` is technically reachable via
+ *   this engine. The `loop.repairToolCall` JSDoc retains a caveat reflecting
+ *   the spec's documented limitation, which was written against an earlier SDK
+ *   snapshot where the setting was absent — use with awareness that SDK
+ *   behaviour may differ across versions.
+ *
+ * Phase 5 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export type AiAgentExecutionEngine = 'stream-text' | 'tool-loop-agent'
+
+/**
+ * A serializable stop condition for the agentic loop. The `kind` field
+ * determines which Vercel AI SDK helper is used at runtime:
+ * - `stepCount` → `stepCountIs(count)` — the loop stops after N steps.
+ * - `hasToolCall` → `hasToolCall(toolName)` — the loop stops immediately
+ *   after the model emits a tool call for the named tool.
+ * - `custom` — a raw `StopCondition<ToolSet>` predicate supplied in code.
+ *   NOT valid from JSON-only override sources (tenant DB overrides); only
+ *   accepted when declared directly in `agent.loop` or a `runAiAgentText`
+ *   caller override.
+ *
+ * Phase 0 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export type AiAgentLoopStopCondition =
+  | { kind: 'stepCount'; count: number }
+  | { kind: 'hasToolCall'; toolName: string }
+  | { kind: 'custom'; stop: StopCondition<ToolSet> }
+
+/**
+ * Budget limits for the agentic loop turn. When any limit is exceeded the
+ * wrapper's `prepareStep`/`onStepFinish` aborts the turn via the per-turn
+ * `AbortController` and the loop terminates with a `loop_budget_exceeded`
+ * finish condition.
+ *
+ * Budget enforcement is implemented in Phase 1782-3; for Phases 0–2 the
+ * fields are accepted and forwarded to the prepared-options bag but are not
+ * actively enforced.
+ *
+ * Phase 0 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export interface AiAgentLoopBudget {
+  /** Hard cap on tool calls across all steps in this turn. */
+  maxToolCalls?: number
+  /** Wall-clock cap (ms) per turn; runtime aborts via AbortController. */
+  maxWallClockMs?: number
+  /** Input+output token cap; aggregated from step `usage` fields. */
+  maxTokens?: number
+}
+
+/**
+ * First-class loop configuration for an AI agent. Supersedes the flat
+ * `maxSteps` alias on `AiAgentDefinition`.
+ *
+ * All fields are optional; the runtime falls back to the wrapper default
+ * (`{ maxSteps: 10 }` for chat, `{ maxSteps: undefined }` for object) when
+ * neither the agent nor the caller supplies any loop config.
+ *
+ * Phase 0 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export interface AiAgentLoopConfig {
+  /** Maximum number of agentic steps before the loop is forced to stop. */
+  maxSteps?: number
+  /**
+   * Additional stop conditions. The wrapper ALWAYS composes these with
+   * `stepCountIs(maxSteps ?? 10)` so a misconfigured `hasToolCall` for a
+   * non-existent tool can never cause an infinite loop (R3 mitigation).
+   */
+  stopWhen?: AiAgentLoopStopCondition | AiAgentLoopStopCondition[]
+  /**
+   * Per-step preparation hook. The wrapper composes this with its own
+   * security-critical `prepareStep` that re-asserts the tool allowlist and
+   * mutation-approval wrapping per step.
+   *
+   * Only valid for chat agents. Rejected with `loop_unsupported_in_object_mode`
+   * for object-mode agents.
+   */
+  prepareStep?: PrepareStepFunction<ToolSet>
+  /**
+   * Callback fired when a step finishes. The wrapper chains its own
+   * aggregation callback (LoopTrace builder) before invoking this one.
+   * Exceptions thrown by this callback are caught and logged but do not
+   * abort the turn (matching the SDK's own contract).
+   */
+  onStepFinish?: GenerateTextOnStepFinishCallback<ToolSet>
+  /**
+   * Callback fired when a step starts. Forwarded to the AI SDK as
+   * `experimental_onStepStart`.
+   */
+  onStepStart?: GenerateTextOnStepStartCallback<ToolSet>
+  /**
+   * Callback fired when a tool call starts. Forwarded to the AI SDK as
+   * `experimental_onToolCallStart`.
+   */
+  onToolCallStart?: GenerateTextOnToolCallStartCallback<ToolSet>
+  /**
+   * Callback fired when a tool call finishes. Forwarded to the AI SDK as
+   * `experimental_onToolCallFinish`.
+   */
+  onToolCallFinish?: GenerateTextOnToolCallFinishCallback<ToolSet>
+  /**
+   * Tool-call repair function. Forwarded to the AI SDK as
+   * `experimental_repairToolCall`.
+   *
+   * Only valid for chat agents. Rejected with `loop_unsupported_in_object_mode`
+   * for object-mode agents.
+   *
+   * **Engine note**: this primitive is honored under `executionEngine: 'stream-text'`
+   * (default). Agents on `'tool-loop-agent'` may not reliably support
+   * `repairToolCall` across all SDK versions — if you require it, use the
+   * default `stream-text` engine until support is confirmed stable on the
+   * `ToolLoopAgent` class.
+   *
+   * Phase 5 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  repairToolCall?: ToolCallRepairFunction<ToolSet>
+  /**
+   * Narrow the active tool surface for each step. Names must be a subset of
+   * `agent.allowedTools`; any names outside the allowlist are filtered out
+   * with a `loop:active_tools_filtered` warning.
+   *
+   * Only valid for chat agents. Rejected with `loop_unsupported_in_object_mode`
+   * for object-mode agents.
+   */
+  activeTools?: string[]
+  /**
+   * Tool choice strategy forwarded to the AI SDK on each step.
+   *
+   * Only valid for chat agents. Rejected with `loop_unsupported_in_object_mode`
+   * for object-mode agents.
+   */
+  toolChoice?: ToolChoice<ToolSet>
+  /** Budget caps for this loop turn. */
+  budget?: AiAgentLoopBudget
+  /**
+   * When `false`, per-call `runAiAgentText({ loop })` / HTTP query-param
+   * overrides are rejected with `AgentPolicyError` code
+   * `loop_runtime_override_disabled`. Default is `true` (permissive).
+   *
+   * Agents that pin a loop policy for correctness reasons (e.g. a
+   * `stopWhen: hasToolCall(...)` that must not be bypassed by callers)
+   * should set this to `false`.
+   */
+  allowRuntimeOverride?: boolean
+  /**
+   * Kill switch — when `true`, the runtime forces `stopWhen: stepCountIs(1)` and
+   * ignores all other loop config. Used by the per-tenant operator override to
+   * collapse an agent to a single model call (no tool execution) without
+   * disabling the agent entirely.
+   *
+   * Phase 3 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  disabled?: boolean
+}
+
+/**
+ * Per-step record aggregated by the wrapper-owned `onStepFinish` hook into
+ * `LoopTrace`. Each completed agentic step produces one record.
+ *
+ * Phase 4 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export interface LoopStepRecord {
+  stepIndex: number
+  /** Model id resolved for this step (relevant when prepareStep swaps models). */
+  modelId: string
+  toolCalls: Array<{
+    toolName: string
+    args: unknown
+    result?: unknown
+    error?: { code: string; message: string }
+    repairAttempted: boolean
+    durationMs: number
+  }>
+  /** Raw assistant text emitted in this step. */
+  textDelta: string
+  usage: { inputTokens: number; outputTokens: number }
+  finishReason: 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error'
+}
+
+/**
+ * Per-turn trace aggregated by the wrapper-owned `buildLoopTraceCollector`.
+ * Not persisted — in-memory only; surfaced via the dispatcher SSE stream and
+ * the playground/`<AiChat>` debug panel.
+ *
+ * Phase 4 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+ */
+export interface LoopTrace {
+  agentId: string
+  /**
+   * Stable per-conversation id that ties every turn together. Echoed back on
+   * the SSE `loop-finish` event so clients can persist it for subsequent turns.
+   *
+   * Phase 6.2 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  sessionId: string
+  turnId: string
+  steps: LoopStepRecord[]
+  stopReason:
+    | 'step-count'
+    | 'has-tool-call'
+    | 'custom-stop'
+    | 'budget-tokens'
+    | 'budget-tool-calls'
+    | 'budget-wall-clock'
+    | 'tenant-disabled'
+    | 'finish-reason'
+    | 'abort'
+  totalDurationMs: number
+  totalUsage: { inputTokens: number; outputTokens: number }
+}
+
 export type AiAgentMutationPolicy =
   | 'read-only'
   | 'confirm-required'
@@ -46,6 +284,28 @@ export interface AiAgentDefinition {
   allowedTools: string[]
   suggestions?: AiAgentSuggestion[]
   executionMode?: AiAgentExecutionMode
+  /**
+   * Selects the underlying Vercel AI SDK dispatch strategy for this agent.
+   * Defaults to `'stream-text'` — the existing behavior and the only engine
+   * with unconditional full primitive coverage (`repairToolCall`, all loop
+   * controls).
+   *
+   * Set to `'tool-loop-agent'` to use the `ToolLoopAgent` (`Experimental_Agent`)
+   * class, which is closer to a semantic agent abstraction and receives upcoming
+   * SDK features (multi-agent handoff, streaming approval responses) first.
+   *
+   * **Note on `repairToolCall`**: the current SDK version ships
+   * `experimental_repairToolCall` on `ToolLoopAgentSettings`, so the primitive
+   * is technically available. However, SDK behaviour is not guaranteed to be
+   * identical across versions — prefer `'stream-text'` when `repairToolCall`
+   * correctness is critical.
+   *
+   * This field is opt-in: omitting it leaves the existing `stream-text` path
+   * completely unchanged.
+   *
+   * Phase 5 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  executionEngine?: AiAgentExecutionEngine
   /**
    * Optional provider id this agent prefers (e.g. `'openai'`, `'anthropic'`).
    * Must match a registered `LlmProvider.id`. When the named provider is
@@ -84,15 +344,26 @@ export interface AiAgentDefinition {
   defaultBaseUrl?: string
   /**
    * When false, per-request HTTP overrides (query params `provider`, `model`,
-   * `baseUrl`) and the per-tenant settings override stored in
+   * `baseUrl`, `loopBudget`) 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.
+   * model-factory resolution chain are skipped for this agent, and the
+   * `loopBudget` query parameter is ignored by the chat dispatcher.
    *
    * 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`.
+   * Renamed from `allowRuntimeModelOverride` in Phase 4 of spec
+   * `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  allowRuntimeOverride?: boolean
+  /**
+   * @deprecated Use `allowRuntimeOverride` instead. This alias is kept for
+   * one minor release and will be removed in a future version. The runtime
+   * checks `allowRuntimeOverride` first; if absent it falls back to this field.
+   *
+   * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
    */
   allowRuntimeModelOverride?: boolean
   acceptedMediaTypes?: AiAgentAcceptedMediaType[]
@@ -100,7 +371,23 @@ export interface AiAgentDefinition {
   uiParts?: string[]
   readOnly?: boolean
   mutationPolicy?: AiAgentMutationPolicy
+  /**
+   * @deprecated Use `loop.maxSteps` instead. Honored as alias when `loop` is
+   * omitted. When both `maxSteps` and `loop.maxSteps` are specified, `loop.maxSteps`
+   * wins. This field will be removed in a future minor release.
+   *
+   * Phase 0 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
   maxSteps?: number
+  /**
+   * First-class agentic loop configuration. Supersedes the flat `maxSteps`
+   * alias. The runtime walks a precedence chain (per-call override → tenant
+   * DB override → this block → legacy `maxSteps` alias → wrapper default)
+   * to resolve the effective loop config for each turn.
+   *
+   * Phase 0 of spec `2026-04-28-ai-agents-agentic-loop-controls`.
+   */
+  loop?: AiAgentLoopConfig
   output?: AiAgentStructuredOutput
   resolvePageContext?: (ctx: AiAgentPageContextInput) => Promise<string | null>
   keywords?: string[]

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

@@ -23,15 +23,19 @@
  *   4. Global env `OM_AI_MODEL` (canonical) with `OPENCODE_MODEL` kept as
  *      a backward-compatibility fallback. Accepts either a plain model id
  *      (`gpt-5-mini`) or a slash-qualified id (`openai/gpt-5-mini`).
- *      Slash qualifiers consume the provider axis at the same step — a
- *      higher-priority provider source still wins, but a lower-priority
- *      one cannot overwrite a slash-qualified model.
+ *      Slash qualifiers consume the provider axis at the same step. When the
+ *      selected model source carries a provider hint, the provider/model pair
+ *      is atomic: an unconfigured hinted provider fails instead of sending
+ *      the model id to a different configured provider.
  *   5. The configured provider's own default model id
  *      (`provider.defaultModel`).
  *
  * Every model-axis source is parsed through {@link parseSlashShorthand}.
  * Resolution walks the chain top-down and takes the first non-null hint as
- * the registry-walk seed:
+ * the registry-walk seed. If the winning model source also supplies the
+ * winning provider hint — either through `<provider>/<model>` or through the
+ * same-source provider field/env var — that pair is resolved exactly and
+ * never mixed with a fallback provider.
  *
  *   Provider-axis seed order (highest priority first):
  *   1. Slash-prefix from `callerOverride` (Phase 1).
@@ -104,8 +108,10 @@ export interface AiModelFactoryInput {
   agentDefaultModel?: string
   /**
    * Agent-level default provider, typically `AiAgentDefinition.defaultProvider`.
-   * Named provider id; falls through transparently when the named provider is
-   * registered-but-unconfigured. Sits between `OM_AI_<MODULE>_PROVIDER`
+   * Named provider id. When paired with an agent default model, the pair is
+   * resolved exactly and fails if the provider is unconfigured. When used as
+   * a provider preference without an agent default model, it can fall through
+   * to the next configured provider. Sits between `OM_AI_<MODULE>_PROVIDER`
    * and the global `OM_AI_PROVIDER` in the provider-axis seed list above.
    *
    * Phase 1 of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
@@ -149,9 +155,9 @@ export interface AiModelFactoryInput {
    * between the caller/request override (step 1–2) and the module-env axis
    * (step 4).
    *
-   * Honored ONLY when `allowRuntimeModelOverride !== false` on the agent
-   * definition. The agent runtime is responsible for hydration — the factory
-   * does NOT load the row itself.
+   * Honored ONLY when `allowRuntimeOverride !== false` on the agent definition
+   * (checked via `resolveAllowRuntimeOverride`). The agent runtime is
+   * responsible for hydration — the factory does NOT load the row itself.
    *
    * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
    */
@@ -165,8 +171,9 @@ export interface AiModelFactoryInput {
    * (`?provider=`, `?model=`, `?baseUrl=`). Sits at step 1 of the resolution
    * chain — wins over everything else for that turn.
    *
-   * Honored ONLY when `allowRuntimeModelOverride !== false` on the agent.
-   * The dispatcher validates all three values before setting this input.
+   * Honored ONLY when `allowRuntimeOverride !== false` on the agent (checked
+   * via `resolveAllowRuntimeOverride`). The dispatcher validates all three
+   * values before setting this input.
    *
    * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
    */
@@ -178,8 +185,19 @@ export interface AiModelFactoryInput {
   /**
    * When false, steps 1 (requestOverride) and 3 (tenantOverride) of the
    * resolution chain are skipped. Agents that pin a specific model for
-   * correctness reasons set `AiAgentDefinition.allowRuntimeModelOverride =
-   * false`. Default behavior (omitted) is permissive (= true).
+   * correctness reasons set `AiAgentDefinition.allowRuntimeOverride = false`.
+   * Default behavior (omitted) is permissive (= true).
+   *
+   * Canonical field (renamed from `allowRuntimeModelOverride` in Phase 4 of
+   * spec `2026-04-28-ai-agents-agentic-loop-controls`). The deprecated alias
+   * `allowRuntimeModelOverride` is still accepted via the resolution helper
+   * {@link resolveAllowRuntimeOverride}.
+   *
+   * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
+   */
+  allowRuntimeOverride?: boolean
+  /**
+   * @deprecated Use `allowRuntimeOverride` instead.
    *
    * Phase 4a of spec `2026-04-27-ai-agents-provider-model-baseurl-overrides`.
    */
@@ -410,6 +428,28 @@ function normalizeProviderHint(
   return providerIdAliases(providerId)[0] ?? providerId
 }
 
+function resolveRequiredProvider(
+  providerId: string,
+  registry: AiModelFactoryRegistry,
+  env: EnvLookup,
+): LlmProvider | null {
+  const resolved = registry.resolveFirstConfigured({ env, order: [providerId] })
+  if (resolved?.id === providerId) return resolved
+
+  const direct = registry.get?.(providerId) ?? null
+  if (direct) return direct.isConfigured(env) ? direct : null
+  return null
+}
+
+function requiredProviderMessage(providerId: string, registry: AiModelFactoryRegistry, env: EnvLookup): string {
+  const provider = registry.get?.(providerId) ?? null
+  const envKey = provider?.getConfiguredEnvKey?.(env)
+  const credentialHint = envKey
+    ? ` Set ${envKey} to use this provider.`
+    : ' Configure the matching provider API key to use this provider.'
+  return `The resolved model is pinned to provider "${providerId}", but that provider is not configured.${credentialHint} The runtime refuses to send provider-specific model ids to a different provider.`
+}
+
 function moduleBaseUrlEnvVarName(moduleId: string): string {
   return `${moduleId.toUpperCase()}_AI_BASE_URL`
 }
@@ -443,6 +483,23 @@ export function parseSlashShorthand(
   return { providerHint: before, modelId: after }
 }
 
+/**
+ * Resolves the effective `allowRuntimeOverride` flag from an input that may
+ * carry either the new canonical name (`allowRuntimeOverride`) or the
+ * deprecated alias (`allowRuntimeModelOverride`). The canonical name wins
+ * when both are present. Returns `true` (permissive) when neither is set.
+ *
+ * Exported for test coverage.
+ */
+export function resolveAllowRuntimeOverride(input: {
+  allowRuntimeOverride?: boolean
+  allowRuntimeModelOverride?: boolean
+}): boolean {
+  if (input.allowRuntimeOverride !== undefined) return input.allowRuntimeOverride !== false
+  if (input.allowRuntimeModelOverride !== undefined) return input.allowRuntimeModelOverride !== false
+  return true
+}
+
 /**
  * Creates an {@link AiModelFactory} bound to the DI container. The container
  * reference is accepted for API symmetry with other runtime helpers (and so
@@ -460,9 +517,9 @@ export function createModelFactory(
   return {
     resolveModel(input: AiModelFactoryInput): AiModelResolution {
       const hasModule = typeof input.moduleId === 'string' && input.moduleId.length > 0
-      // When allowRuntimeModelOverride is explicitly false, skip steps 1
-      // (requestOverride) and 3 (tenantOverride) — the agent pins a model.
-      const runtimeOverridesAllowed = input.allowRuntimeModelOverride !== false
+      // When allowRuntimeOverride (or its deprecated alias allowRuntimeModelOverride)
+      // is explicitly false, skip steps 1 (requestOverride) and 3 (tenantOverride).
+      const runtimeOverridesAllowed = resolveAllowRuntimeOverride(input)
 
       // --- Step 1: requestOverride (HTTP query params) — gated by flag ---
       const requestModelRaw = runtimeOverridesAllowed
@@ -506,10 +563,6 @@ export function createModelFactory(
       const agentModelParsed = agentModelRaw ? parseSlashShorthand(agentModelRaw, registry) : null
       const globalModelParsed = globalModelRaw ? parseSlashShorthand(globalModelRaw, registry) : null
 
-      // --- Provider-axis: walk from highest to lowest priority for the seed.
-      // A slash-qualified hint from a model source wins over a plain provider
-      // source at the same priority step. We walk top-down and take the first
-      // non-null hint.
       const providerOverrideRaw = normalizeOverride(input.providerOverride)
       const moduleProviderRaw = hasModule
         ? readModuleProviderEnvOverride(env, input.moduleId!)
@@ -519,70 +572,102 @@ export function createModelFactory(
       // a backward-compatibility fallback through readGlobalProviderFromEnv.
       const globalProviderRaw = readGlobalProviderFromEnv(env, registry)
 
+      const requestProviderHint = normalizeProviderHint(requestProviderRaw, registry)
+      const providerOverrideHint = normalizeProviderHint(providerOverrideRaw, registry)
+      const tenantProviderHint = normalizeProviderHint(tenantProviderRaw, registry)
+      const moduleProviderHint = normalizeProviderHint(moduleProviderRaw, registry)
+      const agentDefaultProviderHint = normalizeProviderHint(agentDefaultProviderRaw, registry)
+
       // Walk the provider-axis seed list: slash hint beats plain provider at
       // the same step. We keep only the first (highest-priority) non-null hint.
       const providerHintCandidates: Array<string | null> = [
         requestModelParsed?.providerHint ?? null,
-        normalizeProviderHint(requestProviderRaw, registry),
+        requestProviderHint,
         callerParsed?.providerHint ?? null,
-        normalizeProviderHint(providerOverrideRaw, registry),
+        providerOverrideHint,
         tenantModelParsed?.providerHint ?? null,
-        normalizeProviderHint(tenantProviderRaw, registry),
+        tenantProviderHint,
         moduleModelParsed?.providerHint ?? null,
-        normalizeProviderHint(moduleProviderRaw, registry),
+        moduleProviderHint,
         agentModelParsed?.providerHint ?? null,
-        normalizeProviderHint(agentDefaultProviderRaw, registry),
+        agentDefaultProviderHint,
         globalModelParsed?.providerHint ?? null,
         globalProviderRaw,
       ]
       const orderHint = providerHintCandidates.find((hint) => hint !== null) ?? null
       const order = orderHint ? [orderHint] : undefined
 
-      const provider = registry.resolveFirstConfigured({ env, order })
-      if (!provider) {
-        throw new AiModelFactoryError(
-          'no_provider_configured',
-          '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 apiKey = provider.resolveApiKey(env)
-      if (!apiKey) {
-        throw new AiModelFactoryError(
-          'api_key_missing',
-          `LLM provider "${provider.id}" is advertised as configured but resolveApiKey() returned empty.`,
-        )
-      }
+      const pairPlainProviderIfWinning = (providerHint: string | null): string | null =>
+        providerHint && providerHint === orderHint ? providerHint : null
 
-      // --- Model-axis: use the post-parse model id from the winning source.
       let modelId: string
       let source: AiModelResolution['source']
+      let pairedProviderHint: string | null = null
       if (requestModelParsed) {
         modelId = requestModelParsed.modelId
         source = 'request_override'
+        pairedProviderHint = requestModelParsed.providerHint ?? pairPlainProviderIfWinning(requestProviderHint)
       } else if (callerParsed) {
         modelId = callerParsed.modelId
         source = 'caller_override'
+        pairedProviderHint = callerParsed.providerHint ?? pairPlainProviderIfWinning(providerOverrideHint)
       } else if (tenantModelParsed) {
         modelId = tenantModelParsed.modelId
         source = 'tenant_override'
+        pairedProviderHint = tenantModelParsed.providerHint ?? pairPlainProviderIfWinning(tenantProviderHint)
       } else if (moduleModelParsed) {
         modelId = moduleModelParsed.modelId
         source = 'module_env'
+        pairedProviderHint = moduleModelParsed.providerHint ?? pairPlainProviderIfWinning(moduleProviderHint)
       } else if (agentModelParsed) {
         modelId = agentModelParsed.modelId
         source = 'agent_default'
+        pairedProviderHint = agentModelParsed.providerHint ?? pairPlainProviderIfWinning(agentDefaultProviderHint)
       } else if (globalModelParsed) {
         modelId = globalModelParsed.modelId
         source = 'env_default'
+        pairedProviderHint = globalModelParsed.providerHint ?? pairPlainProviderIfWinning(globalProviderRaw)
       } else {
-        modelId = provider.defaultModel
+        modelId = ''
         source = 'provider_default'
       }
 
+      // --- Provider-axis: walk from highest to lowest priority for the seed.
+      // A slash-qualified hint from a model source wins over a plain provider
+      // source at the same priority step. We walk top-down and take the first
+      // non-null hint.
+      const provider = pairedProviderHint
+        ? resolveRequiredProvider(pairedProviderHint, registry, env)
+        : registry.resolveFirstConfigured({ env, order })
+      if (!provider) {
+        if (pairedProviderHint) {
+          throw new AiModelFactoryError(
+            'no_provider_configured',
+            requiredProviderMessage(pairedProviderHint, registry, env),
+          )
+        }
+        throw new AiModelFactoryError(
+          'no_provider_configured',
+          '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 apiKey = provider.resolveApiKey(env)
+      if (!apiKey) {
+        throw new AiModelFactoryError(
+          'api_key_missing',
+          `LLM provider "${provider.id}" is advertised as configured but resolveApiKey() returned empty.`,
+        )
+      }
+
+      // --- Model-axis: use the post-parse model id from the winning source.
+      if (source === 'provider_default') {
+        modelId = provider.defaultModel
+      }
+
       // --- BaseURL-axis resolution (highest to lowest priority) ---
-      // 1. requestOverride.baseURL (HTTP dispatcher) — gated by allowRuntimeModelOverride
+      // 1. requestOverride.baseURL (HTTP dispatcher) — gated by allowRuntimeOverride
       // 2. baseUrlOverride (programmatic caller)
-      // 3. tenantOverride.baseURL (DB row) — gated by allowRuntimeModelOverride
+      // 3. tenantOverride.baseURL (DB row) — gated by allowRuntimeOverride
       // 4. <MODULE>_AI_BASE_URL env
       // 5. agentDefaultBaseUrl
       // Steps 6-7 (preset env + preset default) are handled inside the adapter's