refactor(sdk): extract helpers from promptAiSdkStream (Commit 2.15)

Extracts multiple concerns from llm.ts and run-state.ts into focused helper modules:

1. claude-oauth-errors.ts: Detect rate limit (429) and auth errors (401/403) for Claude OAuth fallback
2. file-tree-builder.ts: Build hierarchical file trees, compute project indexes
3. git-operations.ts: Git status/diff/log operations with graceful error handling
4. knowledge-files.ts: Knowledge file discovery with *.knowledge.md pattern support
5. project-discovery.ts: Auto-discover project files using .gitignore patterns
6. session-state-processors.ts: Process agent and custom tool definitions
7. stream-cost-tracker.ts: Extract and track API costs with profit margin calculation
8. tool-call-repair.ts: Transform misnamed agent calls to spawn_agents format

File reductions:
- llm.ts: ~540 -> ~380 lines (-30%)
- run-state.ts: ~700 -> ~310 lines (-56%)

Comprehensive unit tests added (63 tests total):
- claude-oauth-errors.test.ts: 22 tests (status codes, message patterns)
- stream-cost-tracker.test.ts: 11 tests (cost calculation, profit margin)
- tool-call-repair.test.ts: 15 tests (agent transformation, JSON parsing)
- file-tree-builder.test.ts: 15 tests (tree building, sorting)
- knowledge-file-selection.test.ts: 128 tests (existing)

Author: brandonkachen

sdk/src/__tests__/claude-oauth-errors.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  isClaudeOAuthRateLimitError,
+  isClaudeOAuthAuthError,
+} from '../impl/claude-oauth-errors'
+
+/**
+ * These tests focus on DOMAIN LOGIC - the specific status codes and string patterns
+ * we use to detect Claude OAuth errors. Low-value tests that just verify JavaScript
+ * built-in behavior (typeof, null checks) have been removed.
+ */
+
+describe('isClaudeOAuthRateLimitError', () => {
+  describe('status code 429 detection', () => {
+    it('should detect statusCode 429', () => {
+      expect(isClaudeOAuthRateLimitError({ statusCode: 429 })).toBe(true)
+    })
+
+    it('should detect status 429 (AI SDK format)', () => {
+      expect(isClaudeOAuthRateLimitError({ status: 429 })).toBe(true)
+    })
+
+    it('should NOT detect status 500 as rate limit', () => {
+      expect(isClaudeOAuthRateLimitError({ statusCode: 500 })).toBe(false)
+    })
+  })
+
+  describe('message pattern detection', () => {
+    it('should detect "rate_limit" (underscore)', () => {
+      expect(isClaudeOAuthRateLimitError({ message: 'rate_limit exceeded' })).toBe(true)
+    })
+
+    it('should detect "rate limit" (space)', () => {
+      expect(isClaudeOAuthRateLimitError({ message: 'Rate limit exceeded' })).toBe(true)
+    })
+
+    it('should detect "overloaded"', () => {
+      expect(isClaudeOAuthRateLimitError({ message: 'API is overloaded' })).toBe(true)
+    })
+
+    it('should be case-insensitive (calls toLowerCase)', () => {
+      expect(isClaudeOAuthRateLimitError({ message: 'RATE_LIMIT' })).toBe(true)
+      expect(isClaudeOAuthRateLimitError({ message: 'OVERLOADED' })).toBe(true)
+    })
+  })
+
+  describe('responseBody pattern detection', () => {
+    it('should detect rate_limit in responseBody', () => {
+      expect(isClaudeOAuthRateLimitError({ responseBody: '{"error": "rate_limit"}' })).toBe(true)
+    })
+
+    it('should detect overloaded in responseBody', () => {
+      expect(isClaudeOAuthRateLimitError({ responseBody: 'server is overloaded' })).toBe(true)
+    })
+  })
+
+  it('should work with real Error objects', () => {
+    const error = new Error('Rate limit exceeded')
+    ;(error as any).statusCode = 429
+    expect(isClaudeOAuthRateLimitError(error)).toBe(true)
+  })
+})
+
+describe('isClaudeOAuthAuthError', () => {
+  describe('status code 401/403 detection', () => {
+    it('should detect statusCode 401', () => {
+      expect(isClaudeOAuthAuthError({ statusCode: 401 })).toBe(true)
+    })
+
+    it('should detect statusCode 403', () => {
+      expect(isClaudeOAuthAuthError({ statusCode: 403 })).toBe(true)
+    })
+
+    it('should NOT detect status 429 as auth error', () => {
+      expect(isClaudeOAuthAuthError({ statusCode: 429 })).toBe(false)
+    })
+  })
+
+  describe('message pattern detection', () => {
+    it('should detect "unauthorized"', () => {
+      expect(isClaudeOAuthAuthError({ message: 'Request unauthorized' })).toBe(true)
+    })
+
+    it('should detect "invalid_token"', () => {
+      expect(isClaudeOAuthAuthError({ message: 'invalid_token: expired' })).toBe(true)
+    })
+
+    it('should detect "authentication"', () => {
+      expect(isClaudeOAuthAuthError({ message: 'Authentication failed' })).toBe(true)
+    })
+
+    it('should detect "expired"', () => {
+      expect(isClaudeOAuthAuthError({ message: 'Token expired' })).toBe(true)
+    })
+
+    it('should be case-insensitive', () => {
+      expect(isClaudeOAuthAuthError({ message: 'UNAUTHORIZED' })).toBe(true)
+    })
+  })
+
+  describe('responseBody pattern detection', () => {
+    it('should detect auth patterns in responseBody', () => {
+      expect(isClaudeOAuthAuthError({ responseBody: '{"error": "unauthorized"}' })).toBe(true)
+      expect(isClaudeOAuthAuthError({ responseBody: 'invalid_token' })).toBe(true)
+      expect(isClaudeOAuthAuthError({ responseBody: 'token has expired' })).toBe(true)
+    })
+  })
+})
+
+describe('error type mutual exclusivity', () => {
+  it('rate limit errors should NOT be auth errors', () => {
+    const rateLimitError = { statusCode: 429, message: 'rate_limit' }
+    expect(isClaudeOAuthRateLimitError(rateLimitError)).toBe(true)
+    expect(isClaudeOAuthAuthError(rateLimitError)).toBe(false)
+  })
+
+  it('auth errors should NOT be rate limit errors', () => {
+    const authError = { statusCode: 401, message: 'unauthorized' }
+    expect(isClaudeOAuthAuthError(authError)).toBe(true)
+    expect(isClaudeOAuthRateLimitError(authError)).toBe(false)
+  })
+
+  it('server errors (500) should be neither', () => {
+    const serverError = { statusCode: 500, message: 'internal server error' }
+    expect(isClaudeOAuthRateLimitError(serverError)).toBe(false)
+    expect(isClaudeOAuthAuthError(serverError)).toBe(false)
+  })
+})
+
+/**
+ * Mutation tests - verify our tests would catch real bugs.
+ * These document the specific patterns our implementation relies on.
+ */
+describe('mutation detection (documents implementation requirements)', () => {
+  it('REQUIRES status 429 for rate limit (not 428)', () => {
+    // If implementation changed 429 to 428, this test would catch it
+    expect(isClaudeOAuthRateLimitError({ statusCode: 428 })).toBe(false)
+    expect(isClaudeOAuthRateLimitError({ statusCode: 429 })).toBe(true)
+  })
+
+  it('REQUIRES "overloaded" pattern for rate limit detection', () => {
+    // If implementation removed "overloaded" check, this test would catch it
+    expect(isClaudeOAuthRateLimitError({ message: 'overloaded' })).toBe(true)
+  })
+
+  it('REQUIRES both 401 AND 403 for auth errors', () => {
+    // If implementation only checked 401, this test would catch it
+    expect(isClaudeOAuthAuthError({ statusCode: 401 })).toBe(true)
+    expect(isClaudeOAuthAuthError({ statusCode: 403 })).toBe(true)
+  })
+
+  it('REQUIRES "expired" pattern for auth error detection', () => {
+    // If implementation removed "expired" check, this test would catch it
+    expect(isClaudeOAuthAuthError({ message: 'expired' })).toBe(true)
+  })
+})

