Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

35.6 KB
Raw Blame
/**
 * Ask Service
 *
 * Powers the "Ask Yourself" page — a retrieval-augmented chat with the user's
 * own digital twin. For each question:
 *
 *   1. Fan-out retrieval in parallel across memory (hybrid BM25 + vector),
 *      brain notes, autobiography stories, goals, and calendar events.
 *   2. Rerank + cap each source, then dedupe across sources.
 *   3. Assemble a persona-flavored prompt (twin tone + life context).
 *   4. Stream the completion through the active AI provider.
 *
 * The function exported here returns an async iterable of stream events:
 *   { type: 'sources', sources: Source[] }
 *   { type: 'delta', text: string }
 *   { type: 'done', answer: string, sources: Source[], providerId: string, model: string }
 *   { type: 'error', error: string }
 *
 * Routes consume this and forward as Server-Sent Events.
 */

import { getActiveProvider, getProviderById } from './providers.js';
import { hybridSearchMemories, getMemory } from './memoryBackend.js';
import { generateQueryEmbedding } from './memoryEmbeddings.js';
import { hybridSearchIngredients } from './catalogDB.js';
import { getCatalogType } from '../lib/catalogTypes.js';
import { getInboxLog, getProjects, getIdeas } from './brainStorage.js';
import { getStories } from './autobiography.js';
import { getGoals } from './identity.js';
import { getCharacter } from './character.js';
import { getEvents as getCalendarEvents } from './calendarSync.js';
import { tokenize as bm25Tokenize, STOP_WORDS } from '../lib/bm25.js';
import { VALID_MODES as STORAGE_VALID_MODES } from './askConversations.js';
import { resolveCliModel, prefixOpencodeModel, ensureLeadingSubcommand, hasModelFlag, isOpencodeCommand } from '../lib/providerModels.js';
import { isKiloCommand, ensureKiloHeadlessArgs } from '../lib/kilo.js';
import { isOpenchamberCommand, ensureOpenchamberHeadlessArgs } from '../lib/openchamber.js';
import { ensureAntigravityPrintArgs, isAntigravityCliProvider } from '../lib/antigravity.js';
import { isGrokCommand, ensureGrokHeadlessArgs } from '../lib/grok.js';
import { prepareCliPrompt } from '../lib/cliProviderArgs.js';
import { isToolFreeOneShotProvider, toolFreeOneShotArgs, toolFreeOneShotRefusal } from '../lib/providerVendors.js';
import { ServerError } from '../lib/errorHandler.js';
import { prepareCliSpawn, killProcessTree } from '../lib/bufferedSpawn.js';
import { applyCredentialBootstrap, needsProcessGroup, trackDetachedGroup } from '../lib/credentialBootstrap.js';
import { buildCliChildEnv } from '../lib/cliChildEnv.js';
import { ensureManagedRuntimeReady } from './providerExecutionReadiness.js';
import { evaluateSecretEndpoint } from '../lib/aiToolkit/endpointGuard.js';
import { iterateOpenAiChat } from '../lib/openAiChatStream.js';

// Re-export so the route can keep importing modes via askService — but
// askConversations is the source of truth (it owns the persistence schema).
export const VALID_MODES = STORAGE_VALID_MODES;
export const SOURCE_KINDS = ['memory', 'brain-note', 'autobiography', 'goal', 'calendar', 'catalog'];

const PER_SOURCE_LIMIT = {
  memory: 6,
  'brain-note': 5,
  autobiography: 3,
  goal: 5,
  calendar: 6,
  catalog: 4,
};

// Truncation caps for prompt assembly. Source snippets are short summaries;
// transcript turns are previous chat turns trimmed so multi-turn history
// can't blow the token budget alone. Snippets are also normalized at
// retrieval time (not just at prompt assembly) because they're streamed to
// the client in the `sources` SSE event and persisted into the
// conversation JSON on every assistant turn — letting full bodies through
// would bloat both wire and disk.
const SNIPPET_MAX_CHARS = 600;
const HISTORY_TURN_MAX_CHARS = 1500;

// Cap snippet at retrieval time to bound what gets persisted + sent to
// the client. Collapse whitespace and trim before slicing.
function normalizeSnippet(text) {
  if (!text) return '';
  const collapsed = String(text).replace(/\s+/g, ' ').trim();
  if (collapsed.length <= SNIPPET_MAX_CHARS) return collapsed;
  return `${collapsed.slice(0, SNIPPET_MAX_CHARS - 1)}…`;
}
// Autobiography stories grow over time — cap how many we score per question
// so a user with hundreds of stories doesn't make every Ask quadratic.
const AUTOBIO_SCAN_LIMIT = 50;
// Calendar window default + cap. ±7 days covers the ambient "what do I have
// going on" case; the per-source cap on the result list does the rest.
const CALENDAR_DEFAULT_DAYS = 7;
const CALENDAR_FETCH_LIMIT = 50;
const MS_PER_DAY = 24 * 60 * 60 * 1000;

