brownian-code 2026.2.10

package/src/utils/text-navigation.test.ts

@@ -0,0 +1,222 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  findPrevWordStart,
+  findNextWordEnd,
+  getLineAndColumn,
+  getCursorPosition,
+  getLineStart,
+  getLineEnd,
+  getLineCount,
+} from './text-navigation.js';
+
+// ---------------------------------------------------------------------------
+// findPrevWordStart
+// ---------------------------------------------------------------------------
+
+describe('findPrevWordStart', () => {
+  test('moves to start of current word', () => {
+    // "hello world" with cursor at position 8 (middle of "world")
+    expect(findPrevWordStart('hello world', 8)).toBe(6);
+  });
+
+  test('skips whitespace to previous word', () => {
+    // "hello world" with cursor at position 6 (start of "world")
+    expect(findPrevWordStart('hello world', 6)).toBe(0);
+  });
+
+  test('returns 0 at beginning of text', () => {
+    expect(findPrevWordStart('hello', 0)).toBe(0);
+  });
+
+  test('returns 0 from position 1', () => {
+    expect(findPrevWordStart('hello', 1)).toBe(0);
+  });
+
+  test('handles empty string', () => {
+    expect(findPrevWordStart('', 0)).toBe(0);
+  });
+
+  test('handles punctuation', () => {
+    // "foo.bar" cursor at end → should go to "bar" start (position 4)
+    expect(findPrevWordStart('foo.bar', 7)).toBe(4);
+  });
+
+  test('handles multiple spaces', () => {
+    // "hello   world" cursor at 10 (in "world")
+    expect(findPrevWordStart('hello   world', 10)).toBe(8);
+  });
+
+  test('handles cursor at end of single word', () => {
+    expect(findPrevWordStart('hello', 5)).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findNextWordEnd
+// ---------------------------------------------------------------------------
+
+describe('findNextWordEnd', () => {
+  test('moves to end of current word', () => {
+    // "hello world" cursor at 0 → end of "hello" = position 5
+    expect(findNextWordEnd('hello world', 0)).toBe(5);
+  });
+
+  test('skips whitespace to next word end', () => {
+    // "hello world" cursor at 5 → end of "world" = position 11
+    expect(findNextWordEnd('hello world', 5)).toBe(11);
+  });
+
+  test('returns text length at end', () => {
+    expect(findNextWordEnd('hello', 5)).toBe(5);
+  });
+
+  test('handles empty string', () => {
+    expect(findNextWordEnd('', 0)).toBe(0);
+  });
+
+  test('handles punctuation', () => {
+    // "foo.bar" cursor at 0 → end of "foo" = position 3
+    expect(findNextWordEnd('foo.bar', 0)).toBe(3);
+  });
+
+  test('handles cursor beyond text length', () => {
+    expect(findNextWordEnd('hello', 10)).toBe(5);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getLineAndColumn
+// ---------------------------------------------------------------------------
+
+describe('getLineAndColumn', () => {
+  test('returns line 0 col 0 for position 0', () => {
+    expect(getLineAndColumn('hello\nworld', 0)).toEqual({ line: 0, column: 0 });
+  });
+
+  test('returns correct position within first line', () => {
+    expect(getLineAndColumn('hello\nworld', 3)).toEqual({ line: 0, column: 3 });
+  });
+
+  test('returns start of second line', () => {
+    // Position 6 is 'w' in "world"
+    expect(getLineAndColumn('hello\nworld', 6)).toEqual({ line: 1, column: 0 });
+  });
+
+  test('handles single-line text', () => {
+    expect(getLineAndColumn('hello', 3)).toEqual({ line: 0, column: 3 });
+  });
+
+  test('handles empty string', () => {
+    expect(getLineAndColumn('', 0)).toEqual({ line: 0, column: 0 });
+  });
+
+  test('handles cursor at newline character', () => {
+    // Position 5 is the '\n' in "hello\nworld"
+    expect(getLineAndColumn('hello\nworld', 5)).toEqual({ line: 0, column: 5 });
+  });
+
+  test('handles three lines', () => {
+    const text = 'line1\nline2\nline3';
+    // Position 12 is 'l' of "line3"
+    expect(getLineAndColumn(text, 12)).toEqual({ line: 2, column: 0 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getCursorPosition
+// ---------------------------------------------------------------------------
+
+describe('getCursorPosition', () => {
+  test('returns position for line 0 col 0', () => {
+    expect(getCursorPosition('hello\nworld', 0, 0)).toBe(0);
+  });
+
+  test('returns position for line 1 col 0', () => {
+    expect(getCursorPosition('hello\nworld', 1, 0)).toBe(6);
+  });
+
+  test('clamps column to line length', () => {
+    // "hi\nworld" → line 0 has length 2, asking for col 10 should clamp to 2
+    expect(getCursorPosition('hi\nworld', 0, 10)).toBe(2);
+  });
+
+  test('handles single-line text', () => {
+    expect(getCursorPosition('hello', 0, 3)).toBe(3);
+  });
+
+  test('handles three lines', () => {
+    const text = 'abc\ndef\nghi';
+    expect(getCursorPosition(text, 2, 1)).toBe(9); // 'abc\n' (4) + 'def\n' (4) + 1 = 9
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getLineStart
+// ---------------------------------------------------------------------------
+
+describe('getLineStart', () => {
+  test('returns 0 for first line', () => {
+    expect(getLineStart('hello\nworld', 3)).toBe(0);
+  });
+
+  test('returns start of second line', () => {
+    // Position 8 is in "world", line starts at 6
+    expect(getLineStart('hello\nworld', 8)).toBe(6);
+  });
+
+  test('handles single-line text', () => {
+    expect(getLineStart('hello', 3)).toBe(0);
+  });
+
+  test('handles cursor at position 0', () => {
+    expect(getLineStart('hello\nworld', 0)).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getLineEnd
+// ---------------------------------------------------------------------------
+
+describe('getLineEnd', () => {
+  test('returns position of newline for first line', () => {
+    expect(getLineEnd('hello\nworld', 3)).toBe(5);
+  });
+
+  test('returns text length for last line', () => {
+    expect(getLineEnd('hello\nworld', 8)).toBe(11);
+  });
+
+  test('handles single-line text', () => {
+    expect(getLineEnd('hello', 3)).toBe(5);
+  });
+
+  test('handles cursor at newline', () => {
+    expect(getLineEnd('hello\nworld', 5)).toBe(5);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getLineCount
+// ---------------------------------------------------------------------------
+
+describe('getLineCount', () => {
+  test('returns 1 for single line', () => {
+    expect(getLineCount('hello')).toBe(1);
+  });
+
+  test('returns 2 for two lines', () => {
+    expect(getLineCount('hello\nworld')).toBe(2);
+  });
+
+  test('returns 3 for three lines', () => {
+    expect(getLineCount('a\nb\nc')).toBe(3);
+  });
+
+  test('returns 1 for empty string', () => {
+    expect(getLineCount('')).toBe(1);
+  });
+
+  test('counts trailing newline as extra line', () => {
+    expect(getLineCount('hello\n')).toBe(2);
+  });
+});

package/src/utils/text-navigation.ts

@@ -0,0 +1,81 @@
+/**
+ * Find the start position of the previous word from cursor position.
+ * Used for Option+Left (Mac) / Ctrl+Left (Windows) navigation.
+ */
+export function findPrevWordStart(text: string, pos: number): number {
+  if (pos <= 0) return 0;
+  let i = pos - 1;
+  // Skip non-word chars
+  while (i > 0 && !/\w/.test(text[i])) i--;
+  // Move to word start
+  while (i > 0 && /\w/.test(text[i - 1])) i--;
+  return i;
+}
+
+/**
+ * Find the end position of the next word from cursor position.
+ * Used for Option+Right (Mac) / Ctrl+Right (Windows) navigation.
+ */
+export function findNextWordEnd(text: string, pos: number): number {
+  const len = text.length;
+  if (pos >= len) return len;
+  let i = pos;
+  // Skip non-word chars
+  while (i < len && !/\w/.test(text[i])) i++;
+  // Move to word end
+  while (i < len && /\w/.test(text[i])) i++;
+  return i;
+}
+
+// ============================================================================
+// Multi-line cursor navigation utilities
+// ============================================================================
+
+/**
+ * Get the line number (0-indexed) and column from a cursor position.
+ */
+export function getLineAndColumn(text: string, pos: number): { line: number; column: number } {
+  const beforeCursor = text.slice(0, pos);
+  const lines = beforeCursor.split('\n');
+  return {
+    line: lines.length - 1,
+    column: lines[lines.length - 1].length,
+  };
+}
+
+/**
+ * Get cursor position from line number and column.
+ * Clamps column to the actual line length if it exceeds.
+ */
+export function getCursorPosition(text: string, line: number, column: number): number {
+  const lines = text.split('\n');
+  let pos = 0;
+  for (let i = 0; i < line && i < lines.length; i++) {
+    pos += lines[i].length + 1; // +1 for newline
+  }
+  const targetLine = lines[line] || '';
+  return pos + Math.min(column, targetLine.length);
+}
+
+/**
+ * Get the start position of the line containing the cursor.
+ */
+export function getLineStart(text: string, pos: number): number {
+  const lastNewline = text.lastIndexOf('\n', pos - 1);
+  return lastNewline + 1; // -1 + 1 = 0 if no newline found
+}
+
+/**
+ * Get the end position of the line containing the cursor (before the newline).
+ */
+export function getLineEnd(text: string, pos: number): number {
+  const nextNewline = text.indexOf('\n', pos);
+  return nextNewline === -1 ? text.length : nextNewline;
+}
+
+/**
+ * Get the total number of lines in the text.
+ */
+export function getLineCount(text: string): number {
+  return text.split('\n').length;
+}

package/src/utils/thinking-verbs.ts

@@ -0,0 +1,29 @@
+export const THINKING_VERBS = [
+  'Alchemizing', 'Ambling', 'Baking', 'Boogieing',
+  'Brainstorming', 'Brewing', 'Buffering', 'Buzzing',
+  'Cerebrating', 'Chugging', 'Chugging along', 'Churning',
+  'Clauding', 'Cogitating', 'Concocting', 'Conjuring',
+  'Cooking', 'Crafting', 'Cruising', 'Daydreaming',
+  'Defragmenting', 'Deliberating', 'Dillydallying', 'Divining',
+  'Enchanting', 'Fermenting', 'Fiddling', 'Finagling',
+  'Finessing', 'Forging', 'Futzing', 'Gallivanting',
+  'Gliding', 'Grooving', 'Hatching', 'Hemming and hawing',
+  'Humming', 'Hustling', 'Ideating', 'Incanting',
+  'Invoking', 'Juggling', 'Kneading', 'Manifesting',
+  'Marinating', 'Moseying', 'Mulling', 'Musing',
+  'Noodling', 'Percolating', 'Plotting', 'Pondering',
+  'Pottering', 'Prancing', 'Purring', 'Puttering',
+  'Puzzling', 'Reticulating', 'Revving', 'Riffing',
+  'Ruminating', 'Sashaying', 'Sautéing', 'Scampering',
+  'Scheming', 'Scribbling', 'Sculpting', 'Seasoning',
+  'Shimmying', 'Simmering', 'Sketching', 'Sorcering',
+  'Spellcasting', 'Stewing', 'Summoning', 'Swooshing',
+  'Thrumming', 'Tinkering', 'Transmuting', 'Trotting',
+  'Vibing', 'Waddling', 'Warming up', 'Whipping up',
+  'Whirring', 'Whittling', 'Wizarding', 'Woolgathering',
+  'Wrangling', 'Zipping', 'Zooming',
+] as const;
+
+export function getRandomThinkingVerb(): string {
+  return THINKING_VERBS[Math.floor(Math.random() * THINKING_VERBS.length)];
+}

package/src/utils/tokens.test.ts

@@ -0,0 +1,163 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  estimateTokens,
+  getContextWindow,
+  getContextThreshold,
+  TOKEN_BUDGET,
+  KEEP_TOOL_USES,
+} from './tokens.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+describe('token constants', () => {
+  test('TOKEN_BUDGET is 150_000', () => {
+    expect(TOKEN_BUDGET).toBe(150_000);
+  });
+
+  test('KEEP_TOOL_USES is 5', () => {
+    expect(KEEP_TOOL_USES).toBe(5);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// estimateTokens
+// ---------------------------------------------------------------------------
+
+describe('estimateTokens', () => {
+  test('empty string returns 0', () => {
+    expect(estimateTokens('')).toBe(0);
+  });
+
+  test('returns ceil(length / 3.5)', () => {
+    // 7 chars / 3.5 = 2.0 → 2
+    expect(estimateTokens('abcdefg')).toBe(2);
+  });
+
+  test('rounds up for non-integer result', () => {
+    // 10 chars / 3.5 = 2.857… → 3
+    expect(estimateTokens('0123456789')).toBe(3);
+  });
+
+  test('handles single character', () => {
+    // 1 / 3.5 = 0.285… → 1
+    expect(estimateTokens('a')).toBe(1);
+  });
+
+  test('handles long string', () => {
+    const text = 'x'.repeat(35_000);
+    expect(estimateTokens(text)).toBe(10_000);
+  });
+
+  test('handles very long string (100K chars)', () => {
+    const text = 'a'.repeat(100_000);
+    // 100_000 / 3.5 = 28571.4… → 28572
+    expect(estimateTokens(text)).toBe(Math.ceil(100_000 / 3.5));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getContextWindow
+// ---------------------------------------------------------------------------
+
+describe('getContextWindow', () => {
+  test('claude models return 200K', () => {
+    expect(getContextWindow('claude-sonnet-4-5')).toBe(200_000);
+    expect(getContextWindow('claude-opus-4-6')).toBe(200_000);
+    expect(getContextWindow('claude-haiku-4-5')).toBe(200_000);
+  });
+
+  test('gpt-4o returns 128K', () => {
+    expect(getContextWindow('gpt-4o')).toBe(128_000);
+    expect(getContextWindow('gpt-4o-mini')).toBe(128_000);
+  });
+
+  test('gpt-4 returns 128K', () => {
+    expect(getContextWindow('gpt-4')).toBe(128_000);
+    expect(getContextWindow('gpt-4-turbo')).toBe(128_000);
+  });
+
+  test('gpt-3.5 returns 16K', () => {
+    expect(getContextWindow('gpt-3.5-turbo')).toBe(16_000);
+  });
+
+  test('gemini returns 1M', () => {
+    expect(getContextWindow('gemini-2.0-flash')).toBe(1_000_000);
+    expect(getContextWindow('gemini-1.5-pro')).toBe(1_000_000);
+  });
+
+  test('grok returns 131072', () => {
+    expect(getContextWindow('grok-beta')).toBe(131_072);
+  });
+
+  test('deepseek returns 64K', () => {
+    expect(getContextWindow('deepseek-chat')).toBe(64_000);
+    expect(getContextWindow('deepseek-coder')).toBe(64_000);
+  });
+
+  test('moonshot returns 128K', () => {
+    expect(getContextWindow('moonshot-v1-8k')).toBe(128_000);
+  });
+
+  test('o1 returns 128K', () => {
+    expect(getContextWindow('o1')).toBe(128_000);
+    expect(getContextWindow('o1-preview')).toBe(128_000);
+  });
+
+  test('o3 returns 200K', () => {
+    expect(getContextWindow('o3')).toBe(200_000);
+    expect(getContextWindow('o3-mini')).toBe(200_000);
+  });
+
+  test('unknown model returns default 128K', () => {
+    expect(getContextWindow('some-unknown-model')).toBe(128_000);
+    expect(getContextWindow('llama-3.1')).toBe(128_000);
+  });
+
+  test('is case-insensitive', () => {
+    expect(getContextWindow('Claude-Sonnet-4-5')).toBe(200_000);
+    expect(getContextWindow('GPT-4O')).toBe(128_000);
+    expect(getContextWindow('GEMINI-2.0')).toBe(1_000_000);
+  });
+
+  test('empty string returns default', () => {
+    expect(getContextWindow('')).toBe(128_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getContextThreshold
+// ---------------------------------------------------------------------------
+
+describe('getContextThreshold', () => {
+  test('returns 75% of context window', () => {
+    // Claude: 200K * 0.75 = 150K
+    expect(getContextThreshold('claude-sonnet-4-5')).toBe(150_000);
+  });
+
+  test('returns floor of 75%', () => {
+    // grok: 131072 * 0.75 = 98304
+    expect(getContextThreshold('grok-beta')).toBe(98_304);
+  });
+
+  test('returns 75% for gpt-4o', () => {
+    // 128K * 0.75 = 96K
+    expect(getContextThreshold('gpt-4o')).toBe(96_000);
+  });
+
+  test('returns 75% for gemini', () => {
+    // 1M * 0.75 = 750K
+    expect(getContextThreshold('gemini-2.0-flash')).toBe(750_000);
+  });
+
+  test('returns 75% for deepseek', () => {
+    // 64K * 0.75 = 48K
+    expect(getContextThreshold('deepseek-chat')).toBe(48_000);
+  });
+
+  test('returns 75% for unknown model (default window)', () => {
+    // 128K * 0.75 = 96K
+    expect(getContextThreshold('unknown-model')).toBe(96_000);
+  });
+});

package/src/utils/tokens.ts

@@ -0,0 +1,67 @@
+/**
+ * Token estimation utilities for context management.
+ * Used to prevent exceeding LLM context window limits.
+ */
+
+/**
+ * Rough token estimation based on character count.
+ * JSON is denser than prose, so we use ~3.5 chars per token.
+ * This is conservative - better to underestimate available space.
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 3.5);
+}
+
+/**
+ * Maximum token budget for context data in final answer generation.
+ * Conservative limit that leaves room for system prompt, query, and response.
+ */
+export const TOKEN_BUDGET = 150_000;
+
+// ============================================================================
+// Model Context Windows & Thresholds
+// ============================================================================
+
+/**
+ * Known context window sizes (in tokens) by model prefix.
+ * Checked in order — first match wins.
+ */
+const MODEL_CONTEXT_WINDOWS: [prefix: string, tokens: number][] = [
+  ['claude-',     200_000],
+  ['gpt-4o',      128_000],
+  ['gpt-4',       128_000],
+  ['gpt-3.5',      16_000],
+  ['gemini-',   1_000_000],
+  ['grok-',       131_072],
+  ['deepseek-',    64_000],
+  ['moonshot-',   128_000],
+  ['o1',          128_000],
+  ['o3',          200_000],
+];
+
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+
+/**
+ * Returns the context window size (in tokens) for the given model.
+ */
+export function getContextWindow(model: string): number {
+  const lower = model.toLowerCase();
+  for (const [prefix, tokens] of MODEL_CONTEXT_WINDOWS) {
+    if (lower.startsWith(prefix)) return tokens;
+  }
+  return DEFAULT_CONTEXT_WINDOW;
+}
+
+/**
+ * Returns the token threshold at which context clearing should trigger.
+ * Set at 75% of the model's context window to leave room for system prompt + response.
+ */
+export function getContextThreshold(model: string): number {
+  return Math.floor(getContextWindow(model) * 0.75);
+}
+
+/**
+ * Number of most recent tool results to keep when clearing.
+ * Anthropic's default is 3, but we use 5 for slightly more context.
+ */
+export const KEEP_TOOL_USES = 5;

package/src/utils/tool-description.ts

@@ -0,0 +1,88 @@
+/**
+ * Generate a deterministic human-readable description of a tool call.
+ * Used for context compaction during the agent loop.
+ *
+ * Examples:
+ * - "Get Bitcoin Price"
+ * - "Wallet Analysis (0xd8dA...6045)"
+ * - '"trending tokens" web search'
+ */
+export function getToolDescription(toolName: string, args: Record<string, unknown>): string {
+  const parts: string[] = [];
+  const usedKeys = new Set<string>();
+
+  // Crypto-specific: invoke_api_endpoint gets special formatting
+  if (toolName === 'invoke_api_endpoint' && args.endpoint_name) {
+    const endpoint = String(args.endpoint_name);
+    const formatted = endpoint.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    parts.push(formatted);
+    usedKeys.add('endpoint_name');
+
+    // Add key identifiers from arguments
+    const innerArgs = (args.arguments ?? args) as Record<string, unknown>;
+    if (innerArgs.ids) {
+      parts.push(`(${String(innerArgs.ids)})`);
+      usedKeys.add('arguments');
+    } else if (innerArgs.address) {
+      const addr = String(innerArgs.address);
+      const short = addr.length > 12 ? `${addr.slice(0, 6)}...${addr.slice(-4)}` : addr;
+      parts.push(`(${short})`);
+      usedKeys.add('arguments');
+    }
+    return parts.join(' ');
+  }
+
+  // Schema lookup
+  if (toolName === 'get_api_endpoint_schema' && args.endpoint_name) {
+    return `Schema: ${String(args.endpoint_name)}`;
+  }
+
+  // Category discovery tools
+  if (toolName.startsWith('get_') && toolName.endsWith('_endpoints')) {
+    const category = toolName
+      .replace(/^get_/, '')
+      .replace(/_endpoints$/, '')
+      .replace(/_/g, ' ')
+      .replace(/\b\w/g, (c) => c.toUpperCase());
+    return `Discover ${category} Endpoints`;
+  }
+
+  // Add search query if present
+  if (args.query) {
+    parts.push(`"${truncate(String(args.query), 50)}"`);
+    usedKeys.add('query');
+  }
+
+  // Add address if present
+  if (args.address) {
+    const addr = String(args.address);
+    const short = addr.length > 12 ? `${addr.slice(0, 6)}...${addr.slice(-4)}` : addr;
+    parts.push(short);
+    usedKeys.add('address');
+  }
+
+  // Format tool name: get_income_statements -> income statements
+  const formattedToolName = toolName
+    .replace(/^get_/, '')
+    .replace(/^search_/, '')
+    .replace(/_/g, ' ');
+  parts.push(formattedToolName);
+
+  // Add period qualifier if present
+  if (args.period) {
+    parts.push(`(${args.period})`);
+    usedKeys.add('period');
+  }
+
+  // Add limit if present
+  if (args.limit && typeof args.limit === 'number') {
+    parts.push(`- ${args.limit} items`);
+    usedKeys.add('limit');
+  }
+
+  return parts.join(' ');
+}
+
+function truncate(str: string, max: number): string {
+  return str.length <= max ? str : str.slice(0, max) + '...';
+}