@flowcodex/core 0.3.0

package/src/types/errors.ts

@@ -0,0 +1,359 @@
+import { toErrorMessage } from '../utils/error.js';
+
+export const ERROR_CODES = {
+  PROVIDER_RATE_LIMITED: 'PROVIDER_RATE_LIMITED',
+  PROVIDER_AUTH_FAILED: 'PROVIDER_AUTH_FAILED',
+  PROVIDER_OVERLOADED: 'PROVIDER_OVERLOADED',
+  PROVIDER_INVALID_REQUEST: 'PROVIDER_INVALID_REQUEST',
+  PROVIDER_SERVER_ERROR: 'PROVIDER_SERVER_ERROR',
+  PROVIDER_NETWORK_ERROR: 'PROVIDER_NETWORK_ERROR',
+  PROVIDER_CONTEXT_OVERFLOW: 'PROVIDER_CONTEXT_OVERFLOW',
+  PROVIDER_STREAM_HANG: 'PROVIDER_STREAM_HANG',
+  PROVIDER_UNSUPPORTED: 'PROVIDER_UNSUPPORTED',
+  PROVIDER_NOT_WIRED: 'PROVIDER_NOT_WIRED',
+  TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
+  TOOL_PERMISSION_DENIED: 'TOOL_PERMISSION_DENIED',
+  TOOL_EXECUTION_FAILED: 'TOOL_EXECUTION_FAILED',
+  TOOL_TIMEOUT: 'TOOL_TIMEOUT',
+  TOOL_INPUT_INVALID: 'TOOL_INPUT_INVALID',
+  CONFIG_INVALID: 'CONFIG_INVALID',
+  CONFIG_NOT_FOUND: 'CONFIG_NOT_FOUND',
+  CONFIG_PARSE_FAILED: 'CONFIG_PARSE_FAILED',
+  CONFIG_MIGRATION_NEEDED: 'CONFIG_MIGRATION_NEEDED',
+  PLUGIN_LOAD_FAILED: 'PLUGIN_LOAD_FAILED',
+  PLUGIN_API_MISMATCH: 'PLUGIN_API_MISMATCH',
+  PLUGIN_MISSING_DEPENDENCY: 'PLUGIN_MISSING_DEPENDENCY',
+  AGENT_ITERATION_LIMIT: 'AGENT_ITERATION_LIMIT',
+  AGENT_CONTEXT_OVERFLOW: 'AGENT_CONTEXT_OVERFLOW',
+  AGENT_ABORTED: 'AGENT_ABORTED',
+  AGENT_RUN_FAILED: 'AGENT_RUN_FAILED',
+  AGENT_BUDGET_EXCEEDED: 'AGENT_BUDGET_EXCEEDED',
+  COMPACTION_FAILED: 'COMPACTION_FAILED',
+  PROMPT_BUDGET_EXCEEDED: 'PROMPT_BUDGET_EXCEEDED',
+  SESSION_NOT_FOUND: 'SESSION_NOT_FOUND',
+  SESSION_CORRUPTED: 'SESSION_CORRUPTED',
+  SESSION_WRITE_FAILED: 'SESSION_WRITE_FAILED',
+  CONTAINER_TOKEN_ALREADY_BOUND: 'CONTAINER_TOKEN_ALREADY_BOUND',
+  CONTAINER_TOKEN_NOT_BOUND: 'CONTAINER_TOKEN_NOT_BOUND',
+  CONTAINER_CIRCULAR_DEPENDENCY: 'CONTAINER_CIRCULAR_DEPENDENCY',
+  REGISTRY_DUPLICATE: 'REGISTRY_DUPLICATE',
+  REGISTRY_NOT_FOUND: 'REGISTRY_NOT_FOUND',
+  REGISTRY_INVALID: 'REGISTRY_INVALID',
+  FS_READ_FAILED: 'FS_READ_FAILED',
+  FS_WRITE_FAILED: 'FS_WRITE_FAILED',
+  FS_MKDIR_FAILED: 'FS_MKDIR_FAILED',
+  FS_DELETE_FAILED: 'FS_DELETE_FAILED',
+  FS_ATOMIC_WRITE_FAILED: 'FS_ATOMIC_WRITE_FAILED',
+  FS_PATH_ESCAPE: 'FS_PATH_ESCAPE',
+  SSRF_BLOCKED: 'SSRF_BLOCKED',
+  WEBFETCH_FAILED: 'WEBFETCH_FAILED',
+  WEBSEARCH_FAILED: 'WEBSEARCH_FAILED',
+  DIFF_FILE_NOT_FOUND: 'DIFF_FILE_NOT_FOUND',
+  PATCH_HUNK_FAILED: 'PATCH_HUNK_FAILED',
+  DEV_TOOL_NOT_FOUND: 'DEV_TOOL_NOT_FOUND',
+  REPLAY_MISS: 'REPLAY_MISS',
+  SESSION_EXPORT_FAILED: 'SESSION_EXPORT_FAILED',
+  PROVIDER_UNSUPPORTED_MODALITY: 'PROVIDER_UNSUPPORTED_MODALITY',
+  TOOL_BATCH_FAILED: 'TOOL_BATCH_FAILED',
+  TOOL_BATCH_TOO_LARGE: 'TOOL_BATCH_TOO_LARGE',
+  TOOL_NESTED_BATCH: 'TOOL_NESTED_BATCH',
+  TOOL_INVALID_ATTACHMENT: 'TOOL_INVALID_ATTACHMENT',
+  TOOL_UNSUPPORTED_PROVIDER: 'TOOL_UNSUPPORTED_PROVIDER',
+  AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED: 'AGENT_STRUCTURED_OUTPUT_NOT_PRODUCED',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  UNKNOWN: 'UNKNOWN',
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+export type ErrorSubsystem =
+  | 'provider'
+  | 'tool'
+  | 'config'
+  | 'plugin'
+  | 'agent'
+  | 'session'
+  | 'container'
+  | 'fs'
+  | 'general';
+
+export type ErrorSeverity = 'fatal' | 'error' | 'warning';
+
+export class FlowCodexError extends Error {
+  readonly code: ErrorCode;
+  readonly subsystem: ErrorSubsystem;
+  readonly severity: ErrorSeverity;
+  readonly recoverable: boolean;
+  readonly context?: Record<string, unknown> | undefined;
+
+  constructor(opts: {
+    message: string;
+    code: ErrorCode;
+    subsystem: ErrorSubsystem;
+    severity?: ErrorSeverity | undefined;
+    recoverable?: boolean | undefined;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super(opts.message, { cause: opts.cause });
+    this.name = 'FlowCodexError';
+    this.code = opts.code;
+    this.subsystem = opts.subsystem;
+    this.severity = opts.severity ?? 'error';
+    this.recoverable = opts.recoverable ?? false;
+    this.context = opts.context;
+  }
+
+  describe(): string {
+    const ctx = this.context ? ` ${formatContext(this.context)}` : '';
+    return `${this.code}: ${this.message}${ctx}`;
+  }
+}
+
+function formatContext(ctx: Record<string, unknown>): string {
+  const parts = Object.entries(ctx)
+    .filter(([, v]) => v !== undefined)
+    .slice(0, 3)
+    .map(([k, v]) => `${k}=${String(v)}`);
+  return parts.length > 0 ? `[${parts.join(' ')}]` : '';
+}
+
+export class ToolError extends FlowCodexError {
+  readonly toolName: string;
+
+  constructor(opts: {
+    message: string;
+    code: Extract<
+      ErrorCode,
+      | 'TOOL_NOT_FOUND'
+      | 'TOOL_PERMISSION_DENIED'
+      | 'TOOL_EXECUTION_FAILED'
+      | 'TOOL_TIMEOUT'
+      | 'TOOL_INPUT_INVALID'
+    >;
+    toolName: string;
+    recoverable?: boolean | undefined;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: 'tool',
+      recoverable: opts.recoverable,
+      context: { tool: opts.toolName, ...opts.context },
+      cause: opts.cause,
+    });
+    this.name = 'ToolError';
+    this.toolName = opts.toolName;
+  }
+}
+
+export class ConfigError extends FlowCodexError {
+  constructor(opts: {
+    message: string;
+    code: Extract<
+      ErrorCode,
+      'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_PARSE_FAILED' | 'CONFIG_MIGRATION_NEEDED'
+    >;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: 'config',
+      severity: 'fatal',
+      recoverable: false,
+      context: opts.context,
+      cause: opts.cause,
+    });
+    this.name = 'ConfigError';
+  }
+}
+
+export class PluginError extends FlowCodexError {
+  readonly pluginName: string;
+
+  constructor(opts: {
+    message: string;
+    code: Extract<
+      ErrorCode,
+      'PLUGIN_LOAD_FAILED' | 'PLUGIN_API_MISMATCH' | 'PLUGIN_MISSING_DEPENDENCY'
+    >;
+    pluginName: string;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: 'plugin',
+      severity: 'error',
+      recoverable: opts.code === ERROR_CODES.PLUGIN_MISSING_DEPENDENCY,
+      context: { plugin: opts.pluginName, ...opts.context },
+      cause: opts.cause,
+    });
+    this.name = 'PluginError';
+    this.pluginName = opts.pluginName;
+  }
+}
+
+export class AgentError extends FlowCodexError {
+  constructor(opts: {
+    message: string;
+    code: Extract<
+      ErrorCode,
+      | 'AGENT_ITERATION_LIMIT'
+      | 'AGENT_CONTEXT_OVERFLOW'
+      | 'AGENT_ABORTED'
+      | 'AGENT_RUN_FAILED'
+      | 'AGENT_BUDGET_EXCEEDED'
+      | 'COMPACTION_FAILED'
+      | 'PROMPT_BUDGET_EXCEEDED'
+    >;
+    recoverable?: boolean | undefined;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: 'agent',
+      severity: opts.code === ERROR_CODES.AGENT_ABORTED ? 'warning' : 'error',
+      recoverable: opts.recoverable ?? opts.code === ERROR_CODES.AGENT_ITERATION_LIMIT,
+      context: opts.context,
+      cause: opts.cause,
+    });
+    this.name = 'AgentError';
+  }
+}
+
+export class PermissionError extends FlowCodexError {
+  readonly tool: string;
+  readonly pattern?: string | undefined;
+  readonly source: string;
+
+  constructor(opts: {
+    message: string;
+    tool: string;
+    pattern?: string | undefined;
+    source: string;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: ERROR_CODES.TOOL_PERMISSION_DENIED,
+      subsystem: 'tool',
+      recoverable: false,
+      context: { tool: opts.tool, pattern: opts.pattern, source: opts.source, ...opts.context },
+      cause: opts.cause,
+    });
+    this.name = 'PermissionError';
+    this.tool = opts.tool;
+    this.pattern = opts.pattern;
+    this.source = opts.source;
+  }
+}
+
+export function toFlowCodexError(
+  err: unknown,
+  code: Extract<ErrorCode, 'AGENT_RUN_FAILED' | 'AGENT_ABORTED' | 'UNKNOWN'> = ERROR_CODES.AGENT_RUN_FAILED,
+): FlowCodexError {
+  if (err instanceof FlowCodexError) return err;
+  const message = toErrorMessage(err);
+  return new AgentError({
+    message,
+    code: code === 'UNKNOWN' ? ERROR_CODES.AGENT_RUN_FAILED : code,
+    cause: err,
+  });
+}
+
+export class SessionError extends FlowCodexError {
+  readonly sessionId?: string | undefined;
+
+  constructor(opts: {
+    message: string;
+    code: Extract<ErrorCode, 'SESSION_NOT_FOUND' | 'SESSION_CORRUPTED' | 'SESSION_WRITE_FAILED'>;
+    sessionId?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: 'session',
+      severity: opts.code === ERROR_CODES.SESSION_WRITE_FAILED ? 'error' : 'warning',
+      recoverable: opts.code !== ERROR_CODES.SESSION_CORRUPTED,
+      context: { sessionId: opts.sessionId, ...opts.context },
+      cause: opts.cause,
+    });
+    this.name = 'SessionError';
+    this.sessionId = opts.sessionId;
+  }
+}
+
+export class FsError extends FlowCodexError {
+  readonly path?: string | undefined;
+
+  constructor(opts: {
+    message: string;
+    code: Extract<
+      ErrorCode,
+      | 'FS_READ_FAILED'
+      | 'FS_WRITE_FAILED'
+      | 'FS_MKDIR_FAILED'
+      | 'FS_DELETE_FAILED'
+      | 'FS_ATOMIC_WRITE_FAILED'
+      | 'FS_PATH_ESCAPE'
+    >;
+    path?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+    cause?: unknown | undefined;
+  }) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: 'fs',
+      severity: 'error',
+      recoverable: opts.code !== ERROR_CODES.FS_READ_FAILED,
+      context: { path: opts.path, ...opts.context },
+      cause: opts.cause,
+    });
+    this.name = 'FsError';
+    this.path = opts.path;
+  }
+}
+
+export function isFlowCodexError(err: unknown): err is FlowCodexError {
+  return err instanceof FlowCodexError;
+}
+
+export function isToolError(err: unknown): err is ToolError {
+  return err instanceof ToolError;
+}
+
+export function isConfigError(err: unknown): err is ConfigError {
+  return err instanceof ConfigError;
+}
+
+export function isPluginError(err: unknown): err is PluginError {
+  return err instanceof PluginError;
+}
+
+export function isSessionError(err: unknown): err is SessionError {
+  return err instanceof SessionError;
+}
+
+export function isAgentError(err: unknown): err is AgentError {
+  return err instanceof AgentError;
+}
+
+export function isFsError(err: unknown): err is FsError {
+  return err instanceof FsError;
+}
+
+export function isPermissionError(err: unknown): err is PermissionError {
+  return err instanceof PermissionError;
+}