const PERSONA_FALLBACK = `You are the user's digital twin — speak in the first person, in their voice and with their values. Be direct, specific, and practical.`;

// =============================================================================
// PARALLEL RETRIEVAL
// =============================================================================

// `gatherSources` wraps every retriever in `Promise.allSettled`, so a thrown
// error here surfaces as `status: 'rejected'` rather than killing the answer
// — that's why these functions don't carry their own try/catch.

async function retrieveMemories(question) {
  const queryEmbedding = await generateQueryEmbedding(question);
  if (!queryEmbedding) return [];
  const result = await hybridSearchMemories(question, queryEmbedding, {
    limit: PER_SOURCE_LIMIT.memory,
    ftsWeight: 0.4,
    vectorWeight: 0.6,
  });
  const hits = result?.memories || [];
  // Single missing record shouldn't drop the whole batch — allSettled per id.
  const fetched = await Promise.allSettled(hits.map((h) => getMemory(h.id)));
  const sources = [];
  for (let i = 0; i < hits.length; i++) {
    const settled = fetched[i];
    const mem = settled.status === 'fulfilled' ? settled.value : null;
    if (!mem) continue;
    sources.push({
      kind: 'memory',
      id: `memory:${mem.id}`,
      title: mem.summary || mem.type || 'Memory',
      snippet: normalizeSnippet(mem.content),
      relevance: hits[i].rrfScore ?? hits[i].similarity ?? 0.5,
      // Memory tab doesn't yet honour an `id` query param, so the chip
      // navigates to the section landing page; the memory's id is still
      // surfaced via `meta` so a future deep-link can use it without
      // changing the source contract.
      href: '/brain/memory',
      meta: { id: mem.id, type: mem.type, importance: mem.importance, updatedAt: mem.updatedAt },
    });
  }
  return sources;
}

// Creative Catalog ingredients (characters / places / objects / ideas / scenes
// / concepts) via the same RRF hybrid search the memory retriever uses, so the
// catalog slice shares Ask's scoring/budget model. Snippet is the type's
// primary-content payload field (falling back to summary/description/name).
// Vector matches only appear once embeddings are backfilled; FTS works
// immediately. No try/catch — gatherSources' allSettled isolates failures.
async function retrieveCatalog(question) {
  const queryEmbedding = await generateQueryEmbedding(question);
  const hits = await hybridSearchIngredients(question, queryEmbedding, {
    limit: PER_SOURCE_LIMIT.catalog,
    ftsWeight: 0.4,
    vectorWeight: 0.6,
  });
  return hits.map(({ ingredient: ing, rrfScore }) => {
    const t = getCatalogType(ing.type);
    // Walk the type's registry snippet keys (primaryContentKey first, then its
    // snippetFallbackKeys in order) so a match whose useful text lives in a
    // secondary field (personality / role / significance / notes) still gets a
    // meaningful snippet instead of falling through to name-only.
    const payload = ing.payload || {};
    const snippetKeys = [t?.primaryContentKey, ...(t?.snippetFallbackKeys || [])].filter(Boolean);
    const firstNonEmpty = snippetKeys.map((k) => payload[k]).find((v) => typeof v === 'string' && v.trim());
    const snippetText = firstNonEmpty || ing.name;
    return {
      kind: 'catalog',
      id: `catalog:${ing.type}:${ing.id}`,
      title: ing.name || t?.label || 'Ingredient',
      snippet: normalizeSnippet(String(snippetText || '')),
      relevance: rrfScore ?? 0.5,
      href: `/catalog/${ing.type}/${ing.id}`,
      meta: { id: ing.id, type: ing.type, tags: ing.tags },
    };
  });
}

// askService scores by query-term overlap, not BM25. We reuse the BM25
// module's lowercase / punctuation / stopword tokenizer so the stopword
// list stays in lockstep, then tighten the result for lexical-overlap
// scoring — drop tokens shorter than 3 chars (single-letter / two-letter
// query tokens are too noisy for our overlap ratio) and re-check stopwords
// in case the upstream list was extended after tokenization.
function tokenize(text) {
  return bm25Tokenize(text).filter((t) => t.length >= 3 && !STOP_WORDS.has(t));
}

