agent-worker 0.13.0 → 0.15.0

package/dist/{backends-CziIqKRg.mjs → backends-C7pQwuAx.mjs}

@@ -1,8 +1,7 @@
 import { gateway, generateText } from "ai";
 import { execa } from "execa";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { stringify } from "yaml";
 
 //#region src/agent/models.ts
 const providerCache = {};
@@ -119,12 +118,21 @@ async function createModelWithProvider(modelName, provider) {
 *    Examples: anthropic:claude-sonnet-4-5, openai:gpt-5.2, deepseek:deepseek-chat
 */
 function createModel(modelId) {
-	if (modelId.includes("/")) return gateway(modelId);
+	if (modelId.includes("/")) {
+		if (process.env.AI_GATEWAY_API_KEY) return gateway(modelId);
+		const slashIndex = modelId.indexOf("/");
+		const provider = modelId.slice(0, slashIndex);
+		const modelName = modelId.slice(slashIndex + 1);
+		if (provider in providerCache && providerCache[provider]) return providerCache[provider](modelName);
+		throw new Error(`Provider '${provider}' not loaded. Call createModelAsync() first or set AI_GATEWAY_API_KEY for gateway access.`);
+	}
 	if (!modelId.includes(":")) {
 		const provider = modelId;
 		if (provider in FRONTIER_MODELS) {
 			const defaultModel = FRONTIER_MODELS[provider][0];
-			return gateway(`${provider}/${defaultModel}`);
+			if (process.env.AI_GATEWAY_API_KEY) return gateway(`${provider}/${defaultModel}`);
+			if (provider in providerCache && providerCache[provider]) return providerCache[provider](defaultModel);
+			throw new Error(`Provider '${provider}' not loaded. Call createModelAsync() first or set AI_GATEWAY_API_KEY for gateway access.`);
 		}
 		throw new Error(`Unknown provider: ${modelId}. Supported: ${Object.keys(FRONTIER_MODELS).join(", ")}`);
 	}
@@ -133,19 +141,24 @@ function createModel(modelId) {
 	const modelName = modelId.slice(colonIndex + 1);
 	if (!modelName) throw new Error(`Invalid model identifier: ${modelId}. Model name is required.`);
 	if (provider in providerCache && providerCache[provider]) return providerCache[provider](modelName);
-	throw new Error(`Provider '${provider}' not loaded. Use gateway format (${provider}/${modelName}) or call createModelAsync() for direct provider access.`);
+	throw new Error(`Provider '${provider}' not loaded. Call createModelAsync() first or set AI_GATEWAY_API_KEY for gateway access.`);
 }
 /**
 * Async version of createModel - supports lazy loading of direct providers
 * Use this when you need direct provider access (provider:model format)
 */
 async function createModelAsync(modelId) {
-	if (modelId.includes("/")) return gateway(modelId);
+	if (modelId.includes("/")) {
+		if (process.env.AI_GATEWAY_API_KEY) return gateway(modelId);
+		const slashIndex = modelId.indexOf("/");
+		return loadProviderModel(modelId.slice(0, slashIndex), modelId.slice(slashIndex + 1));
+	}
 	if (!modelId.includes(":")) {
 		const provider = modelId;
 		if (provider in FRONTIER_MODELS) {
 			const defaultModel = FRONTIER_MODELS[provider][0];
-			return gateway(`${provider}/${defaultModel}`);
+			if (process.env.AI_GATEWAY_API_KEY) return gateway(`${provider}/${defaultModel}`);
+			return loadProviderModel(provider, defaultModel);
 		}
 		throw new Error(`Unknown provider: ${modelId}. Supported: ${Object.keys(FRONTIER_MODELS).join(", ")}`);
 	}
@@ -153,6 +166,13 @@ async function createModelAsync(modelId) {
 	const provider = modelId.slice(0, colonIndex);
 	const modelName = modelId.slice(colonIndex + 1);
 	if (!modelName) throw new Error(`Invalid model identifier: ${modelId}. Model name is required.`);
+	return loadProviderModel(provider, modelName);
+}
+/**
+* Load a provider SDK and create a model instance.
+* Used as fallback when AI Gateway is not available.
+*/
+async function loadProviderModel(provider, modelName) {
 	const config = PROVIDER_PACKAGES[provider];
 	if (!config) throw new Error(`Unknown provider: ${provider}. Supported: ${Object.keys(PROVIDER_PACKAGES).join(", ")}. Or use gateway format: provider/model (e.g., openai/gpt-5.2)`);
 	const providerFn = await loadProvider(provider, config.package, config.export);
@@ -210,6 +230,165 @@ const FRONTIER_MODELS = {
 	],
 	xai: ["grok-4", "grok-4-fast-reasoning"]
 };
+/**
+* Environment variable that each provider uses for authentication.
+* Ordered by priority — first match wins during auto-discovery.
+*
+* Gateway is first because it supports all providers via a single key.
+*/
+const PROVIDER_ENV_KEYS = {
+	gateway: "AI_GATEWAY_API_KEY",
+	anthropic: "ANTHROPIC_API_KEY",
+	openai: "OPENAI_API_KEY",
+	deepseek: "DEEPSEEK_API_KEY",
+	google: "GOOGLE_GENERATIVE_AI_API_KEY",
+	groq: "GROQ_API_KEY",
+	mistral: "MISTRAL_API_KEY",
+	xai: "XAI_API_KEY"
+};
+/** Provider discovery priority order */
+const DISCOVERY_ORDER = [
+	"gateway",
+	"anthropic",
+	"openai",
+	"deepseek",
+	"google",
+	"groq",
+	"mistral",
+	"xai"
+];
+/**
+* Reverse map: model name → provider name.
+* Built from FRONTIER_MODELS so "deepseek-chat" → "deepseek", etc.
+*/
+const MODEL_TO_PROVIDER = {};
+for (const [provider, models] of Object.entries(FRONTIER_MODELS)) for (const model of models) {
+	const shortName = model.includes("/") ? model.split("/").pop() : model;
+	MODEL_TO_PROVIDER[model] = provider;
+	if (shortName !== model) MODEL_TO_PROVIDER[shortName] = provider;
+}
+/**
+* Discover the best available provider by scanning environment variables.
+*
+* Note: This function does NOT read AGENT_MODEL — that's handled by
+* resolveModelFallback() which supports comma-separated fallback chains.
+*
+* @param options.preferredModel - If set, prefer the provider that owns this model.
+*   E.g. "deepseek-chat" → prefer "deepseek" if DEEPSEEK_API_KEY is set.
+* @param options.env - Environment to scan (defaults to process.env).
+* @returns The discovered provider and model, or null if none available.
+*/
+function discoverProvider(options) {
+	const env = options?.env ?? process.env;
+	const preferredModel = options?.preferredModel;
+	if (preferredModel && preferredModel !== "auto") {
+		const ownerProvider = MODEL_TO_PROVIDER[preferredModel];
+		if (ownerProvider) {
+			const envKey = PROVIDER_ENV_KEYS[ownerProvider];
+			if (envKey && env[envKey]) return {
+				provider: ownerProvider,
+				model: preferredModel.includes("/") ? preferredModel : `${ownerProvider}/${preferredModel}`
+			};
+		}
+	}
+	for (const provider of DISCOVERY_ORDER) {
+		if (!env[PROVIDER_ENV_KEYS[provider]]) continue;
+		if (provider === "gateway") {
+			if (preferredModel && preferredModel !== "auto") return {
+				provider: "gateway",
+				model: `${MODEL_TO_PROVIDER[preferredModel] || "anthropic"}/${preferredModel}`
+			};
+			return {
+				provider: "gateway",
+				model: getDefaultModel()
+			};
+		}
+		const defaultModel = FRONTIER_MODELS[provider]?.[0];
+		return {
+			provider,
+			model: defaultModel ? defaultModel.includes("/") ? defaultModel : `${provider}/${defaultModel}` : provider
+		};
+	}
+	return null;
+}
+/**
+* Check if a value is the "auto" sentinel.
+*/
+function isAutoProvider(value) {
+	return value === "auto";
+}
+/**
+* Check if a model's provider has a valid API key in the environment.
+*/
+function isModelAvailable(model, env) {
+	if (model === "auto") return true;
+	let provider;
+	provider = MODEL_TO_PROVIDER[model];
+	if (!provider && model.includes("/")) provider = model.split("/")[0];
+	if (!provider && model.includes(":")) provider = model.split(":")[0];
+	if (!provider) return false;
+	if (env[PROVIDER_ENV_KEYS["gateway"]]) return true;
+	const envKey = PROVIDER_ENV_KEYS[provider];
+	return !!envKey && !!env[envKey];
+}
+/**
+* Resolve a model to a single concrete value, supporting fallback chains.
+*
+* Resolution order:
+*   1. AGENT_DEFAULT_MODELS env var — comma-separated preference list
+*      (e.g. "deepseek-chat, anthropic/claude-sonnet-4-5")
+*   2. Workflow YAML model field (single string, or "auto")
+*   3. Full auto-discovery — scan all provider API keys
+*
+* The preference list does NOT contain "auto" — the env var itself IS
+* the auto configuration. After exhausting the explicit list, the system
+* implicitly falls back to full provider discovery.
+*
+* Example:
+*   AGENT_DEFAULT_MODELS="deepseek-chat, anthropic/claude-sonnet-4-5"
+*   → try deepseek-chat (need DEEPSEEK_API_KEY)
+*   → try claude-sonnet-4-5 (need ANTHROPIC_API_KEY)
+*   → implicit fallback: discover any available provider
+*
+* @returns Resolved { model, provider } — never contains "auto".
+* @throws if nothing is available (no explicit candidate and no provider key).
+*/
+function resolveModelFallback(config) {
+	const env = config.env ?? process.env;
+	const isProviderAuto = config.provider === "auto";
+	const autoModel = env.AGENT_DEFAULT_MODELS;
+	if (!isProviderAuto && config.model && config.model !== "auto" && !autoModel) return {
+		model: config.model,
+		provider: config.provider
+	};
+	const preferences = autoModel ? autoModel.split(",").map((s) => s.trim()).filter(Boolean) : [];
+	for (const candidate of preferences) if (isModelAvailable(candidate, env)) return {
+		model: candidate,
+		provider: isProviderAuto ? void 0 : config.provider
+	};
+	if (isProviderAuto && config.model && config.model !== "auto") {
+		const model = config.model;
+		if (isModelAvailable(model, env)) {
+			const ownerProvider = MODEL_TO_PROVIDER[model];
+			if (ownerProvider && !model.includes("/") && !model.includes(":")) return {
+				model: `${ownerProvider}/${model}`,
+				provider: void 0
+			};
+			return {
+				model,
+				provider: void 0
+			};
+		}
+	}
+	const discovered = discoverProvider({ env });
+	if (discovered) return {
+		model: discovered.model,
+		provider: void 0
+	};
+	const envVars = Object.values(PROVIDER_ENV_KEYS).join(", ");
+	const hint = preferences.length > 0 ? `Tried: ${preferences.join(", ")}. ` : "";
+	throw new Error(`No provider available for auto model resolution. ${hint}Set one of: ${envVars}`);
+}
 
 //#endregion
 //#region src/backends/model-maps.ts
@@ -354,68 +533,24 @@ const DEFAULT_IDLE_TIMEOUT = 6e5;
 * producing output (tool calls, analysis, etc.).
 */
 /**
-* Execute a command with idle timeout.
-*
-* The timeout resets every time the process writes to stdout or stderr.
-* If the process goes silent for longer than `timeout` ms, it's killed.
+* Default startup timeout (30 seconds).
+* If the process produces zero output within this window, it's killed.
+* This catches unresponsive backends (e.g., nested `claude -p` inside Claude Code).
 */
+const DEFAULT_STARTUP_TIMEOUT = 3e4;
 /** Minimum idle timeout to prevent accidental instant kills */
 const MIN_TIMEOUT_MS = 1e3;
-async function execWithIdleTimeout(options) {
-	const { command, args, cwd, onStdout } = options;
-	const timeout = Math.max(options.timeout, MIN_TIMEOUT_MS);
-	let idleTimedOut = false;
-	let timer;
-	let stdout = "";
-	let stderr = "";
-	const subprocess = execa(command, args, {
-		cwd,
-		stdin: "ignore",
-		buffer: false
-	});
-	const resetTimer = () => {
-		clearTimeout(timer);
-		timer = setTimeout(() => {
-			idleTimedOut = true;
-			subprocess.kill();
-		}, timeout);
-	};
-	subprocess.stdout?.on("data", (chunk) => {
-		const text = chunk.toString();
-		stdout += text;
-		resetTimer();
-		if (onStdout) try {
-			onStdout(text);
-		} catch (err) {
-			console.error("onStdout callback error:", err);
-		}
-	});
-	subprocess.stderr?.on("data", (chunk) => {
-		stderr += chunk.toString();
-		resetTimer();
-	});
-	resetTimer();
-	try {
-		await subprocess;
-		clearTimeout(timer);
-		return {
-			stdout: stdout.trimEnd(),
-			stderr: stderr.trimEnd()
-		};
-	} catch (error) {
-		clearTimeout(timer);
-		if (idleTimedOut) throw new IdleTimeoutError(timeout, stdout, stderr);
-		throw error;
-	}
-}
 /**
-* Execute a command with idle timeout and return abort controller
-* This version returns both the promise and an abort function for external control
+* Core implementation shared by both sync and abortable variants.
+* Returns the promise, an abort function, and the subprocess handle.
 */
-function execWithIdleTimeoutAbortable(options) {
+function execWithIdleTimeoutInternal(options) {
 	const { command, args, cwd, onStdout } = options;
 	const timeout = Math.max(options.timeout, MIN_TIMEOUT_MS);
+	const rawStartup = options.startupTimeout !== void 0 ? options.startupTimeout : DEFAULT_STARTUP_TIMEOUT;
+	const startupTimeout = rawStartup > 0 ? Math.min(rawStartup, timeout) : 0;
 	let idleTimedOut = false;
+	let hasReceivedOutput = false;
 	let timer;
 	let stdout = "";
 	let stderr = "";
@@ -435,6 +570,7 @@ function execWithIdleTimeoutAbortable(options) {
 	subprocess.stdout?.on("data", (chunk) => {
 		const text = chunk.toString();
 		stdout += text;
+		hasReceivedOutput = true;
 		resetTimer();
 		if (onStdout) try {
 			onStdout(text);
@@ -444,9 +580,16 @@ function execWithIdleTimeoutAbortable(options) {
 	});
 	subprocess.stderr?.on("data", (chunk) => {
 		stderr += chunk.toString();
+		hasReceivedOutput = true;
 		resetTimer();
 	});
-	resetTimer();
+	if (startupTimeout > 0) timer = setTimeout(() => {
+		if (!hasReceivedOutput) {
+			idleTimedOut = true;
+			subprocess.kill();
+		}
+	}, startupTimeout);
+	else resetTimer();
 	const abort = () => {
 		if (!isAborted) {
 			isAborted = true;
@@ -469,7 +612,7 @@ function execWithIdleTimeoutAbortable(options) {
 			} catch (error) {
 				clearTimeout(timer);
 				if (isAborted) throw new Error("Process aborted by user");
-				if (idleTimedOut) throw new IdleTimeoutError(timeout, stdout, stderr);
+				if (idleTimedOut) throw new IdleTimeoutError(hasReceivedOutput ? timeout : startupTimeout, stdout, stderr);
 				throw error;
 			}
 		})(),
@@ -477,6 +620,23 @@ function execWithIdleTimeoutAbortable(options) {
 	};
 }
 /**
+* Execute a command with idle timeout.
+*
+* The timeout resets every time the process writes to stdout or stderr.
+* If the process goes silent for longer than `timeout` ms, it's killed.
+*/
+async function execWithIdleTimeout(options) {
+	const { promise } = execWithIdleTimeoutInternal(options);
+	return promise;
+}
+/**
+* Execute a command with idle timeout and return abort handle.
+* This version returns both the promise and an abort function for external control.
+*/
+function execWithIdleTimeoutAbortable(options) {
+	return execWithIdleTimeoutInternal(options);
+}
+/**
 * Error thrown when a process is killed due to idle timeout
 */
 var IdleTimeoutError = class extends Error {
@@ -492,6 +652,45 @@ var IdleTimeoutError = class extends Error {
 	}
 };
 
+//#endregion
+//#region src/backends/cli-helpers.ts
+/**
+* Shared helpers for CLI backends
+*
+* Eliminates duplicated error handling and availability check patterns
+* across claude-code, codex, cursor, and opencode backends.
+*/
+/**
+* Handle errors from CLI backend execution.
+*
+* Standardizes the error handling pattern shared by all CLI backends:
+* 1. IdleTimeoutError → human-readable timeout message
+* 2. Process exit error → include exit code and stderr
+* 3. Everything else → re-throw
+*/
+function handleCliBackendError(error, backendName, timeout) {
+	if (error instanceof IdleTimeoutError) throw new Error(`${backendName} timed out after ${timeout}ms of inactivity`);
+	if (error && typeof error === "object" && "exitCode" in error) {
+		const execError = error;
+		throw new Error(`${backendName} failed (exit ${execError.exitCode}): ${execError.stderr || execError.shortMessage}`);
+	}
+	throw error;
+}
+/**
+* Check if a CLI command is available by running `command --version`.
+*/
+async function checkCliAvailable(command, args = ["--version"], timeout = 5e3) {
+	try {
+		await execa(command, args, {
+			stdin: "ignore",
+			timeout
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 //#endregion
 //#region src/backends/stream-json.ts
 /**
@@ -758,7 +957,8 @@ function formatToolInput(input) {
 *
 * MCP Configuration:
 * Claude supports per-invocation MCP config via --mcp-config flag.
-* Use setWorkspace() for workspace isolation, or setMcpConfigPath() directly.
+* The loop writes mcp-config.json to the workspace; this backend
+* auto-discovers it when workspace is set.
 *
 * @see https://docs.anthropic.com/en/docs/claude-code
 */
@@ -772,17 +972,6 @@ var ClaudeCodeBackend = class {
 			...options
 		};
 	}
-	/**
-	* Set up workspace directory with MCP config
-	* Claude uses --mcp-config flag, so we just write the config file
-	*/
-	setWorkspace(workspaceDir, mcpConfig) {
-		this.options.workspace = workspaceDir;
-		if (!existsSync(workspaceDir)) mkdirSync(workspaceDir, { recursive: true });
-		const mcpConfigPath = join(workspaceDir, "mcp-config.json");
-		writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
-		this.options.mcpConfigPath = mcpConfigPath;
-	}
 	async send(message, options) {
 		const args = this.buildArgs(message, options);
 		const cwd = this.options.workspace || this.options.cwd;
@@ -813,7 +1002,10 @@ var ClaudeCodeBackend = class {
 			return { content: stdout.trim() };
 		} catch (error) {
 			this.currentAbort = void 0;
-			if (error instanceof IdleTimeoutError) throw new Error(`claude timed out after ${timeout}ms of inactivity`);
+			if (error instanceof IdleTimeoutError) {
+				if (error.stdout === "" && error.stderr === "") throw new Error(`claude produced no output within ${error.timeout}ms. This often happens when running nested 'claude -p' inside an existing Claude Code session. Consider using the SDK backend (model: "anthropic/claude-sonnet-4-5") instead.`);
+				throw new Error(`claude timed out after ${timeout}ms of inactivity`);
+			}
 			if (error && typeof error === "object" && "exitCode" in error) {
 				const execError = error;
 				throw new Error(`claude failed (exit ${execError.exitCode}): ${execError.stderr || execError.shortMessage}`);
@@ -822,15 +1014,7 @@ var ClaudeCodeBackend = class {
 		}
 	}
 	async isAvailable() {
-		try {
-			await execa("claude", ["--version"], {
-				stdin: "ignore",
-				timeout: 5e3
-			});
-			return true;
-		} catch {
-			return false;
-		}
+		return checkCliAvailable("claude");
 	}
 	getInfo() {
 		return {
@@ -855,16 +1039,14 @@ var ClaudeCodeBackend = class {
 		if (outputFormat === "stream-json") args.push("--verbose");
 		if (this.options.continue) args.push("--continue");
 		if (this.options.resume) args.push("--resume", this.options.resume);
-		if (this.options.mcpConfigPath) args.push("--mcp-config", this.options.mcpConfigPath);
+		const mcpConfigPath = this.options.mcpConfigPath ?? (this.options.workspace ? (() => {
+			const p = join(this.options.workspace, "mcp-config.json");
+			return existsSync(p) ? p : void 0;
+		})() : void 0);
+		if (mcpConfigPath) args.push("--mcp-config", mcpConfigPath);
 		return args;
 	}
 	/**
-	* Set MCP config path (for workflow integration)
-	*/
-	setMcpConfigPath(path) {
-		this.options.mcpConfigPath = path;
-	}
-	/**
 	* Abort any running claude process
 	*/
 	abort() {
@@ -877,16 +1059,6 @@ var ClaudeCodeBackend = class {
 
 //#endregion
 //#region src/backends/codex.ts
-/**
-* OpenAI Codex CLI backend
-* Uses `codex exec` for non-interactive mode with JSON event output
-*
-* MCP Configuration:
-* Codex uses project-level MCP config. Use setWorkspace() to set up
-* a dedicated workspace directory with .codex/config.yaml for MCP settings.
-*
-* @see https://github.com/openai/codex
-*/
 var CodexBackend = class {
 	type = "codex";
 	options;
@@ -896,17 +1068,6 @@ var CodexBackend = class {
 			...options
 		};
 	}
-	/**
-	* Set up workspace directory with MCP config
-	* Creates .codex/config.yaml in the workspace with MCP server config
-	*/
-	setWorkspace(workspaceDir, mcpConfig) {
-		this.options.workspace = workspaceDir;
-		const codexDir = join(workspaceDir, ".codex");
-		if (!existsSync(codexDir)) mkdirSync(codexDir, { recursive: true });
-		const codexConfig = { mcp_servers: mcpConfig.mcpServers };
-		writeFileSync(join(codexDir, "config.yaml"), stringify(codexConfig));
-	}
 	async send(message, _options) {
 		const args = this.buildArgs(message);
 		const cwd = this.options.workspace || this.options.cwd;
@@ -921,24 +1082,11 @@ var CodexBackend = class {
 			});
 			return extractCodexResult(stdout);
 		} catch (error) {
-			if (error instanceof IdleTimeoutError) throw new Error(`codex timed out after ${timeout}ms of inactivity`);
-			if (error && typeof error === "object" && "exitCode" in error) {
-				const execError = error;
-				throw new Error(`codex failed (exit ${execError.exitCode}): ${execError.stderr || execError.shortMessage}`);
-			}
-			throw error;
+			handleCliBackendError(error, "codex", timeout);
 		}
 	}
 	async isAvailable() {
-		try {
-			await execa("codex", ["--version"], {
-				stdin: "ignore",
-				timeout: 5e3
-			});
-			return true;
-		} catch {
-			return false;
-		}
+		return checkCliAvailable("codex");
 	}
 	getInfo() {
 		return {
@@ -962,37 +1110,22 @@ var CodexBackend = class {
 
 //#endregion
 //#region src/backends/cursor.ts
-/**
-* Cursor CLI backend
-* Uses `cursor agent -p` for non-interactive mode with stream-json output
-*
-* MCP Configuration:
-* Cursor uses project-level MCP config via .cursor/mcp.json in the workspace.
-* Use setWorkspace() to set up a dedicated workspace with MCP config.
-*
-* @see https://docs.cursor.com/context/model-context-protocol
-*/
 var CursorBackend = class {
 	type = "cursor";
 	options;
-	/** Resolved command: "cursor" (subcommand style) */
-	resolvedCommand = null;
+	/**
+	* Resolved command style:
+	* - "subcommand": `cursor agent -p ...` (IDE-bundled CLI)
+	* - "direct": `agent -p ...` (standalone install via cursor.com/install)
+	* - null: not yet resolved
+	*/
+	resolvedStyle = null;
 	constructor(options = {}) {
 		this.options = {
 			timeout: DEFAULT_IDLE_TIMEOUT,
 			...options
 		};
 	}
-	/**
-	* Set up workspace directory with MCP config
-	* Creates .cursor/mcp.json in the workspace
-	*/
-	setWorkspace(workspaceDir, mcpConfig) {
-		this.options.workspace = workspaceDir;
-		const cursorDir = join(workspaceDir, ".cursor");
-		if (!existsSync(cursorDir)) mkdirSync(cursorDir, { recursive: true });
-		writeFileSync(join(cursorDir, "mcp.json"), JSON.stringify(mcpConfig, null, 2));
-	}
 	async send(message, _options) {
 		const { command, args } = await this.buildCommand(message);
 		const cwd = this.options.workspace || this.options.cwd;
@@ -1007,16 +1140,11 @@ var CursorBackend = class {
 			});
 			return extractClaudeResult(stdout);
 		} catch (error) {
-			if (error instanceof IdleTimeoutError) throw new Error(`cursor agent timed out after ${timeout}ms of inactivity`);
-			if (error && typeof error === "object" && "exitCode" in error) {
-				const execError = error;
-				throw new Error(`cursor agent failed (exit ${execError.exitCode}): ${execError.stderr || execError.shortMessage}`);
-			}
-			throw error;
+			handleCliBackendError(error, "cursor agent", timeout);
 		}
 	}
 	async isAvailable() {
-		return await this.resolveCommand() !== null;
+		return await this.resolveStyle() !== null;
 	}
 	getInfo() {
 		return {
@@ -1025,24 +1153,26 @@ var CursorBackend = class {
 		};
 	}
 	/**
-	* Resolve which cursor command is available.
-	* Checks `cursor agent --version` (subcommand style).
+	* Resolve which cursor command style is available.
+	* Tries in order:
+	*   1. `cursor agent --version` — IDE-bundled CLI (subcommand style)
+	*   2. `agent --version` — standalone install via cursor.com/install (direct style)
 	* Result is cached after first resolution.
 	*/
-	async resolveCommand() {
-		if (this.resolvedCommand !== null) return this.resolvedCommand;
-		try {
-			await execa("cursor", ["agent", "--version"], {
-				stdin: "ignore",
-				timeout: 2e3
-			});
-			this.resolvedCommand = "cursor";
-			return "cursor";
-		} catch {}
+	async resolveStyle() {
+		if (this.resolvedStyle !== null) return this.resolvedStyle;
+		if (await checkCliAvailable("cursor", ["agent", "--version"], 2e3)) {
+			this.resolvedStyle = "subcommand";
+			return "subcommand";
+		}
+		if (await checkCliAvailable("agent", ["--version"], 2e3)) {
+			this.resolvedStyle = "direct";
+			return "direct";
+		}
 		return null;
 	}
 	async buildCommand(message) {
-		const cmd = await this.resolveCommand();
+		const style = await this.resolveStyle();
 		const agentArgs = [
 			"-p",
 			"--force",
@@ -1051,7 +1181,11 @@ var CursorBackend = class {
 			message
 		];
 		if (this.options.model) agentArgs.push("--model", this.options.model);
-		if (!cmd) throw new Error("cursor agent CLI not found");
+		if (!style) throw new Error("cursor agent CLI not found. Install via: curl -fsS https://cursor.com/install | bash");
+		if (style === "direct") return {
+			command: "agent",
+			args: agentArgs
+		};
 		return {
 			command: "cursor",
 			args: ["agent", ...agentArgs]
@@ -1061,16 +1195,6 @@ var CursorBackend = class {
 
 //#endregion
 //#region src/backends/opencode.ts
-/**
-* OpenCode CLI backend
-* Uses `opencode run` for non-interactive mode with JSON event output
-*
-* MCP Configuration:
-* OpenCode uses project-level MCP config via opencode.json in the workspace.
-* Use setWorkspace() to set up a dedicated workspace with MCP config.
-*
-* @see https://opencode.ai/docs/
-*/
 var OpenCodeBackend = class {
 	type = "opencode";
 	options;
@@ -1080,29 +1204,6 @@ var OpenCodeBackend = class {
 			...options
 		};
 	}
-	/**
-	* Set up workspace directory with MCP config
-	* Creates opencode.json in the workspace with MCP server config
-	*/
-	setWorkspace(workspaceDir, mcpConfig) {
-		this.options.workspace = workspaceDir;
-		if (!existsSync(workspaceDir)) mkdirSync(workspaceDir, { recursive: true });
-		const opencodeMcp = {};
-		for (const [name, config] of Object.entries(mcpConfig.mcpServers)) {
-			const serverConfig = config;
-			opencodeMcp[name] = {
-				type: "local",
-				command: [serverConfig.command, ...serverConfig.args || []],
-				enabled: true,
-				...serverConfig.env ? { environment: serverConfig.env } : {}
-			};
-		}
-		const opencodeConfig = {
-			$schema: "https://opencode.ai/config.json",
-			mcp: opencodeMcp
-		};
-		writeFileSync(join(workspaceDir, "opencode.json"), JSON.stringify(opencodeConfig, null, 2));
-	}
 	async send(message, _options) {
 		const args = this.buildArgs(message);
 		const cwd = this.options.workspace || this.options.cwd;
@@ -1117,24 +1218,11 @@ var OpenCodeBackend = class {
 			});
 			return extractOpenCodeResult(stdout);
 		} catch (error) {
-			if (error instanceof IdleTimeoutError) throw new Error(`opencode timed out after ${timeout}ms of inactivity`);
-			if (error && typeof error === "object" && "exitCode" in error) {
-				const execError = error;
-				throw new Error(`opencode failed (exit ${execError.exitCode}): ${execError.stderr || execError.shortMessage}`);
-			}
-			throw error;
+			handleCliBackendError(error, "opencode", timeout);
 		}
 	}
 	async isAvailable() {
-		try {
-			await execa("opencode", ["--version"], {
-				stdin: "ignore",
-				timeout: 5e3
-			});
-			return true;
-		} catch {
-			return false;
-		}
+		return checkCliAvailable("opencode");
 	}
 	getInfo() {
 		return {
@@ -1266,8 +1354,8 @@ var SdkBackend = class {
 * Mock AI Backend for testing
 *
 * In single-agent mode, provides a simple echo send().
-* In workflow mode, the controller handles MCP tool orchestration
-* via the mock runner strategy (controller/mock-runner.ts).
+* In workflow mode, the loop handles MCP tool orchestration
+* via the mock runner strategy (loop/mock-runner.ts).
 */
 var MockAIBackend = class {
 	type = "mock";
@@ -1393,4 +1481,4 @@ async function listBackends() {
 }
 
 //#endregion
-export { parseModel as A, CLAUDE_MODEL_MAP as C, SDK_MODEL_ALIASES as D, OPENCODE_MODEL_MAP as E, createModelWithProvider as F, getDefaultModel as I, SUPPORTED_PROVIDERS as M, createModel as N, getModelForBackend as O, createModelAsync as P, BACKEND_DEFAULT_MODELS as S, CURSOR_MODEL_MAP as T, extractCodexResult as _, createMockBackend as a, execWithIdleTimeout as b, extractOpenCodeResult as c, CodexBackend as d, ClaudeCodeBackend as f, extractClaudeResult as g, createStreamParser as h, MockAIBackend as i, FRONTIER_MODELS as j, normalizeBackendType as k, opencodeAdapter as l, codexAdapter as m, createBackend as n, SdkBackend as o, claudeAdapter as p, listBackends as r, OpenCodeBackend as s, checkBackends as t, CursorBackend as u, formatEvent as v, CODEX_MODEL_MAP as w, DEFAULT_IDLE_TIMEOUT as x, IdleTimeoutError as y };
+export { parseModel as A, CLAUDE_MODEL_MAP as C, SDK_MODEL_ALIASES as D, OPENCODE_MODEL_MAP as E, createModelWithProvider as F, getDefaultModel as I, isAutoProvider as L, SUPPORTED_PROVIDERS as M, createModel as N, getModelForBackend as O, createModelAsync as P, resolveModelFallback as R, BACKEND_DEFAULT_MODELS as S, CURSOR_MODEL_MAP as T, extractCodexResult as _, createMockBackend as a, execWithIdleTimeout as b, extractOpenCodeResult as c, CodexBackend as d, ClaudeCodeBackend as f, extractClaudeResult as g, createStreamParser as h, MockAIBackend as i, FRONTIER_MODELS as j, normalizeBackendType as k, opencodeAdapter as l, codexAdapter as m, createBackend as n, SdkBackend as o, claudeAdapter as p, listBackends as r, OpenCodeBackend as s, checkBackends as t, CursorBackend as u, formatEvent as v, CODEX_MODEL_MAP as w, DEFAULT_IDLE_TIMEOUT as x, IdleTimeoutError as y };