@geraldmaron/construct 1.2.2 → 1.2.3

package/apps/chat/engine/ai-sdk-agent.mjs

@@ -0,0 +1,183 @@
+/**
+ * apps/chat/engine/ai-sdk-agent.mjs — the real owned-loop engine (Vercel AI SDK).
+ *
+ * Lazy-loaded by the launcher only when `construct chat` runs the rich/owned path,
+ * so the optional dependencies (`ai`, `@ai-sdk/*`, `zod`) never load in the zero-dep
+ * core or in tests of the mapping layer. It resolves a Construct model id (the
+ * router's `provider/model` form) to an AI SDK language model through the adapter
+ * registry (provider-adapters.mjs), builds the agent tool set from the tool
+ * registry, and runs streamText under the turn's compiled execution policy
+ * (turn-controls.mjs): the step cap, tool-group / schema budget, output cap, and
+ * caching eligibility all derive from the resolved capability profile, so the loop
+ * adapts to the model while staying behavior-preserving for hosted-direct. It
+ * yields the SDK fullStream parts unchanged; loop-driver.mjs owns the
+ * normalization into the event union.
+ */
+
+import { listChatModels } from './models.mjs';
+import { resolveLanguageModel } from './provider-adapters.mjs';
+import { resolveTurnControls } from './turn-controls.mjs';
+import { buildSystemPrompt } from '../../../lib/chat/system-prompt.mjs';
+import { applyToolBudget } from '../../../lib/mcp/tool-budget.mjs';
+import { recordPolicyTelemetry } from '../../../lib/chat/policy-telemetry.mjs';
+import { maybeCompact, estimateTextTokens, messageText } from '../../../lib/chat/context-compactor.mjs';
+
+// Real summarization of the compactible layers (tool results, prior assistant
+// reasoning) the contract elides, run on the same language model as the turn.
+// Bounded output and zero retries keep the once-per-compaction cost small; a throw
+// is caught upstream and falls back to the deterministic extractive summary, so a
+// summarizer failure degrades fidelity without breaking the turn.
+
+function makeSummarizer({ generateText, languageModel, signal }) {
+  return async (text, meta = {}) => {
+    const { text: summary } = await generateText({
+      model: languageModel,
+      system: 'Compress earlier agent work into a faithful, terse recap for context continuation. Preserve decisions, findings, file paths, identifiers, and unresolved threads. Never invent facts. No preamble.',
+      prompt: `Summarize these ${meta.segmentCount || 'earlier'} turn(s) of an agent working in a repository. Use compact bullets, keep concrete identifiers, stay under 200 words:\n\n${text}`,
+      maxOutputTokens: 512,
+      maxRetries: 0,
+      abortSignal: signal,
+    });
+    return summary;
+  };
+}
+
+export async function createAiSdkAgent({ env = process.env, cwd = process.cwd(), model = null, handlers = {}, systemPrompt = '', tools = null, onTelemetry = recordPolicyTelemetry } = {}) {
+  const { streamText, stepCountIs, generateText } = await import('ai');
+
+  const { buildAgentTools } = await import('./tools/registry.mjs');
+  const sdkTools = await buildAgentTools({ env, cwd, handlers, only: tools });
+
+  const messages = [];
+  const languageModels = new Map();
+  let activeModelId = model;
+  let contextTokens = 0;
+
+  async function languageModelFor(modelId) {
+    const id = modelId || activeModelId;
+    if (!id) {
+      const err = new Error('No model selected and no configured provider found. Run `construct models` or set CX_MODEL_STANDARD.');
+      err.code = 'PROVIDER_MODEL_UNRESOLVED';
+      throw err;
+    }
+    if (!languageModels.has(id)) {
+      languageModels.set(id, await resolveLanguageModel(id, env));
+    }
+    return languageModels.get(id);
+  }
+
+  return {
+    sessionId: `construct-${Date.now()}`,
+    model,
+    listModels: () => listChatModels({ env }),
+    async *streamTurn(text, { signal, model: turnModel = null, turnOverlay = null } = {}) {
+      if (turnModel) activeModelId = turnModel;
+      const languageModel = await languageModelFor(activeModelId);
+
+      const controls = resolveTurnControls({ model: activeModelId, turnOverlay, env });
+      if (controls.degraded) {
+        onTelemetry({
+          kind: 'execution-policy-degraded',
+          model: activeModelId,
+          capabilityClass: controls.policy?.source?.capabilityClass || 'unknown',
+          reasons: controls.policy?.telemetry?.reasons || [],
+        });
+      }
+      const turnTools = applyToolBudget(sdkTools, {
+        allowedToolGroups: controls.allowedToolGroups,
+        maxToolSchemas: controls.maxToolSchemas,
+      });
+
+      // Per-turn routing policy belongs in the SYSTEM role (via buildSystemPrompt),
+      // never prepended to the user message: a user-role policy gets echoed in model
+      // reasoning and compounds in persisted history.
+      messages.push({ role: 'user', content: String(text) });
+      const systemText = buildSystemPrompt({ base: systemPrompt || undefined, overlay: turnOverlay });
+
+      const request = {
+        model: languageModel,
+        tools: turnTools,
+        stopWhen: stepCountIs(controls.iterations),
+        abortSignal: signal,
+        maxRetries: 0,
+      };
+      if (controls.outputCap) request.maxOutputTokens = controls.outputCap;
+
+      // A cache-eligible provider marks the stable system prefix as a cache
+      // breakpoint: the AI SDK maps a single leading system message onto the
+      // provider's system field, so the request stays output-identical and only the
+      // cache_control annotation is added. Every other provider keeps the plain
+      // system string — today's exact request shape.
+      if (controls.cacheEligible) {
+        const providerNs = String(activeModelId || '').split('/')[0] || 'anthropic';
+        request.messages = [
+          { role: 'system', content: systemText, providerOptions: { [providerNs]: { cacheControl: { type: 'ephemeral' } } } },
+          ...messages,
+        ];
+      } else {
+        request.system = systemText;
+        request.messages = messages;
+      }
+
+      const result = streamText(request);
+
+      // The compaction trigger needs the current context SIZE, which is the last
+      // model call's per-step input (system + full history), not the turn's
+      // aggregate input — totalUsage sums input across tool steps and would
+      // over-count a multi-step turn, tripping compaction below the real budget.
+      // Prefer the last finish-step's per-call usage; fall back to the aggregate
+      // only when the host reports no per-step usage. Host numbers only, no split.
+      let lastStepUsage = null;
+      let aggregateUsage = null;
+      for await (const part of result.fullStream) {
+        if (part.type === 'finish-step' && part.usage) lastStepUsage = part.usage;
+        if (part.type === 'finish') aggregateUsage = part.totalUsage || part.usage || aggregateUsage;
+        yield part;
+      }
+      const turnUsage = lastStepUsage || aggregateUsage;
+
+      // Persist the assistant turn (incl. tool exchanges) so the next prompt has history.
+      try {
+        const response = await result.response;
+        if (Array.isArray(response?.messages)) messages.push(...response.messages);
+        // Surface the model that actually answered — the OpenRouter free router
+        // resolves to an underlying model id, not the "openrouter/free" alias.
+        const resolved = response?.modelId;
+        if (resolved && resolved !== activeModelId && !String(activeModelId).endsWith(resolved)) {
+          yield { type: 'model-resolved', model: resolved };
+        }
+      } catch { /* history append is best-effort */ }
+
+      // The next turn's context ≈ this turn's input (system + full history) plus the
+      // output just appended. When that crosses the policy's continuation trigger,
+      // compact without silent loss. Behavior-preserving: hosted only crosses near
+      // its ~150k budget, so short conversations are never touched. Compaction is
+      // best-effort — any failure leaves the live history intact.
+      const input = Number(turnUsage?.inputTokens) || 0;
+      const output = Number(turnUsage?.outputTokens) || 0;
+      if (input || output) contextTokens = input + output;
+
+      const trigger = controls.continuation?.triggerTokens || null;
+      if (trigger && contextTokens >= trigger) {
+        try {
+          const outcome = await maybeCompact({
+            messages,
+            systemText,
+            triggerTokens: trigger,
+            contextTokens,
+            summarize: makeSummarizer({ generateText, languageModel, signal }),
+          });
+          if (outcome.packet) yield { type: 'context-continuation', packet: outcome.packet, compacted: outcome.compacted };
+          if (outcome.notice) {
+            yield { type: 'context-notice', level: outcome.blocker ? 'warn' : 'info', code: outcome.blocker ? 'context-blocker' : 'context-compacted', message: outcome.notice };
+          }
+          if (outcome.compacted && Array.isArray(outcome.messages)) {
+            messages.length = 0;
+            messages.push(...outcome.messages);
+            contextTokens = estimateTextTokens(systemText) + messages.reduce((n, m) => n + estimateTextTokens(messageText(m)), 0);
+          }
+        } catch { /* compaction must never break a turn */ }
+      }
+    },
+  };
+}

