codmir 0.3.3 → 0.4.1

package/dist/voice-daemon/index.d.mts

@@ -0,0 +1,354 @@
+/**
+ * Log level supported by the daemon logger.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Converts a string or undefined into a valid log level.
+ * Defaults to "info" if the provided value is invalid.
+ *
+ * @param value Raw log level value, typically from environment variables.
+ */
+declare function normalizeLogLevel(value?: string): LogLevel;
+/**
+ * Simple structured logger used by the voice daemon.
+ * Logs to stdout with timestamps and JSON metadata.
+ */
+declare class Logger {
+    private level;
+    private readonly prefix;
+    constructor(level: LogLevel, prefix?: string);
+    /**
+     * Logs a debug-level message.
+     */
+    debug(message: string, meta?: unknown): void;
+    /**
+     * Logs an info-level message.
+     */
+    info(message: string, meta?: unknown): void;
+    /**
+     * Logs a warning-level message.
+     */
+    warn(message: string, meta?: unknown): void;
+    /**
+     * Logs an error-level message.
+     */
+    error(message: string, meta?: unknown): void;
+    private log;
+}
+
+/**
+ * Runtime configuration for the codmir voice daemon.
+ */
+interface DaemonConfig {
+    /** TCP port for the WebSocket server (localhost only). */
+    port: number;
+    /** HTTP port for the webhook receiver (wakeword events). */
+    httpPort: number;
+    /** Log level used by the daemon. */
+    logLevel: LogLevel;
+    /** URL of the desktop-automation service. */
+    desktopAutomationUrl: string;
+    /** URL of the TTS worker service. */
+    ttsWorkerUrl: string;
+    /** URL of the orchestrator service. */
+    orchestratorUrl: string;
+    /** URL of the overlay service (Python PyQt5 ball UI). */
+    overlayUrl: string;
+    /** Whether approval is required before executing commands. */
+    approvalMode: boolean;
+    /** Whether the daemon is muted (ignores wake words). */
+    muted: boolean;
+}
+/**
+ * Loads daemon configuration from environment variables.
+ *
+ * @param logger Logger instance for debug output.
+ */
+declare function loadConfig(logger: Logger): DaemonConfig;
+
+/**
+ * Voice assistant states for UI overlay.
+ */
+type AssistantState = "idle" | "listening" | "thinking" | "speaking" | "error";
+/**
+ * Structured commands that can be executed by the daemon.
+ * All commands are logged and require explicit approval in safe mode.
+ */
+type CodmirCommand = {
+    type: "open_app";
+    name: string;
+} | {
+    type: "open_url";
+    url: string;
+} | {
+    type: "focus_window";
+    titleContains: string;
+} | {
+    type: "type_text";
+    text: string;
+} | {
+    type: "press_key";
+    key: string;
+} | {
+    type: "click";
+    button?: number;
+} | {
+    type: "scroll";
+    direction: "up" | "down";
+    amount?: number;
+} | {
+    type: "speak";
+    text: string;
+    voice?: string;
+} | {
+    type: "run_script";
+    script: string;
+    allowListId?: string;
+};
+
+/**
+ * Callback invoked when the assistant state changes.
+ */
+type StateChangeCallback = (newState: AssistantState, previousState: AssistantState) => void;
+/**
+ * Manages the voice assistant state machine.
+ * States: idle → listening → thinking → speaking → idle
+ */
+declare class AssistantStateMachine {
+    private state;
+    private readonly logger;
+    private readonly listeners;
+    constructor(logger: Logger);
+    /**
+     * Returns the current assistant state.
+     */
+    getState(): AssistantState;
+    /**
+     * Transitions to a new state and notifies listeners.
+     */
+    setState(newState: AssistantState): void;
+    /**
+     * Registers a callback to be invoked on state changes.
+     */
+    onStateChange(callback: StateChangeCallback): () => void;
+    /**
+     * Called when wake word is detected.
+     */
+    handleWake(): void;
+    /**
+     * Called when speech-to-text is complete.
+     */
+    handleTranscriptComplete(): void;
+    /**
+     * Called when AI response is ready and TTS begins.
+     */
+    handleSpeakStart(): void;
+    /**
+     * Called when TTS playback is complete.
+     */
+    handleSpeakEnd(): void;
+    /**
+     * Called on any error, resets to idle.
+     */
+    handleError(): void;
+    /**
+     * Force reset to idle.
+     */
+    reset(): void;
+}
+
+/**
+ * Result of executing a command.
+ */
+interface CommandResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Executes commands by calling the desktop-automation and TTS services.
+ */
+declare class CommandExecutor {
+    private readonly config;
+    private readonly logger;
+    constructor(config: DaemonConfig, logger: Logger);
+    /**
+     * Executes a single command.
+     */
+    execute(command: CodmirCommand): Promise<CommandResult>;
+    private callDesktopAutomation;
+    private callTts;
+}
+
+/**
+ * WebSocket server for the voice daemon.
+ * Clients (overlay, CLI, IDE, web) connect here to receive state updates and send commands.
+ */
+declare class VoiceDaemonWebSocketServer {
+    private readonly config;
+    private readonly logger;
+    private readonly stateMachine;
+    private readonly executor;
+    private readonly wss;
+    private readonly clients;
+    constructor(config: DaemonConfig, logger: Logger, stateMachine: AssistantStateMachine, executor: CommandExecutor);
+    private setupListeners;
+    private setupStateListener;
+    private sendDaemonStarted;
+    private handleMessage;
+    /**
+     * Called when wake word is detected (from wakeword-listener webhook or client).
+     */
+    handleWakeEvent(wakeword: string): void;
+    private handleExecuteCommand;
+    /**
+     * Broadcasts a transcript update to all clients.
+     */
+    broadcastTranscript(text: string, isFinal: boolean): void;
+    /**
+     * Broadcasts an AI response to all clients.
+     */
+    broadcastResponse(text: string, commands?: CodmirCommand[]): void;
+    /**
+     * Broadcasts an error to all clients.
+     */
+    broadcastError(message: string, code?: string): void;
+    private broadcast;
+    private sendToClient;
+    private sendToClientRaw;
+    /**
+     * Shuts down the WebSocket server.
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * HTTP server that receives webhook events from the wakeword-listener.
+ */
+declare class VoiceDaemonHttpServer {
+    private readonly config;
+    private readonly logger;
+    private readonly wsServer;
+    private readonly server;
+    constructor(config: DaemonConfig, logger: Logger, wsServer: VoiceDaemonWebSocketServer);
+    /**
+     * Starts the HTTP server.
+     */
+    start(): void;
+    private handleRequest;
+    private handleWakewordWebhook;
+    /**
+     * Shuts down the HTTP server.
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Display mode for the CLI renderer.
+ */
+type DisplayMode = "gui" | "terminal" | "compact" | "inline" | "none";
+/**
+ * Renderer options.
+ */
+interface RendererOptions {
+    /** Display mode. Auto-detected if not specified. */
+    mode?: DisplayMode;
+    /** Force a specific mode regardless of environment. */
+    forceMode?: boolean;
+}
+/**
+ * CLI Renderer that adapts to the environment.
+ * Uses GUI overlay when available, falls back to terminal/compact modes.
+ */
+declare class CLIRenderer {
+    private readonly mode;
+    private terminalBall;
+    private inlineIndicator;
+    private state;
+    private guiProcess;
+    constructor(options?: RendererOptions);
+    /**
+     * Get the current display mode.
+     */
+    getMode(): DisplayMode;
+    /**
+     * Start the renderer.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the renderer.
+     */
+    stop(): void;
+    /**
+     * Update the assistant state.
+     */
+    setState(state: AssistantState): void;
+    /**
+     * Update transcript display.
+     */
+    setTranscript(text: string): void;
+    /**
+     * Update response display.
+     */
+    setResponse(text: string): void;
+    private startGUI;
+}
+/**
+ * Factory function to create the appropriate renderer.
+ */
+declare function createRenderer(options?: RendererOptions): CLIRenderer;
+
+/**
+ * Terminal-based ball renderer for CLI/server environments.
+ * Renders the assistant state as ASCII art in the terminal.
+ */
+declare class TerminalBall {
+    private state;
+    private frameIndex;
+    private intervalId;
+    private lastTranscript;
+    private lastResponse;
+    private isRunning;
+    private readonly compact;
+    constructor(options?: {
+        compact?: boolean;
+    });
+    /**
+     * Start the terminal ball animation.
+     */
+    start(): void;
+    /**
+     * Stop the terminal ball.
+     */
+    stop(): void;
+    /**
+     * Update the assistant state.
+     */
+    setState(state: AssistantState): void;
+    /**
+     * Update the transcript display.
+     */
+    setTranscript(text: string): void;
+    /**
+     * Update the response display.
+     */
+    setResponse(text: string): void;
+    /**
+     * Get the current state.
+     */
+    getState(): AssistantState;
+    private render;
+    private getFrames;
+    private renderCompact;
+    private renderFull;
+}
+/**
+ * Simple inline status indicator for logging environments.
+ */
+declare class InlineBallIndicator {
+    private state;
+    setState(state: AssistantState): void;
+    getIndicator(): string;
+    getStatusLine(): string;
+}
+
+export { type AssistantState, AssistantStateMachine, CLIRenderer, type CodmirCommand, CommandExecutor, type DaemonConfig, type DisplayMode, InlineBallIndicator, Logger, TerminalBall, VoiceDaemonHttpServer, VoiceDaemonWebSocketServer, createRenderer, loadConfig, normalizeLogLevel };

package/dist/voice-daemon/index.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Log level supported by the daemon logger.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Converts a string or undefined into a valid log level.
+ * Defaults to "info" if the provided value is invalid.
+ *
+ * @param value Raw log level value, typically from environment variables.
+ */
+declare function normalizeLogLevel(value?: string): LogLevel;
+/**
+ * Simple structured logger used by the voice daemon.
+ * Logs to stdout with timestamps and JSON metadata.
+ */
+declare class Logger {
+    private level;
+    private readonly prefix;
+    constructor(level: LogLevel, prefix?: string);
+    /**
+     * Logs a debug-level message.
+     */
+    debug(message: string, meta?: unknown): void;
+    /**
+     * Logs an info-level message.
+     */
+    info(message: string, meta?: unknown): void;
+    /**
+     * Logs a warning-level message.
+     */
+    warn(message: string, meta?: unknown): void;
+    /**
+     * Logs an error-level message.
+     */
+    error(message: string, meta?: unknown): void;
+    private log;
+}
+
+/**
+ * Runtime configuration for the codmir voice daemon.
+ */
+interface DaemonConfig {
+    /** TCP port for the WebSocket server (localhost only). */
+    port: number;
+    /** HTTP port for the webhook receiver (wakeword events). */
+    httpPort: number;
+    /** Log level used by the daemon. */
+    logLevel: LogLevel;
+    /** URL of the desktop-automation service. */
+    desktopAutomationUrl: string;
+    /** URL of the TTS worker service. */
+    ttsWorkerUrl: string;
+    /** URL of the orchestrator service. */
+    orchestratorUrl: string;
+    /** URL of the overlay service (Python PyQt5 ball UI). */
+    overlayUrl: string;
+    /** Whether approval is required before executing commands. */
+    approvalMode: boolean;
+    /** Whether the daemon is muted (ignores wake words). */
+    muted: boolean;
+}
+/**
+ * Loads daemon configuration from environment variables.
+ *
+ * @param logger Logger instance for debug output.
+ */
+declare function loadConfig(logger: Logger): DaemonConfig;
+
+/**
+ * Voice assistant states for UI overlay.
+ */
+type AssistantState = "idle" | "listening" | "thinking" | "speaking" | "error";
+/**
+ * Structured commands that can be executed by the daemon.
+ * All commands are logged and require explicit approval in safe mode.
+ */
+type CodmirCommand = {
+    type: "open_app";
+    name: string;
+} | {
+    type: "open_url";
+    url: string;
+} | {
+    type: "focus_window";
+    titleContains: string;
+} | {
+    type: "type_text";
+    text: string;
+} | {
+    type: "press_key";
+    key: string;
+} | {
+    type: "click";
+    button?: number;
+} | {
+    type: "scroll";
+    direction: "up" | "down";
+    amount?: number;
+} | {
+    type: "speak";
+    text: string;
+    voice?: string;
+} | {
+    type: "run_script";
+    script: string;
+    allowListId?: string;
+};
+
+/**
+ * Callback invoked when the assistant state changes.
+ */
+type StateChangeCallback = (newState: AssistantState, previousState: AssistantState) => void;
+/**
+ * Manages the voice assistant state machine.
+ * States: idle → listening → thinking → speaking → idle
+ */
+declare class AssistantStateMachine {
+    private state;
+    private readonly logger;
+    private readonly listeners;
+    constructor(logger: Logger);
+    /**
+     * Returns the current assistant state.
+     */
+    getState(): AssistantState;
+    /**
+     * Transitions to a new state and notifies listeners.
+     */
+    setState(newState: AssistantState): void;
+    /**
+     * Registers a callback to be invoked on state changes.
+     */
+    onStateChange(callback: StateChangeCallback): () => void;
+    /**
+     * Called when wake word is detected.
+     */
+    handleWake(): void;
+    /**
+     * Called when speech-to-text is complete.
+     */
+    handleTranscriptComplete(): void;
+    /**
+     * Called when AI response is ready and TTS begins.
+     */
+    handleSpeakStart(): void;
+    /**
+     * Called when TTS playback is complete.
+     */
+    handleSpeakEnd(): void;
+    /**
+     * Called on any error, resets to idle.
+     */
+    handleError(): void;
+    /**
+     * Force reset to idle.
+     */
+    reset(): void;
+}
+
+/**
+ * Result of executing a command.
+ */
+interface CommandResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Executes commands by calling the desktop-automation and TTS services.
+ */
+declare class CommandExecutor {
+    private readonly config;
+    private readonly logger;
+    constructor(config: DaemonConfig, logger: Logger);
+    /**
+     * Executes a single command.
+     */
+    execute(command: CodmirCommand): Promise<CommandResult>;
+    private callDesktopAutomation;
+    private callTts;
+}
+
+/**
+ * WebSocket server for the voice daemon.
+ * Clients (overlay, CLI, IDE, web) connect here to receive state updates and send commands.
+ */
+declare class VoiceDaemonWebSocketServer {
+    private readonly config;
+    private readonly logger;
+    private readonly stateMachine;
+    private readonly executor;
+    private readonly wss;
+    private readonly clients;
+    constructor(config: DaemonConfig, logger: Logger, stateMachine: AssistantStateMachine, executor: CommandExecutor);
+    private setupListeners;
+    private setupStateListener;
+    private sendDaemonStarted;
+    private handleMessage;
+    /**
+     * Called when wake word is detected (from wakeword-listener webhook or client).
+     */
+    handleWakeEvent(wakeword: string): void;
+    private handleExecuteCommand;
+    /**
+     * Broadcasts a transcript update to all clients.
+     */
+    broadcastTranscript(text: string, isFinal: boolean): void;
+    /**
+     * Broadcasts an AI response to all clients.
+     */
+    broadcastResponse(text: string, commands?: CodmirCommand[]): void;
+    /**
+     * Broadcasts an error to all clients.
+     */
+    broadcastError(message: string, code?: string): void;
+    private broadcast;
+    private sendToClient;
+    private sendToClientRaw;
+    /**
+     * Shuts down the WebSocket server.
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * HTTP server that receives webhook events from the wakeword-listener.
+ */
+declare class VoiceDaemonHttpServer {
+    private readonly config;
+    private readonly logger;
+    private readonly wsServer;
+    private readonly server;
+    constructor(config: DaemonConfig, logger: Logger, wsServer: VoiceDaemonWebSocketServer);
+    /**
+     * Starts the HTTP server.
+     */
+    start(): void;
+    private handleRequest;
+    private handleWakewordWebhook;
+    /**
+     * Shuts down the HTTP server.
+     */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Display mode for the CLI renderer.
+ */
+type DisplayMode = "gui" | "terminal" | "compact" | "inline" | "none";
+/**
+ * Renderer options.
+ */
+interface RendererOptions {
+    /** Display mode. Auto-detected if not specified. */
+    mode?: DisplayMode;
+    /** Force a specific mode regardless of environment. */
+    forceMode?: boolean;
+}
+/**
+ * CLI Renderer that adapts to the environment.
+ * Uses GUI overlay when available, falls back to terminal/compact modes.
+ */
+declare class CLIRenderer {
+    private readonly mode;
+    private terminalBall;
+    private inlineIndicator;
+    private state;
+    private guiProcess;
+    constructor(options?: RendererOptions);
+    /**
+     * Get the current display mode.
+     */
+    getMode(): DisplayMode;
+    /**
+     * Start the renderer.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the renderer.
+     */
+    stop(): void;
+    /**
+     * Update the assistant state.
+     */
+    setState(state: AssistantState): void;
+    /**
+     * Update transcript display.
+     */
+    setTranscript(text: string): void;
+    /**
+     * Update response display.
+     */
+    setResponse(text: string): void;
+    private startGUI;
+}
+/**
+ * Factory function to create the appropriate renderer.
+ */
+declare function createRenderer(options?: RendererOptions): CLIRenderer;
+
+/**
+ * Terminal-based ball renderer for CLI/server environments.
+ * Renders the assistant state as ASCII art in the terminal.
+ */
+declare class TerminalBall {
+    private state;
+    private frameIndex;
+    private intervalId;
+    private lastTranscript;
+    private lastResponse;
+    private isRunning;
+    private readonly compact;
+    constructor(options?: {
+        compact?: boolean;
+    });
+    /**
+     * Start the terminal ball animation.
+     */
+    start(): void;
+    /**
+     * Stop the terminal ball.
+     */
+    stop(): void;
+    /**
+     * Update the assistant state.
+     */
+    setState(state: AssistantState): void;
+    /**
+     * Update the transcript display.
+     */
+    setTranscript(text: string): void;
+    /**
+     * Update the response display.
+     */
+    setResponse(text: string): void;
+    /**
+     * Get the current state.
+     */
+    getState(): AssistantState;
+    private render;
+    private getFrames;
+    private renderCompact;
+    private renderFull;
+}
+/**
+ * Simple inline status indicator for logging environments.
+ */
+declare class InlineBallIndicator {
+    private state;
+    setState(state: AssistantState): void;
+    getIndicator(): string;
+    getStatusLine(): string;
+}
+
+export { type AssistantState, AssistantStateMachine, CLIRenderer, type CodmirCommand, CommandExecutor, type DaemonConfig, type DisplayMode, InlineBallIndicator, Logger, TerminalBall, VoiceDaemonHttpServer, VoiceDaemonWebSocketServer, createRenderer, loadConfig, normalizeLogLevel };