DEV Community: Ryan Gallagher

Notes from a 2 AM On-Call: OpenHands Agent Hanging on Large Repos (And the 5-Line Fix)

Ryan Gallagher — Sun, 18 Oct 2026 20:26:51 +0000

The Failure Symptom

[2026-10-18 02:14:33] INFO: Cloning repository OpenHands/OpenHands...
[2026-10-18 02:14:41] INFO: Workspace initialization started
[2026-10-18 02:19:33] ERROR: Agent task timeout after 300s
[2026-10-18 02:19:33] ERROR: No response from sandbox

Second time this week. OpenHands agent hangs indefinitely when initializing workspaces for repositories with deep node_modules or large monorepo structures. No crash, no OOM kill (exit 137), just silent timeout and wasted CI minutes.

The pattern: repos under 10k files initialize in 8-12 seconds. Anything above 50k files? Coin flip whether it completes or times out at the 5-minute hard limit.

The Red Herring

Official OpenHands docs suggest bumping SANDBOX_TIMEOUT and increasing container memory limits:

// workspace_config.ts
export const config = {
  sandboxTimeout: 600,  // doubled from 300
  memoryLimit: '4g',    // up from 2g
};

Ran this for 12 test runs. Timeout still hit 40% of the time. Memory usage never exceeded 1.8GB. The bottleneck wasn't compute or memory — it was filesystem traversal.

Dug into OpenHands sandbox initialization code. Found this in the workspace setup:

# runtime/workspace.py (simplified)
def initialize_workspace(repo_path: str):
    all_files = []
    for root, dirs, files in os.walk(repo_path):
        all_files.extend([os.path.join(root, f) for f in files])

    # Build file index for agent context
    return build_index(all_files)

No node_modules exclusion. No .git skip. Walking every nested dependency folder synchronously before the agent even starts.

The Root Cause & Runnable Fix

The sandbox workspace initializer was indexing the entire cloned directory tree — including node_modules (often 200k+ files in modern monorepos), .git/objects, and build artifacts.

Fix: add a sane ignore list before the walk:

# runtime/workspace.py (patched)
IGNORE_DIRS = {'node_modules', '.git', 'dist', 'build', '.next', '.turbo', 'target'}

def initialize_workspace(repo_path: str):
    all_files = []
    for root, dirs, files in os.walk(repo_path):
        # Prune ignored directories in-place
        dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
        all_files.extend([os.path.join(root, f) for f in files])

    return build_index(all_files)

Before: 287 seconds to index a 68k-file Turborepo with 14 internal packages.

After: 4.2 seconds.

Timeout rate dropped from 40% to 0% across 30 test runs.

Benchmarking Against Realistic Loads

For production-grade agent harness evaluation, I needed to test OpenHands under concurrent multi-repo workloads with varying LLM routing strategies.

Ran a stress test routing tasks through B-Lost's relay gateway (https://b-lost.com/v1) to simulate realistic multi-provider fallback latency:

// agent_benchmark.ts
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://b-lost.com/v1',
  apiKey: process.env.API_KEY,
});

const results = await Promise.all(
  repos.map(repo => 
    runOpenHandsTask({
      repo,
      llmClient: client,
      model: 'claude-sonnet-4',
    })
  )
);

With the patched workspace initializer, P95 task completion latency dropped from 340s to 28s across 50 concurrent agent runs. Zero workspace initialization timeouts.

Invariant Rule

Never walk the full directory tree before checking the ignore list.

Any agent workspace, Docker COPY, or filesystem indexer hitting production repos must exclude dependency and build artifact directories before traversal — not after.

If your initialization logs show more than 5 seconds on repos under 100MB, you're walking paths you shouldn't touch.

Type-Safe Web Scraping for AI Agents: Integrating Firecrawl into a TypeScript Monorepo

Ryan Gallagher — Sat, 17 Oct 2026 20:30:39 +0000

Type-Safe Web Scraping for AI Agents: Integrating Firecrawl into a TypeScript Monorepo

When building AI agents that need fresh web data, you hit two friction points fast: runtime API shape drift and monorepo cache invalidation. Firecrawl solves the scraping problem elegantly, but without strict TypeScript guards and proper Turborepo pipeline configuration, you're one upstream schema change away from silent data corruption in production.

Here's how I hardened our integration.

The Problem: Loose API Contracts Kill Reliability