package/apps/chat/engine/loop-driver.mjs

@@ -0,0 +1,211 @@
+/**
+ * apps/chat/engine/loop-driver.mjs — Construct's owned agent loop, exposed as a
+ * driver implementing the normalized event union (lib/chat/harness/driver.mjs).
+ *
+ * ADR-0041 reverses the delegate-the-loop posture: Construct now runs the loop
+ * (prompt -> model -> tool calls -> tool results -> repeat) on a provider-agnostic
+ * engine (Vercel AI SDK), so every token, tool result, and routing choice is
+ * first-party data. This module is the seam that keeps the rest of the surface
+ * host-agnostic: it owns the lifecycle (start/prompt/cancel/stop), maps the
+ * engine's fullStream parts onto the driver event union, and accumulates per-turn
+ * usage from the host's own numbers (no fabricated splits).
+ *
+ * The engine itself is injected as `createAgent` so this mapping layer is tested
+ * against a scripted mock with no network or API key — the same dependency-
+ * injection discipline the retired host adapters used (fetchImpl / spawnFn). The
+ * real engine lives in ai-sdk-agent.mjs and is lazy-imported only when chat runs.
+ */
+
+import { AsyncEventQueue } from '../../../lib/chat/harness/driver.mjs';
+import { listChatModels, recommendChatModel } from './models.mjs';
+
+// Vercel AI SDK fullStream parts use a few delta field names across versions;
+// read text from any of them so the mapping survives a minor SDK bump.
+
+function partText(part) {
+  if (typeof part.text === 'string') return part.text;
+  if (typeof part.textDelta === 'string') return part.textDelta;
+  if (typeof part.delta === 'string') return part.delta;
+  return '';
+}
+
+// Usage arrives on finish parts as inputTokens/outputTokens/etc.; normalize to
+// the union's token shape, emitting only fields the engine actually reported.
+
+function normalizeUsage(part) {
+  const u = part.totalUsage || part.usage || null;
+  if (!u) return null;
+  const tokens = {};
+  if (Number.isFinite(u.inputTokens)) tokens.input = u.inputTokens;
+  if (Number.isFinite(u.outputTokens)) tokens.output = u.outputTokens;
+  if (Number.isFinite(u.reasoningTokens)) tokens.reasoning = u.reasoningTokens;
+  if (Number.isFinite(u.cachedInputTokens)) tokens.cacheRead = u.cachedInputTokens;
+  if (Number.isFinite(u.totalTokens)) tokens.total = u.totalTokens;
+  else if (Number.isFinite(tokens.input) || Number.isFinite(tokens.output)) {
+    tokens.total = (tokens.input || 0) + (tokens.output || 0) + (tokens.reasoning || 0);
+  }
+  if (!Object.keys(tokens).length) return null;
+  const event = { type: 'usage', tokens };
+  if (part.providerMetadata?.cost && Number.isFinite(part.providerMetadata.cost.amount)) {
+    event.cost = { amount: part.providerMetadata.cost.amount, currency: part.providerMetadata.cost.currency || 'USD' };
+  }
+  return event;
+}
+
+// One fullStream part -> zero or more normalized driver events on the turn queue.
+// Tool ids are tracked so a tool_call is emitted once and tool_update carries the
+// terminal state, matching the union the renderers already consume.
+
+function mapPart(part, queue, state) {
+  switch (part.type) {
+    case 'text-delta':
+    case 'text': {
+      const t = partText(part);
+      if (t) queue.push({ type: 'text', text: t, messageId: part.id || null });
+      break;
+    }
+    case 'reasoning-delta':
+    case 'reasoning': {
+      const t = partText(part);
+      if (t) queue.push({ type: 'thinking', text: t, messageId: part.id || null });
+      break;
+    }
+    case 'model-resolved': {
+      if (part.model) queue.push({ type: 'model_resolved', model: part.model });
+      break;
+    }
+    case 'context-notice': {
+      queue.push({ type: 'notice', level: part.level || 'info', code: part.code || 'context', message: part.message || '' });
+      break;
+    }
+    case 'context-continuation': {
+      queue.push({ type: 'context_continuation', packet: part.packet || null, compacted: part.compacted === true });
+      break;
+    }
+    case 'tool-call': {
+      const id = part.toolCallId || part.id;
+      state.tools.add(id);
+      queue.push({ type: 'tool_call', id, title: part.toolName || 'tool', kind: part.toolName || 'other', status: 'pending', input: part.input ?? part.args ?? null });
+      break;
+    }
+    case 'tool-result': {
+      const id = part.toolCallId || part.id;
+      queue.push({ type: 'tool_update', id, status: 'completed', content: part.output ?? part.result ?? null });
+      break;
+    }
+    case 'tool-error': {
+      const id = part.toolCallId || part.id;
+      queue.push({ type: 'tool_update', id, status: 'failed', content: part.error ? String(part.error.message || part.error) : null });
+      break;
+    }
+    case 'finish-step':
+    case 'finish': {
+      const usage = normalizeUsage(part);
+      if (usage) queue.push(usage);
+      break;
+    }
+    case 'error':
+      state.errored = true;
+      queue.push({ type: 'error', message: part.error ? String(part.error.message || part.error) : 'engine error' });
+      break;
+    case 'abort':
+      state.aborted = true;
+      break;
+    default:
+      break;
+  }
+}
+
+export function createOwnedLoopDriver({
+  env = process.env,
+  cwd = process.cwd(),
+  model = null,
+  handlers = {},
+  systemPrompt = '',
+  tools = null,
+  createAgent,
+} = {}) {
+  if (typeof createAgent !== 'function') {
+    throw new Error('createOwnedLoopDriver requires a `createAgent` factory (real engine or test mock)');
+  }
+
+  let agent = null;
+  let activeTurn = null;
+  let currentModel = model || null;
+
+  async function start() {
+    agent = await createAgent({ env, cwd, model: currentModel, handlers, systemPrompt, tools });
+    if (agent?.model && !currentModel) currentModel = agent.model;
+    return { sessionId: agent?.sessionId || `owned-${Date.now()}`, capabilities: { host: 'construct', ownedLoop: true } };
+  }
+
+  function prompt(text, opts = {}) {
+    if (!agent) throw new Error('prompt() called before start()');
+    const queue = new AsyncEventQueue();
+    const controller = new AbortController();
+    const turn = { queue, controller, tools: new Set(), aborted: false, errored: false };
+    activeTurn = turn;
+    if (opts.model) currentModel = opts.model;
+
+    (async () => {
+      try {
+        const stream = await agent.streamTurn(text, {
+          signal: controller.signal,
+          model: currentModel,
+          turnOverlay: opts.turnOverlay ?? null,
+        });
+        for await (const part of stream) {
+          if (queue.closed) break;
+          mapPart(part, queue, turn);
+        }
+        queue.push({ type: 'done', stopReason: turn.aborted ? 'cancelled' : turn.errored ? 'error' : 'end_turn' });
+      } catch (err) {
+        if (err?.name === 'AbortError' || turn.aborted) {
+          queue.push({ type: 'done', stopReason: 'cancelled' });
+        } else {
+          queue.push({ type: 'error', message: err?.message || String(err) });
+          queue.push({ type: 'done', stopReason: 'error' });
+        }
+      } finally {
+        queue.close();
+        if (activeTurn === turn) activeTurn = null;
+      }
+    })();
+
+    return queue;
+  }
+
+  function cancel() {
+    if (activeTurn) {
+      activeTurn.aborted = true;
+      try { activeTurn.controller.abort(); } catch { /* already aborted */ }
+    }
+  }
+
+  function stop() {
+    try { agent?.dispose?.(); } catch { /* nothing to dispose */ }
+  }
+
+  async function listModels() {
+    if (agent?.listModels) {
+      try { return await agent.listModels(); } catch { /* fall through to catalog */ }
+    }
+    return listChatModels({ env });
+  }
+
+  async function recommendModel() {
+    if (currentModel) return null;
+    return recommendChatModel({ env });
+  }
+
+  return {
+    start,
+    prompt,
+    cancel,
+    stop,
+    listModels,
+    recommendModel,
+    get model() { return currentModel; },
+    get sessionId() { return agent?.sessionId || null; },
+  };
+}