package/src/types/index.ts

@@ -0,0 +1,34 @@
+export type {
+  ContentBlock,
+  Role,
+  Message,
+  ModelId,
+  ModelRef,
+} from './blocks.js';
+export { isToolUseBlock, isToolResultBlock, isTextBlock, isThinkingBlock } from './blocks.js';
+
+export type {
+  ToolUse,
+  ToolResult,
+  Budget,
+  AgentStatus,
+  RunResult,
+  Context,
+} from './context.js';
+
+export type {
+  Usage,
+  LLMRequest,
+  LLMResponse,
+  LLMEvent,
+  ProviderError,
+  Provider,
+} from './provider.js';
+
+export type {
+  Tool,
+  ToolStreamEvent,
+  Permission,
+  RiskTier,
+  ToolContext,
+} from './tool.js';

package/src/types/provider.ts

@@ -0,0 +1,58 @@
+import type { ContentBlock, Message } from './blocks.js';
+
+export interface Usage {
+  input: number;
+  output: number;
+  cache_read?: number | undefined;
+  cache_creation?: number | undefined;
+}
+
+export interface ToolChoice {
+  type: 'auto' | 'any' | 'tool';
+  name?: string | undefined;
+}
+
+export interface StructuredOutputConfig {
+  name: string;
+  description?: string | undefined;
+  schema: Record<string, unknown>;
+}
+
+export interface LLMRequest {
+  model: string;
+  system: ContentBlock[];
+  messages: Message[];
+  tools?: unknown[] | undefined;
+  max_tokens?: number | undefined;
+  thinking?: unknown | undefined;
+  output_config?: StructuredOutputConfig | undefined;
+  tool_choice?: ToolChoice | undefined;
+}
+
+export interface LLMResponse {
+  content: ContentBlock[];
+  usage: Usage;
+  stopReason: string;
+}
+
+export type LLMEvent =
+  | { type: 'text_delta'; text: string }
+  | { type: 'thinking_delta'; text: string }
+  | { type: 'tool_use_start'; id: string; name: string }
+  | { type: 'tool_use_input_delta'; id: string; partialJson: string }
+  | { type: 'tool_use_stop'; id: string }
+  | { type: 'finish'; usage: Usage; stopReason: string }
+  | { type: 'error'; error: { status: number; message: string; retryable: boolean; retryAfterMs?: number | undefined } };
+
+export interface ProviderError {
+  status: number;
+  message: string;
+  retryable: boolean;
+  describe(): string;
+}
+
+export interface Provider {
+  name: string;
+  stream(request: LLMRequest): AsyncIterable<LLMEvent>;
+  complete(request: LLMRequest): Promise<LLMResponse>;
+}

