@selesai/code 0.1.19 → 0.2.1

package/dist/extensions/pi-subagents/src/runs/shared/pi-spawn.ts

@@ -2,36 +2,36 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
-export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+export const SELESAI_PACKAGE = "@selesai/code";
 
-export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
+export function findSelesaiPackageRootFromEntry(entryPoint: string): string | undefined {
 	let dir = path.dirname(entryPoint);
 	while (dir !== path.dirname(dir)) {
 		const packageJsonPath = path.join(dir, "package.json");
 		if (fs.existsSync(packageJsonPath)) {
 			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { name?: unknown };
-			if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
+			if (pkg.name === SELESAI_PACKAGE) return dir;
 		}
 		dir = path.dirname(dir);
 	}
 	return undefined;
 }
 
-export function resolveInstalledPiPackageRoot(): string | undefined {
-	return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+export function resolveInstalledSelesaiPackageRoot(): string | undefined {
+	return findSelesaiPackageRootFromEntry(fileURLToPath(import.meta.resolve(SELESAI_PACKAGE)));
 }
 
-export function resolvePiPackageRoot(): string | undefined {
+export function resolveSelesaiPackageRoot(): string | undefined {
 	try {
 		const entry = process.argv[1];
-		return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
+		return entry ? findSelesaiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
 	} catch {
 		// process.argv[1] probing is best-effort; callers can fall back to PATH/package resolution.
 		return undefined;
 	}
 }
 
-export interface PiSpawnDeps {
+export interface SelesaiSpawnDeps {
 	platform?: NodeJS.Platform;
 	execPath?: string;
 	argv1?: string;
@@ -42,7 +42,7 @@ export interface PiSpawnDeps {
 	piPackageRoot?: string;
 }
 
-interface PiSpawnCommand {
+interface SelesaiSpawnCommand {
 	command: string;
 	args: string[];
 }
@@ -56,7 +56,7 @@ function normalizePath(filePath: string): string {
 	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
 }
 
-export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | undefined {
+export function resolveWindowsSelesaiCliScript(deps: SelesaiSpawnDeps = {}): string | undefined {
 	const existsSync = deps.existsSync ?? fs.existsSync;
 	const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
 	const argv1 = deps.argv1 ?? process.argv[1];
@@ -82,12 +82,12 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 
 	try {
 		const resolvePackageJson = deps.resolvePackageJson ?? (() => {
-			const root = deps.piPackageRoot ?? resolvePiPackageRoot();
+			const root = deps.piPackageRoot ?? resolveSelesaiPackageRoot();
 			if (root) return path.join(root, "package.json");
 			const packageRoot = deps.resolvePackageEntry
-				? findPiPackageRootFromEntry(deps.resolvePackageEntry())
-				: resolveInstalledPiPackageRoot();
-			if (!packageRoot) throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
+				? findSelesaiPackageRootFromEntry(deps.resolvePackageEntry())
+				: resolveInstalledSelesaiPackageRoot();
+			if (!packageRoot) throw new Error(`Could not resolve ${SELESAI_PACKAGE} package root`);
 			return path.join(packageRoot, "package.json");
 		});
 		const packageJsonPath = resolvePackageJson();
@@ -97,33 +97,33 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 		const binField = packageJson.bin;
 		const binPath = typeof binField === "string"
 			? binField
-			: binField?.pi ?? Object.values(binField ?? {})[0];
+			: binField?.selesai ?? Object.values(binField ?? {})[0];
 		if (!binPath) return undefined;
 		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
 		if (isRunnableNodeScript(candidate, existsSync)) {
 			return candidate;
 		}
 	} catch {
-		// Windows CLI resolution is optional; falling back to `pi` lets PATH handle execution.
+		// Windows CLI resolution is optional; falling back to `selesai` lets PATH handle execution.
 		return undefined;
 	}
 
 	return undefined;
 }
 
-export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
+export function getSelesaiSpawnCommand(args: string[], deps: SelesaiSpawnDeps = {}): SelesaiSpawnCommand {
 	// On all platforms, prefer the running CLI script (process.argv[1]) so a
 	// renamed fork like "selesai" spawns its own binary instead of the upstream
-	// "pi" from PATH (which has a different agent dir / providers / auth).
-	const piCliPath = resolveWindowsPiCliScript(deps);
-	if (piCliPath) {
+	// "selesai" from PATH (which has a different agent dir / providers / auth).
+	const selesaiCliPath = resolveWindowsSelesaiCliScript(deps);
+	if (selesaiCliPath) {
 		return {
 			command: deps.execPath ?? process.execPath,
-			args: [piCliPath, ...args],
+			args: [selesaiCliPath, ...args],
 		};
 	}
 
 	// Fall back to the upstream binary name only if the CLI script could not be
-	// resolved. "pi" remains the historical default for stock pi installs.
-	return { command: "pi", args };
-}
+	// resolved. "selesai" is the default for selesai installs.
+	return { command: "selesai", args };
+}

package/dist/extensions/pi-subagents/src/runs/shared/spawn-timing.ts

@@ -0,0 +1,46 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { performance } from "node:perf_hooks";
+import { appendJsonl } from "../../shared/artifacts.ts";
+
+export type SpawnTimingMarker =
+	| "spawn_start"
+	| "spawn_command_resolved"
+	| "child_first_event"
+	| "child_first_jsonl_event";
+
+export interface SpawnTimingMarkers {
+	spawnStart: number;
+}
+
+export function createSpawnTimingMarkers(): SpawnTimingMarkers {
+	return { spawnStart: performance.now() };
+}
+
+export function emitSpawnTiming(options: {
+	eventsPath: string | undefined;
+	marker: SpawnTimingMarker;
+	markers: SpawnTimingMarkers;
+	runId?: string;
+	stepIndex?: number;
+	agent?: string;
+}): void {
+	if (!options.eventsPath) return;
+	try {
+		fs.mkdirSync(path.dirname(options.eventsPath), { recursive: true });
+		appendJsonl(
+			options.eventsPath,
+			JSON.stringify({
+				type: "subagent.spawn.timing",
+				ts: Date.now(),
+				runId: options.runId ?? "",
+				stepIndex: options.stepIndex ?? 0,
+				agent: options.agent ?? "runner",
+				marker: options.marker,
+				elapsedMs: Math.round(performance.now() - options.markers.spawnStart),
+			}),
+		);
+	} catch {
+		// Timing diagnostics must never fail the run.
+	}
+}

package/dist/extensions/pi-subagents/src/runs/shared/structured-output.ts

@@ -4,8 +4,8 @@ import * as path from "node:path";
 import { Compile } from "typebox/compile";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 
-export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
-export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+export const STRUCTURED_OUTPUT_SCHEMA_ENV = "SELESAI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
+export const STRUCTURED_OUTPUT_CAPTURE_ENV = "SELESAI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
 
 export interface StructuredOutputRuntime {
 	schema: JsonSchemaObject;

package/dist/extensions/pi-subagents/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,13 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@selesai/code";
 import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 
-const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
-const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
-export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
+const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "SELESAI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
+const SUBAGENT_INHERIT_SKILLS_ENV = "SELESAI_SUBAGENT_INHERIT_SKILLS";
+export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "SELESAI_SUBAGENT_INTERCOM_SESSION_NAME";
 
 const STRUCTURED_OUTPUT_INSTRUCTIONS = [
 	"This subagent step has a strict structured output contract.",

package/dist/extensions/pi-subagents/src/shared/fork-context.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@selesai/code";
 
 type SubagentExecutionContext = "fresh" | "fork";
 

package/dist/extensions/pi-subagents/src/shared/types.ts

@@ -6,7 +6,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import type { FSWatcher } from "node:fs";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@selesai/code";
 
 // ============================================================================
 // Basic Types
@@ -982,7 +982,7 @@ export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
 }
 
 export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
-	return normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH)
+	return normalizeMaxSubagentDepth(process.env.SELESAI_SUBAGENT_MAX_DEPTH)
 		?? normalizeMaxSubagentDepth(configMaxDepth)
 		?? DEFAULT_SUBAGENT_MAX_DEPTH;
 }
@@ -994,18 +994,18 @@ export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDep
 }
 
 export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
-	const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+	const depth = Number(process.env.SELESAI_SUBAGENT_DEPTH ?? "0");
 	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
 	const blocked = Number.isFinite(depth) && depth >= maxDepth;
 	return { blocked, depth, maxDepth };
 }
 
 export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
-	const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
+	const parentDepth = Number(process.env.SELESAI_SUBAGENT_DEPTH ?? "0");
 	const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
 	return {
-		PI_SUBAGENT_DEPTH: String(nextDepth),
-		PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
+		SELESAI_SUBAGENT_DEPTH: String(nextDepth),
+		SELESAI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
 	};
 }
 

package/dist/extensions/pi-subagents/src/shared/utils.ts

@@ -5,7 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import * as piCodingAgent from "@earendil-works/pi-coding-agent";
+import * as piCodingAgent from "@selesai/code";
 import type { Message } from "@earendil-works/pi-ai";
 import { formatToolCall } from "./formatters.ts";
 import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, SingleResult, ToolCallSummary } from "./types.ts";
@@ -14,7 +14,7 @@ import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, Singl
 // File System Utilities
 // ============================================================================
 
-const DEFAULT_CONFIG_DIR_NAME = ".pi";
+const DEFAULT_CONFIG_DIR_NAME = ".selesai";
 
 export function resolveConfigDirName(codingAgentModule: unknown = piCodingAgent): string {
 	const value = codingAgentModule && typeof codingAgentModule === "object"
@@ -32,7 +32,7 @@ export function getProjectConfigDir(projectRoot: string): string {
 }
 
 export function getAgentDir(): string {
-	const configured = process.env.PI_CODING_AGENT_DIR;
+	const configured = process.env.SELESAI_CODING_AGENT_DIR;
 	if (configured === "~") return os.homedir();
 	if (configured?.startsWith("~/")) return path.join(os.homedir(), configured.slice(2));
 	return configured || path.join(os.homedir(), getConfigDirName(), "agent");

package/dist/extensions/pi-subagents/src/slash/slash-bridge.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@selesai/code";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import {
 	SLASH_SUBAGENT_CANCEL_EVENT,

package/dist/extensions/pi-subagents/src/slash/slash-commands.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@selesai/code";
 import { Key, matchesKey } from "@earendil-works/pi-tui";
 import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, type ChainConfig } from "../agents/agents.ts";
 import {

package/dist/extensions/pi-subagents/src/tui/render-helpers.ts

@@ -1,4 +1,4 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@selesai/code";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 function fuzzyScore(query: string, text: string): number {

package/dist/extensions/pi-subagents/src/tui/render.ts

@@ -4,7 +4,7 @@
 
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { getMarkdownTheme, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme, type ExtensionContext } from "@selesai/code";
 import { Container, Markdown, Spacer, Text, visibleWidth, type Component } from "@earendil-works/pi-tui";
 import {
 	type AgentProgress,

package/dist/extensions/pi-subagents/test/unit/spawn-timing.test.ts

@@ -0,0 +1,45 @@
+import { describe, it } from "node:test";
+import * as assert from "node:assert";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createSpawnTimingMarkers, emitSpawnTiming } from "../../src/runs/shared/spawn-timing.ts";
+
+describe("spawn-timing", () => {
+	it("creates markers with a start time", () => {
+		const markers = createSpawnTimingMarkers();
+		assert.ok(markers.spawnStart > 0);
+	});
+
+	it("emits a timing line when an eventsPath is provided", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-timing-"));
+		const eventsPath = path.join(dir, "events.jsonl");
+		const markers = createSpawnTimingMarkers();
+		emitSpawnTiming({
+			eventsPath,
+			marker: "spawn_start",
+			markers,
+			runId: "run-1",
+			stepIndex: 2,
+			agent: "scout",
+		});
+		const lines = fs.readFileSync(eventsPath, "utf-8").trim().split("\n");
+		assert.equal(lines.length, 1);
+		const event = JSON.parse(lines[0]!);
+		assert.equal(event.type, "subagent.spawn.timing");
+		assert.equal(event.runId, "run-1");
+		assert.equal(event.stepIndex, 2);
+		assert.equal(event.agent, "scout");
+		assert.equal(event.marker, "spawn_start");
+		assert.ok(typeof event.elapsedMs === "number");
+		assert.ok(event.ts > 0);
+		fs.rmSync(dir, { recursive: true, force: true });
+	});
+
+	it("skips emission when eventsPath is missing", () => {
+		const markers = createSpawnTimingMarkers();
+		assert.doesNotThrow(() => {
+			emitSpawnTiming({ eventsPath: undefined, marker: "spawn_start", markers });
+		});
+	});
+});

package/dist/extensions/pi-subagents/tsconfig.runner.json

@@ -0,0 +1,17 @@
+{
+	"extends": "../../../tsconfig.base.json",
+	"compilerOptions": {
+		"outDir": "dist/runner",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"target": "ES2022",
+		"sourceMap": true,
+		"noCheck": true,
+		"noEmitOnError": false,
+		"declaration": false,
+		"declarationMap": false,
+		"inlineSources": false
+	},
+	"include": ["src/**/*"],
+	"exclude": ["test", "**/*.test.ts"]
+}

package/dist/extensions/pi-web-agent/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@selesai/bundled-pi-web-agent",
+	"version": "1.5.1",
+	"private": true,
+	"description": "Bundled pi-web-agent extension for reliable web access with explicit search, fetch, and headless boundaries. Vendored source-first from @demigodmode/pi-web-agent.",
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"extension",
+		"web-search",
+		"web-fetch"
+	],
+	"license": "AGPL-3.0-only",
+	"pi": {
+		"extensions": [
+			"./src/extension.ts"
+		]
+	},
+	"dependencies": {
+		"@mozilla/readability": "^0.6.0",
+		"cheerio": "^1.1.0",
+		"jsdom": "^26.0.0",
+		"playwright": "^1.60.0",
+		"typebox": "^1.1.37"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/dist/extensions/pi-web-agent/src/backends/config.ts

@@ -0,0 +1,205 @@
+export type SearxngOptions = {
+  categories?: string[];
+  language?: string;
+  safesearch?: 0 | 1 | 2;
+};
+
+export type FirecrawlOptions = {
+  formats?: string[];
+  onlyMainContent?: boolean;
+};
+
+export type SearchBackendConfig = {
+  provider: 'duckduckgo' | 'searxng' | 'brave';
+  baseUrl?: string;
+  fallback?: 'duckduckgo';
+  options?: SearxngOptions;
+};
+
+export type FetchBackendConfig = {
+  provider: 'http' | 'firecrawl';
+  baseUrl?: string;
+  apiKey?: string;
+  fallback?: 'http';
+  options?: FirecrawlOptions;
+};
+export type HeadlessBackendConfig = { provider: 'local-browser' };
+
+export type BackendConfig = {
+  search: SearchBackendConfig;
+  fetch: FetchBackendConfig;
+  headless: HeadlessBackendConfig;
+};
+
+export type BackendConfigOverride = {
+  search?: Partial<SearchBackendConfig>;
+  fetch?: Partial<FetchBackendConfig>;
+  headless?: Partial<HeadlessBackendConfig>;
+};
+
+export type BackendConfigFile = {
+  backends?: {
+    search?: { provider?: unknown; baseUrl?: unknown; fallback?: unknown; options?: unknown };
+    fetch?: { provider?: unknown; baseUrl?: unknown; apiKey?: unknown; fallback?: unknown; options?: unknown };
+    headless?: { provider?: unknown };
+  };
+};
+
+export const DEFAULT_BACKEND_CONFIG: BackendConfig = {
+  search: { provider: 'duckduckgo' },
+  fetch: { provider: 'http' },
+  headless: { provider: 'local-browser' }
+};
+
+function extractStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const strings = value.filter((item): item is string => typeof item === 'string');
+  return strings.length === value.length ? strings : undefined;
+}
+
+function extractSearxngOptions(value: unknown): SearxngOptions | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const raw = value as { categories?: unknown; language?: unknown; safesearch?: unknown };
+  const options: SearxngOptions = {};
+  const categories = extractStringArray(raw.categories);
+  if (categories) options.categories = categories;
+  if (typeof raw.language === 'string') options.language = raw.language;
+  if (raw.safesearch === 0 || raw.safesearch === 1 || raw.safesearch === 2) options.safesearch = raw.safesearch;
+  return Object.keys(options).length > 0 ? options : undefined;
+}
+
+function extractFirecrawlOptions(value: unknown): FirecrawlOptions | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const raw = value as { formats?: unknown; onlyMainContent?: unknown };
+  const options: FirecrawlOptions = {};
+  const formats = extractStringArray(raw.formats);
+  if (formats) options.formats = formats;
+  if (typeof raw.onlyMainContent === 'boolean') options.onlyMainContent = raw.onlyMainContent;
+  return Object.keys(options).length > 0 ? options : undefined;
+}
+
+export function extractBackendConfigOverride(
+  file: BackendConfigFile | null | undefined
+): BackendConfigOverride {
+  const backends = file?.backends;
+  const override: BackendConfigOverride = {};
+
+  if (
+    backends?.search?.provider === 'duckduckgo' ||
+    backends?.search?.provider === 'searxng' ||
+    backends?.search?.provider === 'brave'
+  ) {
+    override.search = { provider: backends.search.provider };
+    if (backends.search.provider === 'searxng' && typeof backends.search.baseUrl === 'string') {
+      override.search.baseUrl = backends.search.baseUrl;
+    }
+    if (backends.search.fallback === 'duckduckgo') {
+      override.search.fallback = 'duckduckgo';
+    }
+    if (backends.search.provider === 'searxng') {
+      const options = extractSearxngOptions(backends.search.options);
+      if (options) {
+        override.search.options = options;
+      }
+    }
+  }
+
+  if (backends?.fetch?.provider === 'http' || backends?.fetch?.provider === 'firecrawl') {
+    override.fetch = { provider: backends.fetch.provider };
+    if (typeof backends.fetch.baseUrl === 'string') {
+      override.fetch.baseUrl = backends.fetch.baseUrl;
+    }
+    if (typeof backends.fetch.apiKey === 'string') {
+      override.fetch.apiKey = backends.fetch.apiKey;
+    }
+    if (backends.fetch.fallback === 'http') {
+      override.fetch.fallback = 'http';
+    }
+    const options = extractFirecrawlOptions(backends.fetch.options);
+    if (options) {
+      override.fetch.options = options;
+    }
+  }
+
+  if (backends?.headless?.provider === 'local-browser') {
+    override.headless = { provider: 'local-browser' };
+  }
+
+  return override;
+}
+
+export function validateBackendConfig(config: BackendConfig): string[] {
+  const issues: string[] = [];
+
+  if (config.search.provider === 'searxng' && !config.search.baseUrl) {
+    issues.push('search provider searxng requires backends.search.baseUrl');
+  }
+
+  if (config.fetch.provider === 'firecrawl' && !config.fetch.baseUrl) {
+    issues.push('fetch provider firecrawl requires backends.fetch.baseUrl');
+  }
+
+  if (config.search.fallback === 'duckduckgo' && config.search.provider !== 'searxng' && config.search.provider !== 'brave') {
+    issues.push('search fallback duckduckgo is only supported when search provider is searxng or brave');
+  }
+
+  if (config.fetch.fallback === 'http' && config.fetch.provider !== 'firecrawl') {
+    issues.push('fetch fallback http is only supported when fetch provider is firecrawl');
+  }
+
+  if (config.search.options?.categories && config.search.options.categories.length === 0) {
+    issues.push('search options.categories must contain at least one category when provided');
+  }
+
+  if (config.search.options?.language !== undefined && !config.search.options.language.trim()) {
+    issues.push('search options.language must not be empty when provided');
+  }
+
+  if (
+    config.search.options?.safesearch !== undefined &&
+    ![0, 1, 2].includes(config.search.options.safesearch)
+  ) {
+    issues.push('search options.safesearch must be 0, 1, or 2 when provided');
+  }
+
+  if (config.fetch.options?.formats && config.fetch.options.formats.length === 0) {
+    issues.push('fetch options.formats must contain at least one format when provided');
+  }
+
+  return issues;
+}
+
+function mergeSearchConfig(
+  current: SearchBackendConfig,
+  override: Partial<SearchBackendConfig> | undefined
+): SearchBackendConfig {
+  if (!override) return current;
+  if (override.provider && override.provider !== current.provider) {
+    return { ...override, provider: override.provider };
+  }
+  return { ...current, ...override };
+}
+
+function mergeFetchConfig(
+  current: FetchBackendConfig,
+  override: Partial<FetchBackendConfig> | undefined
+): FetchBackendConfig {
+  if (!override) return current;
+  if (override.provider && override.provider !== current.provider) {
+    return { ...override, provider: override.provider };
+  }
+  return { ...current, ...override };
+}
+
+export function mergeBackendConfigLayers(
+  ...layers: Array<BackendConfig | BackendConfigOverride | undefined>
+): BackendConfig {
+  return layers.reduce<BackendConfig>(
+    (merged, layer) => ({
+      search: mergeSearchConfig(merged.search, layer?.search),
+      fetch: mergeFetchConfig(merged.fetch, layer?.fetch),
+      headless: { ...merged.headless, ...layer?.headless }
+    }),
+    DEFAULT_BACKEND_CONFIG
+  );
+}