@jhizzard/termdeck 1.6.1 → 1.7.0

package/packages/server/src/agent-adapters/gemini.js

@@ -106,54 +106,108 @@ async function resolveTranscriptPath(session) {
 }
 
 // ──────────────────────────────────────────────────────────────────────────
-// parseTranscript — Gemini CLI session JSON format (NOT JSONL).
+// parseTranscript — Gemini CLI session transcript → normalized Memory[].
 //
-// Captured shape (from `gemini -p "say hi"` 2026-05-01):
-//   {
-//     sessionId, projectHash, startTime, lastUpdated, kind,
-//     messages: [
-//       { id, timestamp, type: 'user',   content: [{ text: '...' }] },
-//       { id, timestamp, type: 'gemini', content: '...', thoughts, tokens, model },
-//       ...
-//     ]
-//   }
+// TWO on-disk shapes, both handled (verified 2026-06-07 against real files in
+// `~/.gemini/tmp/<proj>/chats/`):
 //
-// The user role carries a content ARRAY of `{text}` parts; the gemini
-// (assistant) role carries a STRING. We normalize both to the Claude
-// adapter's output shape — `{ role: 'user'|'assistant', content: string }`
-// truncated to 400 chars — so the memory-hook summary builder doesn't have
-// to branch on adapter type.
+//   (A) LEGACY single-JSON object (`.json`, Gemini CLI ≤ ~2026-05-02) —
+//       pretty-printed across many lines:
+//         { sessionId, projectHash, startTime, lastUpdated, kind,
+//           messages: [ { id, timestamp, type:'user'|'gemini', content }, ... ] }
 //
-// `type: 'gemini'` maps to `role: 'assistant'` for cross-adapter parity.
+//   (B) MODERN JSONL (`.jsonl`, Gemini CLI ≥ ~2026-05-08 — what ships today) —
+//       one JSON object per line, heterogeneous:
+//         line 0           → session header { sessionId, projectHash, ... }   (no messages/type → skipped)
+//         { "$set": {...} } → incremental mutation deltas                      (no type        → skipped)
+//         { id, timestamp, type:'user'|'gemini'|'info', content } → a message  (extracted)
+//
+// In BOTH shapes a `type:'user'` message carries a content ARRAY of `{text}`
+// parts and a `type:'gemini'` message carries a STRING. We normalize both to
+// the Claude adapter's output shape — `{ role:'user'|'assistant', content }`
+// truncated to 400 chars — so the memory-hook summary builder never branches
+// on adapter type. `type:'gemini'` → `role:'assistant'`; any other type
+// (info / system / tool) is skipped.
+//
+// Pre-Sprint-70 this did a single `JSON.parse(raw)` and `return []` on throw,
+// so EVERY modern `.jsonl` session threw `Extra data: line 2` and captured
+// NOTHING (silent data loss). Strategy now: try a whole-blob parse first — it
+// succeeds only for shape (A) and any genuinely single-line input, keeping the
+// Sprint-45 fixtures green — then fall back to line-by-line JSONL for shape
+// (B), tolerating blank lines, a trailing newline, and a partial last line,
+// and skipping any line that isn't a well-formed transcript turn.
+//
+// CROSS-FILE CONTRACT: the parser the LIVE capture path actually invokes is
+// the hook-side mirror `parseGeminiJson` in `~/.claude/hooks/memory-session-
+// end.js` (+ its bundled copy `packages/stack-installer/assets/hooks/memory-
+// session-end.js`); the bundled comment there mandates "keep the two in sync."
+// Those copies need the same whole-blob→JSONL fix to close the capture gap
+// end-to-end — that file is Sprint-70 T3-owned (see STATUS.md T2 cross-lane
+// FINDING). This adapter copy is the canonical reference they mirror.
 // ──────────────────────────────────────────────────────────────────────────
 