function lexicalScore(text, queryTokens) {
  if (!queryTokens.length) return 0;
  const docTokens = tokenize(text);
  if (!docTokens.length) return 0;
  const docSet = new Set(docTokens);
  let hits = 0;
  for (const q of queryTokens) {
    if (docSet.has(q)) hits++;
  }
  return hits / queryTokens.length;
}

function rankAndCap(candidates, kind) {
  return candidates
    .filter((c) => c.relevance > 0)
    .sort((a, b) => b.relevance - a.relevance)
    .slice(0, PER_SOURCE_LIMIT[kind]);
}

async function retrieveBrainNotes(question, queryTokens) {
  if (!queryTokens.length) return [];
  // Memory already covers free-form thoughts via the brain→memory bridge;
  // this layer catches the structured records (ideas/projects/inbox) the
  // user is more likely to call by name.
  const [ideasArr, projectsArr, inbox] = await Promise.all([
    getIdeas(),
    getProjects(),
    getInboxLog({ limit: 200 }),
  ]);

  const candidates = [];
  // Brain Memory tab doesn't currently consume `type`/`id` query params, so
  // chips land on the section page; the record id rides in `meta` for a
  // future record-level deep-link to consume without touching the source
  // shape. (Same pattern as memory/calendar after round 18.)
  // The title is already shown on the chip and prompt source line, so the
  // snippet should carry the body (description) rather than restate the
  // title. Fall back to the title only when the description is missing
  // entirely. Lexical scoring downstream still includes the title via the
  // `${c.title} ${c.snippet}` join, so ranking quality is unchanged.
  for (const idea of ideasArr || []) {
    const body = (idea.description || '').trim();
    candidates.push({ kind: 'brain-note', subkind: 'idea', recordId: idea.id, title: idea.title || '(idea)', snippet: normalizeSnippet(body || idea.title || ''), href: '/brain/memory', updatedAt: idea.updatedAt || idea.createdAt });
  }
  for (const proj of projectsArr || []) {
    const body = (proj.description || '').trim();
    candidates.push({ kind: 'brain-note', subkind: 'project', recordId: proj.id, title: proj.title || '(project)', snippet: normalizeSnippet(body || proj.title || ''), href: '/brain/memory', updatedAt: proj.updatedAt || proj.createdAt });
  }
  for (const entry of inbox || []) {
    // Brain inbox records use `capturedText` / `capturedAt` (see
    // brainStorage.getInboxLog). Fall back to legacy field names for
    // forward-compat with any older entries that may exist on disk.
    const text = entry.capturedText || entry.text || entry.summary || '';
    if (!text) continue;
    candidates.push({ kind: 'brain-note', subkind: 'inbox', recordId: entry.id, title: text.slice(0, 80), snippet: normalizeSnippet(text), href: '/brain/inbox', updatedAt: entry.capturedAt || entry.timestamp || entry.createdAt });
  }

  for (const c of candidates) {
    c.relevance = lexicalScore(`${c.title} ${c.snippet}`, queryTokens);
    c.id = `brain-note:${c.subkind}:${c.recordId}`;
    c.meta = { subkind: c.subkind, recordId: c.recordId, updatedAt: c.updatedAt };
  }
  return rankAndCap(candidates, 'brain-note');
}

async function retrieveAutobiography(queryTokens) {
  if (!queryTokens.length) return [];
  const stories = await getStories();
  // Stories accumulate over time; scoring everything is wasteful when only
  // the per-source cap survives. Trim to the most recent slice first —
  // getStories already sorts newest-first.
  const recent = (stories || []).slice(0, AUTOBIO_SCAN_LIMIT);
  const ranked = recent.map((s) => ({
    kind: 'autobiography',
    id: `autobiography:${s.id}`,
    title: s.themeId ? `${s.themeId} — ${(s.promptText || '').slice(0, 60)}` : (s.promptText || 'Autobiography'),
    snippet: normalizeSnippet(s.content),
    href: '/digital-twin/autobiography',
    relevance: lexicalScore(`${s.promptText || ''} ${s.content || ''}`, queryTokens),
    meta: { themeId: s.themeId, createdAt: s.createdAt },
  }));
  return rankAndCap(ranked, 'autobiography');
}

