osborn 0.1.6 → 0.5.3

package/.env.example

@@ -1,5 +1,5 @@
 # LLM Provider: 'openai' or 'gemini'
-LLM_PROVIDER=openai
+LLM_PROVIDER=gemini
 
 # LiveKit
 LIVEKIT_URL=wss://your-project.livekit.cloud
@@ -12,3 +12,10 @@ OPENAI_API_KEY=sk-...
 # Google AI (for Gemini Live - FREE during preview!)
 # Get your key at: https://aistudio.google.com/apikey
 GOOGLE_API_KEY=AIzaSy...
+
+# Anthropic (required for Claude Agent SDK + Fast Brain)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Smithery (cloud-hosted MCP servers - YouTube, GitHub, etc.)
+# Get your key at: https://smithery.ai
+# SMITHERY_API_KEY=your-smithery-api-key

package/dist/bridge-llm.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bridge LLM Module - Creates LLM instances for pipelined voice sessions
+ *
+ * In pipelined mode, we use a separate LLM (Gemini or GPT-4o) as the
+ * "conversation manager" that handles voice I/O and routes to Claude Code.
+ */
+import * as google from '@livekit/agents-plugin-google';
+import * as openai from '@livekit/agents-plugin-openai';
+export interface BridgeLLMConfig {
+    provider: 'gemini-pro' | 'gemini-flash' | 'gpt-4o' | 'gpt-4o-mini';
+    model?: string;
+}
+/**
+ * Create Bridge LLM instance for pipelined voice sessions
+ *
+ * Options:
+ * - gemini-pro: Gemini 2.5 Pro (smart, good reasoning)
+ * - gemini-flash: Gemini 2.0 Flash (faster, cheaper)
+ * - gpt-4o: GPT-4o (alternative if OpenAI preferred)
+ * - gpt-4o-mini: GPT-4o Mini (faster, cheaper)
+ */
+export declare function createBridgeLLM(config: BridgeLLMConfig): google.LLM | openai.LLM;

package/dist/bridge-llm.js

@@ -0,0 +1,39 @@
+/**
+ * Bridge LLM Module - Creates LLM instances for pipelined voice sessions
+ *
+ * In pipelined mode, we use a separate LLM (Gemini or GPT-4o) as the
+ * "conversation manager" that handles voice I/O and routes to Claude Code.
+ */
+import * as google from '@livekit/agents-plugin-google';
+import * as openai from '@livekit/agents-plugin-openai';
+/**
+ * Create Bridge LLM instance for pipelined voice sessions
+ *
+ * Options:
+ * - gemini-pro: Gemini 2.5 Pro (smart, good reasoning)
+ * - gemini-flash: Gemini 2.0 Flash (faster, cheaper)
+ * - gpt-4o: GPT-4o (alternative if OpenAI preferred)
+ * - gpt-4o-mini: GPT-4o Mini (faster, cheaper)
+ */
+export function createBridgeLLM(config) {
+    switch (config.provider) {
+        case 'gemini-pro':
+            return new google.LLM({
+                model: config.model || 'gemini-2.5-pro',
+            });
+        case 'gemini-flash':
+            return new google.LLM({
+                model: config.model || 'gemini-2.0-flash',
+            });
+        case 'gpt-4o':
+            return new openai.LLM({
+                model: config.model || 'gpt-4o',
+            });
+        case 'gpt-4o-mini':
+            return new openai.LLM({
+                model: config.model || 'gpt-4o-mini',
+            });
+        default:
+            throw new Error(`Unknown Bridge LLM provider: ${config.provider}`);
+    }
+}

package/dist/claude-handler.d.ts

@@ -35,6 +35,12 @@ export declare class ClaudeHandler extends EventEmitter {
     private static readonly ALL_TOOLS;
     private static readonly PLAN_TOOLS;
     private static readonly EXECUTE_TOOLS;
+    private static readonly MCP_READ_ONLY_PATTERNS;
+    /**
+     * Check if an MCP tool is safe for read-only/plan mode
+     * Returns true if the tool only reads data (doesn't modify external resources)
+     */
+    private static isMcpToolReadOnly;
     private agentRole;
     constructor(options?: ClaudeHandlerOptions);
     /**

package/dist/claude-handler.js

@@ -67,6 +67,30 @@ export class ClaudeHandler extends EventEmitter {
     ];
     // Execute mode tools - full access
     static EXECUTE_TOOLS = ClaudeHandler.ALL_TOOLS;
+    // MCP Read-Only patterns - tools that don't modify external resources
+    // These patterns match MCP tool names that are safe for read-only/plan mode
+    static MCP_READ_ONLY_PATTERNS = [
+        // GitHub - read operations only (search, list, get)
+        /^mcp__github__(search|list|get)_/,
+        // YouTube - all tools are typically read-only
+        /^mcp__youtube__/,
+        // LiveKit - read operations only (list, get)
+        /^mcp__livekit__(list|get)_/,
+        // LiveKit docs - all read-only
+        /^mcp__livekit-docs__/,
+        // Filesystem - read only
+        /^mcp__filesystem__read/,
+        // Generic patterns for common read operations across any MCP server
+        /^mcp__[^_]+__(get|list|search|read|fetch|query|describe|show|find)_/,
+        /^mcp__[^_]+__(get|list|search|read|fetch|query|describe|show|find)$/,
+    ];
+    /**
+     * Check if an MCP tool is safe for read-only/plan mode
+     * Returns true if the tool only reads data (doesn't modify external resources)
+     */
+    static isMcpToolReadOnly(toolName) {
+        return ClaudeHandler.MCP_READ_ONLY_PATTERNS.some(pattern => pattern.test(toolName));
+    }
     agentRole;
     constructor(options = {}) {
         super();
@@ -175,6 +199,24 @@ export class ClaudeHandler extends EventEmitter {
                                     const description = this.getToolDescription(toolName, toolInput);
                                     // Record start time for duration tracking
                                     this.toolStartTimes.set(id, Date.now());
+                                    // Block write MCP operations in plan/read-only mode
+                                    if (this.agentRole === 'plan' && toolName.startsWith('mcp__')) {
+                                        if (!ClaudeHandler.isMcpToolReadOnly(toolName)) {
+                                            console.log(`❌ Blocked write MCP tool in plan mode: ${toolName}`);
+                                            logToolCall({
+                                                timestamp: new Date().toISOString(),
+                                                toolName,
+                                                toolUseId: id,
+                                                input: toolInput,
+                                                status: 'blocked',
+                                                error: 'MCP write operation blocked in read-only mode',
+                                            });
+                                            return {
+                                                decision: 'block',
+                                                reason: 'Write operations are not allowed in read-only mode. Switch to edit mode to use this tool.'
+                                            };
+                                        }
+                                    }
                                     // Log tool start (background, non-blocking)
                                     logToolCall({
                                         timestamp: new Date().toISOString(),
@@ -248,7 +290,7 @@ export class ClaudeHandler extends EventEmitter {
                                         duration,
                                     });
                                     console.log(`✅ Completed: ${toolName} (${duration ? duration + 'ms' : 'unknown duration'})`);
-                                    this.emit('tool_result', { name: toolName, output: toolOutput, duration });
+                                    this.emit('tool_result', { name: toolName, input: input?.tool_input || {}, output: toolOutput, duration });
                                     return {};
                                 }]
                         }]

package/dist/claude-llm.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Claude LLM Wrapper for LiveKit Agents
+ *
+ * Wraps the Claude Agent SDK (@anthropic-ai/claude-agent-sdk) to work
+ * with LiveKit's AgentSession as an LLM provider.
+ *
+ * Flow: User speaks → STT → ClaudeLLM (Agent SDK) → TTS → User hears
+ */
+import { llm, type APIConnectOptions } from '@livekit/agents';
+import { type McpServerConfig } from '@anthropic-ai/claude-agent-sdk';
+import { EventEmitter } from 'events';
+export interface ClaudeLLMOptions {
+    workingDirectory?: string;
+    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions';
+    allowedTools?: string[];
+    eventEmitter?: EventEmitter;
+    resumeSessionId?: string;
+    continueSession?: boolean;
+    mcpServers?: Record<string, McpServerConfig>;
+    model?: string;
+}
+/**
+ * Claude LLM - Wraps Claude Agent SDK for LiveKit
+ * Research mode: reads anything, writes only to session workspace
+ */
+export declare class ClaudeLLM extends llm.LLM {
+    #private;
+    constructor(opts?: ClaudeLLMOptions);
+    /**
+     * Respond to a pending permission request
+     * Call this after receiving 'permission_request' event
+     */
+    respondToPermission(allow: boolean, message?: string): void;
+    /**
+     * Check if there's a pending permission request
+     */
+    hasPendingPermission(): boolean;
+    /**
+     * Get pending permission details
+     */
+    getPendingPermission(): {
+        toolName: string;
+        input: any;
+    } | null;
+    /**
+     * Get all currently enabled MCP servers
+     */
+    getMcpServers(): Record<string, McpServerConfig>;
+    /**
+     * Get list of enabled MCP server keys
+     */
+    getEnabledMcpServerKeys(): string[];
+    /**
+     * Replace all MCP servers at once
+     */
+    setMcpServers(servers: Record<string, McpServerConfig>): void;
+    /**
+     * Enable a single MCP server
+     */
+    enableMcpServer(key: string, config: McpServerConfig): void;
+    /**
+     * Disable a single MCP server
+     */
+    disableMcpServer(key: string): void;
+    label(): string;
+    get model(): string;
+    get sessionId(): string | null;
+    /**
+     * Set session ID to resume a specific conversation
+     * Call this before sending the first message to resume from a previous session
+     */
+    setResumeSessionId(sessionId: string | null): void;
+    /**
+     * Reset state for mid-conversation session switch
+     * Clears pending permissions and resets conversation tracking
+     */
+    resetForSessionSwitch(): void;
+    /**
+     * Enable "continue" mode - resumes most recent session
+     */
+    setContinueSession(enabled: boolean): void;
+    /**
+     * Check if this instance is configured to resume a session
+     */
+    get isResumingSession(): boolean;
+    get events(): EventEmitter;
+    /**
+     * Capture a checkpoint UUID for potential file rewind
+     * Called internally when receiving user message UUIDs from the SDK
+     */
+    captureCheckpoint(checkpointId: string): void;
+    /**
+     * Get the most recent checkpoint UUID
+     * Use this to rewind all file changes back to the beginning
+     */
+    getLatestCheckpoint(): string | null;
+    /**
+     * Get the first checkpoint UUID (initial state)
+     * Rewinding to this restores all files to their original state
+     */
+    getFirstCheckpoint(): string | null;
+    /**
+     * Get all captured checkpoint UUIDs
+     * Ordered from oldest to newest
+     */
+    getCheckpoints(): string[];
+    /**
+     * Clear all captured checkpoints
+     * Call this when starting a new session
+     */
+    clearCheckpoints(): void;
+    /**
+     * Check if checkpoints are available
+     */
+    hasCheckpoints(): boolean;
+    chat({ chatCtx, toolCtx, connOptions, }: {
+        chatCtx: llm.ChatContext;
+        toolCtx?: llm.ToolContext;
+        connOptions?: APIConnectOptions;
+        parallelToolCalls?: boolean;
+        toolChoice?: llm.ToolChoice;
+        extraKwargs?: Record<string, unknown>;
+    }): llm.LLMStream;
+}
+/**
+ * Create a ClaudeLLM instance
+ */
+export declare function createClaudeLLM(opts?: ClaudeLLMOptions): ClaudeLLM;