@geraldmaron/construct 1.2.1 → 1.2.3

package/README.md

@@ -28,7 +28,7 @@ Bootstrap local services (once per machine, opt-in to machine-scope writes):
 construct install --scope=user --yes
 ```
 
-`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
+`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/decisions/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
 
 Initialize a project:
 
@@ -87,7 +87,7 @@ Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deplo
 
 ## Intake
 
-Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
+Anything dropped into `inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
 
 Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage).
 
@@ -111,11 +111,11 @@ Construct's writes are scoped and disclosed up front. The default `construct ins
 | Machine | `construct install --scope=user` | `~/.construct/config.env`, `~/.construct/lib` (symlink), `~/.construct/services/`, `~/Library/LaunchAgents/` (macOS), MCP entries in `~/.config/opencode/opencode.json` and `~/.codex/config.toml`, marker block in `~/.claude/CLAUDE.md`, hook injection in `~/.claude/settings.json` (last two require interactive consent or `--yes`) |
 | Never touched | — | Shell rc files (`~/.bashrc`, `~/.zshrc`), npm global config, `git config --global` |
 
-Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md).
+Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/decisions/adr/0029-install-scopes-and-hook-budgets.md).
 
 ## Learning loops
 
-Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
+Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/guides/concepts/learning-loops.mdx`](./docs/guides/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
 
 ## `.cx/` is local-only runtime state
 
@@ -226,7 +226,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct doc` | Verify or inspect auditability stamps on Construct-generated markdown files |
 | `construct docs:check` | Check for missing how-to guides (alias for `docs check`) |
 | `construct docs:reconcile` | Reconcile docs against the registry |
-| `construct docs:site` | Regenerate generated reference pages under docs/reference/ |
+| `construct docs:site` | Regenerate generated reference pages under docs/guides/reference/ |
 | `construct docs:update` | Regenerate AUTO-managed doc regions (alias for `docs update`) |
 | `construct docs:verify` | Validate documentation quality (alias for `docs verify`) |
 | `construct impact` | Change-impact analysis — map changed files to affected tests, capabilities, and workflows |
@@ -269,7 +269,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md). Branch workflow, gates, review expectations.
 - [`CHANGELOG.md`](./CHANGELOG.md). Release history.
-- [`docs/concepts/architecture.mdx`](./docs/concepts/architecture.mdx). Canonical architecture.
+- [`docs/guides/concepts/architecture.mdx`](./docs/guides/concepts/architecture.mdx). Canonical architecture.
 - [`AGENTS.md`](./AGENTS.md). Agent operating contract.
 
 ## Project structure

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 });
+}