sdk/src/__tests__/file-tree-builder.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it, mock } from 'bun:test'
+
+import { buildFileTree, computeProjectIndex } from '../impl/file-tree-builder'
+
+/**
+ * These tests focus on DOMAIN LOGIC - the tree building algorithm,
+ * sorting rules (directories before files, alphabetical), and hierarchy.
+ * Low-value tests that just verify JavaScript built-in behavior have been removed.
+ */
+
+describe('buildFileTree', () => {
+  describe('tree structure building', () => {
+    it('should create nested directory structure from path', () => {
+      const result = buildFileTree(['src/components/Button.tsx'])
+      
+      expect(result[0].name).toBe('src')
+      expect(result[0].type).toBe('directory')
+      expect(result[0].children![0].name).toBe('components')
+      expect(result[0].children![0].children![0].name).toBe('Button.tsx')
+      expect(result[0].children![0].children![0].type).toBe('file')
+    })
+
+    it('should group multiple files in same directory', () => {
+      const result = buildFileTree(['src/a.ts', 'src/b.ts', 'src/c.ts'])
+      
+      expect(result).toHaveLength(1) // single src directory
+      expect(result[0].children).toHaveLength(3) // three files inside
+    })
+
+    it('should create separate root directories', () => {
+      const result = buildFileTree(['src/file.ts', 'lib/file.ts', 'tests/file.ts'])
+      
+      expect(result).toHaveLength(3)
+      expect(result.map(n => n.name)).toContain('src')
+      expect(result.map(n => n.name)).toContain('lib')
+      expect(result.map(n => n.name)).toContain('tests')
+    })
+
+    it('should handle mixed root files and directories', () => {
+      const result = buildFileTree(['root.ts', 'src/nested.ts'])
+      
+      const rootFile = result.find(n => n.name === 'root.ts')
+      const srcDir = result.find(n => n.name === 'src')
+      
+      expect(rootFile?.type).toBe('file')
+      expect(srcDir?.type).toBe('directory')
+    })
+  })
+
+  describe('sorting: directories before files, then alphabetical', () => {
+    it('should sort directories BEFORE files at same level', () => {
+      const result = buildFileTree(['file.ts', 'src/file.ts', 'another.ts'])
+      
+      // Directory should come first
+      expect(result[0].name).toBe('src')
+      expect(result[0].type).toBe('directory')
+      // Then files
+      expect(result[1].type).toBe('file')
+      expect(result[2].type).toBe('file')
+    })
+
+    it('should sort alphabetically within same type', () => {
+      const result = buildFileTree(['z.ts', 'a.ts', 'm.ts'])
+      
+      expect(result[0].name).toBe('a.ts')
+      expect(result[1].name).toBe('m.ts')
+      expect(result[2].name).toBe('z.ts')
+    })
+
+    it('should sort children within directories', () => {
+      const result = buildFileTree(['src/z.ts', 'src/a.ts', 'src/utils/helper.ts'])
+      
+      // utils directory should come before files
+      expect(result[0].children![0].name).toBe('utils')
+      expect(result[0].children![0].type).toBe('directory')
+      // then files alphabetically
+      expect(result[0].children![1].name).toBe('a.ts')
+      expect(result[0].children![2].name).toBe('z.ts')
+    })
+  })
+
+  describe('filePath property', () => {
+    it('should set correct filePath for nested items', () => {
+      const result = buildFileTree(['src/components/Button.tsx'])
+      
+      expect(result[0].filePath).toBe('src')
+      expect(result[0].children![0].filePath).toBe('src/components')
+      expect(result[0].children![0].children![0].filePath).toBe('src/components/Button.tsx')
+    })
+  })
+
+  describe('complex project structure', () => {
+    it('should handle typical project layout', () => {
+      const files = [
+        'package.json',
+        'tsconfig.json',
+        'src/index.ts',
+        'src/components/Button.tsx',
+        'src/utils/helpers.ts',
+        'tests/unit/button.test.ts',
+      ]
+      const result = buildFileTree(files)
+      
+      // Directories first (src, tests), then files (package.json, tsconfig.json)
+      expect(result[0].type).toBe('directory')
+      expect(result[1].type).toBe('directory')
+      expect(result.map(n => n.name)).toContain('src')
+      expect(result.map(n => n.name)).toContain('tests')
+      expect(result.map(n => n.name)).toContain('package.json')
+    })
+  })
+})
+
+describe('computeProjectIndex', () => {
+  it('should return file tree for project files', async () => {
+    const projectFiles = {
+      'src/index.ts': 'export const hello = "world"',
+      'src/utils.ts': 'export const add = (a, b) => a + b',
+    }
+    
+    const result = await computeProjectIndex('/mock/cwd', projectFiles)
+    
+    expect(result.fileTree).toHaveLength(1)
+    expect(result.fileTree[0].name).toBe('src')
+    expect(result.fileTree[0].children).toHaveLength(2)
+  })
+
+  it('should sort file paths before building tree', async () => {
+    const projectFiles = {
+      'z.ts': 'const z = 1',
+      'a.ts': 'const a = 1',
+      'm.ts': 'const m = 1',
+    }
+    
+    const result = await computeProjectIndex('/mock/cwd', projectFiles)
+    
+    expect(result.fileTree[0].name).toBe('a.ts')
+    expect(result.fileTree[1].name).toBe('m.ts')
+    expect(result.fileTree[2].name).toBe('z.ts')
+  })
+
+  it('should return correct structure shape', async () => {
+    const result = await computeProjectIndex('/mock/cwd', { 'file.ts': 'export const x = 1' })
+    
+    expect(result).toHaveProperty('fileTree')
+    expect(result).toHaveProperty('fileTokenScores')
+    expect(result).toHaveProperty('tokenCallers')
+    expect(Array.isArray(result.fileTree)).toBe(true)
+  })
+})
+
+/**
+ * Mutation tests - verify our tests would catch real bugs
+ */
+describe('mutation detection', () => {
+  it('REQUIRES directories to sort before files', () => {
+    // If sorting was removed/broken, this would fail
+    const result = buildFileTree(['z-file.ts', 'a-dir/file.ts'])
+    expect(result[0].name).toBe('a-dir') // directory first, even though z < a alphabetically for files
+    expect(result[0].type).toBe('directory')
+  })
+
+  it('REQUIRES alphabetical sorting within type', () => {
+    // If localeCompare was removed, this would fail
+    const result = buildFileTree(['z.ts', 'a.ts'])
+    expect(result[0].name).toBe('a.ts')
+  })
+
+  it('REQUIRES recursive sorting of children', () => {
+    // If sortNodes wasn't called recursively, this would fail
+    const result = buildFileTree(['parent/z.ts', 'parent/a.ts'])
+    expect(result[0].children![0].name).toBe('a.ts')
+  })
+})