dual-brain 0.2.22 → 0.2.23

package/bin/dual-brain.mjs

@@ -68,6 +68,7 @@ import { loadRepoCache } from '../src/repo.mjs';
 import { loadSession, saveSession, formatSessionCard, importReplitSessions, getSessionMeta, saveSessionMeta, renameSession, pinSession, unpinSession, categorizeSession, enrichSessions, archiveSession, getArchivedSessions } from '../src/session.mjs';
 
 import { box, bar, badge, menu, separator, panel, divider, statusChip, headerBar, prompt as tuiPrompt, signalLine } from '../src/tui.mjs';
+import { checkBudget } from '../src/governance.mjs';
 
 // ─── Dynamic imports for receipts + failure memory ───────────────────────────
 
@@ -2884,66 +2885,157 @@ async function mainScreen(rl, ask) {
   if (_spinnerTimeout) clearTimeout(_spinnerTimeout);
   if (dashSpinner) dashSpinner.succeed('Dashboard ready');
 
-  // ── Stale hint ────────────────────────────────────────────────────────────
-  if (staleCount >= 3) {
-    process.stdout.write(`${DIM}${staleCount} stale sessions (>7d) — type "sessions" to manage${RST}\n`);
-  }
-
   // ── Render Studio Console (paneled layout) ────────────────────────────────
   const CYAN = '\x1b[36m';
   const panelW = Math.min(sepW + 2, 72);
 
-  // Header panel — project, branch, providers, version
-  const headerLeft  = `${DIM}${projectName}${RST}  ${BOLD}${branchStr}${RST}  ${DIM}Claude${RST} ${claudeDot}  ${DIM}GPT${RST} ${openaiDot}`;
-  const headerRight = `${DIM}v${version}${RST}`;
-  const headerContent = [headerBar(headerLeft, headerRight, panelW - 4)];
-  process.stdout.write('\n' + panel('dual-brain', headerContent, { width: panelW, titleColor: CYAN }) + '\n\n');
+  // ── Budget / governance data ──────────────────────────────────────────────
+  let budgetInfo = null;
+  try {
+    const orchestratorCfg = JSON.parse(readFileSync(join(cwd, '.claude', 'orchestrator.json'), 'utf8'));
+    budgetInfo = checkBudget(cwd, orchestratorCfg);
+  } catch {
+    // No orchestrator config or no state — use a fresh read with defaults
+    try { budgetInfo = checkBudget(cwd, {}); } catch {}
+  }
+
+  // ── Panel 1: Providers + Budget (top priority — always render) ───────────
+  {
+    const providerLines = [];
+
+    // Provider health rows
+    const claudeLabel = claudeAvail ? `${GRN}✓${RST} Claude` : `${RED}✗${RST} ${DIM}Claude${RST}`;
+    const openaiLabel = openaiAvail ? `${GRN}✓${RST} GPT-4`  : `${RED}✗${RST} ${DIM}GPT-4${RST}`;
+
+    // Detect subscription expiry warnings
+    const claudeWarnStr = (claudeSub?.expiresAt && Date.parse(claudeSub.expiresAt) < Date.now())
+      ? `  ${YLW}⚠ expired${RST}` : '';
+    const openaiWarnStr = (openaiSub?.expiresAt && Date.parse(openaiSub.expiresAt) < Date.now())
+      ? `  ${YLW}⚠ expired${RST}` : '';
+
+    const providerCols = `${claudeLabel}${claudeWarnStr}   ${openaiLabel}${openaiWarnStr}`;
+
+    // Budget row
+    let budgetRow = null;
+    if (budgetInfo) {
+      const spent     = budgetInfo.spent.toFixed(2);
+      const remaining = budgetInfo.remaining.toFixed(2);
+      const limit     = budgetInfo.limit.toFixed(2);
+      const tc        = budgetInfo.tierCounts || {};
+      const tierStr   = `${DIM}t1:${tc[1] || 0}  t2:${tc[2] || 0}  t3:${tc[3] || 0}${RST}`;
+
+      if (budgetInfo.blocked) {
+        budgetRow = `${RED}✗${RST} Budget exhausted  $${spent}/$${limit}   ${tierStr}`;
+      } else if (budgetInfo.warning) {
+        budgetRow = `${YLW}⚠${RST} Budget low  ${YLW}$${remaining} remaining${RST}  of $${limit}   ${tierStr}`;
+      } else if (budgetInfo.spent > 0) {
+        budgetRow = `${GRN}✓${RST} Budget  ${DIM}$${spent} spent · $${remaining} remaining${RST}   ${tierStr}`;
+      } else {
+        budgetRow = `${DIM}· Budget  $0 spent · $${remaining} remaining   t1:0  t2:0  t3:0${RST}`;
+      }
+    }
+
+    providerLines.push(providerCols);
+    if (budgetRow) providerLines.push(budgetRow);
+
+    process.stdout.write('\n' + panel('dual-brain', providerLines, { width: panelW, titleColor: CYAN }) + '\n\n');
+  }
+
+  // ── Panel 2: Workspace signals (contextual, semantic icons) ──────────────
+  {
+    const signalLines = [];
+
+    // Git workspace status
+    if (gitBranch !== 'unknown') {
+      const dirtyStr = gitUncommitted > 0
+        ? `${YLW}⚠${RST} ${gitUncommitted} uncommitted file${gitUncommitted !== 1 ? 's' : ''}`
+        : `${GRN}✓${RST} ${DIM}clean${RST}`;
+      const aheadStr = gitAheadCount > 0 ? `  ${YLW}⚠${RST} ${gitAheadCount} ahead of remote` : '';
+      signalLines.push(`${DIM}${gitBranch}${RST}   ${dirtyStr}${aheadStr}`);
+    }
+
+    // Last commit
+    if (gitLastMsg) {
+      const isStale = /\d{2,}d ago/.test(gitLastAgo);
+      const icon = isStale ? `${YLW}⚠${RST}` : `${DIM}·${RST}`;
+      signalLines.push(`${icon} ${DIM}${gitLastMsg}  ${gitLastAgo}${RST}`);
+    }
+
+    // Open PRs
+    if (openPRs.length > 0) {
+      const prSummary = openPRs.slice(0, 2).map(pr => `#${pr.number}`).join(', ');
+      const trunc = openPRs.length > 2 ? ` +${openPRs.length - 2}` : '';
+      signalLines.push(`${DIM}·${RST} ${openPRs.length} open PR${openPRs.length !== 1 ? 's' : ''}${DIM}: ${prSummary}${trunc}${RST}`);
+    }
+
+    // Observer / awareness signals (high-priority only)
+    for (const obs of quickObservations) {
+      if (obs.priority === 'high') {
+        signalLines.push(`${RED}✗${RST} ${obs.message}`);
+      } else if (obs.priority === 'medium') {
+        signalLines.push(`${YLW}⚠${RST} ${obs.message}`);
+      }
+    }
+
+    // Risk / model registry
+    if (awarenessLine3 && !/No risk flags/.test(awarenessLine3)) {
+      const clean3 = awarenessLine3.replace(/\x1b\[[0-9;]*m/g, '').replace(/^[⚠✓]\s*/, '').trim();
+      if (clean3) signalLines.push(`${YLW}⚠${RST} ${clean3}`);
+    }
+
+    // Stale sessions hint
+    if (staleCount >= 3) {
+      signalLines.push(`${DIM}· ${staleCount} stale sessions (>7d) — type "sessions" to manage${RST}`);
+    }
+
+    // Resume / continuation hint
+    if (isReturning) {
+      const labelTrunc = (resumeState.label || 'last session').slice(0, 40);
+      const agePart    = resumeState.ageLabel ? `  ${DIM}${resumeState.ageLabel}${RST}` : '';
+      const nextPart   = resumeState.nextAction ? `  ${DIM}→ ${resumeState.nextAction}${RST}` : '';
+      signalLines.push(`${CYAN}↩${RST} Resume: ${BOLD}${labelTrunc}${RST}${agePart}${nextPart}`);
+    }
 
-  // Resume / prompt panel (only when there is something to show)
-  if (isReturning || !anyProviderAvail) {
-    const resumeContent = [];
     if (!anyProviderAvail) {
-      resumeContent.push(`${BOLD}Connect a provider to start working${RST}`);
-    } else {
-      const labelTrunc = (resumeState.label || 'last session').slice(0, 45);
-      const agePart    = resumeState.ageLabel ? ` · ${resumeState.ageLabel}` : '';
-      const nextPart   = resumeState.nextAction ? ` · next: ${resumeState.nextAction}` : '';
-      resumeContent.push(`${DIM}Last task${RST}   ${BOLD}${labelTrunc}${RST}${DIM}${agePart}${RST}`);
-      if (nextPart) resumeContent.push(`${DIM}Next step${RST}   ${nextPart.replace(/^ · /, '')}`);
-    }
-    resumeContent.push('');
-    resumeContent.push(`  ${CYAN}›${RST} ${BOLD}${suggestions[0]}${RST}    ${DIM}${suggestions[1] || ''}${RST}    ${DIM}${suggestions[2] || ''}${RST}`);
-    process.stdout.write(panel(isReturning ? 'Resume work' : 'Get started', resumeContent, { width: panelW }) + '\n\n');
-  } else {
-    // Fresh / no-resume state — just show suggestions inline
-    const suggestContent = [`  ${CYAN}›${RST} ${BOLD}${suggestions[0]}${RST}    ${DIM}${suggestions[1] || ''}${RST}    ${DIM}${suggestions[2] || ''}${RST}`];
-    process.stdout.write(panel('Get started', suggestContent, { width: panelW }) + '\n\n');
+      signalLines.push(`${RED}✗${RST} ${BOLD}No provider connected${RST}  — run: dual-brain login`);
+    }
+
+    if (signalLines.length > 0) {
+      process.stdout.write(panel('Workspace', signalLines, { width: panelW }) + '\n\n');
+    }
   }
 
-  // Signals panel — recent work items (only when there are items)
-  if (recentLines.length > 0) {
-    process.stdout.write(panel('Signals', recentLines, { width: panelW }) + '\n\n');
+  // ── Panel 3: What do you want to do? (suggestions) ───────────────────────
+  {
+    const promptTitle = !anyProviderAvail ? 'Get started' : isReturning ? 'Continue' : 'Start';
+    const suggestContent = suggestions.map((s, i) => {
+      return i === 0
+        ? `  ${CYAN}›${RST} ${BOLD}${s}${RST}`
+        : `    ${DIM}${s}${RST}`;
+    });
+    process.stdout.write(panel(promptTitle, suggestContent, { width: panelW }) + '\n\n');
   }
 
-  // Shortcut bar — always visible so the user never has to guess
+  // ── Shortcuts (vertical layout, one per line) ────────────────────────────
   const shortcuts = [
-    [`Enter`, isReturning ? 'resume last session' : 'start working'],
-    [`n`, 'new session'],
-    [`/`, 'search sessions'],
-    [`s`, 'settings & profiles'],
-    [`d`, 'doctor (diagnose issues)'],
-    [`a`, profile.automode ? 'auto mode ⚡ on' : 'auto mode'],
-    [`q`, 'quit'],
+    [`Enter`, isReturning ? 'resume last session' : 'start working  (or type a task)'],
+    [`n`,     'new session'],
+    [`/`,     'search sessions'],
+    [`s`,     'settings & profiles'],
+    [`d`,     'doctor — diagnose issues'],
+    [`a`,     profile.automode ? 'auto mode  (on)' : 'auto mode  (off)'],
+    [`q`,     'quit'],
   ];
-  process.stdout.write('\n');
   for (const [key, label] of shortcuts) {
-    const keyStr = key === 'Enter' ? `${CYAN}Enter${RST}` : `  ${CYAN}${key}${RST}  `;
-    const padded = key === 'Enter' ? ' ' : '  ';
-    process.stdout.write(`   ${keyStr}${padded}${DIM}${label}${RST}\n`);
+    const keyStr = key === 'Enter'
+      ? `${CYAN}Enter${RST}`
+      : `${CYAN}${key}${RST}    `;
+    const padder = key === 'Enter' ? '    ' : '';
+    process.stdout.write(`   ${keyStr}${padder}${DIM}${label}${RST}\n`);
   }
   process.stdout.write('\n');
 
-  // Input bar — rendered below shortcut bar
+  // Input bar — rendered below shortcuts
   const inputLeft = tuiPrompt('task or command...');
   process.stdout.write(` ${inputLeft}\n`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -46,7 +46,8 @@
     "./memory-tiers": "./src/memory-tiers.mjs",
     "./envelope": "./src/envelope.mjs",
     "./session-lock": "./src/session-lock.mjs",
-    "./governance": "./src/governance.mjs"
+    "./governance": "./src/governance.mjs",
+    "./context-intel": "./src/context-intel.mjs"
   },
   "keywords": [
     "claude-code",
@@ -132,6 +133,7 @@
     "src/envelope.mjs",
     "src/session-lock.mjs",
     "src/governance.mjs",
+    "src/context-intel.mjs",
     "bin/*.mjs",
     "hooks/enforce-tier.mjs",
     "hooks/cost-logger.mjs",

package/src/context-intel.mjs

@@ -0,0 +1,156 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const MODEL_FORMAT = {
+  claude: 'xml', sonnet: 'xml', haiku: 'xml', opus: 'xml',
+  gpt: 'markdown', o3: 'markdown', 'o4-mini': 'markdown',
+};
+
+function detectFormat(targetModel, role) {
+  const m = targetModel.toLowerCase();
+  if (m.includes('o3') || (m.includes('opus') && role === 'thinker')) return 'prose';
+  if (m.includes('gpt') || m.includes('o3') || m.includes('o4')) return 'markdown';
+  return 'xml';
+}
+
+export function selectRelevant(pack, role) {
+  const { intent, constraints, priorAttempts, repoState, fileSummaries,
+          acceptanceCriteria, files } = pack;
+  if (role === 'thinker') {
+    return { intent, constraints, priorAttempts, repoState,
+             fileSummaries, acceptanceCriteria };
+  }
+  if (role === 'worker') {
+    const inScope = [...(files?.explicit || []), ...(files?.gitChanged || [])];
+    return { intent, acceptanceCriteria, constraints, inScope };
+  }
+  // reviewer
+  return { intent, acceptanceCriteria, constraints, fileSummaries, repoState };
+}
+
+function readFiles(paths, cwd) {
+  const base = cwd || process.cwd();
+  const out = {};
+  for (const p of paths) {
+    const abs = resolve(base, p);
+    if (existsSync(abs)) {
+      try { out[p] = readFileSync(abs, 'utf8'); } catch { out[p] = '(unreadable)'; }
+    }
+  }
+  return out;
+}
+
+export function renderForModel(sections, targetModel, role) {
+  const fmt = detectFormat(targetModel, role);
+
+  if (fmt === 'prose') {
+    const parts = [];
+    if (sections.intent) parts.push(`Task: ${sections.intent}`);
+    if (sections.acceptanceCriteria?.length)
+      parts.push(`Success looks like: ${sections.acceptanceCriteria.join('; ')}`);
+    if (sections.constraints?.length)
+      parts.push(`Constraints: ${sections.constraints.join('; ')}`);
+    if (sections.repoState) parts.push(`Repo: ${JSON.stringify(sections.repoState)}`);
+    if (sections.fileSummaries) parts.push(`Files: ${JSON.stringify(sections.fileSummaries)}`);
+    if (sections.priorAttempts?.length)
+      parts.push(`Prior attempts: ${JSON.stringify(sections.priorAttempts)}`);
+    return parts.join('\n\n');
+  }
+
+  if (fmt === 'markdown') {
+    const lines = [];
+    if (sections.intent) lines.push(`## Objective\n${sections.intent}`);
+    if (sections.constraints?.length)
+      lines.push(`## Constraints\n${sections.constraints.map(c => `- ${c}`).join('\n')}`);
+    if (sections.acceptanceCriteria?.length)
+      lines.push(`## Acceptance Criteria\n${sections.acceptanceCriteria.map(c => `- ${c}`).join('\n')}`);
+    if (sections.repoState) lines.push(`## Repo State\n\`\`\`json\n${JSON.stringify(sections.repoState, null, 2)}\n\`\`\``);
+    if (sections.fileSummaries) lines.push(`## Files\n\`\`\`json\n${JSON.stringify(sections.fileSummaries, null, 2)}\n\`\`\``);
+    if (sections.fileContents) {
+      lines.push('## File Contents');
+      for (const [p, content] of Object.entries(sections.fileContents))
+        lines.push(`### ${p}\n\`\`\`\n${content}\n\`\`\``);
+    }
+    if (sections.inScope?.length)
+      lines.push(`## In-Scope Files\n${sections.inScope.map(f => `- ${f}`).join('\n')}`);
+    if (sections.priorAttempts?.length)
+      lines.push(`## Prior Attempts\n${JSON.stringify(sections.priorAttempts, null, 2)}`);
+    return lines.join('\n\n');
+  }
+
+  // xml (Claude models)
+  const tags = [];
+  if (sections.intent) tags.push(`<objective>${sections.intent}</objective>`);
+  if (sections.constraints?.length)
+    tags.push(`<constraints>\n${sections.constraints.map(c => `  <constraint>${c}</constraint>`).join('\n')}\n</constraints>`);
+  if (sections.acceptanceCriteria?.length)
+    tags.push(`<criteria>\n${sections.acceptanceCriteria.map(c => `  <criterion>${c}</criterion>`).join('\n')}\n</criteria>`);
+  if (sections.repoState)
+    tags.push(`<repo_state>${JSON.stringify(sections.repoState)}</repo_state>`);
+  if (sections.fileSummaries)
+    tags.push(`<files>${JSON.stringify(sections.fileSummaries)}</files>`);
+  if (sections.fileContents) {
+    const fc = Object.entries(sections.fileContents)
+      .map(([p, c]) => `  <file path="${p}">\n${c}\n  </file>`).join('\n');
+    tags.push(`<file_contents>\n${fc}\n</file_contents>`);
+  }
+  if (sections.inScope?.length)
+    tags.push(`<in_scope_files>\n${sections.inScope.map(f => `  <file>${f}</file>`).join('\n')}\n</in_scope_files>`);
+  if (sections.priorAttempts?.length)
+    tags.push(`<prior_attempts>${JSON.stringify(sections.priorAttempts)}</prior_attempts>`);
+  return `<context>\n${tags.join('\n')}\n</context>`;
+}
+
+export function enforceTokenBudget(rendered, budget) {
+  const chars = budget * 4;
+  const originalTokens = Math.ceil(rendered.length / 4);
+  if (rendered.length <= chars) return { text: rendered, truncated: false, originalTokens, finalTokens: originalTokens };
+
+  // Try dropping prior_attempts / prior attempts block
+  let text = rendered
+    .replace(/<prior_attempts>[\s\S]*?<\/prior_attempts>/g, '')
+    .replace(/## Prior Attempts[\s\S]*?(?=\n## |$)/, '')
+    .replace(/Prior attempts:.*?(?=\n\n|$)/s, '');
+
+  if (text.length <= chars) return { text: text.trim(), truncated: true, originalTokens, finalTokens: Math.ceil(text.length / 4) };
+
+  // Summarize git/repo state
+  text = text
+    .replace(/<repo_state>[\s\S]*?<\/repo_state>/g, '<repo_state>(truncated)</repo_state>')
+    .replace(/## Repo State[\s\S]*?(?=\n## |$)/, '## Repo State\n(truncated)');
+
+  if (text.length <= chars) return { text: text.trim(), truncated: true, originalTokens, finalTokens: Math.ceil(text.length / 4) };
+
+  // Hard truncate
+  text = text.slice(0, chars) + '\n...(truncated)';
+  return { text, truncated: true, originalTokens, finalTokens: Math.ceil(text.length / 4) };
+}
+
+export function attachOutputSchema(role) {
+  if (role === 'thinker')
+    return 'Return JSON: { decision: string, confidence: 0-1, reasoning: string, workSpec: { objective, files, criteria } }';
+  if (role === 'worker')
+    return 'Return JSON: { filesChanged: string[], testsRun: boolean, issues: string[] }';
+  return 'Return JSON: { pass: boolean, findings: [{ severity, file, line, issue, fix }] }';
+}
+
+export function shapeForRole(pack, role, targetModel, tokenBudget) {
+  const sections = selectRelevant(pack, role);
+
+  if (role === 'worker' && sections.inScope?.length) {
+    const cwd = pack.repoState?.cwd;
+    sections.fileContents = readFiles(sections.inScope, cwd);
+  }
+
+  const rendered = renderForModel(sections, targetModel, role);
+  const { text, truncated, originalTokens, finalTokens } = enforceTokenBudget(rendered, tokenBudget);
+  const sectionKeys = Object.keys(sections);
+
+  return { shaped: text, role, model: targetModel, tokenEstimate: finalTokens, sections: sectionKeys };
+}
+
+export function compilePacket(pack, role, targetModel, tokenBudget) {
+  const { shaped } = shapeForRole(pack, role, targetModel, tokenBudget);
+  const schema = attachOutputSchema(role);
+  return `${shaped}\n\n${schema}`;
+}

package/src/dispatch.mjs

@@ -16,6 +16,8 @@ import { markHot, markDegraded, markHealthy, recordDispatch } from './health.mjs
 import { redact } from './redact.mjs';
 import { getFailoverOrder } from './decide.mjs';
 import { getTemplate, renderPrompt, quickRender } from './templates.mjs';
+import { compilePacket, shapeForRole } from './context-intel.mjs';
+import { buildContextPack } from './context.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const USAGE_DIR = join(__dirname, '..', '.dualbrain', 'usage');
@@ -755,6 +757,28 @@ async function dispatch(input = {}) {
   // structured, typed prompts. Falls back to raw prompt when no template matches.
   prompt = _renderTemplatedPrompt(prompt, decision);
 
+  // ── Context intelligence: model-specific prompt shaping ─────────────────────
+  // When we have files and a target model, shape the prompt context for optimal
+  // model consumption. This adds structured context without replacing the template output.
+  if (files.length > 0 || decision.tier) {
+    try {
+      const pack = await buildContextPack(prompt, files, cwd);
+      const role = decision.tier === 'think' ? 'thinker'
+                 : decision.tier === 'review' ? 'reviewer'
+                 : 'worker';
+      const targetModel = decision.model || 'sonnet';
+      const tokenBudget = role === 'thinker' ? 3000
+                        : role === 'reviewer' ? 4000
+                        : 8000;
+      const { shaped, tokenEstimate } = shapeForRole(pack, role, targetModel, tokenBudget);
+      if (shaped && tokenEstimate > 0) {
+        prompt = `${shaped}\n\n---\n\n${prompt}`;
+        if (verbose) process.stderr.write(`[dual-brain] context-intel: ${role} packet shaped for ${targetModel} (~${tokenEstimate} tokens)\n`);
+      }
+    } catch { /* non-blocking — context shaping failure never prevents dispatch */ }
+  }
+  // ── End context intelligence ─────────────────────────────────────────────────
+
   // ── Resume brief injection ───────────────────────────────────────────────────
   // Inject the last session's receipt as context when no situationBrief is already set.
   // This closes the receipt → brief → next session loop automatically.

package/src/templates.mjs

@@ -142,8 +142,44 @@ const TEMPLATES = {
   },
 };
 
+// ── Output schemas ───────────────────────────────────────────────────────────
+
+const OUTPUT_SCHEMAS = {
+  think: '{ "decision": "string", "confidence": 0.0-1.0, "reasoning": "string", "workSpec": { "objective": "string", "files": ["path"], "criteria": ["string"] } }',
+  execute: '{ "filesChanged": ["path"], "testsRun": boolean, "issues": ["string"] }',
+  review: '{ "pass": boolean, "findings": [{ "severity": "critical|high|medium|low", "file": "path", "line": number, "issue": "string", "fix": "string" }] }',
+  search: '{ "found": [{ "file": "path", "line": number, "snippet": "string" }], "confidence": 0.0-1.0 }',
+};
+
+// ── Model render hints ────────────────────────────────────────────────────────
+
+const MODEL_RENDER_HINTS = {
+  xml: ['claude', 'sonnet', 'haiku', 'opus'],
+  markdown: ['gpt', 'gpt-4', 'gpt-4.1', 'gpt-4o'],
+  prose: ['o3', 'o4-mini'],
+};
+
 // ── Template API ─────────────────────────────────────────────────────────────
 
+/**
+ * Get the structured output schema for a tier.
+ */
+export function getOutputSchema(tier) {
+  return OUTPUT_SCHEMAS[tier] || null;
+}
+
+/**
+ * Get the preferred prompt rendering format for a given model ID.
+ */
+export function getRenderHint(modelId) {
+  if (!modelId) return 'markdown';
+  const normalized = String(modelId).toLowerCase();
+  for (const [format, patterns] of Object.entries(MODEL_RENDER_HINTS)) {
+    if (patterns.some(p => normalized.includes(p))) return format;
+  }
+  return 'markdown';
+}
+
 /**
  * Get a template by tier name.
  */
@@ -193,6 +229,7 @@ export function renderPrompt(tier, contract, context = {}) {
     errors: [],
     template: { id: template.id, version: template.version },
     contract: { ...contract, id: contract.id || Date.now().toString(36) },
+    outputSchema: OUTPUT_SCHEMAS[tier] || null,
     stats: {
       words: prompt.split(/\s+/).length,
       chars: prompt.length,