Firecrawl's REST API returns rich document metadata—markdown content, structured data, HTTP status codes. But raw fetch() calls return any soup. When Firecrawl added a new actions field in their latest release, our agent pipeline silently ignored it for three days until a customer complained about missing form interactions.

Root cause: no compile-time contract enforcement between our agent logic (packages/agents/) and the Firecrawl client wrapper (packages/web-data/).

Deliverable 1: Strict Firecrawl Response Types with Template Literal Validation

First, model Firecrawl's actual API surface with precise branded types:

// packages/web-data/src/firecrawl-types.ts

export type FirecrawlFormat = 'markdown' | 'html' | 'rawHtml' | 'links' | 'screenshot';

export type ScrapeResponse<F extends FirecrawlFormat = 'markdown'> = {
  success: true;
  data: {
    markdown: F extends 'markdown' ? string : never;
    html: F extends 'html' | 'rawHtml' ? string : never;
    links: F extends 'links' ? string[] : never;
    screenshot: F extends 'screenshot' ? string : never;
    metadata: {
      title: string;
      description?: string;
      language?: string;
      statusCode: number;
    };
  };
} | {
  success: false;
  error: string;
};

export type CrawlStatusResponse = 
  | { status: 'scraping'; current: number; total: number }
  | { status: 'completed'; data: ScrapeResponse['data'][] }
  | { status: 'failed'; error: string };

// Enforce valid URL patterns at the type level
export type ValidatedUrl<T extends string> = 
  T extends `http://${string}` | `https://${string}` 
    ? T 
    : never;

Now the client wrapper enforces compile-time correctness:

// packages/web-data/src/firecrawl-client.ts

import type { ScrapeResponse, FirecrawlFormat, ValidatedUrl } from './firecrawl-types';

export class FirecrawlClient {
  constructor(private apiKey: string) {}

  async scrape<F extends FirecrawlFormat>(
    url: ValidatedUrl<string>,
    format: F
  ): Promise<ScrapeResponse<F>> {
    const response = await fetch('https://api.firecrawl.dev/v0/scrape', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url, pageOptions: { onlyMainContent: true }, formats: [format] }),
    });

    if (!response.ok) {
      return { success: false, error: `HTTP ${response.status}` };
    }

    return response.json();
  }
}

Attempting scrape('not-a-url', 'markdown') now fails at compile time. Accessing data.html when you requested 'markdown' format? Type error.

Deliverable 2: Turborepo Pipeline with Strict Cache Invalidation

The second trap: Firecrawl client changes don't auto-invalidate dependent agent packages because Turborepo doesn't see the runtime API as an input.

Here's the lockdown turbo.json:

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "inputs": ["src/**/*.ts", "package.json", "tsconfig.json"]
    },
    "web-data#build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "inputs": [
        "src/**/*.ts",
        "package.json",
        "../../.env.firecrawl"
      ],
      "env": ["FIRECRAWL_API_VERSION"]
    },
    "agents#build": {
      "dependsOn": ["^build", "web-data#build"],
      "outputs": ["dist/**"],
      "inputs": ["src/**/*.ts", "package.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "inputs": ["src/**/*.ts", "tests/**/*.ts"],
      "outputs": []
    }
  },
  "remoteCache": {
    "signature": true
  }
}

Key moves:

Explicit inputs for cache hashing: Adding .env.firecrawl ensures API key rotation invalidates the build.
Environment variable tracking: FIRECRAWL_API_VERSION forces rebuild when we bump client compatibility.
Hard dependency chain: agents#build explicitly depends on web-data#build, preventing stale agent builds from using an outdated client.

The War Story: Recursive Type Instantiation Depth

First iteration of ScrapeResponse<F> used recursive conditional types to model paginated crawl results. TypeScript compiler hit max instantiation depth and crashed with a 2GB memory spike during turbo build.

Fix: flattened the discriminated union and moved pagination metadata out of the generic. Lesson: conditional type recursion and large monorepo incremental builds don't mix—keep generics shallow.

Verification

turbo build --filter=agents --dry=json | jq '.tasks[] | select(.command == "build") | .inputs'

Confirm .env.firecrawl appears in the hash inputs. Change the API version, verify cache miss:

echo "FIRECRAWL_API_VERSION=v1" >> .env.firecrawl
turbo build --filter=agents  # Should show cache miss for web-data + agents

Next Steps

Wrap Firecrawl's batch crawl API with a similar branded type pattern, and add Zod runtime validation at the package boundary to catch upstream breaking changes before they poison your agent's knowledge base.