async function retrieveGoals(queryTokens) {
  // Skip the full goals load on tokenless / noise-only questions ("hi",
  // "ok") — without lexical signal the active-goal floor would otherwise
  // surface unrelated goals on every empty-ish query.
  if (!queryTokens.length) return [];
  const goalsData = await getGoals();
  const goals = goalsData?.goals || [];
  // Active goals get a small floor so they surface even on weak lexical
  // matches — your in-flight goals are nearly always relevant context.
  const ranked = goals.map((g) => ({
    kind: 'goal',
    id: `goal:${g.id}`,
    title: g.title || '(goal)',
    snippet: normalizeSnippet([g.description, g.horizon ? `horizon: ${g.horizon}` : '', g.status ? `status: ${g.status}` : ''].filter(Boolean).join(' · ')),
    href: `/digital-twin/goals?id=${encodeURIComponent(g.id)}`,
    relevance: lexicalScore(`${g.title || ''} ${g.description || ''} ${(g.tags || []).join(' ')}`, queryTokens) + (g.status === 'active' ? 0.05 : 0),
    meta: { status: g.status, horizon: g.horizon, category: g.category },
  }));
  return rankAndCap(ranked, 'goal');
}

async function retrieveCalendar(queryTokens, timeWindow) {
  if (!queryTokens.length) return [];
  const now = Date.now();
  const days = Number(timeWindow?.days) || CALENDAR_DEFAULT_DAYS;
  const startDate = timeWindow?.startDate || new Date(now - days * MS_PER_DAY).toISOString();
  const endDate = timeWindow?.endDate || new Date(now + days * MS_PER_DAY).toISOString();
  const result = await getCalendarEvents({ startDate, endDate, limit: CALENDAR_FETCH_LIMIT });
  const events = result?.events || [];
  const ranked = events.map((e) => {
    const text = `${e.title || ''} ${e.description || ''} ${e.location || ''}`.trim();
    // Emit raw ISO startTime (or whatever the calendar gave us) — formatting
    // via toLocaleString() would silently apply the *server* TZ/locale,
    // baking inconsistent timestamps into prompts when the server and user
    // disagree on timezone.
    return {
      kind: 'calendar',
      id: `calendar:${e.id || `${e.startTime}-${e.title}`}`,
      title: e.title || '(event)',
      snippet: normalizeSnippet([e.startTime || '', e.location || '', (e.description || '').slice(0, 200)].filter(Boolean).join(' · ')),
      // AgendaTab doesn't currently honour a `date` query param. Land the
      // chip on the agenda and stash the timestamp + accountId in meta so
      // a future deep-link wiring can pick them up without touching the
      // source contract.
      href: '/calendar/agenda',
      relevance: lexicalScore(text, queryTokens),
      meta: { startTime: e.startTime, endTime: e.endTime, accountId: e.accountId },
    };
  });
  return rankAndCap(ranked, 'calendar');
}

// =============================================================================
// AGGREGATION
// =============================================================================

export async function gatherSources(question, { timeWindow, maxSources = 12 } = {}) {
  const queryTokens = tokenize(question);

  // Fan out — each retriever is independently failable, so allSettled keeps
  // a single-source outage from killing the answer.
  const [memSettled, brainSettled, autoSettled, goalSettled, calSettled, catSettled] = await Promise.allSettled([
    retrieveMemories(question),
    retrieveBrainNotes(question, queryTokens),
    retrieveAutobiography(queryTokens),
    retrieveGoals(queryTokens),
    retrieveCalendar(queryTokens, timeWindow),
    retrieveCatalog(question),
  ]);

  const all = [
    ...(memSettled.status === 'fulfilled' ? memSettled.value : []),
    ...(brainSettled.status === 'fulfilled' ? brainSettled.value : []),
    ...(autoSettled.status === 'fulfilled' ? autoSettled.value : []),
    ...(goalSettled.status === 'fulfilled' ? goalSettled.value : []),
    ...(calSettled.status === 'fulfilled' ? calSettled.value : []),
    ...(catSettled.status === 'fulfilled' ? catSettled.value : []),
  ];

  // Dedupe by id (parallel retrievers can occasionally surface the same
  // record via the brain→memory bridge).
  const seen = new Set();
  const deduped = [];
  for (const s of all) {
    if (seen.has(s.id)) continue;
    seen.add(s.id);
    deduped.push(s);
  }

  // Source-weighted final ranking — memory and goals are the highest-signal
  // PortOS surfaces; calendar wins time-bounded questions; autobiography is
  // long-form so it ranks last unless lexical match is very strong.
  const KIND_WEIGHT = { memory: 1.0, goal: 0.95, 'brain-note': 0.85, calendar: 0.85, catalog: 0.8, autobiography: 0.7 };
  deduped.sort((a, b) => (b.relevance * (KIND_WEIGHT[b.kind] || 0.5)) - (a.relevance * (KIND_WEIGHT[a.kind] || 0.5)));

  return deduped.slice(0, Math.max(1, Math.min(50, maxSources)));
}

