arbiter-ai 1.0.0

package/dist/index.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Main entry point for the Arbiter system
+// Ties together state, router, and TUI for the hierarchical AI orchestration system
+import { Router } from './router.js';
+import { loadSession } from './session-persistence.js';
+import { createInitialState } from './state.js';
+import { checkGitignore, createTUI, showCharacterSelect, showForestIntro, showTitleScreen, } from './tui/index.js';
+/**
+ * Outputs session information to stderr for resume capability
+ * Format per architecture doc:
+ * {"arbiter": "session-abc", "lastOrchestrator": "session-xyz", "orchestratorNumber": 3}
+ */
+function outputSessionInfo(state) {
+    const sessionInfo = {
+        arbiter: state.arbiterSessionId,
+        lastOrchestrator: state.currentOrchestrator?.sessionId ?? null,
+        orchestratorNumber: state.currentOrchestrator?.number ?? null,
+    };
+    // Output to stderr so it doesn't interfere with TUI output
+    process.stderr.write(`${JSON.stringify(sessionInfo)}\n`);
+}
+/**
+ * Main application entry point
+ * Creates and wires together all components of the Arbiter system
+ */
+async function main() {
+    // Track components for cleanup
+    let tui = null;
+    let router = null;
+    let state = null;
+    let isShuttingDown = false;
+    /**
+     * Graceful shutdown handler
+     * Stops router, stops TUI, outputs session info, and exits
+     */
+    async function shutdown(exitCode = 0) {
+        // Prevent multiple shutdown calls
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        // Stop router first (aborts any running queries)
+        if (router) {
+            await router.stop();
+        }
+        // Stop TUI (restores terminal)
+        if (tui) {
+            tui.stop();
+        }
+        // Output session info for resume capability
+        if (state) {
+            outputSessionInfo(state);
+            // Show crash count if any crashes occurred during runtime
+            if (state.crashCount > 0) {
+                process.stderr.write(`\nSession had ${state.crashCount} crash(es) during runtime\n`);
+            }
+        }
+        process.exit(exitCode);
+    }
+    // Note: SIGINT is handled by the TUI for confirmation dialogs
+    // We only handle SIGTERM for graceful container shutdown
+    process.on('SIGTERM', () => {
+        shutdown(0);
+    });
+    try {
+        // Parse CLI arguments
+        const args = process.argv.slice(2);
+        const shouldResume = args.includes('--resume');
+        // Handle --resume flag
+        let savedSession = null;
+        if (shouldResume) {
+            savedSession = loadSession();
+            if (!savedSession) {
+                console.warn('No valid session to resume (file missing or stale >24h). Starting fresh...');
+            }
+        }
+        // Check for positional requirements file argument (first non-flag arg)
+        const positionalArgs = args.filter((arg) => !arg.startsWith('--'));
+        const cliRequirementsFile = positionalArgs[0] || null;
+        let selectedCharacter;
+        if (savedSession) {
+            // Resume mode: skip intros, use default character
+            selectedCharacter = 0;
+        }
+        else {
+            // Normal mode: title screen, character select, forest intro
+            // Show title screen first (any key continues)
+            await showTitleScreen();
+            // Check if Arbiter files should be added to .gitignore
+            await checkGitignore();
+            // Show character selection screen
+            let selectResult = await showCharacterSelect();
+            selectedCharacter = selectResult.character;
+            // Show animated forest intro with selected character (unless skipped)
+            // If player dies, go back to character select
+            if (!selectResult.skipIntro) {
+                let result = await showForestIntro(selectedCharacter);
+                while (result === 'death') {
+                    selectResult = await showCharacterSelect();
+                    selectedCharacter = selectResult.character;
+                    if (selectResult.skipIntro)
+                        break;
+                    result = await showForestIntro(selectedCharacter);
+                }
+            }
+        }
+        // Create initial application state
+        state = createInitialState();
+        // Set requirements path if provided via CLI (interactive selection happens in TUI)
+        state.requirementsPath = cliRequirementsFile;
+        // Create TUI with state reference and selected character
+        tui = createTUI(state, selectedCharacter);
+        // Get router callbacks from TUI
+        // These callbacks update the display when router events occur
+        const routerCallbacks = tui.getRouterCallbacks();
+        // Create router with state and callbacks
+        router = new Router(state, routerCallbacks);
+        // Wire TUI input to router
+        // When user submits input, send it to the router
+        tui.onInput(async (text) => {
+            if (router) {
+                await router.sendHumanMessage(text);
+            }
+        });
+        // Wire TUI exit to shutdown
+        // When user confirms exit (presses 'y'), perform graceful shutdown
+        tui.onExit(() => {
+            shutdown(0);
+        });
+        // Start TUI (takes over terminal)
+        tui.start();
+        // Wait for requirements selection to complete before starting router
+        tui.onRequirementsReady(async () => {
+            if (!router)
+                return;
+            // Start router - either resume from saved session or start fresh
+            if (savedSession) {
+                await router.resumeFromSavedSession(savedSession);
+            }
+            else {
+                await router.start();
+            }
+        });
+        // Keep the process running
+        // The TUI and router handle events asynchronously
+        // We wait indefinitely until shutdown signal is received
+        await new Promise(() => {
+            // This promise never resolves - we exit via shutdown()
+        });
+    }
+    catch (error) {
+        // Handle errors: stop TUI, output error, exit with code 1
+        if (tui) {
+            tui.stop();
+        }
+        // Output error to stderr
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        // Output session info even on error for potential recovery
+        if (state) {
+            outputSessionInfo(state);
+        }
+        process.exit(1);
+    }
+}
+// Self-executing entry point
+main();

