arbiter-ai 1.0.0

package/dist/router.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Router Integration Tests
+ *
+ * Note: The Router class is tightly coupled to the Claude Agent SDK's `query()` function,
+ * which returns an async generator. Full integration testing would require:
+ * - Mocking the SDK's `query()` function with async generators
+ * - Mocking message sequences (SDKMessage types)
+ * - Mocking abort controllers and timers for watchdog behavior
+ *
+ * These tests cover what's feasible without deep SDK mocking:
+ * - Type exports are correct
+ * - Router can be instantiated with proper callbacks
+ * - Basic structural validation
+ */
+export {};

package/dist/router.test.js

@@ -0,0 +1,95 @@
+/**
+ * Router Integration Tests
+ *
+ * Note: The Router class is tightly coupled to the Claude Agent SDK's `query()` function,
+ * which returns an async generator. Full integration testing would require:
+ * - Mocking the SDK's `query()` function with async generators
+ * - Mocking message sequences (SDKMessage types)
+ * - Mocking abort controllers and timers for watchdog behavior
+ *
+ * These tests cover what's feasible without deep SDK mocking:
+ * - Type exports are correct
+ * - Router can be instantiated with proper callbacks
+ * - Basic structural validation
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Router } from './router.js';
+import { createInitialState } from './state.js';
+// Mock the SDK query function to prevent actual API calls
+vi.mock('@anthropic-ai/claude-agent-sdk', () => ({
+    query: vi.fn(),
+}));
+// Mock session persistence to prevent file I/O
+vi.mock('./session-persistence.js', () => ({
+    saveSession: vi.fn(),
+    loadSession: vi.fn(() => null),
+    clearSession: vi.fn(),
+}));
+describe('router', () => {
+    let state;
+    let callbacks;
+    beforeEach(() => {
+        state = createInitialState();
+        // Create mock callbacks matching actual RouterCallbacks interface
+        callbacks = {
+            onHumanMessage: vi.fn(),
+            onArbiterMessage: vi.fn(),
+            onOrchestratorMessage: vi.fn(),
+            onContextUpdate: vi.fn(),
+            onToolUse: vi.fn(),
+            onModeChange: vi.fn(),
+            onDebugLog: vi.fn(),
+        };
+    });
+    describe('Router instantiation', () => {
+        it('should create a Router instance with state and callbacks', () => {
+            const router = new Router(state, callbacks);
+            expect(router).toBeInstanceOf(Router);
+        });
+        it('should have required public methods', () => {
+            const router = new Router(state, callbacks);
+            // Check that required methods exist
+            expect(typeof router.start).toBe('function');
+            expect(typeof router.stop).toBe('function');
+            expect(typeof router.sendHumanMessage).toBe('function');
+            expect(typeof router.resumeFromSavedSession).toBe('function');
+        });
+    });
+    describe('Type exports', () => {
+        it('should export RouterCallbacks type with correct structure', () => {
+            // This test validates at compile time that the types are correct
+            // Using vi.fn() satisfies both type checking and linting (no empty blocks)
+            const validCallbacks = {
+                onHumanMessage: vi.fn(),
+                onArbiterMessage: vi.fn(),
+                onOrchestratorMessage: vi.fn(),
+                onContextUpdate: vi.fn(),
+                onToolUse: vi.fn(),
+                onModeChange: vi.fn(),
+            };
+            expect(validCallbacks.onHumanMessage).toBeDefined();
+            expect(validCallbacks.onArbiterMessage).toBeDefined();
+            expect(validCallbacks.onOrchestratorMessage).toBeDefined();
+            expect(validCallbacks.onContextUpdate).toBeDefined();
+            expect(validCallbacks.onToolUse).toBeDefined();
+            expect(validCallbacks.onModeChange).toBeDefined();
+        });
+        it('should export DebugLogEntry type', () => {
+            const entry = {
+                type: 'message',
+                speaker: 'arbiter',
+                text: 'test content',
+            };
+            expect(entry.type).toBe('message');
+            expect(entry.speaker).toBe('arbiter');
+            expect(entry.text).toBe('test content');
+        });
+    });
+    describe('Router.stop()', () => {
+        it('should be safe to call stop on a router that was never started', async () => {
+            const router = new Router(state, callbacks);
+            // Should not throw
+            await expect(router.stop()).resolves.toBeUndefined();
+        });
+    });
+});

package/dist/session-persistence.d.ts

@@ -0,0 +1,9 @@
+export interface PersistedSession {
+    arbiterSessionId: string;
+    orchestratorSessionId: string | null;
+    orchestratorNumber: number | null;
+    savedAt: string;
+}
+export declare function saveSession(arbiterSessionId: string, orchestratorSessionId: string | null, orchestratorNumber: number | null): void;
+export declare function loadSession(): PersistedSession | null;
+export declare function clearSession(): void;

package/dist/session-persistence.js

@@ -0,0 +1,63 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const SESSION_FILE = '.claude/.arbiter-session.json';
+function getSessionFilePath() {
+    return path.join(process.cwd(), SESSION_FILE);
+}
+export function saveSession(arbiterSessionId, orchestratorSessionId, orchestratorNumber) {
+    try {
+        const sessionData = {
+            arbiterSessionId,
+            orchestratorSessionId,
+            orchestratorNumber,
+            savedAt: new Date().toISOString(),
+        };
+        const filePath = getSessionFilePath();
+        const dirPath = path.dirname(filePath);
+        // Create .claude directory if it doesn't exist
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+        fs.writeFileSync(filePath, JSON.stringify(sessionData, null, 2), 'utf-8');
+    }
+    catch {
+        // Silent on errors (best-effort save)
+    }
+}
+export function loadSession() {
+    try {
+        const filePath = getSessionFilePath();
+        // Return null if file doesn't exist
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const session = JSON.parse(content);
+        // Validate savedAt exists and is not stale (more than 24 hours old)
+        if (!session.savedAt) {
+            return null;
+        }
+        const savedTime = new Date(session.savedAt).getTime();
+        const now = Date.now();
+        const twentyFourHours = 24 * 60 * 60 * 1000;
+        if (now - savedTime > twentyFourHours) {
+            return null;
+        }
+        return session;
+    }
+    catch {
+        // Return null if file is invalid JSON or any other error
+        return null;
+    }
+}
+export function clearSession() {
+    try {
+        const filePath = getSessionFilePath();
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+    catch {
+        // Silent on errors
+    }
+}

package/dist/session-persistence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session-persistence.test.js

@@ -0,0 +1,165 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { clearSession, loadSession, saveSession, } from './session-persistence.js';
+// Mock the fs module
+vi.mock('node:fs');
+vi.mock('node:path');
+describe('session-persistence', () => {
+    const mockCwd = '/test/workspace';
+    const mockSessionPath = '/test/workspace/.claude/.arbiter-session.json';
+    const mockDirPath = '/test/workspace/.claude';
+    beforeEach(() => {
+        vi.resetAllMocks();
+        vi.spyOn(process, 'cwd').mockReturnValue(mockCwd);
+        vi.mocked(path.join).mockReturnValue(mockSessionPath);
+        vi.mocked(path.dirname).mockReturnValue(mockDirPath);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('saveSession', () => {
+        it('should create directory and save session data', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+            vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+            saveSession('arbiter-123', 'orch-456', 2);
+            expect(fs.existsSync).toHaveBeenCalledWith(mockDirPath);
+            expect(fs.mkdirSync).toHaveBeenCalledWith(mockDirPath, { recursive: true });
+            expect(fs.writeFileSync).toHaveBeenCalledWith(mockSessionPath, expect.stringContaining('"arbiterSessionId": "arbiter-123"'), 'utf-8');
+        });
+        it('should not create directory if it already exists', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+            saveSession('arbiter-123', null, null);
+            expect(fs.existsSync).toHaveBeenCalledWith(mockDirPath);
+            expect(fs.mkdirSync).not.toHaveBeenCalled();
+        });
+        it('should save session with null orchestrator values', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+            saveSession('arbiter-789', null, null);
+            const writeCall = vi.mocked(fs.writeFileSync).mock.calls[0];
+            const savedData = JSON.parse(writeCall[1]);
+            expect(savedData.arbiterSessionId).toBe('arbiter-789');
+            expect(savedData.orchestratorSessionId).toBeNull();
+            expect(savedData.orchestratorNumber).toBeNull();
+            expect(savedData.savedAt).toBeDefined();
+        });
+        it('should silently handle write errors', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.writeFileSync).mockImplementation(() => {
+                throw new Error('Write error');
+            });
+            // Should not throw
+            expect(() => saveSession('arbiter-123', null, null)).not.toThrow();
+        });
+        it('should include ISO timestamp in savedAt', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+            const beforeSave = new Date();
+            saveSession('arbiter-123', 'orch-456', 1);
+            const afterSave = new Date();
+            const writeCall = vi.mocked(fs.writeFileSync).mock.calls[0];
+            const savedData = JSON.parse(writeCall[1]);
+            const savedTime = new Date(savedData.savedAt);
+            expect(savedTime.getTime()).toBeGreaterThanOrEqual(beforeSave.getTime());
+            expect(savedTime.getTime()).toBeLessThanOrEqual(afterSave.getTime());
+        });
+    });
+    describe('loadSession', () => {
+        it('should return null if file does not exist', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            const result = loadSession();
+            expect(result).toBeNull();
+            expect(fs.readFileSync).not.toHaveBeenCalled();
+        });
+        it('should load and return valid session data', () => {
+            const sessionData = {
+                arbiterSessionId: 'arbiter-123',
+                orchestratorSessionId: 'orch-456',
+                orchestratorNumber: 2,
+                savedAt: new Date().toISOString(),
+            };
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(sessionData));
+            const result = loadSession();
+            expect(result).toEqual(sessionData);
+        });
+        it('should return null for stale session (>24 hours old)', () => {
+            const staleTime = new Date(Date.now() - 25 * 60 * 60 * 1000); // 25 hours ago
+            const sessionData = {
+                arbiterSessionId: 'arbiter-123',
+                orchestratorSessionId: null,
+                orchestratorNumber: null,
+                savedAt: staleTime.toISOString(),
+            };
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(sessionData));
+            const result = loadSession();
+            expect(result).toBeNull();
+        });
+        it('should return session at exactly 24 hours', () => {
+            const exactlyOneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+            const sessionData = {
+                arbiterSessionId: 'arbiter-123',
+                orchestratorSessionId: null,
+                orchestratorNumber: null,
+                savedAt: exactlyOneDayAgo.toISOString(),
+            };
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(sessionData));
+            const result = loadSession();
+            // At exactly 24 hours, it should still be valid (not > 24 hours)
+            expect(result).toEqual(sessionData);
+        });
+        it('should return null for session missing savedAt', () => {
+            const sessionData = {
+                arbiterSessionId: 'arbiter-123',
+                orchestratorSessionId: null,
+                orchestratorNumber: null,
+                // savedAt is missing
+            };
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(sessionData));
+            const result = loadSession();
+            expect(result).toBeNull();
+        });
+        it('should return null for invalid JSON', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockReturnValue('not valid json');
+            const result = loadSession();
+            expect(result).toBeNull();
+        });
+        it('should return null on read error', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.readFileSync).mockImplementation(() => {
+                throw new Error('Read error');
+            });
+            const result = loadSession();
+            expect(result).toBeNull();
+        });
+    });
+    describe('clearSession', () => {
+        it('should delete file if it exists', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.unlinkSync).mockReturnValue(undefined);
+            clearSession();
+            expect(fs.existsSync).toHaveBeenCalledWith(mockSessionPath);
+            expect(fs.unlinkSync).toHaveBeenCalledWith(mockSessionPath);
+        });
+        it('should not attempt delete if file does not exist', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            clearSession();
+            expect(fs.unlinkSync).not.toHaveBeenCalled();
+        });
+        it('should silently handle delete errors', () => {
+            vi.mocked(fs.existsSync).mockReturnValue(true);
+            vi.mocked(fs.unlinkSync).mockImplementation(() => {
+                throw new Error('Delete error');
+            });
+            // Should not throw
+            expect(() => clearSession()).not.toThrow();
+        });
+    });
+});

package/dist/sound.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sound effects module for the Arbiter TUI
+ *
+ * Provides simple fire-and-forget sound effect playback.
+ * Uses play-sound package for cross-platform support (Linux, Mac, Windows).
+ */
+/**
+ * Sound effect filename mappings
+ */
+export declare const SFX: {
+    readonly footstep: "footstep.wav";
+    readonly jump: "jump.wav";
+    readonly magic: "magic.wav";
+    readonly death: "death.wav";
+    readonly menuLeft: "menu-left.wav";
+    readonly menuRight: "menu-right.wav";
+    readonly menuSelect: "menu-select.wav";
+    readonly quickNotice: "quick-notice.wav";
+};
+/**
+ * Type for valid sound effect names
+ */
+export type SfxName = keyof typeof SFX;
+/**
+ * Play a sound effect by name
+ *
+ * Fire-and-forget: does not await, catches errors silently
+ *
+ * @param name - The name of the sound effect to play
+ */
+export declare function playSfx(name: SfxName): void;