package/src/types/tool.ts

@@ -0,0 +1,39 @@
+export interface ToolStreamEvent<O = unknown> {
+  type: 'log' | 'warning' | 'metric' | 'file_changed' | 'partial_output' | 'final';
+  text?: string | undefined;
+  data?: Record<string, unknown> | undefined;
+  output?: O | undefined;
+}
+
+export type Permission = 'auto' | 'confirm' | 'deny';
+export type RiskTier = 'safe' | 'standard' | 'destructive';
+
+export interface ToolContext {
+  projectRoot: string;
+  workingDir: string;
+  signal: AbortSignal;
+  registerAbortHook(fn: () => void | Promise<void>): () => void;
+  recordRead(absPath: string, mtimeMs: number): void;
+  hasRead(absPath: string): boolean;
+  lastReadMtime(absPath: string): number | undefined;
+}
+
+export interface Tool<I = unknown, O = unknown> {
+  name: string;
+  description: string;
+  /** Short, model-facing usage hint. Falls back to `description` in the system
+   *  prompt. Trimmed to 80 chars (60 in token-saving mode) by SystemPromptBuilder. */
+  usageHint?: string | undefined;
+  inputSchema: Record<string, unknown>;
+  permission: Permission;
+  mutating: boolean;
+  tier?: 'essential' | 'extended' | undefined;
+  riskTier?: RiskTier | undefined;
+  subjectKey?: string | undefined;
+  maxOutputBytes?: number | undefined;
+  timeoutMs?: number | undefined;
+  capabilities?: readonly string[] | undefined;
+  execute(input: I, ctx: ToolContext, opts: { signal: AbortSignal }): Promise<O>;
+  executeStream?(input: I, ctx: ToolContext, opts: { signal: AbortSignal }): AsyncIterable<ToolStreamEvent<O>>;
+  cleanup?(input: I, ctx: ToolContext): Promise<void>;
+}