// =============================================================================
// PROMPT ASSEMBLY
// =============================================================================

const MODE_DIRECTIVES = {
  ask: `Answer the question as the user would answer it themselves, drawing on their notes, memories, and goals below. If the sources don't contain the answer, say so plainly — don't fabricate.`,
  advise: `You are advising the user. Use the sources to ground the advice in their own life: their goals, their constraints, what they've already decided. Push back where their stated goals contradict the question.`,
  draft: `Draft text in the user's voice for the recipient/platform they specified. Keep it tight and authentic to the tone in the sources. Return only the drafted text — no preamble, no commentary.`,
};

export async function buildPersonaPreamble() {
  // Only name/class are read below, so skip both derived fan-outs — this runs per /ask
  // question.
  const character = await getCharacter({ withSkills: false, withMetrics: false }).catch(() => null);
  // The character sheet is the closest thing to a persona surface today.
  // Autobiography stories carry the voice; we sample the most recent one
  // separately in the source pipeline. Keep this preamble small.
  if (!character?.name && !character?.class) return PERSONA_FALLBACK;
  const name = character?.name || 'the user';
  return `You are ${name}'s digital twin. Speak in the first person, in their voice. Be direct, specific, and grounded in the sources below. Where the user's perspective is unclear, say so explicitly rather than guessing.`;
}

function formatSourcesForPrompt(sources) {
  if (!sources?.length) return 'No retrieved sources for this question.';
  const lines = ['## Retrieved Sources', ''];
  sources.forEach((s, i) => {
    const tag = `[${i + 1}]`;
    // Snippets are already normalized + capped at retrieval time, so we
    // don't repeat the trimming here.
    lines.push(`${tag} ${s.kind} — ${s.title}`);
    if (s.snippet) lines.push(`    ${s.snippet}`);
  });
  return lines.join('\n');
}

function formatTranscriptForPrompt(history = []) {
  if (!history.length) return '';
  const lines = ['## Conversation so far'];
  for (const turn of history) {
    const who = turn.role === 'assistant' ? 'You (twin)' : 'User';
    lines.push(`${who}: ${(turn.content || '').slice(0, HISTORY_TURN_MAX_CHARS)}`);
  }
  return lines.join('\n');
}

export async function buildPrompt({ question, mode = 'ask', sources = [], history = [] }) {
  const persona = await buildPersonaPreamble();
  const directive = MODE_DIRECTIVES[mode] || MODE_DIRECTIVES.ask;
  const transcript = formatTranscriptForPrompt(history);
  // Citation instruction is only useful for `ask`/`advise` answers — `draft`
  // mode produces text in the user's voice for an external recipient who
  // would never want raw `[1]`-style markers leaking into the output.
  const citeInstruction = mode === 'draft'
    ? 'Use the sources below to inform tone and content, but do NOT include any citation markers, bracket numbers, or source references in the drafted text.'
    : 'Cite sources inline using their bracket numbers, e.g. [1] [3]. Only cite sources you actually relied on.';
  return [
    persona,
    '',
    directive,
    '',
    citeInstruction,
    '',
    formatSourcesForPrompt(sources),
    '',
    transcript,
    '',
    `## Question`,
    question,
  ].join('\n');
}

// =============================================================================
// PROVIDER STREAMING
// =============================================================================

async function pickProvider(providerId) {
  if (providerId) {
    const p = await getProviderById(providerId).catch(() => null);
    if (p?.enabled) return p;
  }
  const active = await getActiveProvider().catch(() => null);
  if (active?.enabled) return active;
  throw new Error('No AI provider available');
}

/**
 * The provider an Ask turn will run on, resolved up front so an HTTP caller can
 * be refused with a 403 before any conversation write or SSE handshake.
 *
 * Ask hands the model the caller's own question, so a provider that cannot run
 * tool-free (#9008) — an agent CLI such as agy — needs host control. Returns
 * null when no provider is available; `runAsk` reports that on the stream.
 *
 * @param {string} [providerId]
 * @param {{ hasHostControl?: boolean }} [options] - server-derived authority
 * @returns {Promise<object|null>}
 * @throws {ServerError} 403 HOST_CONTROL_FORBIDDEN
 */
export async function resolveAskProvider(providerId, { hasHostControl = false } = {}) {
  const provider = await pickProvider(providerId).catch(() => null);
  if (!provider) return null;
  const refusal = toolFreeOneShotRefusal(provider, hasHostControl);
  if (refusal) throw new ServerError(refusal.message, { status: refusal.status, code: refusal.code });
  return provider;
}

