osborn 0.5.2 → 0.5.5

package/dist/fast-brain.d.ts

@@ -1,31 +1,40 @@
 /**
- * Fast Brain Agent — Middle-tier intelligence for the Voice AI System
+ * Fast Brain — Central Orchestrator for the Voice AI System
  *
- * A fast intermediary between the realtime voice model and the Claude SDK agent.
- * Uses direct API calls for ~2 second responses.
+ * The sole intelligence layer between the user and all backend capabilities.
+ * The realtime voice model is a thin teleprompter — it speaks what this module returns.
  *
  * Capabilities:
  * - Read/write session files (spec.md + library/)
  * - Web search for quick factual lookups
  * - Record user decisions and preferences into spec.md
- * - Post-research: synthesize findings into spec.md
- * - Escalate to ask_agent when deeper research is needed
+ * - Trigger deep research (via callbacks to index.ts)
+ * - Generate teleprompter scripts for ALL voice output
+ * - Post-research: synthesize findings from JSONL into spec.md + voice scripts
+ * - Generate visual documents (comparison, diagram, analysis, summary)
  *
- * Key constraint: The fast brain NEVER calls ask_agent. The realtime model is always the router.
+ * Central function: askFastBrain() — ALL user questions route here.
+ * It returns a FastBrainResponse with a teleprompter script the voice model reads verbatim.
  *
  * Auth chain (tried in order):
  * 1. ANTHROPIC_API_KEY env var → Anthropic SDK (Haiku)
  * 2. ANTHROPIC_AUTH_TOKEN env var → Anthropic SDK (Haiku)
  * 3. GOOGLE_API_KEY env var → Gemini Flash fallback
- *
- * Note: Claude Code OAuth (macOS Keychain) was tested but Anthropic's Messages API
- * rejects OAuth tokens with 401 "OAuth authentication is currently not supported."
  */
 /**
  * Extract useful content snippets from tool responses, truncated by tool type.
  * Returns null for tools with no useful content (Write confirmations, etc.)
  */
 export declare function extractToolContent(toolName: string, toolInput: any, toolResponse: any): string | null;
+/** A single voice conversation turn from the realtime LLM's chatCtx */
+export interface ConversationTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+/** Clear fast brain session state — call on disconnect/reconnect/session switch */
+export declare function clearFastBrainSession(): void;
+/** @deprecated Use clearFastBrainSession() instead */
+export declare function clearFastBrainHistory(): void;
 /**
  * Ask the fast brain a question with access to session files and web search.
  * Returns an answer or "NEEDS_DEEPER_RESEARCH: ..." for escalation.
@@ -35,17 +44,49 @@ export declare function extractToolContent(toolName: string, toolInput: any, too
  * @param researchContext - Optional snapshot of the live research log.
  * ~2 second response time for most queries.
  */
-export declare function askHaiku(workingDir: string, sessionId: string, question: string, researchContext?: string): Promise<string>;
+export declare function askHaiku(workingDir: string, sessionId: string, question: string, researchContext?: string, chatHistory?: ConversationTurn[], sendToChat?: (text: string) => void, sessionBaseDir?: string): Promise<string>;
+/** Callbacks for the fast brain to trigger side effects in index.ts */
+export interface FastBrainCallbacks {
+    triggerResearch: (task: string) => void;
+    queueVoice: (script: string) => void;
+    sendToFrontend: (data: any) => void;
+}
+/** Structured response from the fast brain orchestrator */
+export interface FastBrainResponse {
+    /** Teleprompter script for the voice model to speak */
+    script: string;
+    /** Response type for caller routing */
+    type: 'answer' | 'research_started' | 'recorded' | 'question';
+}
+/**
+ * Central orchestrator — ALL user questions from the realtime model come here.
+ * Routes to: direct answer, research triggering, decision recording, or document generation.
+ * Returns a teleprompter script the voice model reads verbatim.
+ */
+export declare function askFastBrain(workingDir: string, sessionId: string, question: string, opts: {
+    chatHistory?: ConversationTurn[];
+    researchContext?: string;
+    callbacks: FastBrainCallbacks;
+    sessionBaseDir?: string;
+}): Promise<FastBrainResponse>;
 /**
  * Process a batch of research content chunks through the fast brain.
  * Updates spec.md and library/ files incrementally during research.
  *
  * @param isRefinement - true for the final post-research consolidation pass (higher token budget)
  */