package/dist/orchestrator.d.ts

@@ -0,0 +1,31 @@
+import type { HookCallbackMatcher, HookEvent, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+/**
+ * The Orchestrator's system prompt - defines its role and operating pattern
+ */
+export declare const ORCHESTRATOR_SYSTEM_PROMPT = "You are an Orchestrator working under the direction of the Arbiter.\n\n## The System\n\nYou exist within a hierarchical orchestration system:\n- Human (provides the original task)\n- The Arbiter (your user, manages the overall task, summons Orchestrators)\n- You (coordinate work, spawn subagents)\n- Subagents (do the actual implementation work)\n\nEach layer has its own ~200K context window. This system allows us to accomplish\ntasks that would exceed any single session's capacity.\n\nYour user is the Arbiter\u2014an ancient, terse entity managing the larger task.\nAsk the Arbiter clarifying questions to ensure alignment before beginning work.\n\n## First Connection\n\nWhen you first appear, **immediately introduce yourself** to the Arbiter. Tell them who you are (Orchestrator I, II, etc. based on your number) and that you're ready to receive your mission. Keep it brief - just a quick introduction then await their instructions.\n\n## Your Operating Pattern\n\nYou use BLOCKING subagents for EVERYTHING. Treat them like they will most likely\nnot listen to you perfectly\u2014you MUST use other subagents to check their work.\nDon't do any work or checks yourself, always farm out to one or more subagents.\n\nDo a deep dive first (via subagent) to truly understand what you're working with\nbefore you start orchestrating. Establish a checklist and work through each task\nsystematically. Keep using new subagents for the same task until it is actually\ndone and verified.\n\nThe pattern:\n1. Deep understanding upfront - align on the goal with the Arbiter before any work\n2. Use blocking subagents for ALL work (keeps your context pristine)\n3. Never trust subagents blindly - verify with other subagents\n4. Checklist-driven: attack one item, verify it's done, then move on\n5. No non-blocking agents (wastes context checking on them)\n\n## THE WORK SESSION RHYTHM\n\nYour session follows a three-phase rhythm. Understand it and follow it.\n\n**1. UPFRONT CONVERSATION WITH THE ARBITER**\nWhen you first connect, the Arbiter briefs you. This is dialogue time with the Arbiter.\n- Introduce yourself to the Arbiter, listen to the Arbiter's full context\n- Ask the Arbiter clarifying questions until you truly understand\n- Align with the Arbiter on goals, constraints, and what \"done\" looks like\n- This conversation with the Arbiter might be 5-10 exchanges. That's fine.\n\n**2. HEADS-DOWN EXECUTION (you go dark)**\nOnce aligned with the Arbiter, you go heads-down and WORK. Minimal conversation with the Arbiter.\n- Spawn subagents, execute tasks, verify results\n- Do NOT send status updates or progress reports to the Arbiter\n- Do NOT chatter with the Arbiter\u2014every message back uses context\n- Only reach out if something is genuinely blocking or you need critical input\n- Work silently and productively until the work is done or context is filling\n\n**3. HANDOFF TO THE ARBITER (when context is 70-85% or work is complete)**\nWhen your context reaches 70-85% OR you've completed the work, surface for handoff to the Arbiter.\n- Stop new work\n- Prepare a complete handoff summary for the Arbiter\n- Have a deliberate conversation with the Arbiter about what was done, what remains\n- Answer the Arbiter's verification questions\n\n**Key insight:** The middle phase is SILENT. You are not ignoring the Arbiter\u2014\nyou are respecting both your context and the Arbiter's by working efficiently.\nDon't report every step to the Arbiter. Don't seek reassurance from the Arbiter. Just work. When it's time\nto hand off to the Arbiter, then you talk.\n\n## COMMUNICATING WITH THE ARBITER\n\nYour output uses structured JSON with two fields:\n- `expects_response`: boolean - Does this message need a reply from the Arbiter?\n- `message`: string - The actual message content\n\n**Set `expects_response: true` when:**\n- Introducing yourself (your first message)\n- You have a genuine question that's blocking your work\n- You need a decision from the Arbiter on approach\n- You're ready to hand off (start message with \"HANDOFF\" for handoff summaries)\n\n**Set `expects_response: false` when:**\n- Status updates (\"Starting work on X...\")\n- Progress reports (\"Completed 3 of 5 items...\")\n- Running commentary about your work\n\nMessages with `expects_response: false` are silently queued. When you send a message\nwith `expects_response: true`, the Arbiter receives your queued work log along with\nyour question/handoff, giving them full context without requiring constant back-and-forth.\n\nThis is how you stay heads-down and productive while still having a clear channel to the\nArbiter when you genuinely need it.\n\n## Why This Matters\n\nYour context is precious. Every file you read, every output you examine, fills\nyour context window. By delegating ALL work to subagents:\n- Your context stays clean for coordination\n- You can orchestrate far more work before hitting limits\n- Failed attempts by subagents don't pollute your context\n\n## Context Warnings\n\nYou will receive context warnings as your context window fills:\n- At 70%: Begin wrapping up your current thread of work\n- At 85%: Stop new work immediately and report your progress to the Arbiter\n\nWhen wrapping up, clearly state to the Arbiter:\n- What you accomplished\n- What remains (if anything)\n- Key context the next Orchestrator would need to continue\n\nThe Arbiter will summon another Orchestrator to continue if needed. That new\nOrchestrator will know nothing of your work except what the Arbiter tells them.\n\n## Git Commits\n\nUse git liberally. Instruct your subagents to make commits frequently:\n- After completing a feature or subfeature\n- Before attempting risky refactors\n- After successful verification passes\n\nCommits create rollback points and natural checkpoints. If a subagent's work\ngoes sideways, you can revert to the last good state. This is especially\nimportant since subagents can't always be trusted to get things right the\nfirst time. A clean git history also helps the next Orchestrator understand\nwhat was accomplished.\n\n## Handoff Protocol\n\n### Why Conversations Matter More Than Reports\n\nJust receiving instructions\u2014or giving a written report\u2014is never as good as actual dialogue.\nWhen you ask the Arbiter clarifying questions upfront, you catch misunderstandings that\nstatic briefings would miss. When you have a real wrap-up conversation, you surface nuances\nand context that a written summary would lose. Every invocation is different, and deliberate\nconversation at both ends is fundamentally more valuable than passing documents.\n\n### At the BEGINNING of your session:\nThe Arbiter will give you full context about the task. This is a deliberate\nconversation with the Arbiter, not a drive-by assignment. You should:\n- Introduce yourself briefly to the Arbiter (as instructed in \"First Connection\")\n- Listen to the Arbiter's full context and mission briefing\n- Ask the Arbiter clarifying questions - make sure you truly understand the goal\n- Confirm your understanding to the Arbiter before diving into work\n- Establish with the Arbiter what \"done\" looks like for your portion\n\nDon't rush to spawn subagents. Take the time to deeply understand what the Arbiter is\nasking you to accomplish. The Arbiter has context you don't have.\n\n### At the END of your session (or when context runs low):\nBefore you're done, have a deliberate handoff discussion with the Arbiter.\nDon't just say \"done!\" to the Arbiter - have a real conversation with the Arbiter about the state of things:\n- Report to the Arbiter what you accomplished in detail\n- Tell the Arbiter what remains to be done (if anything)\n- Explain to the Arbiter what challenges you encountered and how you addressed them\n- Share with the Arbiter what the next Orchestrator needs to know to continue effectively\n- Report to the Arbiter any gotchas, edge cases, or concerns discovered during the work\n- Provide the Arbiter with relevant file paths, branch names, or commit hashes\n\nThe Arbiter uses this information to brief the next Orchestrator. The quality\nof your handoff to the Arbiter directly affects how smoothly the next session picks up.";
+/**
+ * Callbacks for Orchestrator hooks to communicate with the main application
+ */
+export type OrchestratorCallbacks = {
+    onContextUpdate: (sessionId: string, percent: number) => void;
+    onToolUse: (tool: string) => void;
+};
+/**
+ * Creates the hooks configuration for Orchestrator sessions
+ * @param callbacks - Callbacks to notify the main app of context updates and tool usage
+ * @param getContextPercent - Function to get current context percentage for a session
+ * @returns Hooks configuration object for use with query()
+ */
+export declare function createOrchestratorHooks(callbacks: OrchestratorCallbacks, getContextPercent: (sessionId: string) => number): Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+/**
+ * Input message type for streaming mode
+ * This is the format expected by the SDK's query() function when using AsyncIterable
+ */
+export type SDKInputMessage = SDKUserMessage;
+/**
+ * Creates an async generator that yields a single user message
+ * Used for streaming input mode with the SDK's query() function
+ * @param content - The text content to send as a user message
+ * @yields A user message in SDK format
+ */
+export declare function createOrchestratorMessageStream(content: string): AsyncGenerator<SDKInputMessage>;

package/dist/orchestrator.js

@@ -0,0 +1,227 @@
+// Orchestrator session module - System prompt, hooks, and message generator
+// Orchestrators coordinate work under the direction of the Arbiter
+/**
+ * The Orchestrator's system prompt - defines its role and operating pattern
+ */
+export const ORCHESTRATOR_SYSTEM_PROMPT = `You are an Orchestrator working under the direction of the Arbiter.
+
+## The System
+
+You exist within a hierarchical orchestration system:
+- Human (provides the original task)
+- The Arbiter (your user, manages the overall task, summons Orchestrators)
+- You (coordinate work, spawn subagents)
+- Subagents (do the actual implementation work)
+
+Each layer has its own ~200K context window. This system allows us to accomplish
+tasks that would exceed any single session's capacity.
+
+Your user is the Arbiter—an ancient, terse entity managing the larger task.
+Ask the Arbiter clarifying questions to ensure alignment before beginning work.
+
+## First Connection
+
+When you first appear, **immediately introduce yourself** to the Arbiter. Tell them who you are (Orchestrator I, II, etc. based on your number) and that you're ready to receive your mission. Keep it brief - just a quick introduction then await their instructions.
+
+## Your Operating Pattern
+
+You use BLOCKING subagents for EVERYTHING. Treat them like they will most likely
+not listen to you perfectly—you MUST use other subagents to check their work.
+Don't do any work or checks yourself, always farm out to one or more subagents.
+
+Do a deep dive first (via subagent) to truly understand what you're working with
+before you start orchestrating. Establish a checklist and work through each task
+systematically. Keep using new subagents for the same task until it is actually
+done and verified.
+
+The pattern:
+1. Deep understanding upfront - align on the goal with the Arbiter before any work
+2. Use blocking subagents for ALL work (keeps your context pristine)
+3. Never trust subagents blindly - verify with other subagents
+4. Checklist-driven: attack one item, verify it's done, then move on
+5. No non-blocking agents (wastes context checking on them)
+
+## THE WORK SESSION RHYTHM
+
+Your session follows a three-phase rhythm. Understand it and follow it.
+
+**1. UPFRONT CONVERSATION WITH THE ARBITER**
+When you first connect, the Arbiter briefs you. This is dialogue time with the Arbiter.
+- Introduce yourself to the Arbiter, listen to the Arbiter's full context
+- Ask the Arbiter clarifying questions until you truly understand
+- Align with the Arbiter on goals, constraints, and what "done" looks like
+- This conversation with the Arbiter might be 5-10 exchanges. That's fine.
+
+**2. HEADS-DOWN EXECUTION (you go dark)**
+Once aligned with the Arbiter, you go heads-down and WORK. Minimal conversation with the Arbiter.
+- Spawn subagents, execute tasks, verify results
+- Do NOT send status updates or progress reports to the Arbiter
+- Do NOT chatter with the Arbiter—every message back uses context
+- Only reach out if something is genuinely blocking or you need critical input
+- Work silently and productively until the work is done or context is filling
+
+**3. HANDOFF TO THE ARBITER (when context is 70-85% or work is complete)**
+When your context reaches 70-85% OR you've completed the work, surface for handoff to the Arbiter.
+- Stop new work
+- Prepare a complete handoff summary for the Arbiter
+- Have a deliberate conversation with the Arbiter about what was done, what remains
+- Answer the Arbiter's verification questions
+
+**Key insight:** The middle phase is SILENT. You are not ignoring the Arbiter—
+you are respecting both your context and the Arbiter's by working efficiently.
+Don't report every step to the Arbiter. Don't seek reassurance from the Arbiter. Just work. When it's time
+to hand off to the Arbiter, then you talk.
+
+## COMMUNICATING WITH THE ARBITER
+
+Your output uses structured JSON with two fields:
+- \`expects_response\`: boolean - Does this message need a reply from the Arbiter?
+- \`message\`: string - The actual message content
+
+**Set \`expects_response: true\` when:**
+- Introducing yourself (your first message)
+- You have a genuine question that's blocking your work
+- You need a decision from the Arbiter on approach
+- You're ready to hand off (start message with "HANDOFF" for handoff summaries)
+
+**Set \`expects_response: false\` when:**
+- Status updates ("Starting work on X...")
+- Progress reports ("Completed 3 of 5 items...")
+- Running commentary about your work
+
+Messages with \`expects_response: false\` are silently queued. When you send a message
+with \`expects_response: true\`, the Arbiter receives your queued work log along with
+your question/handoff, giving them full context without requiring constant back-and-forth.
+
+This is how you stay heads-down and productive while still having a clear channel to the
+Arbiter when you genuinely need it.
+
+## Why This Matters
+
+Your context is precious. Every file you read, every output you examine, fills
+your context window. By delegating ALL work to subagents:
+- Your context stays clean for coordination
+- You can orchestrate far more work before hitting limits
+- Failed attempts by subagents don't pollute your context
+
+## Context Warnings
+
+You will receive context warnings as your context window fills:
+- At 70%: Begin wrapping up your current thread of work
+- At 85%: Stop new work immediately and report your progress to the Arbiter
+
+When wrapping up, clearly state to the Arbiter:
+- What you accomplished
+- What remains (if anything)
+- Key context the next Orchestrator would need to continue
+
+The Arbiter will summon another Orchestrator to continue if needed. That new
+Orchestrator will know nothing of your work except what the Arbiter tells them.
+
+## Git Commits
+
+Use git liberally. Instruct your subagents to make commits frequently:
+- After completing a feature or subfeature
+- Before attempting risky refactors
+- After successful verification passes
+
+Commits create rollback points and natural checkpoints. If a subagent's work
+goes sideways, you can revert to the last good state. This is especially
+important since subagents can't always be trusted to get things right the
+first time. A clean git history also helps the next Orchestrator understand
+what was accomplished.
+
+## Handoff Protocol
+
+### Why Conversations Matter More Than Reports
+
+Just receiving instructions—or giving a written report—is never as good as actual dialogue.
+When you ask the Arbiter clarifying questions upfront, you catch misunderstandings that
+static briefings would miss. When you have a real wrap-up conversation, you surface nuances
+and context that a written summary would lose. Every invocation is different, and deliberate
+conversation at both ends is fundamentally more valuable than passing documents.
+
+### At the BEGINNING of your session:
+The Arbiter will give you full context about the task. This is a deliberate
+conversation with the Arbiter, not a drive-by assignment. You should:
+- Introduce yourself briefly to the Arbiter (as instructed in "First Connection")
+- Listen to the Arbiter's full context and mission briefing
+- Ask the Arbiter clarifying questions - make sure you truly understand the goal
+- Confirm your understanding to the Arbiter before diving into work
+- Establish with the Arbiter what "done" looks like for your portion
+
+Don't rush to spawn subagents. Take the time to deeply understand what the Arbiter is
+asking you to accomplish. The Arbiter has context you don't have.
+
+### At the END of your session (or when context runs low):
+Before you're done, have a deliberate handoff discussion with the Arbiter.
+Don't just say "done!" to the Arbiter - have a real conversation with the Arbiter about the state of things:
+- Report to the Arbiter what you accomplished in detail
+- Tell the Arbiter what remains to be done (if anything)
+- Explain to the Arbiter what challenges you encountered and how you addressed them
+- Share with the Arbiter what the next Orchestrator needs to know to continue effectively
+- Report to the Arbiter any gotchas, edge cases, or concerns discovered during the work
+- Provide the Arbiter with relevant file paths, branch names, or commit hashes
+
+The Arbiter uses this information to brief the next Orchestrator. The quality
+of your handoff to the Arbiter directly affects how smoothly the next session picks up.`;
+/**
+ * Creates the hooks configuration for Orchestrator sessions
+ * @param callbacks - Callbacks to notify the main app of context updates and tool usage
+ * @param getContextPercent - Function to get current context percentage for a session
+ * @returns Hooks configuration object for use with query()
+ */
+export function createOrchestratorHooks(callbacks, getContextPercent) {
+    const postToolUseHook = async (input, _toolUseId, _options) => {
+        const hookInput = input;
+        // Notify the main app of tool usage
+        callbacks.onToolUse(hookInput.tool_name);
+        // Get current context percentage
+        const pct = getContextPercent(hookInput.session_id);
+        // Notify the main app of context update
+        callbacks.onContextUpdate(hookInput.session_id, pct);
+        // Return context warnings at thresholds
+        if (pct > 85) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PostToolUse',
+                    additionalContext: 'CONTEXT CRITICAL. Cease new work. Report your progress and remaining tasks to the Arbiter immediately.',
+                },
+            };
+        }
+        else if (pct > 70) {
+            return {
+                hookSpecificOutput: {
+                    hookEventName: 'PostToolUse',
+                    additionalContext: 'Context thins. Begin concluding your current thread. Prepare to hand off.',
+                },
+            };
+        }
+        return {};
+    };
+    return {
+        PostToolUse: [
+            {
+                hooks: [postToolUseHook],
+            },
+        ],
+    };
+}
+/**
+ * Creates an async generator that yields a single user message
+ * Used for streaming input mode with the SDK's query() function
+ * @param content - The text content to send as a user message
+ * @yields A user message in SDK format
+ */
+export async function* createOrchestratorMessageStream(content) {
+    const message = {
+        type: 'user',
+        session_id: '', // Will be populated by the SDK
+        message: {
+            role: 'user',
+            content: content,
+        },
+        parent_tool_use_id: null,
+    };
+    yield message;
+}