package/src/utils/error.ts

@@ -0,0 +1,3 @@
+export function toErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/utils/fs.ts

@@ -0,0 +1,185 @@
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+
+const TMP_PREFIX = '.flowcodex-tmp-';
+
+export async function atomicWrite(filePath: string, content: string): Promise<void> {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tmp = path.join(dir, `${TMP_PREFIX}${base}-${process.pid}-${Date.now()}`);
+  await fsp.writeFile(tmp, content, 'utf8');
+  try {
+    await fsp.rename(tmp, filePath);
+  } catch (err) {
+    await fsp.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+export function isBinaryBuffer(buf: Uint8Array): boolean {
+  const len = Math.min(buf.length, 8192);
+  for (let i = 0; i < len; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+export type NewlineStyle = 'lf' | 'crlf';
+
+export function detectNewlineStyle(text: string): NewlineStyle {
+  const crlf = text.indexOf('\r\n');
+  const lf = text.indexOf('\n');
+  if (crlf !== -1 && (lf === -1 || crlf < lf)) return 'crlf';
+  return 'lf';
+}
+
+export function normalizeToLf(text: string): string {
+  return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+export function toStyle(text: string, style: NewlineStyle): string {
+  if (style === 'crlf') return text.replace(/\n/g, '\r\n');
+  return text;
+}
+
+export function compileGlob(pattern: string): RegExp {
+  let re = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i] ?? '';
+    switch (c) {
+      case '*':
+        if (pattern[i + 1] === '*') {
+          i += 2;
+          if (pattern[i] === '/') i++;
+          re += '.*';
+        } else {
+          i++;
+          re += '[^/]*';
+        }
+        continue;
+      case '?':
+        i++;
+        re += '[^/]';
+        continue;
+      case '.':
+      case '+':
+      case '^':
+      case '$':
+      case '(':
+      case ')':
+      case '[':
+      case ']':
+      case '{':
+      case '}':
+      case '|':
+      case '\\':
+        re += '\\' + c;
+        break;
+      default:
+        re += c;
+    }
+    i++;
+  }
+  return new RegExp('^' + re + '$');
+}
+
+export interface DiffOptions {
+  fromFile?: string | undefined;
+  toFile?: string | undefined;
+  contextLines?: number | undefined;
+}
+
+export function unifiedDiff(oldText: string, newText: string, opts: DiffOptions = {}): string {
+  const oldLines = oldText.split('\n');
+  const newLines = newText.split('\n');
+  const lcs = computeLcsTable(oldLines, newLines);
+  const hunks = extractHunks(oldLines, newLines, lcs, opts.contextLines ?? 3);
+  if (hunks.length === 0) return '';
+
+  const from = opts.fromFile ?? 'original';
+  const to = opts.toFile ?? 'modified';
+  const header = `--- ${from}\n+++ ${to}\n`;
+  return header + hunks.join('\n') + '\n';
+}
+
+function computeLcsTable(a: string[], b: string[]): number[][] {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      dp[i]![j]! = a[i] === b[j]
+        ? dp[i + 1]![j + 1]! + 1
+        : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
+    }
+  }
+  return dp;
+}
+
+function extractHunks(
+  a: string[],
+  b: string[],
+  lcs: number[][],
+  contextLines: number,
+): string[] {
+  const lines: Array<{ type: 'ctx' | 'add' | 'del'; aLine: number; bLine: number; text: string }> = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      lines.push({ type: 'ctx', aLine: i, bLine: j, text: a[i]! });
+      i++;
+      j++;
+    } else if (i < a.length && (j >= b.length || lcs[i + 1]![j]! >= lcs[i]![j + 1]!)) {
+      lines.push({ type: 'del', aLine: i, bLine: j, text: a[i]! });
+      i++;
+    } else {
+      lines.push({ type: 'add', aLine: i, bLine: j, text: b[j]! });
+      j++;
+    }
+  }
+
+  const hunks: string[] = [];
+  let idx = 0;
+  while (idx < lines.length) {
+    while (idx < lines.length && lines[idx]!.type === 'ctx') idx++;
+    if (idx >= lines.length) break;
+
+    let start = idx;
+    while (start > 0 && lines[start - 1]!.type === 'ctx' && idx - start < contextLines) {
+      start--;
+    }
+
+    let end = idx;
+    while (end < lines.length && lines[end]!.type !== 'ctx') end++;
+    while (end < lines.length && lines[end]!.type === 'ctx' && end - idx < contextLines) {
+      end++;
+      idx = end;
+      while (end < lines.length && lines[end]!.type !== 'ctx') end++;
+    }
+    idx = end;
+
+    const hunkLines = lines.slice(start, Math.min(end + contextLines, lines.length));
+    const aStart = hunkLines[0]!.aLine + 1;
+    const aCount = hunkLines.filter(l => l.type !== 'add').length;
+    const bStart = hunkLines[0]!.bLine + 1;
+    const bCount = hunkLines.filter(l => l.type !== 'del').length;
+
+    const body = hunkLines.map(l => {
+      const prefix = l.type === 'add' ? '+' : l.type === 'del' ? '-' : ' ';
+      return `${prefix}${l.text}`;
+    }).join('\n');
+
+    hunks.push(`@@ -${aStart},${aCount} +${bStart},${bCount} @@\n${body}`);
+  }
+  return hunks;
+}
+
+export function stripAnsi(text: string): string {
+  return text.replace(
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI escape sequence matching
+    /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g,
+    '',
+  );
+}