package/apps/chat/engine/models.mjs

@@ -0,0 +1,122 @@
+/**
+ * apps/chat/engine/models.mjs — model and provider resolution for the owned loop.
+ *
+ * The owned loop is provider-agnostic (ADR-0041/ADR-0003): model choice is never
+ * hardcoded. This module reuses the core router (lib/model-router.mjs) so the chat
+ * surface, the orchestration worker, and the embedded contract all resolve models
+ * the same way. resolveChatModelSelection validates CX_MODEL pins against live
+ * credential detection; resolveChatModelSelectionAsync also probes Copilot session
+ * exchange so a bad token falls through before the first turn.
+ */
+
+import {
+  getProviderModelCatalog,
+  describeModelFamily,
+  resolveValidatedChatModel,
+  isChatModelAvailable,
+} from '../../../lib/model-router.mjs';
+import { resolveFirstSecret } from '../../../lib/providers/secret-resolver.mjs';
+
+export function listChatModels({ env = process.env, cwd = process.cwd(), activeModelId = null } = {}) {
+  const { providers } = getProviderModelCatalog({ env, cwd, activeModelId });
+  const models = [];
+  const seen = new Set();
+  for (const provider of providers) {
+    for (const tier of ['reasoning', 'standard', 'fast']) {
+      for (const id of provider.options?.[tier] || []) {
+        if (seen.has(id)) continue;
+        seen.add(id);
+        models.push({
+          id,
+          label: id,
+          provider: provider.id,
+          configured: provider.configured,
+          local: provider.local === true,
+          suitable: true,
+          tier,
+          available: isChatModelAvailable(id, { env }).ok,
+        });
+      }
+    }
+  }
+  return models.sort((a, b) => Number(b.configured) - Number(a.configured) || a.id.localeCompare(b.id));
+}
+
+export { refreshLiveOpenRouterCatalog } from '../../../lib/models/catalog.mjs';
+
+export function recommendChatModel({ env = process.env } = {}) {
+  const { providers } = getProviderModelCatalog({ env });
+  const configured = providers.find((p) => p.configured);
+  if (!configured) return null;
+  const id = configured.tiers?.standard || configured.tiers?.fast || null;
+  if (!id) return null;
+  const check = isChatModelAvailable(id, { env });
+  if (!check.ok) return null;
+  return { id, reason: `configured provider ${configured.label}` };
+}
+
+export function resolveChatModelSelection({ env = process.env, requested = null, excludeFamilies = [] } = {}) {
+  return resolveValidatedChatModel({ env, requested, excludeFamilies });
+}
+
+export async function resolveFreeOpenRouterModel({ env = process.env, tier = 'standard', exclude = [] } = {}) {
+  const apiKey = resolveFirstSecret(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], { env });
+  if (!apiKey) return null;
+  const excludeSet = new Set(Array.isArray(exclude) ? exclude : []);
+  const { pollFreeModels, topForTier } = await import('../../../lib/model-free-selector.mjs');
+  const freeModels = await pollFreeModels(apiKey);
+  for (const candidate of topForTier(freeModels, tier, 20)) {
+    const modelId = candidate.id.startsWith('openrouter/') ? candidate.id : `openrouter/${candidate.id}`;
+    if (excludeSet.has(modelId)) continue;
+    if (isChatModelAvailable(modelId, { env }).ok) return modelId;
+  }
+  return null;
+}
+
+export async function resolveSessionModel(session, { env = process.env, exclude = [], tier = 'standard' } = {}) {
+  if (session?.modelMode === 'free-router') {
+    const merged = [...new Set([...getExcludeFromSession(session), ...exclude])];
+    return resolveFreeOpenRouterModel({ env, tier, exclude: merged });
+  }
+  return session?.model || session?.savedModel || null;
+}
+
+function getExcludeFromSession(session) {
+  if (!session?.failedModels) return [];
+  return session.failedModels instanceof Set ? [...session.failedModels] : [];
+}
+
+export async function resolveChatModelSelectionAsync({
+  env = process.env,
+  requested = null,
+  fetchImpl = fetch,
+} = {}) {
+  let resolution = resolveValidatedChatModel({ env, requested });
+  if (!resolution.id?.startsWith('github-copilot/')) return resolution;
+
+  const { preflightCopilotSession } = await import('../../../lib/providers/copilot-auth.mjs');
+  const probe = await preflightCopilotSession({ fetchImpl });
+  if (probe.ok) return resolution;
+
+  const fallback = resolveValidatedChatModel({ env, requested: null, excludeFamilies: ['github-copilot'] });
+  if (fallback.id) {
+    return {
+      ...fallback,
+      notice: `GitHub Copilot session failed (${probe.message}). Using ${fallback.id}.`,
+    };
+  }
+  return {
+    id: null,
+    source: null,
+    notice: `GitHub Copilot session failed: ${probe.message}`,
+    rejected: resolution.rejected,
+  };
+}
+
+export function resolveChatModel(opts = {}) {
+  return resolveChatModelSelection(opts).id;
+}
+
+export function describeChatModel(modelId, { env = process.env } = {}) {
+  return describeModelFamily(modelId, { env });
+}