package/dist/sound.js

@@ -0,0 +1,50 @@
+/**
+ * Sound effects module for the Arbiter TUI
+ *
+ * Provides simple fire-and-forget sound effect playback.
+ * Uses play-sound package for cross-platform support (Linux, Mac, Windows).
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import playSound from 'play-sound';
+// Get package root directory (works when installed globally or locally)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, '..'); // From dist/ to package root
+// Create player instance
+// play-sound auto-detects available audio players:
+// - Mac: afplay
+// - Linux: aplay, mpg123, mpg321, play, mplayer, etc.
+// - Windows: powershell, cmdmp3
+const player = playSound();
+/**
+ * Sound effect filename mappings
+ */
+export const SFX = {
+    footstep: 'footstep.wav',
+    jump: 'jump.wav',
+    magic: 'magic.wav',
+    death: 'death.wav',
+    menuLeft: 'menu-left.wav',
+    menuRight: 'menu-right.wav',
+    menuSelect: 'menu-select.wav',
+    quickNotice: 'quick-notice.wav',
+};
+/**
+ * Play a sound effect by name
+ *
+ * Fire-and-forget: does not await, catches errors silently
+ *
+ * @param name - The name of the sound effect to play
+ */
+export function playSfx(name) {
+    const filename = SFX[name];
+    const filepath = path.join(PACKAGE_ROOT, 'sounds', filename);
+    player.play(filepath, (err) => {
+        if (err) {
+            // Silently ignore errors - sound is non-critical
+            // Uncomment below for debugging:
+            // console.error(`Failed to play sound "${name}":`, err);
+        }
+    });
+}