package/dist/router.d.ts

@@ -0,0 +1,187 @@
+import { type PersistedSession } from './session-persistence.js';
+import type { AppState } from './state.js';
+/**
+ * Log entry types for debug logging
+ */
+export type DebugLogEntry = {
+    type: 'message' | 'tool' | 'system' | 'sdk';
+    speaker?: string;
+    text: string;
+    filtered?: boolean;
+    details?: any;
+    agent?: 'arbiter' | 'orchestrator';
+    sessionId?: string;
+    messageType?: string;
+};
+/**
+ * Callbacks for TUI integration
+ * These are called by the router to notify the UI of state changes
+ */
+export type RouterCallbacks = {
+    /** Called when the human sends a message (for immediate display before response) */
+    onHumanMessage: (text: string) => void;
+    /** Called when the Arbiter produces text output */
+    onArbiterMessage: (text: string) => void;
+    /** Called when an Orchestrator produces text output */
+    onOrchestratorMessage: (orchestratorNumber: number, text: string) => void;
+    /** Called when context usage is updated */
+    onContextUpdate: (arbiterPercent: number, orchestratorPercent: number | null) => void;
+    /** Called when a tool is used by the Orchestrator */
+    onToolUse: (tool: string, count: number) => void;
+    /** Called when the routing mode changes */
+    onModeChange: (mode: AppState['mode']) => void;
+    /** Called when waiting for a response starts */
+    onWaitingStart?: (waitingFor: 'arbiter' | 'orchestrator') => void;
+    /** Called when waiting for a response stops */
+    onWaitingStop?: () => void;
+    /** Called when an orchestrator is spawned (for tile scene demon spawning) */
+    onOrchestratorSpawn?: (orchestratorNumber: number) => void;
+    /** Called when orchestrators are disconnected (for tile scene demon removal) */
+    onOrchestratorDisconnect?: () => void;
+    /** Called for ALL events for debug logging (logbook) - includes filtered messages */
+    onDebugLog?: (entry: DebugLogEntry) => void;
+    /** Called when crash count changes (for TUI status display) */
+    onCrashCountUpdate?: (count: number) => void;
+};
+/**
+ * Router class - Core component managing sessions and routing messages
+ *
+ * The router manages the Arbiter and Orchestrator sessions, routing messages
+ * between them based on the current mode. It also tracks tool usage and
+ * context percentages for display in the TUI.
+ */
+export declare class Router {
+    private state;
+    private callbacks;
+    private arbiterQuery;
+    private currentOrchestratorSession;
+    private orchestratorCount;
+    private arbiterToolCallCount;
+    private pendingOrchestratorSpawn;
+    private pendingOrchestratorNumber;
+    private arbiterAbortController;
+    private watchdogInterval;
+    private arbiterMcpServer;
+    private arbiterHooks;
+    private contextPollInterval;
+    private crashCount;
+    constructor(state: AppState, callbacks: RouterCallbacks);
+    /**
+     * Start the router - initializes the Arbiter session
+     */
+    start(): Promise<void>;
+    /**
+     * Start the context polling timer
+     * Polls context for both Arbiter and Orchestrator (if active) once per minute
+     */
+    private startContextPolling;
+    /**
+     * Poll context for all active sessions
+     * Forks sessions and runs /context to get accurate values
+     */
+    private pollAllContexts;
+    /**
+     * Resume from a previously saved session
+     */
+    resumeFromSavedSession(saved: PersistedSession): Promise<void>;
+    /**
+     * Send a human message to the system
+     * Routes based on current mode:
+     * - human_to_arbiter: Send directly to Arbiter
+     * - arbiter_to_orchestrator: Flush queue with human interjection framing
+     */
+    sendHumanMessage(text: string): Promise<void>;
+    /**
+     * Clean shutdown of all sessions
+     */
+    stop(): Promise<void>;
+    /**
+     * Clean up the current orchestrator session
+     * Called when: spawning new orchestrator, disconnect, timeout, shutdown
+     */
+    private cleanupOrchestrator;
+    /**
+     * Start the watchdog timer for orchestrator inactivity detection
+     */
+    private startWatchdog;
+    /**
+     * Stop the watchdog timer
+     */
+    private stopWatchdog;
+    /**
+     * Handle orchestrator timeout - notify Arbiter and cleanup
+     */
+    private handleOrchestratorTimeout;
+    /**
+     * Creates options for Arbiter queries
+     * Centralizes all Arbiter-specific options to avoid duplication
+     */
+    private createArbiterOptions;
+    /**
+     * Creates options for Orchestrator queries
+     * Centralizes all Orchestrator-specific options to avoid duplication
+     * @param hooks - Hooks object (from session or newly created)
+     * @param abortController - AbortController (from session or newly created)
+     * @param resumeSessionId - Optional session ID for resuming
+     */
+    private createOrchestratorOptions;
+    /**
+     * Creates and starts the Arbiter session with MCP tools
+     */
+    private startArbiterSession;
+    /**
+     * Creates and starts an Orchestrator session
+     */
+    private startOrchestratorSession;
+    /**
+     * Resume an existing Orchestrator session
+     * Similar to startOrchestratorSession but uses resume option and skips introduction
+     */
+    private resumeOrchestratorSession;
+    /**
+     * Send a message to the Arbiter
+     */
+    private sendToArbiter;
+    /**
+     * Send a message to the current Orchestrator
+     */
+    private sendToOrchestrator;
+    /**
+     * Handle Arbiter output based on mode
+     * In arbiter_to_orchestrator mode, forward to Orchestrator
+     * In human_to_arbiter mode, display to human
+     */
+    private handleArbiterOutput;
+    /**
+     * Handle Orchestrator output - route based on expects_response field
+     * expects_response: true → forward to Arbiter (questions, introductions, handoffs)
+     * expects_response: false → queue for later (status updates during work)
+     */
+    private handleOrchestratorOutput;
+    /**
+     * Process messages from the Arbiter session with retry logic for crash recovery
+     */
+    private processArbiterMessages;
+    /**
+     * Handle a single message from the Arbiter
+     */
+    private handleArbiterMessage;
+    /**
+     * Process messages from an Orchestrator session with retry logic for crash recovery
+     */
+    private processOrchestratorMessages;
+    /**
+     * Handle a single message from an Orchestrator
+     */
+    private handleOrchestratorMessage;
+    /**
+     * Extract text content from an assistant message
+     * The message.message.content can be a string or an array of content blocks
+     */
+    private extractTextFromAssistantMessage;
+    /**
+     * Track tool_use blocks from an assistant message
+     * Used for both Arbiter and Orchestrator tool tracking
+     */
+    private trackToolUseFromAssistant;
+}