package/apps/chat/engine/provider-adapters.mjs

@@ -0,0 +1,171 @@
+/**
+ * apps/chat/engine/provider-adapters.mjs — centralized provider execution adapters
+ * (construct-6zga.1.3).
+ *
+ * One registry, keyed by provider group, owns provider execution. Each adapter
+ * owns its own credential resolution, base URL, native model-id translation, auth
+ * scheme, and AI SDK provider construction; the dispatcher does no
+ * provider/model-prefix behavior branch — it extracts the structural provider
+ * group (the model id's first segment, the same identity lib/models keys on) and
+ * looks the adapter up. Adding a compatible provider is a registry entry plus
+ * matrix fixtures, never a dispatch edit.
+ *
+ * Public model ids are preserved: the native id handed to the SDK is the model id
+ * with its group segment stripped, so anthropic/claude-x → claude-x and
+ * openrouter/anthropic/claude-x → anthropic/claude-x (OpenRouter's own id).
+ * Credentials resolve through the shared secret resolver (env, dotenv, shell rc,
+ * 1Password op:// refs); a missing key fails fast with a remediation hint.
+ */
+import { resolveFirstSecret } from '../../../lib/providers/secret-resolver.mjs';
+import { providerGroupForModel } from '../../../lib/models/execution-capability-profile.mjs';
+
+const OPENROUTER_BASE = 'https://openrouter.ai/api/v1';
+
+function envKey(env, ...names) {
+  return resolveFirstSecret(names, { env });
+}
+
+function missingKey(provider, varName) {
+  const err = new Error(`No credentials for ${provider}: set ${varName} (or run \`construct creds\`) and retry.`);
+  err.code = 'PROVIDER_KEY_MISSING';
+  return err;
+}
+
+// Adapter descriptors. `describe` is the serializable contract (auth scheme,
+// protocol, credential env, base URL source) for tracing and conformance fixtures;
+// `createModel` builds the AI SDK handle from the native id. The @ai-sdk/* imports
+// stay lazy so the zero-dep core never loads them.
+
+const ADAPTERS = {
+  anthropic: {
+    id: 'anthropic',
+    auth: 'api_key',
+    protocol: 'anthropic-messages',
+    credentialEnv: ['ANTHROPIC_API_KEY'],
+    baseURL: 'default',
+    async createModel({ nativeModelId, env }) {
+      const apiKey = envKey(env, 'ANTHROPIC_API_KEY');
+      if (!apiKey) throw missingKey('Anthropic', 'ANTHROPIC_API_KEY');
+      const { createAnthropic } = await import('@ai-sdk/anthropic');
+      return createAnthropic({ apiKey })(nativeModelId);
+    },
+  },
+  openai: {
+    id: 'openai',
+    auth: 'api_key',
+    protocol: 'openai-chat-completions',
+    credentialEnv: ['OPENAI_API_KEY'],
+    baseURL: 'default',
+    async createModel({ nativeModelId, env }) {
+      const apiKey = envKey(env, 'OPENAI_API_KEY');
+      if (!apiKey) throw missingKey('OpenAI', 'OPENAI_API_KEY');
+      const { createOpenAI } = await import('@ai-sdk/openai');
+      return createOpenAI({ apiKey })(nativeModelId);
+    },
+  },
+  openrouter: {
+    id: 'openrouter',
+    auth: 'api_key',
+    protocol: 'openai-compatible',
+    credentialEnv: ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+    baseURL: OPENROUTER_BASE,
+    async createModel({ nativeModelId, env }) {
+      const apiKey = envKey(env, 'OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY');
+      if (!apiKey) throw missingKey('OpenRouter', 'OPENROUTER_API_KEY');
+      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
+      return createOpenAICompatible({ name: 'openrouter', baseURL: OPENROUTER_BASE, apiKey })(nativeModelId);
+    },
+  },
+  ollama: {
+    id: 'ollama',
+    auth: 'none',
+    protocol: 'openai-compatible',
+    credentialEnv: [],
+    baseURL: 'env:OLLAMA_BASE_URL',
+    async createModel({ modelId, nativeModelId, env }) {
+      const { isOllamaModelInstalled, formatOllamaModelMissingMessage } = await import('../../../lib/ollama/installed-models.mjs');
+      if (isOllamaModelInstalled(modelId, { env }) === false) {
+        const err = new Error(formatOllamaModelMissingMessage(nativeModelId));
+        err.code = 'OLLAMA_MODEL_NOT_PULLED';
+        throw err;
+      }
+      const baseURL = envKey(env, 'OLLAMA_BASE_URL') || 'http://localhost:11434/v1';
+      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
+      return createOpenAICompatible({ name: 'ollama', baseURL, apiKey: 'ollama' })(nativeModelId);
+    },
+  },
+  local: {
+    id: 'local',
+    auth: 'api_key',
+    protocol: 'openai-compatible',
+    credentialEnv: ['LOCAL_LLM_API_KEY'],
+    baseURL: 'env:LOCAL_LLM_BASE_URL',
+    async createModel({ nativeModelId, env }) {
+      const baseURL = envKey(env, 'LOCAL_LLM_BASE_URL');
+      if (!baseURL) throw missingKey('local OpenAI-compatible server', 'LOCAL_LLM_BASE_URL');
+      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
+      return createOpenAICompatible({ name: 'local', baseURL, apiKey: envKey(env, 'LOCAL_LLM_API_KEY') || 'local' })(nativeModelId);
+    },
+  },
+  'github-copilot': {
+    id: 'github-copilot',
+    auth: 'oauth',
+    protocol: 'openai-chat-completions',
+    credentialEnv: [],
+    baseURL: 'copilot',
+    async createModel({ nativeModelId }) {
+      const { getCopilotToken, copilotApiHeaders, COPILOT_API_BASE } = await import('../../../lib/providers/copilot-auth.mjs');
+      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
+      const copilotFetch = async (url, init = {}) => {
+        const token = await getCopilotToken();
+        const headers = new Headers(init.headers);
+        for (const [key, value] of Object.entries(copilotApiHeaders())) headers.set(key, value);
+        headers.set('Authorization', `Bearer ${token}`);
+        return fetch(url, { ...init, headers });
+      };
+      return createOpenAICompatible({ name: 'github-copilot', baseURL: COPILOT_API_BASE, apiKey: 'via-fetch', fetch: copilotFetch })(nativeModelId);
+    },
+  },
+};
+
+export function getProviderAdapter(group) {
+  return ADAPTERS[group] || null;
+}
+
+// Serializable adapter contract for tracing and conformance fixtures (no secrets,
+// no SDK handles) — the metadata a new provider must register.
+
+export function describeProviderAdapters() {
+  return Object.values(ADAPTERS).map((a) => ({
+    id: a.id,
+    auth: a.auth,
+    protocol: a.protocol,
+    credentialEnv: a.credentialEnv,
+    baseURL: a.baseURL,
+  }));
+}
+
+export function nativeModelId(modelId, group = providerGroupForModel(modelId)) {
+  return String(modelId).slice(group.length + 1);
+}
+
+/**
+ * Map a Construct "provider/model" id onto an AI SDK language model via the
+ * adapter registry. No provider/model-prefix behavior branch: the group is a
+ * structural key, the adapter owns the behavior.
+ */
+export async function resolveLanguageModel(modelId, env) {
+  if (!modelId) {
+    const err = new Error('No model selected and no configured provider found. Run `construct models` or set CX_MODEL_STANDARD.');
+    err.code = 'PROVIDER_MODEL_UNRESOLVED';
+    throw err;
+  }
+  const group = providerGroupForModel(modelId);
+  const adapter = ADAPTERS[group];
+  if (!adapter) {
+    const err = new Error(`Provider for model '${modelId}' is not wired into the owned loop yet. Try an anthropic/, openai/, openrouter/, ollama/, local/, or github-copilot/ model.`);
+    err.code = 'PROVIDER_UNSUPPORTED';
+    throw err;
+  }
+  return adapter.createModel({ modelId, nativeModelId: nativeModelId(modelId, group), env });
+}