package/dist/state.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Message type for conversation log entries
+ */
+export interface Message {
+    speaker: 'human' | 'arbiter' | string;
+    text: string;
+    timestamp: Date;
+}
+/**
+ * Current orchestrator state
+ */
+export interface OrchestratorState {
+    id: string;
+    sessionId: string;
+    number: number;
+    contextPercent: number;
+    currentTool: string | null;
+    toolCallCount: number;
+}
+/**
+ * Main application state interface
+ */
+export interface AppState {
+    mode: 'human_to_arbiter' | 'arbiter_to_orchestrator';
+    arbiterSessionId: string | null;
+    arbiterContextPercent: number;
+    currentOrchestrator: OrchestratorState | null;
+    conversationLog: Message[];
+    crashCount: number;
+    requirementsPath: string | null;
+}
+/**
+ * Creates the initial application state
+ */
+export declare function createInitialState(): AppState;
+/**
+ * Updates the Arbiter's context percentage
+ */
+export declare function updateArbiterContext(state: AppState, percent: number): void;
+/**
+ * Updates the current Orchestrator's context percentage
+ */
+export declare function updateOrchestratorContext(state: AppState, percent: number): void;
+/**
+ * Sets the current orchestrator
+ */
+export declare function setCurrentOrchestrator(state: AppState, orch: {
+    id: string;
+    sessionId: string;
+    number: number;
+}): void;
+/**
+ * Clears the current orchestrator (sets to null)
+ */
+export declare function clearCurrentOrchestrator(state: AppState): void;
+/**
+ * Sets the routing mode
+ */
+export declare function setMode(state: AppState, mode: AppState['mode']): void;
+/**
+ * Adds a message to the conversation log
+ */
+export declare function addMessage(state: AppState, speaker: string, text: string): void;
+/**
+ * Updates the current orchestrator's tool info
+ */
+export declare function updateOrchestratorTool(state: AppState, tool: string | null, count: number): void;
+/**
+ * Converts a number to Roman numerals
+ * Supports numbers 1-3999
+ */
+export declare function toRoman(num: number): string;