+// Normalize one parsed Gemini message object into the cross-adapter
+// `{ role, content }` shape and push it onto `out`. Non-message objects
+// (the session header, `$set` deltas, info/system/tool roles, empty content)
+// contribute nothing.
+function pushGeminiMessage(msg, out) {
+  if (!msg || typeof msg !== 'object') return;
+  let role;
+  if (msg.type === 'user') role = 'user';
+  else if (msg.type === 'gemini' || msg.type === 'assistant') role = 'assistant';
+  else return; // header line, $set delta, info/system/tool — not a transcript turn
+
+  const content = msg.content;
+  let text = '';
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content
+      .filter((c) => c && typeof c.text === 'string')
+      .map((c) => c.text)
+      .join(' ');
+  }
+  if (text) out.push({ role, content: text.slice(0, 400) });
+}
+
+// Collect messages from one parsed JSON node, whether it's a session wrapper
+// (shape A — carries a `messages` array) or a single bare message (shape B —
+// one JSONL line). A node that is neither contributes nothing.
+function collectGeminiNode(node, out) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node.messages)) {
+    for (const msg of node.messages) pushGeminiMessage(msg, out);
+  } else {
+    pushGeminiMessage(node, out);
+  }
+}
+
 function parseTranscript(raw) {
   if (typeof raw !== 'string' || raw.length === 0) return [];
-  let session;
-  try { session = JSON.parse(raw); } catch (_) { return []; }
-  if (!session || !Array.isArray(session.messages)) return [];
+  const out = [];
 
-  const messages = [];
-  for (const msg of session.messages) {
-    if (!msg || typeof msg !== 'object') continue;
-    let role;
-    if (msg.type === 'user') role = 'user';
-    else if (msg.type === 'gemini' || msg.type === 'assistant') role = 'assistant';
-    else continue;
+  // Shape (A): a single (possibly pretty-printed, multi-line) JSON object.
+  // Succeeds only when the WHOLE blob is valid JSON — the legacy `.json`
+  // format or a 1-line `.jsonl`. A multi-line `.jsonl` throws here
+  // ("Extra data: line 2") and falls through to the JSONL path below.
+  try {
+    collectGeminiNode(JSON.parse(raw), out);
+    if (out.length) return out;
+  } catch (_) { /* not a single JSON blob → try JSONL */ }
 
-    const content = msg.content;
-    let text = '';
-    if (typeof content === 'string') {
-      text = content;
-    } else if (Array.isArray(content)) {
-      text = content
-        .filter((c) => c && typeof c.text === 'string')
-        .map((c) => c.text)
-        .join(' ');
-    }
-    if (text) messages.push({ role, content: text.slice(0, 400) });
+  // Shape (B): JSONL — one object per line. Tolerate blank lines, a trailing
+  // newline, and a partial/truncated final line (skip unparseable lines rather
+  // than aborting the whole transcript). Only reached when the whole-blob parse
+  // threw OR yielded zero messages (e.g. a header-only single object), so `out`
+  // is still empty here and there is no double-collection.
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let node;
+    try { node = JSON.parse(trimmed); } catch (_) { continue; }
+    collectGeminiNode(node, out);
   }
-  return messages;
+  return out;
 }
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -233,6 +287,202 @@ function buildMnestraBlock({ secrets } = {}) {
   };
 }
 
