typeclaw 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/auth.ts

@@ -83,8 +83,10 @@ export function getAuthFor(providerId: KnownProviderId): Auth {
 
 // Back-compat shim for callers that still want the `default` profile's auth
 // (the main session path). Equivalent to `getAuthFor(provider-of-default)`.
+// Uses the head of the fallback chain; auth for the rest of the chain is
+// resolved lazily when fallback actually fires.
 export function getAuth(): Auth {
-  const defaultRef = getConfig().models.default
+  const defaultRef = getConfig().models.default[0]!
   return getAuthFor(providerForModelRef(defaultRef))
 }
 
@@ -98,7 +100,7 @@ function hasAnyCredentialInEnv(apiKeyEnv: string | null): boolean {
 
 function missingCredentialMessage(providerId: KnownProviderId): string {
   const provider = KNOWN_PROVIDERS[providerId]
-  const defaultRef = getConfig().models.default
+  const defaultRef = getConfig().models.default[0]!
   const defaultProviderId = providerForModelRef(defaultRef)
   // For the `default` profile, name the model in the error message (matches
   // pre-multi-model behavior). For any other profile, the user is mixing

package/src/agent/index.ts

@@ -8,7 +8,7 @@ import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent
 import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
-import { providerForModelRef } from '@/config/providers'
+import { providerForModelRef, type KnownModelRef } from '@/config/providers'
 import type { PermissionService } from '@/permissions'
 import type {
   BuiltinToolRef,
@@ -134,6 +134,12 @@ export type CreateSessionOptions = {
   // overrides) so different sessions on the same agent can run different
   // models without per-session config edits.
   profile?: string
+  // Override the resolved ref directly, bypassing `profile` resolution. Used
+  // by the model-fallback helper (`promptWithFallback`) to recreate a session
+  // pinned to the next ref in the chain after the previous one failed. When
+  // set, `profile` is still recorded for the fallback-warning bookkeeping;
+  // the profile→refs resolution is skipped.
+  refOverride?: KnownModelRef
   // Defensive ceiling on cumulative bytes of tool-result text per session,
   // applied to the named tools only. See `src/agent/tool-result-budget.ts`
   // for the rationale. Intended for subagents that read large files
@@ -161,10 +167,14 @@ export async function createSession(options: CreateSessionOptions = {}): Promise
 
 export async function createSessionWithDispose(options: CreateSessionOptions = {}): Promise<CreateSessionResult> {
   const resolved = resolveProfile(getConfig().models, options.profile)
-  if (resolved.fellBackToDefault && options.profile !== undefined && options.profile !== 'default') {
-    warnProfileFallbackOnce(options.profile, resolved.ref)
-  }
-  const { authStorage, modelRegistry } = getAuthFor(providerForModelRef(resolved.ref))
+  // Unknown profiles silently fall back to `default`. The fallback is by design
+  // (see `resolveProfile`) and surfacing a warning here just creates noise on
+  // every memory-logger / dreaming subagent spawn for advanced users who know
+  // exactly what they're doing.
+  // `refOverride` lets the model-fallback helper pin a specific entry from
+  // the chain when it recreates a session after the previous ref failed.
+  const activeRef: KnownModelRef = options.refOverride ?? resolved.ref
+  const { authStorage, modelRegistry } = getAuthFor(providerForModelRef(activeRef))
 
   const materializedSkills =
     options.plugins && options.plugins.registry.skills.length > 0
@@ -279,7 +289,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
       ? customToolsPreBudget.map((t) => wrapToolDefinitionWithBudget(t, sessionBudget, sessionBudgetState))
       : customToolsPreBudget
 
-  const model = resolveModel(resolved.ref)
+  const model = resolveModel(activeRef)
   const { session } = await createAgentSession({
     model,
     sessionManager,
@@ -737,25 +747,3 @@ function resolveRoleContext(
 export function getBundledSkillsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 }
-
-// Profile-fallback warning is fired once per (profile, ref) pair per process.
-// Without rate-limiting, every memory-logger spawn (~every idle event) would
-// emit a fresh warning when the user has only `default` configured — tens of
-// warnings per channel session is noise the operator will learn to ignore.
-// The pair includes `ref` so a config reload that changes `default` re-warns.
-const profileFallbackWarned = new Set<string>()
-
-function warnProfileFallbackOnce(profile: string, ref: string): void {
-  const key = `${profile}\x00${ref}`
-  if (profileFallbackWarned.has(key)) return
-  profileFallbackWarned.add(key)
-  console.warn(
-    `[agent] unknown model profile "${profile}"; falling back to "default" (${ref}). Add it under \`models\` in typeclaw.json to remove this warning. (further occurrences suppressed)`,
-  )
-}
-
-// Test-only: clear the rate-limit cache so a test can assert the warning fires
-// once after rate-limit reset.
-export function __resetProfileFallbackWarningsForTesting(): void {
-  profileFallbackWarned.clear()
-}

package/src/agent/model-fallback.ts

@@ -0,0 +1,127 @@
+import { resolveProfile } from '@/config'
+import type { Models } from '@/config/config'
+import type { KnownModelRef } from '@/config/providers'
+
+import type { AgentSession } from './index'
+import { subscribeProviderErrors } from './provider-error'
+
+// Result of a single fallback-aware prompt run.
+// - `refUsed` is the ref whose session ultimately handled the turn.
+// - `attempts` lists every ref that was tried, in order, with the failure
+//   reason for each attempt that didn't make it through. `attempts.length`
+//   is always >= 1; the last entry succeeded iff `success: true`.
+// - `session` / `dispose` are the session that handled the turn (or attempted
+//   the final entry, on full-chain failure). Callers that need to keep using
+//   the session for subsequent turns store these in their state; callers that
+//   tear down per-turn (cron) just call `dispose()` and discard.
+export type FallbackPromptResult = {
+  success: boolean
+  refUsed: KnownModelRef
+  attempts: FallbackAttempt[]
+  session: AgentSession
+  dispose: () => Promise<void>
+  // When `success === false`, this is the error from the final attempt.
+  lastError?: Error
+}
+
+export type FallbackAttempt = {
+  ref: KnownModelRef
+  // 'hard' = session.prompt() threw. 'soft' = pi-coding-agent surfaced an
+  // upstream error via stopReason: 'error' on the final assistant message.
+  // 'success' = the turn finished cleanly.
+  outcome: 'hard' | 'soft' | 'success'
+  errorMessage?: string
+}
+
+// Build the ordered list of refs to attempt for a given profile. Single-ref
+// profiles produce a length-1 chain; the fallback path is then a no-op in
+// practice (the first attempt either succeeds or the error propagates).
+//
+// Exported so callers can introspect the chain (e.g. logs, telemetry) before
+// firing the prompt — useful for `[cron] ${jobId}: trying chain a → b → c`.
+export function resolveFallbackChain(models: Models, profile: string | undefined): KnownModelRef[] {
+  return resolveProfile(models, profile).refs
+}
+
+// Drives one `session.prompt(text)` call with full fallback semantics:
+//
+//   1. Create a session bound to `refs[0]` via `createSessionForRef`.
+//   2. Subscribe to provider-error events so soft errors (pi-coding-agent's
+//      `stopReason: 'error'` shape) trigger fallback in addition to throws.
+//   3. Await `session.prompt(text)`.
+//   4. If the prompt threw OR a soft error fired during the turn:
+//      - dispose the failed session
+//      - advance to `refs[i+1]` and retry (only if a fallback is available)
+//   5. Return the session that handled the turn (or the last-tried session
+//      on full-chain failure), the ref used, and the attempt log.
+//
+// The wrapper intentionally does NOT swallow the final failure: when every
+// ref in the chain has been exhausted, the returned `success: false` plus
+// `lastError` lets the caller surface the failure however it already does
+// (console.error in the server drain, channel reaction in the router,
+// cron-job status). This keeps the helper composable with the existing
+// error-handling code at each call site.
+export async function promptWithFallback(opts: {
+  refs: KnownModelRef[]
+  text: string
+  createSessionForRef: (ref: KnownModelRef) => Promise<{ session: AgentSession; dispose: () => Promise<void> }>
+  // Called after each non-final attempt so callers can log the per-attempt
+  // failure with their own context (sessionId, channel key, job id, ...).
+  onAttemptFailed?: (attempt: FallbackAttempt) => void
+}): Promise<FallbackPromptResult> {
+  if (opts.refs.length === 0) {
+    throw new Error('promptWithFallback: refs[] must be non-empty')
+  }
+  const attempts: FallbackAttempt[] = []
+  let lastError: Error | undefined
+  for (let i = 0; i < opts.refs.length; i++) {
+    const ref = opts.refs[i]!
+    const isLast = i === opts.refs.length - 1
+    const { session, dispose } = await opts.createSessionForRef(ref)
+    // Capture the first soft error per attempt. The `subscribeProviderErrors`
+    // listener fires synchronously off the `message_end` event, which lands
+    // BEFORE `session.prompt()` resolves — so by the time `await` returns,
+    // `softError` is populated if a soft error occurred.
+    let softError: Error | undefined
+    const unsub = subscribeProviderErrors(session, (err) => {
+      if (!softError) softError = new Error(err.message)
+    })
+    try {
+      try {
+        await session.prompt(opts.text)
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err))
+        const attempt: FallbackAttempt = { ref, outcome: 'hard', errorMessage: error.message }
+        attempts.push(attempt)
+        lastError = error
+        if (!isLast) opts.onAttemptFailed?.(attempt)
+        unsub()
+        await dispose()
+        if (isLast) {
+          return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
+        }
+        continue
+      }
+      if (softError !== undefined) {
+        const attempt: FallbackAttempt = { ref, outcome: 'soft', errorMessage: softError.message }
+        attempts.push(attempt)
+        lastError = softError
+        if (!isLast) opts.onAttemptFailed?.(attempt)
+        unsub()
+        await dispose()
+        if (isLast) {
+          return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
+        }
+        continue
+      }
+      attempts.push({ ref, outcome: 'success' })
+      unsub()
+      return { success: true, refUsed: ref, attempts, session, dispose }
+    } catch (err) {
+      unsub()
+      await dispose()
+      throw err
+    }
+  }
+  throw new Error('promptWithFallback: unreachable — loop terminated without returning')
+}

package/src/agent/tools/curl-impersonate.ts

@@ -0,0 +1,300 @@
+// Shared curl-impersonate spawn primitive.
+//
+// Why this exists: by 2026, every non-trivial public site (DDG, Reuters via
+// Akamai, MarketWatch via Cloudflare, etc.) fingerprints incoming traffic at
+// the TLS handshake (JA3/JA4) and HTTP/2 SETTINGS frame BEFORE any HTTP header
+// is read. Bun's native fetch cannot match Chrome's handshake (upstream issue
+// #11368), so outbound requests get gated by anomaly checks regardless of
+// headers, body shape, or pacing. The fix is to shell out to curl-impersonate
+// (lexiforest fork), which replays Chrome's exact TLS handshake, HTTP/2
+// settings, and header ordering. Pinned by the typeclaw Dockerfile at
+// /usr/local/bin/curl_chrome136 — see src/init/dockerfile.ts for the version
+// and SHA pin.
+//
+// AGENTS.md explicitly warns against adding `-H` overrides because the
+// curl_chrome wrapper already sends the full Chrome header set (correct
+// ordering, sec-ch-ua, sec-fetch-*, accept-encoding, etc.) and any custom
+// header corrupts the impersonation. We therefore expose NO header-override
+// surface from this primitive; add one only when a real caller needs it AND
+// the override is something curl_chrome can't be told to send another way.
+
+import { randomBytes } from 'node:crypto'
+
+import { spawn } from 'bun'
+
+export const CURL_IMPERSONATE_BINARY = 'curl_chrome136'
+export const DEFAULT_TIMEOUT_SECONDS = 30
+
+let curlBinary: string = CURL_IMPERSONATE_BINARY
+
+// Test-only seam: lets *.test.ts point the spawn at a fake `curl_chrome136`
+// script in a tmpdir so we exercise the real Bun.spawn path without depending
+// on a curl-impersonate install on the test host. Production code never calls
+// this — the module-level default above is what production sees.
+export function _setCurlBinaryForTest(binary: string | null): void {
+  curlBinary = binary ?? CURL_IMPERSONATE_BINARY
+}
+
+export type CurlImpersonateRequest = {
+  url: string
+  method?: 'GET' | 'POST'
+  // Form-urlencoded body fields for POST. Each entry is passed as a separate
+  // --data-urlencode argument so curl handles the encoding. Required if
+  // method is 'POST' and you want a body.
+  formFields?: Array<{ name: string; value: string }>
+  // Hard cap on bytes accepted from the response (passed as --max-filesize).
+  // The actual buffer is still bounded by the caller; this just makes curl
+  // bail early instead of streaming gigabytes.
+  maxBytes?: number
+  timeoutSeconds?: number
+  signal?: AbortSignal
+}
+
+export type CurlImpersonateResponse = {
+  body: string
+  finalUrl: string
+  httpStatus: number
+  contentType: string
+  bytesIn: number
+}
+
+// Specific curl exit codes we map to typed errors. The full list is in
+// `man curl` § "EXIT CODES"; these are the only ones we translate at the
+// primitive layer. Everything else surfaces as a generic CurlImpersonateError
+// with stderr attached for caller-side diagnostics.
+export const CURL_EXIT_TIMEOUT = 28
+export const CURL_EXIT_MAX_FILESIZE_PRECHECK = 63
+// Observed empirically (and corroborated by Oracle review): curl returns
+// exit 56 with stderr `Exceeded the maximum allowed file size (...)` when
+// --max-filesize is hit at TRANSFER time (e.g. server omitted Content-Length
+// and curl discovered the overflow mid-stream). The Linux man page lists 56
+// as the more general "Failure in receiving network data," so we additionally
+// gate on a stderr match to avoid mis-classifying real network drops as
+// size-exceeded.
+export const CURL_EXIT_RECV_FAILURE_OR_FILESIZE = 56
+
+export class CurlImpersonateError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: number | null,
+    public readonly stderr: string,
+  ) {
+    super(message)
+    this.name = 'CurlImpersonateError'
+  }
+}
+
+export function isCurlExitFilesizeExceeded(error: CurlImpersonateError): boolean {
+  if (error.exitCode === CURL_EXIT_MAX_FILESIZE_PRECHECK) return true
+  if (error.exitCode === CURL_EXIT_RECV_FAILURE_OR_FILESIZE && /maximum.{0,30}file size/i.test(error.stderr)) {
+    return true
+  }
+  return false
+}
+
+export function isCurlExitTimeout(error: CurlImpersonateError): boolean {
+  return error.exitCode === CURL_EXIT_TIMEOUT
+}
+
+export async function curlImpersonate(req: CurlImpersonateRequest): Promise<CurlImpersonateResponse> {
+  const timeoutSeconds = req.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS
+  const method = req.method ?? 'GET'
+
+  // Per-request random sentinel + UTF-8-safe parsing. The static sentinel
+  // approach (previous revision) had a hardening hole: webfetch reads
+  // attacker-controlled pages, and a static sentinel is a public, fixed
+  // string. A page could include the sentinel byte sequence plus fabricated
+  // metadata before the real write-out tail and `indexOf` would split at
+  // the attacker-controlled occurrence. Per-request randomness (96 bits)
+  // removes the attacker's ability to predict the sentinel, and the parser
+  // anchors on the LAST occurrence (curl writes `-w` after the body, so the
+  // real metadata block is always last). Both defenses are needed: random
+  // alone fails if the attacker can read the sentinel from a previous
+  // response and replay it; last-match alone fails if the attacker can
+  // append text after curl's write-out (they can't, but defense in depth).
+  const sentinel = generateSentinel()
+  const writeOutTemplate = `${sentinel}%{http_code}\n%{url_effective}\n%{content_type}\n%{size_download}\n`
+
+  const cmd: string[] = [
+    curlBinary,
+    // `--disable` (alias -q) MUST be the first argument to suppress reading
+    // ~/.curlrc and /etc/curlrc. Without it, a user or attacker-controlled
+    // curlrc could inject --proxy, --header, --resolve, --no-location, etc.,
+    // silently subverting both the Chrome impersonation contract and the
+    // protocol restrictions below. Order is load-bearing: curl ignores
+    // --disable if it appears after any other flag.
+    '--disable',
+    '--silent',
+    '--show-error',
+    // Protocol allowlist. curl-impersonate supports many protocols by default
+    // (ftp, file, dict, etc.). normalizeUrl() already rejects non-http(s) at
+    // the call-site, but redirects are followed by curl after that gate fires
+    // and a 301/302 to ftp://... would otherwise be silently honored. The
+    // `=http,https` syntax means "ONLY these two" rather than "add these to
+    // defaults." --proto-redir governs the redirect chain specifically.
+    '--proto',
+    '=http,https',
+    '--proto-redir',
+    '=http,https',
+    // `--fail-with-body` would make curl exit non-zero on >=400 but still
+    // write the body. We intentionally DO NOT pass it: callers (webfetch,
+    // ddg) want to inspect httpStatus themselves and decide. Curl exits 0
+    // on a 404-with-body in this mode, which matches our contract.
+    '--compressed',
+    '--location',
+    '--max-redirs',
+    '10',
+    '--max-time',
+    String(timeoutSeconds),
+    '-w',
+    writeOutTemplate,
+    '-X',
+    method,
+  ]
+
+  if (req.maxBytes !== undefined) {
+    cmd.push('--max-filesize', String(req.maxBytes))
+  }
+
+  if (req.formFields) {
+    for (const field of req.formFields) {
+      cmd.push('--data-urlencode', `${field.name}=${field.value}`)
+    }
+  }
+
+  // `--` terminates option parsing so a URL beginning with `-` (e.g. an
+  // attacker-supplied "-K /etc/passwd" sneaking through normalizeUrl as
+  // "https://-K /etc/passwd") cannot be reinterpreted as a curl option.
+  cmd.push('--', req.url)
+
+  // Spawn detached so the child becomes the leader of its own process group.
+  // The curl-impersonate wrappers (curl_chrome136 et al.) are bash scripts
+  // that call the real curl-impersonate binary WITHOUT `exec` — meaning the
+  // wrapper is the parent and curl-impersonate is its child. On a plain
+  // SIGKILL to the wrapper PID, the curl child becomes orphaned and keeps
+  // the stdout pipe open until --max-time fires, turning a 50ms abort into
+  // a 30s hang. process.kill(-pid) addresses the negative PID, which signals
+  // the entire process group, killing both atomically. detached: true makes
+  // the child the pgid leader so -pid is well-defined.
+  const proc = spawn({
+    cmd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    detached: true,
+  })
+
+  const onAbort = () => {
+    try {
+      process.kill(-proc.pid, 'SIGKILL')
+    } catch {
+      proc.kill('SIGKILL')
+    }
+  }
+  req.signal?.addEventListener('abort', onAbort, { once: true })
+
+  try {
+    const [stdoutBuf, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).arrayBuffer(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+
+    if (req.signal?.aborted) {
+      throw new CurlImpersonateError('aborted', exitCode, stderr)
+    }
+
+    if (exitCode !== 0) {
+      const detail = stderr.trim() || 'no stderr'
+      throw new CurlImpersonateError(`curl-impersonate exited ${exitCode}: ${detail}`, exitCode, stderr)
+    }
+
+    return parseCurlOutput(stdoutBuf, sentinel, stderr)
+  } finally {
+    req.signal?.removeEventListener('abort', onAbort)
+  }
+}
+
+// Generates a per-request sentinel. Format: `\n--TYPECLAW-CURL-META-<hex>--\n`.
+// 24 hex chars = 96 bits of entropy, plenty to defeat any attempt by an
+// attacker-controlled response body to inject a colliding marker. ASCII-only
+// + leading/trailing newlines means it's unambiguous in textual responses
+// and free of NUL bytes (Bun's spawn rejects NULs in argv).
+function generateSentinel(): string {
+  const hex = randomBytes(12).toString('hex')
+  return `\n--TYPECLAW-CURL-META-${hex}--\n`
+}
+
+function parseCurlOutput(buf: ArrayBuffer, sentinel: string, stderr: string): CurlImpersonateResponse {
+  const sentinelBytes = new TextEncoder().encode(sentinel)
+  const bytes = new Uint8Array(buf)
+
+  // Anchor on the LAST occurrence (defense in depth alongside the random
+  // sentinel). curl writes the `-w` output strictly AFTER the body, so the
+  // real metadata block is always the trailing one.
+  const sentinelIndex = lastIndexOfBytes(bytes, sentinelBytes)
+  if (sentinelIndex < 0) {
+    throw new CurlImpersonateError(
+      'curl-impersonate produced no metadata block (sentinel missing). Wrapper or output corruption suspected.',
+      0,
+      stderr,
+    )
+  }
+
+  const bodyBytes = bytes.subarray(0, sentinelIndex)
+  const metaBytes = bytes.subarray(sentinelIndex + sentinelBytes.byteLength)
+  const meta = new TextDecoder('utf-8', { fatal: false }).decode(metaBytes).split('\n')
+
+  const httpStatus = Number(meta[0]?.trim() ?? '0') || 0
+  const finalUrl = (meta[1] ?? '').trim()
+  const contentType = (meta[2] ?? '').trim().toLowerCase()
+  const declaredBytes = Number(meta[3]?.trim() ?? '0') || bodyBytes.byteLength
+
+  const body = new TextDecoder('utf-8', { fatal: false }).decode(bodyBytes)
+
+  return {
+    body,
+    finalUrl,
+    httpStatus,
+    contentType,
+    bytesIn: declaredBytes,
+  }
+}
+
+function lastIndexOfBytes(haystack: Uint8Array, needle: Uint8Array): number {
+  if (needle.byteLength === 0) return haystack.byteLength
+  for (let i = haystack.byteLength - needle.byteLength; i >= 0; i--) {
+    let matched = true
+    for (let j = 0; j < needle.byteLength; j++) {
+      if (haystack[i + j] !== needle[j]) {
+        matched = false
+        break
+      }
+    }
+    if (matched) return i
+  }
+  return -1
+}
+
+// Detect whether curl-impersonate is available on PATH. Used by fetch.ts to
+// decide between the impersonating transport (production: container has the
+// binary pinned in the image) and a Bun.fetch fallback (test/dev: no binary
+// installed). The check is best-effort and cheap — we spawn `--version`
+// and look at exit code. Cached per-process: the binary doesn't appear or
+// disappear at runtime.
+let availabilityCache: boolean | undefined
+
+export async function isCurlImpersonateAvailable(): Promise<boolean> {
+  if (availabilityCache !== undefined) return availabilityCache
+  try {
+    const proc = spawn({ cmd: [curlBinary, '--version'], stdout: 'ignore', stderr: 'ignore' })
+    const code = await proc.exited
+    availabilityCache = code === 0
+  } catch {
+    availabilityCache = false
+  }
+  return availabilityCache
+}
+
+export function _resetAvailabilityCacheForTest(): void {
+  availabilityCache = undefined
+}

package/src/agent/tools/ddg.ts

@@ -7,40 +7,16 @@
 // single bad fingerprint match. `lite` exists for non-browser clients (text
 // browsers, accessibility tools) and historically gates less aggressively —
 // but as of 2026 it ALSO fingerprints at the TLS layer (JA3/JA4) and the
-// HTTP/2 SETTINGS frame, well before any HTTP header is read. Bun's native
-// fetch cannot match Chrome's handshake (upstream issue #11368), so requests
-// from `fetch()` get gated regardless of headers, body shape, or pacing —
-// confirmed empirically over a multi-hour session against a single home IP
-// where real Chromium succeeded continuously while every fetch variant got
-// 202 anomaly-modal or HTTP-200-with-anomaly responses.
-//
-// The fix is to shell out to `curl-impersonate` (lexiforest fork), which
-// replays Chrome's exact TLS handshake + HTTP/2 settings + header ordering.
-// The binary is installed by the typeclaw Dockerfile (see
-// src/init/dockerfile.ts CURL_IMPERSONATE_* constants) at /usr/local/bin/
-// and invoked via the version-pinned wrapper `curl_chrome136`.
-//
-// Why no `-H` overrides: curl_chrome136 already sends the full Chrome 136
-// header set with correct ordering, sec-ch-ua values, etc. Adding our own
-// headers would corrupt the impersonation. The previous code's
-// BROWSER_HEADERS const has been removed for the same reason.
+// HTTP/2 SETTINGS frame, well before any HTTP header is read. The shared
+// curl-impersonate primitive (./curl-impersonate.ts) replays Chrome's exact
+// TLS handshake + HTTP/2 settings + header ordering. See that file's header
+// for the full rationale and AGENTS.md §"Web search" for the original story.
 
-import { spawn } from 'bun'
-
-const DDG_LITE_URL = 'https://lite.duckduckgo.com/lite/'
-const CURL_IMPERSONATE_BINARY = 'curl_chrome136'
-const REQUEST_TIMEOUT_SECONDS = 30
+import { curlImpersonate } from './curl-impersonate'
 
-let curlBinary = CURL_IMPERSONATE_BINARY
+export { _setCurlBinaryForTest } from './curl-impersonate'
 
-// Test-only seam: lets ddg.test.ts and websearch.test.ts point the spawn
-// at a fake `curl_chrome136` script in a tmpdir so we exercise the real
-// Bun.spawn path without depending on a curl-impersonate install on the
-// test host. Production code never calls this — the const-import default
-// above is what production sees.
-export function _setCurlBinaryForTest(binary: string | null): void {
-  curlBinary = binary ?? CURL_IMPERSONATE_BINARY
-}
+const DDG_LITE_URL = 'https://lite.duckduckgo.com/lite/'
 
 export type DdgResult = {
   title: string
@@ -64,64 +40,13 @@ export class DdgCaptchaError extends Error {
 }
 
 export async function fetchDdgHtml(query: string, signal?: AbortSignal): Promise<string> {
-  // Spawn detached so the child becomes the leader of its own process group.
-  // The curl-impersonate wrappers (curl_chrome136 et al.) are bash scripts
-  // that call the real curl-impersonate binary WITHOUT `exec` — meaning the
-  // wrapper is the parent and curl-impersonate is its child. On a plain
-  // SIGKILL to the wrapper PID, the curl child becomes orphaned and keeps
-  // the stdout pipe open until --max-time fires (30s default), turning a
-  // 50ms abort into a 30s hang. process.kill(-pid) addresses the negative
-  // PID, which signals the entire process group, killing both the wrapper
-  // and the inner curl atomically. detached: true is what makes the child
-  // the pgid leader so -pid is well-defined; without it, the child shares
-  // our pgid and we'd nuke our own process.
-  const proc = spawn({
-    cmd: [
-      curlBinary,
-      '--silent',
-      '--show-error',
-      '--fail-with-body',
-      '--compressed',
-      '--max-time',
-      String(REQUEST_TIMEOUT_SECONDS),
-      '-X',
-      'POST',
-      '--data-urlencode',
-      `q=${query}`,
-      DDG_LITE_URL,
-    ],
-    stdout: 'pipe',
-    stderr: 'pipe',
-    detached: true,
+  const response = await curlImpersonate({
+    url: DDG_LITE_URL,
+    method: 'POST',
+    formFields: [{ name: 'q', value: query }],
+    signal,
   })
-
-  const onAbort = () => {
-    try {
-      process.kill(-proc.pid, 'SIGKILL')
-    } catch {
-      proc.kill('SIGKILL')
-    }
-  }
-  signal?.addEventListener('abort', onAbort, { once: true })
-
-  try {
-    const [stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited,
-    ])
-
-    if (signal?.aborted) {
-      throw new Error('aborted')
-    }
-    if (exitCode !== 0) {
-      const detail = stderr.trim() || 'no stderr'
-      throw new Error(`curl-impersonate exited ${exitCode}: ${detail}`)
-    }
-    return stdout
-  } finally {
-    signal?.removeEventListener('abort', onAbort)
-  }
+  return response.body
 }
 
 // The `lite` endpoint's CAPTCHA page is plainer than `html`'s anomaly-modal: