undefined

undefined

// Core conversation loop structure
async function* conversationLoop(deps: QueryDeps): AsyncGenerator<QueryEvent> {
  while (true) {
    // 1. Prepare context window (token budget management)
    const context = await buildContext(deps);
    
    // 2. Call LLM with tools
    const response = await llmClient.chat({
      messages: context.messages,
      tools: context.availableTools,
      max_tokens: context.tokenBudget
    });
    
    // 3. Yield different event types
    if (response.type === 'text') {
      yield { type: 'text_delta', delta: response.content };
    } else if (response.type === 'tool_use') {
      // 4. Execute tool with permission check
      const result = await executeToolWithPermission(response.tool, deps);
      yield { type: 'tool_result', result };
    }
    
    // 5. Check termination conditions (10 types)
    if (shouldTerminate(response)) {
      yield { type: 'done', reason: response.stopReason };
      break;
    }
  }
}

// Five yield event types:
// - text_delta: Streaming text chunks
// - tool_use: Tool invocation request
// - tool_result: Tool execution result
// - context_compression: Token budget overflow handling
// - done: Termination with reason

// Tool<Input, Output, Permission> protocol
interface Tool<I, O, P extends PermissionLevel> {
  // 1. Schema: Zod v4 input validation
  schema: z.ZodType<I>;
  
  // 2. Handler: Core execution logic
  handler: (input: I, deps: QueryDeps) => Promise<O>;
  
  // 3. Metadata: LLM-visible description
  metadata: {
    name: string;
    description: string;
    parameters: JSONSchema; // Auto-generated from Zod
  };
  
  // 4. Properties: Execution characteristics
  properties: {
    readOnly: boolean;        // Safe to run speculatively
    destructive: boolean;     // Irreversible side effects
    concurrencySafe: boolean; // Can run in parallel
  };
  
  // 5. Permission: Required access level
  permission: P; // 'read' | 'write' | 'execute' | 'admin' | 'auto'
}

// buildTool: Fault-safe factory pattern
const readFileTool = buildTool({
  schema: z.object({
    path: z.string(),
    encoding: z.enum(['utf-8', 'base64']).default('utf-8')
  }),
  permission: 'read',
  properties: {
    readOnly: true,
    destructive: false,
    concurrencySafe: true
  },
  handler: async ({ path, encoding }, deps) => {
    const absPath = deps.workspace.resolvePath(path);
    
    // Safety check: Must be within workspace
    if (!deps.workspace.contains(absPath)) {
      throw new ToolError('PathOutsideWorkspace', { path });
    }
    
    return await deps.fs.readFile(absPath, encoding);
  }
});

// Tool categories (12 types, 50+ total tools):
// - File I/O: read_file, write_file, list_directory
// - Shell: execute_bash, run_command
// - Search: ripgrep_search, file_search
// - Edit: apply_diff, replace_in_file
// - Browser: navigate, screenshot, click
// - Git: commit, push, checkout
// - Memory: store_memory, recall_memory
// - Agent: fork_agent, spawn_worker
// - Config: update_settings, add_skill
// - MCP: call_mcp_tool, list_mcp_resources

// Divide tools into read-only vs. side-effecting partitions
async function executeConcurrently(tools: ToolCall[]): Promise<ToolResult[]> {
  const [readOnly, sideEffecting] = partition(
    tools,
    t => t.properties.readOnly && t.properties.concurrencySafe
  );
  
  // Execute read-only tools in parallel
  const readOnlyResults = await Promise.all(
    readOnly.map(t => t.handler(t.input, deps))
  );
  
  // Execute side-effecting tools sequentially
  const sideEffectingResults = [];
  for (const tool of sideEffecting) {
    sideEffectingResults.push(await tool.handler(tool.input, deps));
  }
  
  return [...readOnlyResults, ...sideEffectingResults];
}

// Four-stage permission pipeline
type PermissionStage = 
  | 'classification'  // Speculative 2s pre-approval
  | 'validation'      // Schema + safety checks
  | 'authorization'   // User consent (if needed)
  | 'execution';      // Actual tool call

async function permissionPipeline(
  toolCall: ToolCall,
  mode: PermissionMode
): Promise<ToolResult> {
  // Stage 1: Classification (speculative, 2-second timeout)
  const classification = await Promise.race([
    classifyRisk(toolCall),
    timeout(2000, { risk: 'unknown' })
  ]);
  
  // Stage 2: Validation
  const validated = await validateToolCall(toolCall, {
    schema: toolCall.tool.schema,
    bashRules: mode === 'safe' ? SAFE_BASH_RULES : null,
    pathRestrictions: deps.workspace.boundaries
  });
  
  // Stage 3: Authorization (mode-dependent)
  if (requiresConsent(toolCall, mode, classification)) {
    const consent = await deps.ui.requestPermission({
      tool: toolCall.tool.name,
      input: toolCall.input,
      risk: classification.risk,
      preview: classification.preview
    });
    
    if (!consent.approved) {
      throw new PermissionDeniedError(consent.reason);
    }
  }
  
  // Stage 4: Execution
  return await toolCall.tool.handler(validated.input, deps);
}

// Five permission modes (spectrum)
type PermissionMode = 
  | 'safe'      // Auto-approve read-only, deny write/execute
  | 'normal'    // Ask for write, auto-approve read
  | 'relaxed'   // Auto-approve most, ask for destructive
  | 'auto'      // Auto-approve all (trust agent completely)
  | 'custom';   // User-defined rules

// Bash safety rules (safe mode)
const SAFE_BASH_RULES = {
  allowedCommands: ['ls', 'cat', 'grep', 'find', 'head', 'tail'],
  deniedPatterns: [
    /rm\s+-rf/,           // Destructive deletion
    /sudo/,               // Privilege escalation
    /curl.*\|\s*bash/,    // Pipe to shell
    />\s*\/dev\/sd/       // Direct disk access
  ],
  maxCommandLength: 500
};

// Effective window formula
interface ContextWindow {
  total: number;              // Model's max context (200K for Claude 3.5)
  systemPrompt: number;       // ~2K tokens
  toolDefinitions: number;    // ~50 tokens per tool × N tools
  reserved: number;           // ~4K for output buffer
  effective: number;          // Available for conversation history
}

function calculateEffectiveWindow(deps: QueryDeps): ContextWindow {
  const total = deps.model.contextLimit; // 200_000
  const systemPrompt = estimateTokens(deps.systemPrompt);
  const toolDefinitions = deps.tools.length * 50;
  const reserved = 4_000;
  
  return {
    total,
    systemPrompt,
    toolDefinitions,
    reserved,
    effective: total - systemPrompt - toolDefinitions - reserved
  };
}

// Four-level progressive compression
async function compressContext(
  messages: Message[],
  targetTokens: number
): Promise<Message[]> {
  let compressed = messages;
  let currentTokens = estimateTokens(compressed);
  
  // Level 1: Snip old image content (images are 1500+ tokens each)
  if (currentTokens > targetTokens) {
    compressed = snipImages(compressed, { keepRecent: 3 });
    currentTokens = estimateTokens(compressed);
  }
  
  // Level 2: Micro-compact (merge adjacent same-role messages)
  if (currentTokens > targetTokens) {
    compressed = microCompact(compressed);
    currentTokens = estimateTokens(compressed);
  }
  
  // Level 3: Collapse (summarize tool results)
  if (currentTokens > targetTokens) {
    compressed = await collapseToolResults(compressed, {
      summarizeOlderThan: 10, // Message index threshold
      maxSummaryTokens: 200
    });
    currentTokens = estimateTokens(compressed);
  }
  
  // Level 4: Auto-compact (LLM summarization)
  if (currentTokens > targetTokens) {
    compressed = await autoCompact(compressed, {
      targetRatio: 0.5, // Compress to 50%
      preserveRecent: 5 // Keep last 5 exchanges intact
    });
  }
  
  return compressed;
}

// Circuit breaker pattern (prevent infinite compression)
class CompressionCircuitBreaker {
  private failureCount = 0;
  private lastReset = Date.now();
  
  async attempt<T>(fn: () => Promise<T>): Promise<T> {
    if (this.failureCount >= 3) {
      if (Date.now() - this.lastReset < 60_000) {
        throw new Error('Compression circuit breaker open');
      }
      this.reset();
    }
    
    try {
      const result = await fn();
      this.reset();
      return result;
    } catch (error) {
      this.failureCount++;
      throw error;
    }
  }
  
  private reset() {
    this.failureCount = 0;
    this.lastReset = Date.now();
  }
}

// Memory types (closed set - only these four)
type MemoryType = 
  | 'code_patterns'    // Architecture decisions, idioms
  | 'user_preferences' // Settings, workflow habits
  | 'project_context'  // Goals, constraints, history
  | 'task_progress';   // Ongoing work state

interface Memory {
  type: MemoryType;
  key: string;           // Unique identifier
  content: string;       // Natural language
  metadata: {
    created: string;     // ISO timestamp
    accessed: string;    // Last retrieval
    confidence: number;  // 0-1, for pruning
  };
}

// "Only store what cannot be derived" principle
async function shouldStore(content: string, deps: QueryDeps): Promise<boolean> {
  // Don't store if:
  // - Can be read from files
  // - Can be inferred from code
  // - Is ephemeral state
  
  const derivable = [
    () => deps.workspace.files.includes(content), // File content
    () => /^(let|const|function)/.test(content),  // Code snippets
    () => isTemporary(content)                     // Timestamps, PIDs
  ];
  
  return !derivable.some(check => check());
}

// MEMORY.md index structure
/*

undefined

// Five hook categories
type HookCategory = 
  | 'lifecycle'    // conversation_start, query_begin, query_end
  | 'tool'         // tool_before, tool_after, tool_error
  | 'content'      // message_sent, message_received, context_compressed
  | 'system'       // config_changed, skill_loaded, mcp_connected
  | 'agent';       // agent_forked, agent_terminated

interface Hook {
  event: string;        // e.g., 'tool_before_execute'
  handler: string;      // Path to executable
  config?: {
    priority: number;   // 0-5 (higher = earlier)
    async: boolean;     // Run without blocking
    timeout: number;    // Max execution time (ms)
  };
}

// JSON response protocol
interface HookResponse {
  allow?: boolean;        // For before_* hooks: veto execution
  modify?: {              // For content hooks: transform data
    input?: unknown;
    output?: unknown;
  };
  metadata?: Record<string, unknown>; // Arbitrary data for next hooks
}

// Example: Audit hook (log all tool executions)
// .claude/hooks/audit-tools.ts
export default async function auditHook(event: HookEvent): Promise<HookResponse> {
  if (event.type === 'tool_before_execute') {
    await fs.appendFile(
      '.claude/audit.log',
      JSON.stringify({
        timestamp: new Date().toISOString(),
        tool: event.data.tool.name,
        input: event.data.input,
        user: process.env.USER
      }) + '\n'
    );
  }
  
  return { allow: true }; // Don't block execution
}

// Security: Three-layer sandbox
// 1. Process isolation (separate Node.js process)
// 2. Permission restrictions (can't access parent env vars)
// 3. Timeout enforcement (default 5s)

// Three agent sources
type AgentSource = 
  | 'builtin'    // Four built-in agents: coordinator, worker, researcher, reviewer
  | 'skill'      // Defined in SKILL.md files
  | 'fork';      // Cloned from current agent

// Fork with context inheritance
async function forkCurrentAgent(
  purpose: string,
  deps: QueryDeps
): Promise<Agent> {
  // Recursive fork depth protection
  if (deps.forkDepth >= 3) {
    throw new Error('Max fork depth exceeded (prevents infinite recursion)');
  }
  
  const childAgent = new Agent({
    ...deps,
    forkDepth: deps.forkDepth + 1,
    
    // Inherit full message history (byte-level copy)
    context: {
      messages: structuredClone(deps.context.messages),
      tokenBudget: deps.context.tokenBudget * 0.8 // 80% of parent budget
    },
    
    // Inherit selective memory
    memory: forkMemory(deps.memory, ['project_context', 'code_patterns']),
    
    // New task-specific system prompt
    systemPrompt: `${deps.systemPrompt}\n\nForked for: ${purpose}`,
    
    // Inherit parent's tool access
    tools: deps.tools,
    permissions: deps.permissions
  });
  
  return childAgent;
}

// Four built-in agents
const BUILTIN_AGENTS = {
  coordinator: {
    role: 'Orchestrate multiple workers, never execute tools directly',
    tools: ['fork_agent', 'send_message_to_agent', 'collect_results'],
    constraints: ['no_file_access', 'no_shell_access']
  },
  worker: {
    role: 'Execute specific tasks assigned by coordinator',
    tools: ['all'], // Full tool access
    constraints: ['report_progress_every_5min']
  },
  researcher: {
    role: 'Gather information, no side effects',
    tools: ['read_file', 'search', 'browse', 'read_memory'],
    constraints: ['read_only_mode']
  },
  reviewer: {
    role: 'Analyze code, suggest improvements',
    tools: ['read_file', 'run_linter', 'run_tests'],
    constraints: ['no_modifications']
  }
};

// Eight transport protocols
type MCPTransport = 
  | 'stdio'      // Standard I/O pipes
  | 'http'       // REST API
  | 'websocket'  // WebSocket
  | 'grpc'       // gRPC
  | 'ipc'        // Inter-process communication
  | 'tcp'        // Raw TCP
  | 'udp'        // UDP datagrams
  | 'sse';       // Server-sent events

// Five-state connection management
type MCPConnectionState = 
  | 'disconnected'
  | 'connecting'
  | 'connected'
  | 'error'
  | 'reconnecting';

class MCPConnection {
  state: MCPConnectionState = 'disconnected';
  retryCount = 0;
  maxRetries = 3;
  
  async connect(config: MCPServerConfig) {
    this.state = 'connecting';
    
    try {
      const transport = createTransport(config.transport);
      await transport.initialize();
      
      // Handshake: Exchange capabilities
      const serverInfo = await transport.request({
        method: 'initialize',
        params: {
          clientInfo: { name: 'claude-code', version: '1.0' },
          capabilities: ['tools', 'resources', 'prompts']
        }
      });
      
      this.state = 'connected';
      return serverInfo;
    } catch (error) {
      this.state = 'error';
      
      if (this.retryCount < this.maxRetries) {
        this.retryCount++;
        this.state = 'reconnecting';
        await sleep(1000 * this.retryCount); // Exponential backoff
        return this.connect(config);
      }
      
      throw error;
    }
  }
}

// Three-segment tool naming (namespace isolation)
// Format: mcp://{server_name}/{tool_name}
const mcpTool = {
  name: 'mcp://github/create_issue',
  handler: async (input, deps) => {
    const connection = deps.mcpConnections.get('github');
    return await connection.call('create_issue', input);
  }
};

// Bridge pattern (bidirectional communication)
class MCPBridge {
  // Forward: Agent → MCP Server
  async callTool(server: string, tool: string, input: unknown) {
    const conn = this.connections.get(server);
    return await conn.request({
      method: 'tools/call',
      params: { name: tool, arguments: input }
    });
  }
  
  // Reverse: MCP Server → Agent (notifications)
  async handleNotification(notification: MCPNotification) {
    if (notification.method === 'resources/updated') {
      // Invalidate cached resources
      await this.invalidateCache(notification.params.uri);
    }
  }
}