package/dist/state.js

@@ -0,0 +1,107 @@
+// Global state management for the Arbiter system
+// Tracks agent states, conversation history, and system configuration
+/**
+ * Creates the initial application state
+ */
+export function createInitialState() {
+    return {
+        mode: 'human_to_arbiter',
+        arbiterSessionId: null,
+        arbiterContextPercent: 0,
+        currentOrchestrator: null,
+        conversationLog: [],
+        crashCount: 0,
+        requirementsPath: null,
+    };
+}
+/**
+ * Updates the Arbiter's context percentage
+ */
+export function updateArbiterContext(state, percent) {
+    state.arbiterContextPercent = percent;
+}
+/**
+ * Updates the current Orchestrator's context percentage
+ */
+export function updateOrchestratorContext(state, percent) {
+    if (state.currentOrchestrator) {
+        state.currentOrchestrator.contextPercent = percent;
+    }
+}
+/**
+ * Sets the current orchestrator
+ */
+export function setCurrentOrchestrator(state, orch) {
+    state.currentOrchestrator = {
+        id: orch.id,
+        sessionId: orch.sessionId,
+        number: orch.number,
+        contextPercent: 0,
+        currentTool: null,
+        toolCallCount: 0,
+    };
+}
+/**
+ * Clears the current orchestrator (sets to null)
+ */
+export function clearCurrentOrchestrator(state) {
+    state.currentOrchestrator = null;
+}
+/**
+ * Sets the routing mode
+ */
+export function setMode(state, mode) {
+    state.mode = mode;
+}
+/**
+ * Adds a message to the conversation log
+ */
+export function addMessage(state, speaker, text) {
+    state.conversationLog.push({
+        speaker,
+        text,
+        timestamp: new Date(),
+    });
+}
+/**
+ * Updates the current orchestrator's tool info
+ */
+export function updateOrchestratorTool(state, tool, count) {
+    if (state.currentOrchestrator) {
+        state.currentOrchestrator.currentTool = tool;
+        state.currentOrchestrator.toolCallCount = count;
+    }
+}
+/**
+ * Converts a number to Roman numerals
+ * Supports numbers 1-3999
+ */
+export function toRoman(num) {
+    if (num < 1 || num > 3999) {
+        throw new Error('Number must be between 1 and 3999');
+    }
+    const romanNumerals = [
+        [1000, 'M'],
+        [900, 'CM'],
+        [500, 'D'],
+        [400, 'CD'],
+        [100, 'C'],
+        [90, 'XC'],
+        [50, 'L'],
+        [40, 'XL'],
+        [10, 'X'],
+        [9, 'IX'],
+        [5, 'V'],
+        [4, 'IV'],
+        [1, 'I'],
+    ];
+    let result = '';
+    let remaining = num;
+    for (const [value, symbol] of romanNumerals) {
+        while (remaining >= value) {
+            result += symbol;
+            remaining -= value;
+        }
+    }
+    return result;
+}

package/dist/state.test.d.ts

@@ -0,0 +1 @@
+export {};