-export declare function processResearchChunk(workingDir: string, sessionId: string, task: string, contentChunks: string[], isRefinement?: boolean): Promise<{
+export declare function processResearchChunk(workingDir: string, sessionId: string, task: string, contentChunks: string[], isRefinement?: boolean, sessionBaseDir?: string): Promise<{
     spec: string | null;
     libraryFiles: string[];
 } | null>;
+/**
+ * Augment agent SDK research results with context from spec.md.
+ * Passes ALL specific details through verbatim — only ADDS context annotations.
+ * The voice model downstream handles summarization for speech.
+ *
+ * Falls back to returning the original result if the fast brain is unavailable.
+ */
+export declare function augmentResearchResult(workingDir: string, sessionId: string, task: string, agentResult: string): Promise<string>;
 /**
  * Update spec.md and library/ files after research completes.
  * Reads FULL untruncated data directly from Claude Agent SDK JSONL files
@@ -58,7 +99,78 @@ export declare function processResearchChunk(workingDir: string, sessionId: stri
  *
  * Returns { spec, libraryFiles } or null if update failed.
  */
-export declare function updateSpecFromJSONL(workingDir: string, sessionId: string, task: string, researchLog: string[]): Promise<{
+export declare function updateSpecFromJSONL(workingDir: string, sessionId: string, task: string, researchLog: string[], sessionBaseDir?: string): Promise<{
     spec: string | null;
     libraryFiles: string[];
 } | null>;
+/**
+ * Fire-and-forget: Write a user question to spec.md Open Questions > From User
+ * before the agent starts researching. Ensures every escalated question is tracked.
+ *
+ * Uses a simple LLM call to fuzzy-match existing questions and avoid duplicates.
+ * Skips if spec.md doesn't exist yet or no provider is available.
+ */
+export declare function writeQuestionToSpec(workingDir: string, sessionId: string, question: string): Promise<void>;
+/**
+ * Fire-and-forget: Check if substantial agent output answers any open questions in spec.md.
+ * Debounced (3s) to prevent flooding during rapid tool_result sequences.
+ *
+ * When a question is answered, marks it with [x] and moves the answer to Findings.
+ */
+export declare function checkOutputAgainstQuestions(workingDir: string, sessionId: string, output: string, outputType: 'tool_result' | 'assistant_text'): Promise<void>;
+/**
+ * Generate a natural, contextualized voice update from raw research events.
+ * Called by scheduleResearchBatch() instead of injecting raw events directly.
+ *
+ * Returns a natural 1-2 sentence update, or null if nothing interesting to say.
+ * 3-second timeout — returns null if the LLM is too slow.
+ */
+export declare function contextualizeResearchUpdate(workingDir: string, sessionId: string, task: string, batchEvents: string[], researchLog: string[], chatHistory?: ConversationTurn[], sessionBaseDir?: string): Promise<string | null>;
+/**
+ * Generate a proactive conversational prompt to keep the user engaged during research.
+ * Called periodically (every 15s) during active research.
+ *
+ * Can ask open questions, discuss implications of findings, or give progress with depth.
+ * Returns null/NOTHING if nothing interesting to say.
+ * 3-second timeout.
+ */
+export declare function generateProactivePrompt(workingDir: string, sessionId: string, task: string, researchLog: string[], previousPrompts: string[], sessionBaseDir?: string): Promise<string | null>;
+/**
+ * Generate a structured visual document (comparison table, Mermaid diagram,
+ * analysis, or summary) from research findings.
+ *
+ * Reads spec.md, JSONL results, and library for context.
+ * Writes the result to library/ and returns the filename + content.
+ */
+export declare function generateVisualDocument(workingDir: string, sessionId: string, request: string, documentType: 'comparison' | 'diagram' | 'analysis' | 'summary', sessionBaseDir?: string): Promise<{
+    fileName: string;
+    content: string;
+} | null>;
+/**
+ * Generate a complete teleprompter script from research results.
+ * Replaces augmentResearchResult + extractPriorityContent.
+ * Reads full JSONL and produces a spoken monologue.
+ */
+export declare function processResearchCompletion(workingDir: string, sessionId: string, task: string, agentResult: string, chatHistory?: ConversationTurn[], sendToChat?: (text: string) => void, sessionBaseDir?: string): Promise<string>;
+/**
+ * Process a batch of research events and decide whether to speak.
+ * Replaces contextualizeResearchUpdate — but usually returns null (silent).
+ * Only speaks when something genuinely critical is found.
+ */
+export declare function handleResearchBatch(workingDir: string, sessionId: string, task: string, batchEvents: string[], researchLog: string[], chatHistory?: ConversationTurn[], sessionBaseDir?: string): Promise<string | null>;
+/**
+ * Generate a brief spoken script for session resume or switch.
+ * Replaces buildContextBriefing + getSpecForVoiceModel.
+ */
+export declare function prepareBriefingScript(workingDir: string, sessionId: string, conversationHistory?: {
+    role: string;
+    text: string;
+}[], type?: 'resume' | 'switch' | 'default'): Promise<string>;
+/**
+ * Generate a spoken script after Gemini auto-recovery.
+ * Replaces inline recovery logic in index.ts.
+ */
+export declare function prepareRecoveryScript(conversationHistory?: {
+    role: string;
+    text: string;
+}[]): Promise<string>;