+// ──────────────────────────────────────────────────────────────────────────
+// Auth — API-key mode + doctor probe (Sprint 70 T2)
+//
+// WHY THIS EXISTS: Google ends the Gemini CLI's OAuth / subscription serving
+// path on JUNE 18 2026. After that date the `gemini` binary authenticates
+// ONLY via a billing-enabled API key, which requires BOTH:
+//   • `GEMINI_API_KEY` in the environment — TermDeck loads it from
+//     ~/.termdeck/secrets.env at server boot and merges it into the panel PTY
+//     env (see spawn.env note above); and
+//   • ~/.gemini/settings.json → `security.auth.selectedType: "gemini-api-key"`
+//     (the *mode* switch — a present key is ignored while the mode is still
+//     `oauth-personal`).
+// Antigravity (`agy`) deliberately stays on OAuth, so the two coexist:
+// agy = OAuth, gemini = API-key. A future operator must NOT have to reverse-
+// engineer why Gemini panels went dark after 2026-06-18 — `checkAuth()` makes
+// every failure mode loud and actionable.
+//
+// `checkAuth(opts)` returns a structured verdict; it never throws and never
+// blocks by default:
+//   { ok, state, keyPresent, keySource, selectedType, detail, hint, live }
+//   state ∈
+//     'valid'            key present + selectedType === 'gemini-api-key'
+//                        (+ live AUTHOK appended when opts.live confirmed it)
+//     'missing-key'      GEMINI_API_KEY absent from env AND secrets.env → the
+//                        binary cannot authenticate at all post-2026-06-18
+//     'wrong-mode'       key present but selectedType !== 'gemini-api-key'
+//                        (e.g. still 'oauth-personal' — works NOW, BREAKS 06-18)
+//     'settings-missing' ~/.gemini/settings.json absent/unparseable → mode unknown
+//     'unverified'       static config is correct but the live probe couldn't
+//                        confirm (offline / binary absent / timeout) — soft-OK
+//
+// The static checks (env + settings.json) are pure and always run. The LIVE
+// probe — actually invoking `gemini` non-interactively to confirm the key is
+// accepted, the "AUTHOK" model the prior session validated — is gated behind
+// `opts.live` and routed through the monkey-patchable `_liveAuthProbe` seam so
+// unit tests stay offline and a future `termdeck doctor` wiring never hangs on
+// it. The seams (`_geminiApiKeyState` / `_readGeminiSettings` /
+// `_liveAuthProbe`) are attached to the adapter object below for the same
+// stub-ability the stack doctor uses (cli/src/doctor.js `_fetchLatest`).
+// ──────────────────────────────────────────────────────────────────────────
+
+// GEMINI_API_KEY presence — env first, then the canonical ~/.termdeck/
+// secrets.env store (the server merges that file into the PTY env at boot, but
+// a standalone probe may run before that merge). PRESENCE ONLY — the key value
+// is never read into a variable, returned, or logged.
+function _geminiApiKeyState({ env, secretsPath } = {}) {
+  const e = env || process.env;
+  if (e && typeof e.GEMINI_API_KEY === 'string' && e.GEMINI_API_KEY.trim()) {
+    return { present: true, source: 'env' };
+  }
+  const fs = require('fs');
+  const os = require('os');
+  const path = require('path');
+  const p = secretsPath || path.join(os.homedir(), '.termdeck', 'secrets.env');
+  try {
+    const txt = fs.readFileSync(p, 'utf8');
+    // Match a non-empty assignment without ever capturing the value.
+    if (/^\s*(?:export\s+)?GEMINI_API_KEY=\s*\S/m.test(txt)) {
+      return { present: true, source: 'secrets.env' };
+    }
+  } catch (_) { /* no secrets.env / unreadable */ }
+  return { present: false, source: null };
+}
+
+// Read ~/.gemini/settings.json and return { selectedType } (or null when the
+// file is absent or unparseable — the caller maps null to 'settings-missing').
+function _readGeminiSettings({ settingsPath } = {}) {
+  const fs = require('fs');
+  const os = require('os');
+  const path = require('path');
+  const p = settingsPath || path.join(os.homedir(), '.gemini', 'settings.json');
+  let txt;
+  try { txt = fs.readFileSync(p, 'utf8'); } catch (_) { return null; }
+  try {
+    const j = JSON.parse(txt);
+    const sel = j && j.security && j.security.auth && j.security.auth.selectedType;
+    return { selectedType: typeof sel === 'string' ? sel : null };
+  } catch (_) { return null; }
+}
+
+// Live auth probe — invoke `gemini` non-interactively and resolve
+//   { ran:true, ok:boolean, note:string }
+// Success = exit 0 with non-empty stdout (the binary only emits a response once
+// the key is accepted); the AUTHOK token, when echoed, is surfaced in `note`.
+// Any spawn error / timeout / non-zero exit resolves ok:false — the caller
+// keeps the static verdict and downgrades 'valid' → 'unverified' (never RED) to
+// avoid false negatives on offline / rate-limited runs. Replaceable for tests.
+function _liveAuthProbe({ timeoutMs = 8000 } = {}) {
+  const { spawn } = require('child_process');
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('gemini', ['-p', 'Reply with exactly: AUTHOK'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (e) {
+      return resolve({ ran: true, ok: false, note: `spawn failed: ${e && e.message || e}` });
+    }
+    let out = '';
+    let timedOut = false;
+    const t = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch (_) { /* already gone */ }
+    }, timeoutMs);
+    child.stdout.on('data', (b) => { out += b.toString('utf8'); });
+    child.stderr.on('data', () => { /* auth errors land here; intentionally not logged */ });
+    child.on('error', (e) => {
+      clearTimeout(t);
+      resolve({ ran: true, ok: false, note: `error: ${e && e.message || e}` });
+    });
+    child.on('close', (code) => {
+      clearTimeout(t);
+      if (timedOut) return resolve({ ran: true, ok: false, note: `timed out after ${timeoutMs}ms` });
+      const responded = code === 0 && out.trim().length > 0;
+      const sawToken = /AUTHOK/i.test(out);
+      resolve({
+        ran: true,
+        ok: responded,
+        note: responded
+          ? (sawToken ? 'AUTHOK' : 'gemini responded (exit 0)')
+          : `gemini exited ${code} without a response`,
+      });
+    });
+  });
+}
+
+// See the WHY / contract block above. Async because the optional live probe
+// awaits a spawn; the static-only path (default) resolves immediately. Seams
+// are dereferenced via `geminiAdapter.*` so tests can monkey-patch them.
+async function checkAuth(opts = {}) {
+  const options = opts || {};
+  const keyState = geminiAdapter._geminiApiKeyState(options);
+  const settings = geminiAdapter._readGeminiSettings(options);
+  const selectedType = settings ? settings.selectedType : null;
+
+  let state;
+  let ok;
+  let detail;
+  let hint;
+  if (!keyState.present) {
+    state = 'missing-key';
+    ok = false;
+    detail = 'GEMINI_API_KEY is not set (checked process env + ~/.termdeck/secrets.env).';
+    hint = 'Add GEMINI_API_KEY=<billing-enabled key> to ~/.termdeck/secrets.env (mode 600). '
+      + 'After 2026-06-18 the Gemini CLI authenticates ONLY via an API key.';
+  } else if (settings === null) {
+    state = 'settings-missing';
+    ok = false;
+    detail = 'GEMINI_API_KEY is present, but ~/.gemini/settings.json is missing or '
+      + 'unparseable — cannot confirm the auth mode.';
+    hint = 'Create ~/.gemini/settings.json with '
+      + '{"security":{"auth":{"selectedType":"gemini-api-key"}}}.';
+  } else if (selectedType !== 'gemini-api-key') {
+    state = 'wrong-mode';
+    ok = false;
+    detail = `GEMINI_API_KEY is present, but settings.json security.auth.selectedType is `
+      + `${selectedType ? `"${selectedType}"` : 'unset'} — not "gemini-api-key", so the key `
+      + `is ignored. This still works until 2026-06-18, then breaks.`;
+    hint = 'Set ~/.gemini/settings.json security.auth.selectedType to "gemini-api-key" '
+      + '(Antigravity `agy` keeps OAuth separately).';
+  } else {
+    state = 'valid';
+    ok = true;
+    detail = `GEMINI_API_KEY present (${keyState.source}) and settings.json `
+      + `selectedType="gemini-api-key".`;
+    hint = '';
+  }
+
+  // Optional live confirmation — only when static config is already valid AND
+  // the caller asked for it. A live miss is a soft downgrade, never a RED.
+  let live = { ran: false, ok: false, note: 'not run (static check only)' };
+  if (state === 'valid' && options.live) {
+    live = await geminiAdapter._liveAuthProbe(options);
+    if (live.ok) {
+      detail += ` Live probe confirmed (${live.note}).`;
+    } else {
+      state = 'unverified';
+      ok = true; // config is correct; the probe just couldn't confirm
+      detail += ` Live probe could not confirm (${live.note}); static config looks correct.`;
+      hint = 'If Gemini panels fail, check the key is billing-enabled and not rate-limited, '
+        + 'and that `gemini` is on PATH.';
+    }
+  }
+
+  return {
+    ok,
+    state,
+    keyPresent: keyState.present,
+    keySource: keyState.source,
+    selectedType,
+    detail,
+    hint,
+    live,
+  };
+}
+
 const geminiAdapter = {
   name: 'gemini',
   sessionType: 'gemini',
@@ -242,10 +492,17 @@ const geminiAdapter = {
   spawn: {
     binary: 'gemini',
     defaultArgs: [],
-    // GEMINI_API_KEY is read via `process.env` at spawn time by index.js'
-    // PTY env merge — declared here for documentation / discoverability,
-    // not for in-adapter overriding. OAuth-personal is the typical auth
-    // path (settings.json `security.auth.selectedType: 'oauth-personal'`).
+    // AUTH (Sprint 70 T2): the Gemini CLI now requires API-KEY auth — Google
+    // ends the OAuth / subscription serving path on 2026-06-18. `GEMINI_API_KEY`
+    // is read via `process.env` at spawn time by index.js' PTY env merge
+    // (loaded from ~/.termdeck/secrets.env at server boot) — declared here for
+    // documentation / discoverability, not for in-adapter overriding — AND
+    // ~/.gemini/settings.json must set `security.auth.selectedType:
+    // 'gemini-api-key'` (the mode switch; a present key is ignored while the
+    // mode is still 'oauth-personal'). Antigravity (`agy`) stays on OAuth — the
+    // two are deliberately segregated. `checkAuth()` below makes a misconfig
+    // loud. (Pre-2026-06-18 the typical path was 'oauth-personal'; it stops
+    // working after the cutoff.)
     env: {},
     // Sprint 64 T2 (carve-out 2.4) — direct spawn (no `zsh -c` wrapper) when
     // the launching command is exactly the binary name. See claude.js for the
@@ -267,6 +524,9 @@ const geminiAdapter = {
   // Sprint 50 T1 — 10th adapter field. Walks ~/.gemini/tmp/<proj>/chats.
   resolveTranscriptPath,
   bootPromptTemplate,
+  // Sprint 70 T2 — API-key auth doctor probe. See the Auth section above for
+  // states + the live-probe seam. async (raw, opts) -> verdict object.
+  checkAuth,
   costBand: 'pay-per-token',
   // Sprint 47 T3 — Gemini's CLI is paste-friendly per the single-JSON-object
   // session shape captured in Sprint 45 T2; bracketed-paste injects cleanly.
@@ -280,4 +540,11 @@ const geminiAdapter = {
   },
 };
 
+// Sprint 70 T2 — monkey-patchable test seams for `checkAuth` (same pattern as
+// cli/src/doctor.js `_fetchLatest`). Attached to the adapter object so unit
+// tests can stub the live spawn / filesystem reads and stay hermetic.
+geminiAdapter._geminiApiKeyState = _geminiApiKeyState;
+geminiAdapter._readGeminiSettings = _readGeminiSettings;
+geminiAdapter._liveAuthProbe = _liveAuthProbe;
+
 module.exports = geminiAdapter;

package/packages/server/src/agent-adapters/grok-models.js

@@ -1,49 +1,61 @@
-// Grok model selection — Sprint 45 T3
+// Grok model selection — Sprint 45 api.x.ai lineup + Sprint 70 Grok Build, MERGED (additive).
 //
-// `grok-dev` (the superagent-ai CLI) ships an 11-model lineup spanning
-// $0.2/$0.5 cheap-fast tiers up to $3/$15 flagship. The wrong default
-// silently 10x's a bill on routine tasks: a "look at this file and tell me
-// what's wrong" lane on `grok-4.20-0309-reasoning` (Heavy, $2/$6) costs the
-// same as ten lanes on `grok-4-1-fast-non-reasoning`. The orchestrator picks
-// per-lane via `chooseModel(taskHint)` at boot-prompt construction time
-// (see SPRINT-45-PREP-NOTES.md § "Concern 2: Model selection heuristic").
-// The adapter's `spawn.env.GROK_MODEL` defaults to the cheap-fast model and
-// is overridden per-lane by the launcher.
+// TWO Grok families are BOTH retained on purpose (per Joshua's directive: do NOT
+// drop the reasoning models — keep the legacy lineup, add Grok Build as an option):
 //
-// Tier table (price = USD per 1M tokens, in/out):
+//   A) api.x.ai models  — the Sprint-45 lineup INCLUDING the reasoning tiers.
+//      Auth: GROK_API_KEY / XAI_API_KEY (per-token billing). These ACCEPT a
+//      `reasoningEffort` knob. Reachable via the raw xAI REST API or a CLI that
+//      honors GROK_MODEL + GROK_API_KEY (the older `grok-dev`).
+//   B) Grok Build models — `grok-build` (coding) + `grok-composer-2.5-fast`.
+//      Auth: grok.com login (subscription). These REJECT `reasoningEffort`
+//      (grok-build → HTTP 400). The current `grok` binary (Grok Build 0.2.33)
+//      exposes ONLY these two.
 //
-//   tier               | model id                          | price    | use case
-//   ───────────────────┼───────────────────────────────────┼──────────┼──────────────────────
-//   fast-non-reasoning | grok-4-1-fast-non-reasoning       | $0.2/0.5 | DEFAULT — routine
-//   fast-reasoning     | grok-4-1-fast-reasoning           | $0.2/0.5 | light CoT under budget
-//   code               | grok-code-fast-1                  | $0.2/1.5 | code gen / refactor
-//   reasoning-deep     | grok-4.20-0309-reasoning          | $2/6     | hard problems, audit
-//   reasoning-non-cot  | grok-4.20-0309-non-reasoning      | $2/6     | high-quality non-CoT
-//   multi-agent        | grok-4.20-multi-agent-0309        | $2/6     | parallel sub-agent fan-out
-//   flagship           | grok-4-0709                       | $3/15    | when Heavy isn't enough
-//   budget-compact     | grok-3-mini                       | $0.3/0.5 | rare — usually wrong
+// ─── REACHABILITY CAVEAT (read before assuming a model just "works") ──────────
+// The adapter (grok.js) currently spawns the `grok` binary, which on this machine
+// is Grok Build — so out of the box only family (B) actually runs. To EXECUTE a
+// family-(A) reasoning model as a lane, the adapter must dispatch it to the
+// api.x.ai path / `grok-dev` instead of the Grok Build CLI. That family-dispatch
+// is a follow-up; this module restores the model OPTIONS, not the wiring that
+// routes each family to the right runtime.
 //
-// `grok-4-fast-non-reasoning`, `grok-4-fast-reasoning`, and `grok-3` are
-// legacy aliases retained for completeness but not in the heuristic switch.
+// AUTH do-nots: don't pipe GROK_API_KEY into a Grok Build spawn (it ignores it —
+// log into grok.com); conversely the reasoning models need GROK_API_KEY and an
+// api.x.ai-targeting caller — the Grok Build CLI will not run them.
+//
+// NOTE: the family-(A) ids are the Sprint-45 lineup (~2 months old). xAI rotates
+// model ids; validate against the current api.x.ai model list before relying on a
+// specific reasoning id.
 
 'use strict';
 
-// Canonical model ids. Use the symbolic key in code; the heuristic resolves
-// to the live id below. Keep these as data, not constants — Sprint 46+ may
-// gain a `taskHint -> model` override file in `~/.termdeck/`.
+// Canonical model ids, keyed by a short symbolic name. Use the key in code; the
+// live id is the value. Kept as data so a future ~/.termdeck/ override file can
+// extend it without touching call sites.
 const MODELS = {
-  'fast-non-reasoning': 'grok-4-1-fast-non-reasoning',
-  'fast-reasoning': 'grok-4-1-fast-reasoning',
-  'code': 'grok-code-fast-1',
-  'reasoning-deep': 'grok-4.20-0309-reasoning',
-  'reasoning-non-cot': 'grok-4.20-0309-non-reasoning',
-  'multi-agent': 'grok-4.20-multi-agent-0309',
-  'flagship': 'grok-4-0709',
-  'budget-compact': 'grok-3-mini',
+  // ── A) api.x.ai tiers (per-token billing; reasoningEffort-capable) ──
+  'fast-non-reasoning': 'grok-4-1-fast-non-reasoning',   // DEFAULT — routine
+  'fast-reasoning': 'grok-4-1-fast-reasoning',           // light CoT under budget
+  'code': 'grok-code-fast-1',                            // code gen / refactor
+  'reasoning-deep': 'grok-4.20-0309-reasoning',          // hard problems, audit
+  'reasoning-non-cot': 'grok-4.20-0309-non-reasoning',   // high-quality non-CoT
+  'multi-agent': 'grok-4.20-multi-agent-0309',           // parallel sub-agent fan-out
+  'flagship': 'grok-4-0709',                             // when Heavy isn't enough
+  'budget-compact': 'grok-3-mini',                       // rare — usually wrong
+  // ── B) Grok Build (grok.com subscription; reasoningEffort REJECTED → 400) ──
+  'build': 'grok-build',                                 // Grok Build coding model
+  'composer-fast': 'grok-composer-2.5-fast',             // fast / lightweight compose
 };
 
-// Legacy aliases — accepted as input to chooseModel for back-compat with
-// Joshua's earlier `grok models` outputs. Resolution table:
+// Default stays the cheap-fast api.x.ai model (the Sprint-45 default) — legacy
+// remains the base; Grok Build is opt-in via a `build`/`composer` hint or an
+// explicit GROK_MODEL. (If you'd rather default to grok-build now that the
+// installed binary is Grok Build, flip this one line — flagged for Joshua.)
+const DEFAULT_MODEL = MODELS['fast-non-reasoning'];
+
+// Legacy aliases accepted as chooseModel input for back-compat with earlier
+// `grok models` outputs.
 const LEGACY_ALIASES = {
   'grok-4-fast-non-reasoning': MODELS['fast-non-reasoning'],
   'grok-4-fast-reasoning': MODELS['fast-reasoning'],
@@ -52,64 +64,88 @@ const LEGACY_ALIASES = {
   'grok-3': MODELS['flagship'],
 };
 
-// chooseModel — orchestrator-side heuristic. Pass `taskHint` from the lane
-// brief (Sprint 46 frontmatter `model-hint: code|reasoning-deep|...`) or omit
-// for the cheap-fast default. Unknown hints fall back to the default rather
-// than throwing — the bill consequence of a typo silently routing to Heavy
-// is worse than the latency hit of cheap-fast on a hard task.
+// The Grok Build family rejects a reasoning-effort knob (grok-build → HTTP 400).
+// Every api.x.ai model accepts it. Unknown ids default to "accepts" (legacy-
+// permissive) — only the explicitly-known Grok Build models are stripped.
+const NO_REASONING_EFFORT = new Set([MODELS['build'], MODELS['composer-fast']]);
+
+// chooseModel — resolve a coarse task hint to a model id. Defaults to the
+// cheap-fast api.x.ai model for anything unrecognized (incl. no/empty/null hint).
+// Signature-compatible with the Sprint-45 chooseModel() grok.js calls no-arg.
 function chooseModel(taskHint) {
   switch (taskHint) {
-    case 'code':
-      return MODELS.code;
-    case 'multi-agent':
-      return MODELS['multi-agent'];
-    case 'reasoning-deep':
-      return MODELS['reasoning-deep'];
+    // family A — api.x.ai
+    case 'code': return MODELS.code;
+    case 'multi-agent': return MODELS['multi-agent'];
+    case 'reasoning-deep': return MODELS['reasoning-deep'];
     case 'reasoning-quick':
-    case 'fast-reasoning':
-      return MODELS['fast-reasoning'];
-    case 'reasoning-non-cot':
-      return MODELS['reasoning-non-cot'];
-    case 'flagship':
-      return MODELS.flagship;
-    case 'budget-compact':
-      return MODELS['budget-compact'];
+    case 'fast-reasoning': return MODELS['fast-reasoning'];
+    case 'reasoning-non-cot': return MODELS['reasoning-non-cot'];
+    case 'flagship': return MODELS.flagship;
+    case 'budget-compact': return MODELS['budget-compact'];
+    // family B — Grok Build (opt-in)
+    case 'build':
+    case 'grok-build': return MODELS['build'];
+    case 'composer':
+    case 'composer-fast':
+    case 'compose':
+    case 'fast':
+    case 'grok-composer-2.5-fast': return MODELS['composer-fast'];
+    // default
     case 'fast-non-reasoning':
     case undefined:
     case null:
-    case '':
-      return MODELS['fast-non-reasoning'];
+    case '': return MODELS['fast-non-reasoning'];
     default:
-      // Accept legacy aliases verbatim; otherwise fall back to cheap-fast.
       if (LEGACY_ALIASES[taskHint]) return LEGACY_ALIASES[taskHint];
       return MODELS['fast-non-reasoning'];
   }
 }
 
-// getModelInfo — for the launcher / dashboard cost annotations (Sprint 46).
-// Returns the price band so the UI can render a $-tier indicator alongside
-// the model name without each caller knowing the table.
+// getModelInfo — capability + cost lookup for callers/dashboards. Returns
+// { tier, priceIn, priceOut, reasoningEffort, role, known }. Grok Build models
+// are subscription-billed (priceIn/priceOut null). Unknown ids return a safe
+// record. (Back-compatible with the Sprint-45 shape: tier/priceIn/priceOut are
+// still present for any existing cost-annotation caller.)
 function getModelInfo(modelId) {
-  const cheap = new Set([
-    MODELS['fast-non-reasoning'],
-    MODELS['fast-reasoning'],
-    MODELS.code,
-  ]);
-  const heavy = new Set([
-    MODELS['reasoning-deep'],
-    MODELS['reasoning-non-cot'],
-    MODELS['multi-agent'],
-  ]);
-  if (cheap.has(modelId)) return { tier: 'cheap', priceIn: 0.2, priceOut: modelId === MODELS.code ? 1.5 : 0.5 };
-  if (heavy.has(modelId)) return { tier: 'heavy', priceIn: 2, priceOut: 6 };
-  if (modelId === MODELS.flagship) return { tier: 'flagship', priceIn: 3, priceOut: 15 };
-  if (modelId === MODELS['budget-compact']) return { tier: 'budget', priceIn: 0.3, priceOut: 0.5 };
-  return { tier: 'unknown', priceIn: null, priceOut: null };
+  const reasoningEffort = !NO_REASONING_EFFORT.has(modelId);
+  const cheap = new Set([MODELS['fast-non-reasoning'], MODELS['fast-reasoning'], MODELS.code]);
+  const heavy = new Set([MODELS['reasoning-deep'], MODELS['reasoning-non-cot'], MODELS['multi-agent']]);
+  if (cheap.has(modelId)) return { tier: 'cheap', priceIn: 0.2, priceOut: modelId === MODELS.code ? 1.5 : 0.5, reasoningEffort, role: 'api.x.ai cheap-fast', known: true };
+  if (heavy.has(modelId)) return { tier: 'heavy', priceIn: 2, priceOut: 6, reasoningEffort, role: 'api.x.ai reasoning/heavy', known: true };
+  if (modelId === MODELS.flagship) return { tier: 'flagship', priceIn: 3, priceOut: 15, reasoningEffort, role: 'api.x.ai flagship', known: true };
+  if (modelId === MODELS['budget-compact']) return { tier: 'budget', priceIn: 0.3, priceOut: 0.5, reasoningEffort, role: 'api.x.ai budget', known: true };
+  if (modelId === MODELS['build']) return { tier: 'subscription', priceIn: null, priceOut: null, reasoningEffort: false, role: 'Grok Build coding', known: true };
+  if (modelId === MODELS['composer-fast']) return { tier: 'subscription', priceIn: null, priceOut: null, reasoningEffort: false, role: 'Grok Build fast-compose', known: true };
+  return { tier: 'unknown', priceIn: null, priceOut: null, reasoningEffort, role: 'unknown', known: false };
+}
+
+// acceptsReasoningEffort — true only if the model supports a reasoning-effort
+// knob. Use it to GUARD request construction so a Grok Build model never gets a
+// reasoningEffort field (grok-build → 400).
+function acceptsReasoningEffort(modelId) {
+  return getModelInfo(modelId).reasoningEffort === true;
+}
+
+// sanitizeModelOptions — strips reasoning-effort fields (both spellings) when the
+// target model rejects them (the Grok Build family), so a caller that blindly
+// forwards options can't trigger the grok-build 400. Shallow copy; never mutates.
+function sanitizeModelOptions(modelId, options) {
+  const opts = { ...(options || {}) };
+  if (!acceptsReasoningEffort(modelId)) {
+    delete opts.reasoningEffort;
+    delete opts.reasoning_effort;
+  }
+  return opts;
 }
 
 module.exports = {
   MODELS,
+  DEFAULT_MODEL,
   LEGACY_ALIASES,
+  NO_REASONING_EFFORT,
   chooseModel,
   getModelInfo,
+  acceptsReasoningEffort,
+  sanitizeModelOptions,
 };