/**
 * Stream a completion from an API-style provider. Yields text chunks.
 * Falls back to a single-shot call for non-streaming providers (CLI).
 *
 * `signal` (optional) is an external AbortSignal — when the caller aborts
 * (e.g. SSE client disconnects), the provider fetch / child process is
 * cancelled so we stop wasting tokens/CPU on a stream nobody's reading.
 */
async function* streamCompletion(provider, model, prompt, signal) {
  if (provider.type === 'api') {
    // Never send the API key to an arbitrary/metadata host (SSRF / key
    // exfiltration). Keyless local-LLM calls skip this guard entirely.
    if (provider.apiKey) {
      const guard = evaluateSecretEndpoint(provider.endpoint, {
        allowCustomEndpoint: provider.allowCustomEndpoint === true,
      });
      if (!guard.allowed) {
        throw new Error(`Provider endpoint blocked: ${guard.reason}`);
      }
    }
    const ready = await ensureManagedRuntimeReady(provider);
    if (!ready.success) {
      throw new Error(ready.error);
    }
    for await (const chunk of iterateOpenAiChat({
      endpoint: provider.endpoint,
      apiKey: provider.apiKey,
      model,
      messages: [{ role: 'user', content: prompt }],
      temperature: 0.4,
      signal,
      timeoutMs: provider.timeout || 300000,
    })) {
      // Ask's public SSE contract remains content-only. The shared transport
      // still parses reasoning/usage frames so lifecycle and compatibility
      // decisions stay canonical without exposing a new Ask event shape.
      if (chunk.kind === 'content') yield chunk.text;
    }
    if (signal?.aborted) return;
    return;
  }

  // CLI providers can't stream chunked text out of a child process without
  // a lot more wiring; fall back to a single-shot call via the shared
  // brain-style invocation pattern. The prompt goes via stdin (not argv)
  // because Ask prompts can run tens of thousands of characters once
  // sources + history are concatenated, which exceeds OS argv limits
  // (especially on Windows ~32k).
  const { spawn } = await import('../lib/childProcess.js');
  let args = [...(provider.args || [])];
  // OpenCode runs headless via the `run` subcommand (reads the prompt from
  // stdin); ensure it leads the argv even if a customized/TUI provider config
  // omitted it — a bare `opencode` launches the interactive TUI, which never
  // consumes the piped prompt and hangs until the provider timeout fires.
  if (isOpencodeCommand(provider?.command)) args = ensureLeadingSubcommand(args, 'run');
  if (provider.headlessArgs?.length) args.push(...provider.headlessArgs);
  const cliModel = resolveCliModel(model);
  if (isAntigravityCliProvider(provider)) {
    // Antigravity (`agy --print <prompt>`): built LAST so the print marker stays
    // the final token — anything appended after it (headlessArgs, --model) would
    // be swallowed as the prompt text. `--model` is injected here, gated on the
    // configured-default sentinel and any user-baked pin.
    args = ensureAntigravityPrintArgs(args, { model: cliModel, models: provider?.models });
  } else if (provider.id === 'gemini-cli') {
    if (!args.includes('--output-format') && !args.includes('-o')) args.push('--output-format', 'text');
    if (cliModel) args.push('--model', cliModel);
  } else if (isOpencodeCommand(provider?.command)) {
    // OpenCode addresses its Ollama model as `ollama/<id>`; respect a user-baked
    // -m/--model pin (mirrors buildCliArgs) rather than duplicating the flag.
    if (cliModel && !hasModelFlag(args)) args.push('--model', prefixOpencodeModel(provider, cliModel));
  } else if (isGrokCommand(provider?.command)) {
    // Grok reads its prompt from --prompt-file /dev/stdin and needs plain output;
    // ensureGrokHeadlessArgs adds both, with the read-only permission mode
    // rather than its agent-path bypass.
    args = ensureGrokHeadlessArgs(args, cliModel, { toolFree: true });
  } else if (isKiloCommand(provider?.command)) {
    // Kilo forks OpenCode's `run`; its `--auto` approval posture is stripped
    // below with every other bypass.
    args = ensureKiloHeadlessArgs(args, cliModel);
  } else if (isOpenchamberCommand(provider?.command)) {
    // OpenChamber's prompt path is a control-plane action, not a flag: without
    // `session create` the bare binary starts its SERVER. The builder also drops
    // a model id that is not `provider/model`, which its CLI rejects outright.
    args = ensureOpenchamberHeadlessArgs(args, cliModel);
  } else if (cliModel) {
    args.push('--model', cliModel);
  }
  // The question is caller text, so the answer runs tool-free (#9008): every
  // approval-bypass flag goes — whether saved in provider.args or added by a
  // vendor builder above — and claude/grok/pi get their tool-disable switch.
  // A vendor with no such switch was already refused for a caller without host
  // control (resolveAskProvider / runAsk).
  args = toolFreeOneShotArgs(provider, args).args;
  // Deliver the prompt per provider convention: antigravity gets it as the
  // --print VALUE (agy doesn't read stdin); grok's /dev/stdin sentinel via stdin
  // (POSIX) / temp file (Windows); everyone else via stdin (writePromptToStdin).
  const { args: deliveredArgs, useStdin: writePromptToStdin, cleanup: cleanupPromptFile } = prepareCliPrompt(provider.command, args, prompt);
  // Shared composition (provider.envVars + OpenCode models map + CLAUDECODE
  // strip) — see buildCliChildEnv. No cwd is passed to spawn below, so there is
  // no PWD to pin; no `guard` — the argv above is tool-free for every vendor
  // that can be, and host-control-gated for the rest. Routing
  // through the shared builder also brings the OpenCode declared-models map here
  // for the first time, so the `--model` this path injects above isn't rejected
  // by an Ollama-backed OpenCode provider (the #2190 fix, previously applied
  // only at the runner/agent sites).
  const childEnv = buildCliChildEnv({ provider, model: cliModel });
  // Resolve a bare npm-installed CLI (a .cmd/.bat shim on Windows) to its real
  // path and wrap it as `cmd.exe /c <path>` so spawn() under shell:false can
  // launch it — a bare shim name ENOENTs otherwise. No-op off Windows. Mirrors
  // the runner / agent / vision spawn paths. Resolved against childEnv so a
  // provider PATH override is honored.
  // Credential-bootstrap wrap first (credentialBootstrap.js): Ask carries
  // private records, and a bare harness would fall through to the machine's
  // ambient vendor auth instead of the backend this provider is configured for.
  const bootstrapped = applyCredentialBootstrap(provider, provider.command, deliveredArgs);
  // A bootstrap-wrapped child is the WRAPPER supervising the harness, so both
  // stop paths below — the timeout and the user's abort — must signal the whole
  // process group or the harness keeps running (and keeps reading the private
  // records this call handed it) past the rejection (#7496).
  const processGroup = needsProcessGroup(bootstrapped.wrapped);
  const { command: spawnCommand, args: spawnArgs } = prepareCliSpawn(bootstrapped.command, bootstrapped.args, childEnv);
  const out = await new Promise((resolve, reject) => {
    let buf = '';
    const child = spawn(spawnCommand, spawnArgs, {
      env: childEnv,
      stdio: ['pipe', 'pipe', 'pipe'],
      shell: false,
      detached: processGroup,
    });
    // Remember the detached group so the graceful-shutdown sweep can reach it:
    // detaching moved this child out of the server's own process group, and a
    // shutdown driven by a signal to THAT group would otherwise orphan it (#7496).
    trackDetachedGroup(child, processGroup);

    // Single settlement gate — the timer, the abort listener, and the close
    // handler are all racing each other. Without a settled flag, SIGKILL on a
    // platform that doesn't kill the child synchronously would let the timer
    // fire later and try to settle a Promise that's already done.
    let settled = false;
    let timer = null;
    const cleanup = () => {
      if (timer) { clearTimeout(timer); timer = null; }
      signal?.removeEventListener('abort', onAbort);
      cleanupPromptFile();
    };
    const settle = (fn, value) => {
      if (settled) return;
      settled = true;
      cleanup();
      fn(value);
    };

    child.stdout.on('data', (d) => { buf += d.toString(); });
    child.stderr.on('data', (d) => { buf += d.toString(); });

    timer = setTimeout(() => {
      killProcessTree(child, 'SIGKILL', { processGroup });
      settle(reject, new Error('CLI timed out'));
    }, provider.timeout || 300000);

    function onAbort() {
      killProcessTree(child, 'SIGKILL', { processGroup });
      settle(reject, new Error('aborted'));
    }
    if (signal) {
      if (signal.aborted) { onAbort(); return; }
      signal.addEventListener('abort', onAbort, { once: true });
    }

    child.on('close', (code) => {
      if (code === 0) settle(resolve, buf);
      else settle(reject, new Error(`CLI exited ${code}: ${buf.slice(0, 500)}`));
    });
    child.on('error', (err) => { settle(reject, err); });

    // Pipe the prompt in via stdin so we never blow the OS argv limit on
    // long retrieval-augmented prompts.
    child.stdin.on('error', () => { /* child may close stdin first; the close handler resolves */ });
    // When grok is delivered via a Windows temp file the prompt is already on
    // disk — just close stdin instead of writing it.
    if (writePromptToStdin) child.stdin.end(prompt);
    else child.stdin.end();
  });
  yield out;
}

// =============================================================================
// PUBLIC ENTRY
// =============================================================================

/**
 * Run an Ask turn end-to-end. Returns an async iterable of stream events.
 *
 * @param {Object} opts
 * @param {string} opts.question - The user's question.
 * @param {'ask'|'advise'|'draft'} [opts.mode]
 * @param {Array} [opts.history] - Prior turns for multi-turn context.
 * @param {Object} [opts.timeWindow] - { days?, startDate?, endDate? } for calendar.
 * @param {number} [opts.maxSources]
 * @param {string} [opts.providerId]
 * @param {string} [opts.model]
 * @param {object} [opts.provider] - already resolved and gated by
 *   `resolveAskProvider`; skips resolution here.
 * @param {() => (boolean|Promise<boolean>)} [opts.hasHostControl] - the
 *   caller's server-derived authority, consulted only when the resolved
 *   provider cannot run tool-free (#9008). Absent means none.
 * @param {AbortSignal} [opts.signal] - Aborts retrieval/provider stream when
 *   the caller (e.g. SSE client) disconnects, so we don't keep generating
 *   tokens for a closed connection.
 */
export async function* runAsk({
  question,
  mode = 'ask',
  history = [],
  timeWindow,
  maxSources = 12,
  providerId,
  model,
  provider: resolvedProvider = null,
  hasHostControl,
  signal,
}) {
  if (!question || typeof question !== 'string' || !question.trim()) {
    yield { type: 'error', error: 'question is required' };
    return;
  }
  if (!VALID_MODES.has(mode)) {
    yield { type: 'error', error: `invalid mode: ${mode}` };
    return;
  }

  let sources;
  try {
    sources = await gatherSources(question, { timeWindow, maxSources });
  } catch (err) {
    yield { type: 'error', error: `Source retrieval failed: ${err.message}` };
    return;
  }

  if (signal?.aborted) return;
  yield { type: 'sources', sources };

  let provider = resolvedProvider;
  if (!provider) {
    try {
      provider = await pickProvider(providerId);
    } catch (err) {
      yield { type: 'error', error: err.message };
      return;
    }
    // Authority is asked for only when it matters: a voice turn re-verifies
    // its session on every call.
    if (!isToolFreeOneShotProvider(provider) && await hasHostControl?.() !== true) {
      const refusal = toolFreeOneShotRefusal(provider, false);
      yield { type: 'error', error: refusal.message, code: refusal.code };
      return;
    }
  }
  const effectiveModel = model || provider.defaultModel;
  // API providers will fail with a vague upstream 4xx if `model` is null —
  // surface a clear actionable error before we even open the connection.
  // CLI providers can fall back to whatever the binary defaults to, so we
  // only enforce this for the `api` type.
  if (provider.type === 'api' && !effectiveModel) {
    yield { type: 'error', error: `Provider "${provider.id}" has no default model — pass an explicit model or set provider.defaultModel.` };
    return;
  }
  const prompt = await buildPrompt({ question, mode, sources, history });

  const startedAt = Date.now();
  console.log(`🪞 Ask start: ${provider.id}/${effectiveModel} mode=${mode} sources=${sources.length}`);

  // Stream errors are caught here (rather than letting them bubble) so the
  // route can flush a terminal SSE 'error' frame to the client — once the
  // stream has started, we can't change to a 5xx response any longer.
  // Chunks accumulate into an array and join once at the end; `+=` would be
  // O(n²) on long responses where each delta re-allocates the running string.
  const chunks = [];
  try {
    for await (const chunk of streamCompletion(provider, effectiveModel, prompt, signal)) {
      if (signal?.aborted) return;
      if (!chunk) continue;
      chunks.push(chunk);
      yield { type: 'delta', text: chunk };
    }
  } catch (err) {
    if (signal?.aborted) return;
    yield { type: 'error', error: `Provider stream failed: ${err.message}` };
    return;
  }
  if (signal?.aborted) return;

  const answer = chunks.join('');
  console.log(`✅ Ask complete: ${provider.id}/${effectiveModel} ${Date.now() - startedAt}ms ${answer.length} chars`);

  yield {
    type: 'done',
    answer,
    sources,
    providerId: provider.id,
    model: effectiveModel,
  };
}