remoteclaw 0.1.0-next.2abd2fa → 0.1.0-next.2e9a6cd

package/dist/extensionAPI.js

@@ -13,16 +13,13 @@ import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import AjvPkg from "ajv";
 import { z } from "zod";
+import { lookup } from "node:dns";
+import { lookup as lookup$1 } from "node:dns/promises";
+import { Agent } from "undici";
+import ipaddr from "ipaddr.js";
+import { fileTypeFromBuffer } from "file-type";
 import { createInterface } from "node:readline";
 
-//#region src/config/model-input.ts
-function resolveAgentModelPrimaryValue(model) {
-	if (typeof model === "string") return model.trim() || void 0;
-	if (!model || typeof model !== "object") return;
-	return model.primary?.trim() || void 0;
-}
-
-//#endregion
 //#region src/infra/home-dir.ts
 function normalize(value) {
 	const trimmed = value?.trim();
@@ -542,8 +539,8 @@ function pruneOldRollingLogs(dir) {
 
 //#endregion
 //#region src/terminal/palette.ts
-const LOBSTER_PALETTE = {
-	accent: "#FF5A2D",
+const PALETTE = {
+	accent: "#FF5A36",
 	accentBright: "#FF7A3D",
 	accentDim: "#D14A22",
 	info: "#FF8A5B",
@@ -559,17 +556,17 @@ const hasForceColor = typeof process.env.FORCE_COLOR === "string" && process.env
 const baseChalk = process.env.NO_COLOR && !hasForceColor ? new Chalk({ level: 0 }) : chalk;
 const hex = (value) => baseChalk.hex(value);
 const theme = {
-	accent: hex(LOBSTER_PALETTE.accent),
-	accentBright: hex(LOBSTER_PALETTE.accentBright),
-	accentDim: hex(LOBSTER_PALETTE.accentDim),
-	info: hex(LOBSTER_PALETTE.info),
-	success: hex(LOBSTER_PALETTE.success),
-	warn: hex(LOBSTER_PALETTE.warn),
-	error: hex(LOBSTER_PALETTE.error),
-	muted: hex(LOBSTER_PALETTE.muted),
-	heading: baseChalk.bold.hex(LOBSTER_PALETTE.accent),
-	command: hex(LOBSTER_PALETTE.accentBright),
-	option: hex(LOBSTER_PALETTE.warn)
+	accent: hex(PALETTE.accent),
+	accentBright: hex(PALETTE.accentBright),
+	accentDim: hex(PALETTE.accentDim),
+	info: hex(PALETTE.info),
+	success: hex(PALETTE.success),
+	warn: hex(PALETTE.warn),
+	error: hex(PALETTE.error),
+	muted: hex(PALETTE.muted),
+	heading: baseChalk.bold.hex(PALETTE.accent),
+	command: hex(PALETTE.accentBright),
+	option: hex(PALETTE.warn)
 };
 
 //#endregion
@@ -578,6 +575,10 @@ let globalVerbose = false;
 function isVerbose() {
 	return globalVerbose;
 }
+function logVerboseConsole(message) {
+	if (!globalVerbose) return;
+	console.log(theme.muted(message));
+}
 const success = theme.success;
 const warn = theme.warn;
 const info = theme.info;
@@ -1087,7 +1088,8 @@ function resolveAgentConfig(cfg, agentId) {
 		groupChat: entry.groupChat,
 		subagents: typeof entry.subagents === "object" && entry.subagents ? entry.subagents : void 0,
 		sandbox: entry.sandbox,
-		tools: entry.tools
+		tools: entry.tools,
+		auth: entry.auth
 	};
 }
 function resolveAgentWorkspaceDir(cfg, agentId) {
@@ -1096,6 +1098,11 @@ function resolveAgentWorkspaceDir(cfg, agentId) {
 	if (configured) return stripNullBytes(resolveUserPath(configured));
 	throw new Error(`agent '${id}' has no workspace configured — set agents.list[].workspace in remoteclaw.json`);
 }
+function resolveAgentWorkspaceDirOrNull(cfg, agentId) {
+	const configured = resolveAgentConfig(cfg, normalizeAgentId(agentId))?.workspace?.trim();
+	if (configured) return stripNullBytes(resolveUserPath(configured));
+	return null;
+}
 function resolveAgentDir(cfg, agentId) {
 	const id = normalizeAgentId(agentId);
 	const configured = resolveAgentConfig(cfg, id)?.agentDir?.trim();
@@ -1104,11 +1111,6 @@ function resolveAgentDir(cfg, agentId) {
 	return path.join(root, "agents", id, "agent");
 }
 
-//#endregion
-//#region src/agents/defaults.ts
-const DEFAULT_PROVIDER = "anthropic";
-const DEFAULT_MODEL = "claude-opus-4-6";
-
 //#endregion
 //#region src/agents/identity.ts
 function resolveAgentIdentity(cfg, agentId) {
@@ -2168,7 +2170,9 @@ function applyContextPruningDefaults(cfg) {
 			};
 			modelsMutated = true;
 		}
-		const primary = resolvePrimaryModelRef(resolveAgentModelPrimaryValue(defaults.model) ?? void 0);
+		const rawModel = defaults.model;
+		const rawPrimary = typeof rawModel === "string" ? rawModel : rawModel?.primary;
+		const primary = resolvePrimaryModelRef(typeof rawPrimary === "string" ? rawPrimary : void 0);
 		if (primary) {
 			const parsedPrimary = parseModelRef(primary, "anthropic");
 			if (isAnthropicCacheRetentionTarget(parsedPrimary)) {
@@ -2201,25 +2205,6 @@ function applyContextPruningDefaults(cfg) {
 		}
 	};
 }
-function applyCompactionDefaults(cfg) {
-	const defaults = cfg.agents?.defaults;
-	if (!defaults) return cfg;
-	const compaction = defaults?.compaction;
-	if (compaction?.mode) return cfg;
-	return {
-		...cfg,
-		agents: {
-			...cfg.agents,
-			defaults: {
-				...defaults,
-				compaction: {
-					...compaction,
-					mode: "safeguard"
-				}
-			}
-		}
-	};
-}
 
 //#endregion
 //#region src/config/env-preserve.ts
@@ -4657,13 +4642,6 @@ function parseDurationMs(raw, opts) {
 	return ms;
 }
 
-//#endregion
-//#region src/config/zod-schema.agent-model.ts
-const AgentModelSchema = z.union([z.string(), z.object({
-	primary: z.string().optional(),
-	fallbacks: z.array(z.string()).optional()
-}).strict()]);
-
 //#endregion
 //#region src/config/zod-schema.allowdeny.ts
 const AllowDenyActionSchema = z.union([z.literal("allow"), z.literal("deny")]);
@@ -5037,6 +5015,12 @@ const ProviderCommandsSchema = z.object({ native: NativeCommandsSettingSchema.op
 
 //#endregion
 //#region src/config/zod-schema.agent-runtime.ts
+/** Auth profile ref: `false` (skip), single string, or string array (rotation). */
+const AuthFieldSchema = z.union([
+	z.literal(false),
+	z.string(),
+	z.array(z.string())
+]).optional();
 const BootSchema = z.object({
 	prompt: z.string().optional(),
 	file: z.string().optional()
@@ -5050,7 +5034,6 @@ const HeartbeatSchema = z.object({
 	}).strict().optional(),
 	model: z.string().optional(),
 	session: z.string().optional(),
-	includeReasoning: z.boolean().optional(),
 	target: z.string().optional(),
 	to: z.string().optional(),
 	accountId: z.string().optional(),
@@ -5195,7 +5178,7 @@ const AgentEntrySchema = z.object({
 	name: z.string().optional(),
 	workspace: z.string().optional(),
 	agentDir: z.string().optional(),
-	model: AgentModelSchema.optional(),
+	model: z.unknown().optional(),
 	skills: z.array(z.string()).optional(),
 	humanDelay: HumanDelaySchema.optional(),
 	heartbeat: HeartbeatSchema,
@@ -5204,14 +5187,11 @@ const AgentEntrySchema = z.object({
 	groupChat: GroupChatSchema,
 	subagents: z.object({
 		allowAgents: z.array(z.string()).optional(),
-		model: z.union([z.string(), z.object({
-			primary: z.string().optional(),
-			fallbacks: z.array(z.string()).optional()
-		}).strict()]).optional(),
-		thinking: z.string().optional()
+		model: z.unknown().optional()
 	}).strict().optional(),
 	editableFiles: z.array(z.string()).optional(),
-	tools: AgentToolsSchema
+	tools: AgentToolsSchema,
+	auth: AuthFieldSchema
 }).strict();
 const ToolsSchema = z.object({
 	...CommonToolPolicyFields,
@@ -5254,13 +5234,10 @@ const ToolsSchema = z.object({
 //#endregion
 //#region src/config/zod-schema.agent-defaults.ts
 const AgentDefaultsSchema = z.object({
-	model: AgentModelSchema.optional(),
-	imageModel: AgentModelSchema.optional(),
-	models: z.record(z.string(), z.object({
-		alias: z.string().optional(),
-		params: z.record(z.string(), z.unknown()).optional(),
-		streaming: z.boolean().optional()
-	}).strict()).optional(),
+	model: z.unknown().optional(),
+	imageModel: z.unknown().optional(),
+	models: z.unknown().optional(),
+	workspace: z.string().optional(),
 	repoRoot: z.string().optional(),
 	skipBootstrap: z.boolean().optional(),
 	bootstrapMaxChars: z.number().int().positive().optional(),
@@ -5275,7 +5252,7 @@ const AgentDefaultsSchema = z.object({
 	envelopeTimestamp: z.union([z.literal("on"), z.literal("off")]).optional(),
 	envelopeElapsed: z.union([z.literal("on"), z.literal("off")]).optional(),
 	contextTokens: z.number().int().positive().optional(),
-	cliBackends: z.record(z.string(), CliBackendSchema).optional(),
+	cliBackends: z.unknown().optional(),
 	contextPruning: z.object({
 		mode: z.union([z.literal("off"), z.literal("cache-ttl")]).optional(),
 		ttl: z.string().optional(),
@@ -5297,21 +5274,6 @@ const AgentDefaultsSchema = z.object({
 			placeholder: z.string().optional()
 		}).strict().optional()
 	}).strict().optional(),
-	compaction: z.object({
-		mode: z.union([z.literal("default"), z.literal("safeguard")]).optional(),
-		reserveTokens: z.number().int().nonnegative().optional(),
-		keepRecentTokens: z.number().int().positive().optional(),
-		reserveTokensFloor: z.number().int().nonnegative().optional(),
-		maxHistoryShare: z.number().min(.1).max(.9).optional()
-	}).strict().optional(),
-	thinkingDefault: z.union([
-		z.literal("off"),
-		z.literal("minimal"),
-		z.literal("low"),
-		z.literal("medium"),
-		z.literal("high"),
-		z.literal("xhigh")
-	]).optional(),
 	verboseDefault: z.union([
 		z.literal("off"),
 		z.literal("on"),
@@ -5341,8 +5303,7 @@ const AgentDefaultsSchema = z.object({
 		maxSpawnDepth: z.number().int().min(1).max(5).optional().describe("Maximum nesting depth for sub-agent spawning. 1 = no nesting (default), 2 = sub-agents can spawn sub-sub-agents."),
 		maxChildrenPerAgent: z.number().int().min(1).max(20).optional().describe("Maximum number of active children a single agent session can spawn (default: 5)."),
 		archiveAfterMinutes: z.number().int().positive().optional(),
-		model: AgentModelSchema.optional(),
-		thinking: z.string().optional(),
+		model: z.unknown().optional(),
 		runTimeoutSeconds: z.number().int().min(0).optional(),
 		announceTimeoutMs: z.number().int().positive().optional()
 	}).strict().optional(),
@@ -5353,7 +5314,10 @@ const AgentDefaultsSchema = z.object({
 		z.literal("gemini"),
 		z.literal("codex"),
 		z.literal("opencode")
-	]).optional()
+	]).optional(),
+	runtimeArgs: z.array(z.string()).optional(),
+	runtimeEnv: z.record(z.string(), z.string()).optional(),
+	auth: AuthFieldSchema
 }).strict().optional();
 
 //#endregion
@@ -7270,7 +7234,8 @@ function validateIdentityAvatar(config) {
 			});
 			continue;
 		}
-		if (!isWorkspaceAvatarPath(avatar, resolveAgentWorkspaceDir(config, entry.id ?? resolveDefaultAgentId(config)))) issues.push({
+		const workspaceDir = resolveAgentWorkspaceDirOrNull(config, entry.id ?? resolveDefaultAgentId(config));
+		if (workspaceDir != null && !isWorkspaceAvatarPath(avatar, workspaceDir)) issues.push({
 			path: `agents.list.${index}.identity.avatar`,
 			message: "identity.avatar must stay within the agent workspace."
 		});
@@ -7346,7 +7311,7 @@ function validateConfigObjectWithPluginsBase(raw, opts) {
 		if (registryInfo) return registryInfo;
 		const registry = loadPluginManifestRegistry({
 			config,
-			workspaceDir: resolveAgentWorkspaceDir(config, resolveDefaultAgentId(config)) ?? void 0
+			workspaceDir: resolveAgentWorkspaceDirOrNull(config, resolveDefaultAgentId(config)) ?? void 0
 		});
 		const knownIds = new Set(registry.plugins.map((record) => record.id));
 		const normalizedPlugins = normalizePluginsConfig(config.plugins);
@@ -7949,7 +7914,7 @@ function createConfigIO(overrides = {}) {
 				deps.logger.warn(`Config warnings:\\n${details}`);
 			}
 			warnIfConfigFromFuture(validated.config, deps.logger);
-			const cfg = applyTalkConfigNormalization(applyModelDefaults(applyCompactionDefaults(applyContextPruningDefaults(applyAgentDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config))))))));
+			const cfg = applyTalkConfigNormalization(applyModelDefaults(applyContextPruningDefaults(applyAgentDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config)))))));
 			normalizeConfigPaths(cfg);
 			const duplicates = findDuplicateAgentDirs(cfg, {
 				env: deps.env,
@@ -8009,7 +7974,7 @@ function createConfigIO(overrides = {}) {
 				parsed: {},
 				resolved: {},
 				valid: true,
-				config: applyTalkApiKey(applyTalkConfigNormalization(applyModelDefaults(applyCompactionDefaults(applyContextPruningDefaults(applyAgentDefaults(applySessionDefaults(applyMessageDefaults({})))))))),
+				config: applyTalkApiKey(applyTalkConfigNormalization(applyModelDefaults(applyContextPruningDefaults(applyAgentDefaults(applySessionDefaults(applyMessageDefaults({}))))))),
 				hash,
 				issues: [],
 				warnings: [],
@@ -9810,6 +9775,32 @@ async function withSessionStoreLock(storePath, fn, opts = {}) {
 	});
 }
 
+//#endregion
+//#region src/logger.ts
+const subsystemPrefixRe = /^([a-z][a-z0-9-]{1,20}):\s+(.*)$/i;
+function splitSubsystem(message) {
+	const match = message.match(subsystemPrefixRe);
+	if (!match) return null;
+	const [, subsystem, rest] = match;
+	return {
+		subsystem,
+		rest
+	};
+}
+function logWarn(message, runtime = defaultRuntime) {
+	const parsed = runtime === defaultRuntime ? splitSubsystem(message) : null;
+	if (parsed) {
+		createSubsystemLogger(parsed.subsystem).warn(parsed.rest);
+		return;
+	}
+	runtime.log(warn(message));
+	getLogger().warn(message);
+}
+function logDebug(message) {
+	getLogger().debug(message);
+	logVerboseConsole(message);
+}
+
 //#endregion
 //#region src/plugins/hook-runner-global.ts
 /**
@@ -9855,46 +9846,77 @@ var DeliveryAdapter = class {
 	async process(events, callbacks) {
 		let textBuffer = "";
 		const payloads = [];
-		for await (const event of events) switch (event.type) {
-			case "text":
-				if (event.text === "") break;
-				textBuffer += event.text;
-				while (textBuffer.length > this.chunkLimit) {
-					const { chunk, rest } = splitAtBoundary(textBuffer, this.chunkLimit);
-					textBuffer = rest;
-					const payload = { text: chunk };
-					payloads.push(payload);
-					await callbacks?.onPartialReply?.(payload);
+		/** Track media delivered via streaming events to avoid duplicates from result.media. */
+		const deliveredMediaKeys = /* @__PURE__ */ new Set();
+		let eventCount = 0;
+		for await (const event of events) {
+			eventCount++;
+			switch (event.type) {
+				case "text":
+					if (event.text === "") break;
+					textBuffer += event.text;
+					while (textBuffer.length > this.chunkLimit) {
+						const { chunk, rest } = splitAtBoundary(textBuffer, this.chunkLimit);
+						textBuffer = rest;
+						const payload = { text: chunk };
+						payloads.push(payload);
+						await callbacks?.onPartialReply?.(payload);
+					}
+					break;
+				case "media": {
+					const mediaUrl = event.media.filePath ?? event.media.sourceUrl;
+					if (mediaUrl) {
+						if (textBuffer.length > 0) {
+							const textPayload = { text: textBuffer };
+							payloads.push(textPayload);
+							await callbacks?.onBlockReply?.(textPayload);
+							textBuffer = "";
+						}
+						deliveredMediaKeys.add(mediaUrl);
+						const payload = { mediaUrl };
+						payloads.push(payload);
+						await callbacks?.onBlockReply?.(payload);
+					}
+					break;
 				}
-				break;
-			case "tool_use": break;
-			case "tool_result": {
-				const payload = { text: formatToolResult(event.toolId, event.output, event.isError) };
-				await callbacks?.onToolResult?.(payload);
-				break;
-			}
-			case "error": {
-				const payload = {
-					text: event.code ? `[${event.code}] ${event.message}` : event.message,
-					isError: true
-				};
-				payloads.push(payload);
-				await callbacks?.onBlockReply?.(payload);
-				break;
-			}
-			case "done":
-				if (textBuffer.length > 0) {
-					const payload = { text: textBuffer };
+				case "tool_use": break;
+				case "tool_result": {
+					const payload = { text: formatToolResult(event.toolId, event.output, event.isError) };
+					await callbacks?.onToolResult?.(payload);
+					break;
+				}
+				case "error": {
+					const payload = {
+						text: event.code ? `[${event.code}] ${event.message}` : event.message,
+						isError: true
+					};
 					payloads.push(payload);
 					await callbacks?.onBlockReply?.(payload);
-					textBuffer = "";
+					break;
 				}
-				break;
+				case "done":
+					if (textBuffer.length > 0) {
+						const payload = { text: textBuffer };
+						payloads.push(payload);
+						await callbacks?.onBlockReply?.(payload);
+						textBuffer = "";
+					}
+					if (event.result.media?.length) for (const media of event.result.media) {
+						const url = media.filePath ?? media.sourceUrl;
+						if (url && !deliveredMediaKeys.has(url)) {
+							const payload = { mediaUrl: url };
+							payloads.push(payload);
+							await callbacks?.onBlockReply?.(payload);
+						}
+					}
+					break;
+			}
 		}
 		if (textBuffer.length > 0) {
 			const payload = { text: textBuffer };
 			payloads.push(payload);
 		}
+		logDebug(`[delivery-adapter] processed ${eventCount} events into ${payloads.length} payloads (chunkLimit=${this.chunkLimit})`);
 		return payloads;
 	}
 };
@@ -10010,9 +10032,19 @@ const fatalAuthPatterns = [
 * Case-insensitive matching throughout.
 */
 function classifyError(message) {
-	for (const pattern of retryablePatterns) if (pattern.test(message)) return "retryable";
-	for (const pattern of contextOverflowPatterns) if (pattern.test(message)) return "context_overflow";
-	for (const pattern of fatalAuthPatterns) if (pattern.test(message)) return "fatal";
+	for (const pattern of retryablePatterns) if (pattern.test(message)) {
+		logDebug(`[error-classifier] classified as retryable: ${message.slice(0, 200)}`);
+		return "retryable";
+	}
+	for (const pattern of contextOverflowPatterns) if (pattern.test(message)) {
+		logDebug(`[error-classifier] classified as context_overflow: ${message.slice(0, 200)}`);
+		return "context_overflow";
+	}
+	for (const pattern of fatalAuthPatterns) if (pattern.test(message)) {
+		logDebug(`[error-classifier] classified as fatal (auth): ${message.slice(0, 200)}`);
+		return "fatal";
+	}
+	logDebug(`[error-classifier] classified as fatal (unmatched): ${message.slice(0, 200)}`);
 	return "fatal";
 }
 
@@ -10058,6 +10090,763 @@ async function readMcpSideEffects(filePath) {
 	return result;
 }
 
+//#endregion
+//#region src/utils/fetch-timeout.ts
+/**
+* Relay abort without forwarding the Event argument as the abort reason.
+* Using .bind() avoids closure scope capture (memory leak prevention).
+*/
+function relayAbort() {
+	this.abort();
+}
+/** Returns a bound abort relay for use as an event listener. */
+function bindAbortRelay(controller) {
+	return relayAbort.bind(controller);
+}
+
+//#endregion
+//#region src/shared/net/ip.ts
+const BLOCKED_IPV4_SPECIAL_USE_RANGES = new Set([
+	"unspecified",
+	"broadcast",
+	"multicast",
+	"linkLocal",
+	"loopback",
+	"carrierGradeNat",
+	"private",
+	"reserved"
+]);
+const PRIVATE_OR_LOOPBACK_IPV4_RANGES = new Set([
+	"loopback",
+	"private",
+	"linkLocal",
+	"carrierGradeNat"
+]);
+const PRIVATE_OR_LOOPBACK_IPV6_RANGES = new Set([
+	"unspecified",
+	"loopback",
+	"linkLocal",
+	"uniqueLocal"
+]);
+const RFC2544_BENCHMARK_PREFIX = [ipaddr.IPv4.parse("198.18.0.0"), 15];
+const EMBEDDED_IPV4_SENTINEL_RULES = [
+	{
+		matches: (parts) => parts[0] === 0 && parts[1] === 0 && parts[2] === 0 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0,
+		toHextets: (parts) => [parts[6], parts[7]]
+	},
+	{
+		matches: (parts) => parts[0] === 100 && parts[1] === 65435 && parts[2] === 1 && parts[3] === 0 && parts[4] === 0 && parts[5] === 0,
+		toHextets: (parts) => [parts[6], parts[7]]
+	},
+	{
+		matches: (parts) => parts[0] === 8194,
+		toHextets: (parts) => [parts[1], parts[2]]
+	},
+	{
+		matches: (parts) => parts[0] === 8193 && parts[1] === 0,
+		toHextets: (parts) => [parts[6] ^ 65535, parts[7] ^ 65535]
+	},
+	{
+		matches: (parts) => (parts[4] & 64767) === 0 && parts[5] === 24318,
+		toHextets: (parts) => [parts[6], parts[7]]
+	}
+];
+function stripIpv6Brackets(value) {
+	if (value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1);
+	return value;
+}
+function isNumericIpv4LiteralPart(value) {
+	return /^[0-9]+$/.test(value) || /^0x[0-9a-f]+$/i.test(value);
+}
+function parseIpv6WithEmbeddedIpv4(raw) {
+	if (!raw.includes(":") || !raw.includes(".")) return;
+	const match = /^(.*:)([^:%]+(?:\.[^:%]+){3})(%[0-9A-Za-z]+)?$/i.exec(raw);
+	if (!match) return;
+	const [, prefix, embeddedIpv4, zoneSuffix = ""] = match;
+	if (!ipaddr.IPv4.isValidFourPartDecimal(embeddedIpv4)) return;
+	const octets = embeddedIpv4.split(".").map((part) => Number.parseInt(part, 10));
+	const normalizedIpv6 = `${prefix}${(octets[0] << 8 | octets[1]).toString(16)}:${(octets[2] << 8 | octets[3]).toString(16)}${zoneSuffix}`;
+	if (!ipaddr.IPv6.isValid(normalizedIpv6)) return;
+	return ipaddr.IPv6.parse(normalizedIpv6);
+}
+function isIpv4Address(address) {
+	return address.kind() === "ipv4";
+}
+function isIpv6Address(address) {
+	return address.kind() === "ipv6";
+}
+function normalizeIpv4MappedAddress(address) {
+	if (!isIpv6Address(address)) return address;
+	if (!address.isIPv4MappedAddress()) return address;
+	return address.toIPv4Address();
+}
+function parseCanonicalIpAddress(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return;
+	const normalized = stripIpv6Brackets(trimmed);
+	if (!normalized) return;
+	if (ipaddr.IPv4.isValid(normalized)) {
+		if (!ipaddr.IPv4.isValidFourPartDecimal(normalized)) return;
+		return ipaddr.IPv4.parse(normalized);
+	}
+	if (ipaddr.IPv6.isValid(normalized)) return ipaddr.IPv6.parse(normalized);
+	return parseIpv6WithEmbeddedIpv4(normalized);
+}
+function parseLooseIpAddress(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return;
+	const normalized = stripIpv6Brackets(trimmed);
+	if (!normalized) return;
+	if (ipaddr.isValid(normalized)) return ipaddr.parse(normalized);
+	return parseIpv6WithEmbeddedIpv4(normalized);
+}
+function isCanonicalDottedDecimalIPv4(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return false;
+	const normalized = stripIpv6Brackets(trimmed);
+	if (!normalized) return false;
+	return ipaddr.IPv4.isValidFourPartDecimal(normalized);
+}
+function isLegacyIpv4Literal(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return false;
+	const normalized = stripIpv6Brackets(trimmed);
+	if (!normalized || normalized.includes(":")) return false;
+	if (isCanonicalDottedDecimalIPv4(normalized)) return false;
+	const parts = normalized.split(".");
+	if (parts.length === 0 || parts.length > 4) return false;
+	if (parts.some((part) => part.length === 0)) return false;
+	if (!parts.every((part) => isNumericIpv4LiteralPart(part))) return false;
+	return true;
+}
+function isPrivateOrLoopbackIpAddress(raw) {
+	const parsed = parseCanonicalIpAddress(raw);
+	if (!parsed) return false;
+	const normalized = normalizeIpv4MappedAddress(parsed);
+	if (isIpv4Address(normalized)) return PRIVATE_OR_LOOPBACK_IPV4_RANGES.has(normalized.range());
+	if (PRIVATE_OR_LOOPBACK_IPV6_RANGES.has(normalized.range())) return true;
+	return (normalized.parts[0] & 65472) === 65216;
+}
+function isBlockedSpecialUseIpv4Address(address, options = {}) {
+	const inRfc2544BenchmarkRange = address.match(RFC2544_BENCHMARK_PREFIX);
+	if (inRfc2544BenchmarkRange && options.allowRfc2544BenchmarkRange === true) return false;
+	return BLOCKED_IPV4_SPECIAL_USE_RANGES.has(address.range()) || inRfc2544BenchmarkRange;
+}
+function decodeIpv4FromHextets(high, low) {
+	const octets = [
+		high >>> 8 & 255,
+		high & 255,
+		low >>> 8 & 255,
+		low & 255
+	];
+	return ipaddr.IPv4.parse(octets.join("."));
+}
+function extractEmbeddedIpv4FromIpv6(address) {
+	if (address.isIPv4MappedAddress()) return address.toIPv4Address();
+	if (address.range() === "rfc6145") return decodeIpv4FromHextets(address.parts[6], address.parts[7]);
+	if (address.range() === "rfc6052") return decodeIpv4FromHextets(address.parts[6], address.parts[7]);
+	for (const rule of EMBEDDED_IPV4_SENTINEL_RULES) {
+		if (!rule.matches(address.parts)) continue;
+		const [high, low] = rule.toHextets(address.parts);
+		return decodeIpv4FromHextets(high, low);
+	}
+}
+
+//#endregion
+//#region src/infra/net/hostname.ts
+function normalizeHostname(hostname) {
+	const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
+	if (normalized.startsWith("[") && normalized.endsWith("]")) return normalized.slice(1, -1);
+	return normalized;
+}
+
+//#endregion
+//#region src/infra/net/ssrf.ts
+var SsrFBlockedError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SsrFBlockedError";
+	}
+};
+const BLOCKED_HOSTNAMES = new Set([
+	"localhost",
+	"localhost.localdomain",
+	"metadata.google.internal"
+]);
+function normalizeHostnameSet(values) {
+	if (!values || values.length === 0) return /* @__PURE__ */ new Set();
+	return new Set(values.map((value) => normalizeHostname(value)).filter(Boolean));
+}
+function normalizeHostnameAllowlist(values) {
+	if (!values || values.length === 0) return [];
+	return Array.from(new Set(values.map((value) => normalizeHostname(value)).filter((value) => value !== "*" && value !== "*." && value.length > 0)));
+}
+function resolveAllowPrivateNetwork(policy) {
+	return policy?.dangerouslyAllowPrivateNetwork === true || policy?.allowPrivateNetwork === true;
+}
+function resolveIpv4SpecialUseBlockOptions(policy) {
+	return { allowRfc2544BenchmarkRange: policy?.allowRfc2544BenchmarkRange === true };
+}
+function isHostnameAllowedByPattern(hostname, pattern) {
+	if (pattern.startsWith("*.")) {
+		const suffix = pattern.slice(2);
+		if (!suffix || hostname === suffix) return false;
+		return hostname.endsWith(`.${suffix}`);
+	}
+	return hostname === pattern;
+}
+function matchesHostnameAllowlist(hostname, allowlist) {
+	if (allowlist.length === 0) return true;
+	return allowlist.some((pattern) => isHostnameAllowedByPattern(hostname, pattern));
+}
+function looksLikeUnsupportedIpv4Literal(address) {
+	const parts = address.split(".");
+	if (parts.length === 0 || parts.length > 4) return false;
+	if (parts.some((part) => part.length === 0)) return true;
+	return parts.every((part) => /^[0-9]+$/.test(part) || /^0x/i.test(part));
+}
+function isPrivateIpAddress(address, policy) {
+	let normalized = address.trim().toLowerCase();
+	if (normalized.startsWith("[") && normalized.endsWith("]")) normalized = normalized.slice(1, -1);
+	if (!normalized) return false;
+	const blockOptions = resolveIpv4SpecialUseBlockOptions(policy);
+	const strictIp = parseCanonicalIpAddress(normalized);
+	if (strictIp) {
+		if (isIpv4Address(strictIp)) return isBlockedSpecialUseIpv4Address(strictIp, blockOptions);
+		if (isPrivateOrLoopbackIpAddress(strictIp.toString())) return true;
+		const embeddedIpv4 = extractEmbeddedIpv4FromIpv6(strictIp);
+		if (embeddedIpv4) return isBlockedSpecialUseIpv4Address(embeddedIpv4, blockOptions);
+		return false;
+	}
+	if (normalized.includes(":") && !parseLooseIpAddress(normalized)) return true;
+	if (!isCanonicalDottedDecimalIPv4(normalized) && isLegacyIpv4Literal(normalized)) return true;
+	if (looksLikeUnsupportedIpv4Literal(normalized)) return true;
+	return false;
+}
+function isBlockedHostnameNormalized(normalized) {
+	if (BLOCKED_HOSTNAMES.has(normalized)) return true;
+	return normalized.endsWith(".localhost") || normalized.endsWith(".local") || normalized.endsWith(".internal");
+}
+function isBlockedHostnameOrIp(hostname, policy) {
+	const normalized = normalizeHostname(hostname);
+	if (!normalized) return false;
+	return isBlockedHostnameNormalized(normalized) || isPrivateIpAddress(normalized, policy);
+}
+const BLOCKED_HOST_OR_IP_MESSAGE = "Blocked hostname or private/internal/special-use IP address";
+const BLOCKED_RESOLVED_IP_MESSAGE = "Blocked: resolves to private/internal/special-use IP address";
+function assertAllowedHostOrIpOrThrow(hostnameOrIp, policy) {
+	if (isBlockedHostnameOrIp(hostnameOrIp, policy)) throw new SsrFBlockedError(BLOCKED_HOST_OR_IP_MESSAGE);
+}
+function assertAllowedResolvedAddressesOrThrow(results, policy) {
+	for (const entry of results) if (isBlockedHostnameOrIp(entry.address, policy)) throw new SsrFBlockedError(BLOCKED_RESOLVED_IP_MESSAGE);
+}
+function createPinnedLookup(params) {
+	const normalizedHost = normalizeHostname(params.hostname);
+	const fallback = params.fallback ?? lookup;
+	const fallbackLookup = fallback;
+	const fallbackWithOptions = fallback;
+	const records = params.addresses.map((address) => ({
+		address,
+		family: address.includes(":") ? 6 : 4
+	}));
+	let index = 0;
+	return ((host, options, callback) => {
+		const cb = typeof options === "function" ? options : callback;
+		if (!cb) return;
+		const normalized = normalizeHostname(host);
+		if (!normalized || normalized !== normalizedHost) {
+			if (typeof options === "function" || options === void 0) return fallbackLookup(host, cb);
+			return fallbackWithOptions(host, options, cb);
+		}
+		const opts = typeof options === "object" && options !== null ? options : {};
+		const requestedFamily = typeof options === "number" ? options : typeof opts.family === "number" ? opts.family : 0;
+		const candidates = requestedFamily === 4 || requestedFamily === 6 ? records.filter((entry) => entry.family === requestedFamily) : records;
+		const usable = candidates.length > 0 ? candidates : records;
+		if (opts.all) {
+			cb(null, usable);
+			return;
+		}
+		const chosen = usable[index % usable.length];
+		index += 1;
+		cb(null, chosen.address, chosen.family);
+	});
+}
+function dedupeAndPreferIpv4(results) {
+	const seen = /* @__PURE__ */ new Set();
+	const ipv4 = [];
+	const otherFamilies = [];
+	for (const entry of results) {
+		if (seen.has(entry.address)) continue;
+		seen.add(entry.address);
+		if (entry.family === 4) {
+			ipv4.push(entry.address);
+			continue;
+		}
+		otherFamilies.push(entry.address);
+	}
+	return [...ipv4, ...otherFamilies];
+}
+async function resolvePinnedHostnameWithPolicy(hostname, params = {}) {
+	const normalized = normalizeHostname(hostname);
+	if (!normalized) throw new Error("Invalid hostname");
+	const allowPrivateNetwork = resolveAllowPrivateNetwork(params.policy);
+	const allowedHostnames = normalizeHostnameSet(params.policy?.allowedHostnames);
+	const hostnameAllowlist = normalizeHostnameAllowlist(params.policy?.hostnameAllowlist);
+	const isExplicitAllowed = allowedHostnames.has(normalized);
+	const skipPrivateNetworkChecks = allowPrivateNetwork || isExplicitAllowed;
+	if (!matchesHostnameAllowlist(normalized, hostnameAllowlist)) throw new SsrFBlockedError(`Blocked hostname (not in allowlist): ${hostname}`);
+	if (!skipPrivateNetworkChecks) assertAllowedHostOrIpOrThrow(normalized, params.policy);
+	const results = await (params.lookupFn ?? lookup$1)(normalized, { all: true });
+	if (results.length === 0) throw new Error(`Unable to resolve hostname: ${hostname}`);
+	if (!skipPrivateNetworkChecks) assertAllowedResolvedAddressesOrThrow(results, params.policy);
+	const addresses = dedupeAndPreferIpv4(results);
+	if (addresses.length === 0) throw new Error(`Unable to resolve hostname: ${hostname}`);
+	return {
+		hostname: normalized,
+		addresses,
+		lookup: createPinnedLookup({
+			hostname: normalized,
+			addresses
+		})
+	};
+}
+function createPinnedDispatcher(pinned) {
+	return new Agent({ connect: {
+		lookup: pinned.lookup,
+		autoSelectFamily: true,
+		autoSelectFamilyAttemptTimeout: 300
+	} });
+}
+async function closeDispatcher(dispatcher) {
+	if (!dispatcher) return;
+	const candidate = dispatcher;
+	try {
+		if (typeof candidate.close === "function") {
+			await candidate.close();
+			return;
+		}
+		if (typeof candidate.destroy === "function") candidate.destroy();
+	} catch {}
+}
+
+//#endregion
+//#region src/infra/net/fetch-guard.ts
+const DEFAULT_MAX_REDIRECTS = 3;
+const CROSS_ORIGIN_REDIRECT_SENSITIVE_HEADERS = [
+	"authorization",
+	"proxy-authorization",
+	"cookie",
+	"cookie2"
+];
+function isRedirectStatus(status) {
+	return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function stripSensitiveHeadersForCrossOriginRedirect(init) {
+	if (!init?.headers) return init;
+	const headers = new Headers(init.headers);
+	for (const header of CROSS_ORIGIN_REDIRECT_SENSITIVE_HEADERS) headers.delete(header);
+	return {
+		...init,
+		headers
+	};
+}
+function buildAbortSignal(params) {
+	const { timeoutMs, signal } = params;
+	if (!timeoutMs && !signal) return {
+		signal: void 0,
+		cleanup: () => {}
+	};
+	if (!timeoutMs) return {
+		signal,
+		cleanup: () => {}
+	};
+	const controller = new AbortController();
+	const timeoutId = setTimeout(controller.abort.bind(controller), timeoutMs);
+	const onAbort = bindAbortRelay(controller);
+	if (signal) if (signal.aborted) controller.abort();
+	else signal.addEventListener("abort", onAbort, { once: true });
+	const cleanup = () => {
+		clearTimeout(timeoutId);
+		if (signal) signal.removeEventListener("abort", onAbort);
+	};
+	return {
+		signal: controller.signal,
+		cleanup
+	};
+}
+async function fetchWithSsrFGuard(params) {
+	const fetcher = params.fetchImpl ?? globalThis.fetch;
+	if (!fetcher) throw new Error("fetch is not available");
+	const maxRedirects = typeof params.maxRedirects === "number" && Number.isFinite(params.maxRedirects) ? Math.max(0, Math.floor(params.maxRedirects)) : DEFAULT_MAX_REDIRECTS;
+	const { signal, cleanup } = buildAbortSignal({
+		timeoutMs: params.timeoutMs,
+		signal: params.signal
+	});
+	let released = false;
+	const release = async (dispatcher) => {
+		if (released) return;
+		released = true;
+		cleanup();
+		await closeDispatcher(dispatcher ?? void 0);
+	};
+	const visited = /* @__PURE__ */ new Set();
+	let currentUrl = params.url;
+	let currentInit = params.init ? { ...params.init } : void 0;
+	let redirectCount = 0;
+	while (true) {
+		let parsedUrl;
+		try {
+			parsedUrl = new URL(currentUrl);
+		} catch {
+			await release();
+			throw new Error("Invalid URL: must be http or https");
+		}
+		if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+			await release();
+			throw new Error("Invalid URL: must be http or https");
+		}
+		let dispatcher = null;
+		try {
+			const pinned = await resolvePinnedHostnameWithPolicy(parsedUrl.hostname, {
+				lookupFn: params.lookupFn,
+				policy: params.policy
+			});
+			if (params.pinDns !== false) dispatcher = createPinnedDispatcher(pinned);
+			const init = {
+				...currentInit ? { ...currentInit } : {},
+				redirect: "manual",
+				...dispatcher ? { dispatcher } : {},
+				...signal ? { signal } : {}
+			};
+			const response = await fetcher(parsedUrl.toString(), init);
+			if (isRedirectStatus(response.status)) {
+				const location = response.headers.get("location");
+				if (!location) {
+					await release(dispatcher);
+					throw new Error(`Redirect missing location header (${response.status})`);
+				}
+				redirectCount += 1;
+				if (redirectCount > maxRedirects) {
+					await release(dispatcher);
+					throw new Error(`Too many redirects (limit: ${maxRedirects})`);
+				}
+				const nextParsedUrl = new URL(location, parsedUrl);
+				const nextUrl = nextParsedUrl.toString();
+				if (visited.has(nextUrl)) {
+					await release(dispatcher);
+					throw new Error("Redirect loop detected");
+				}
+				if (nextParsedUrl.origin !== parsedUrl.origin) currentInit = stripSensitiveHeadersForCrossOriginRedirect(currentInit);
+				visited.add(nextUrl);
+				response.body?.cancel();
+				await closeDispatcher(dispatcher);
+				currentUrl = nextUrl;
+				continue;
+			}
+			return {
+				response,
+				finalUrl: currentUrl,
+				release: async () => release(dispatcher)
+			};
+		} catch (err) {
+			if (err instanceof SsrFBlockedError) logWarn(`security: blocked URL fetch (${params.auditContext ?? "url-fetch"}) target=${parsedUrl.origin}${parsedUrl.pathname} reason=${err.message}`);
+			await release(dispatcher);
+			throw err;
+		}
+	}
+}
+
+//#endregion
+//#region src/media/constants.ts
+const MAX_IMAGE_BYTES = 6 * 1024 * 1024;
+const MAX_AUDIO_BYTES = 16 * 1024 * 1024;
+const MAX_VIDEO_BYTES = 16 * 1024 * 1024;
+const MAX_DOCUMENT_BYTES = 100 * 1024 * 1024;
+
+//#endregion
+//#region src/media/mime.ts
+const EXT_BY_MIME = {
+	"image/heic": ".heic",
+	"image/heif": ".heif",
+	"image/jpeg": ".jpg",
+	"image/png": ".png",
+	"image/webp": ".webp",
+	"image/gif": ".gif",
+	"audio/ogg": ".ogg",
+	"audio/mpeg": ".mp3",
+	"audio/x-m4a": ".m4a",
+	"audio/mp4": ".m4a",
+	"video/mp4": ".mp4",
+	"video/quicktime": ".mov",
+	"application/pdf": ".pdf",
+	"application/json": ".json",
+	"application/zip": ".zip",
+	"application/gzip": ".gz",
+	"application/x-tar": ".tar",
+	"application/x-7z-compressed": ".7z",
+	"application/vnd.rar": ".rar",
+	"application/msword": ".doc",
+	"application/vnd.ms-excel": ".xls",
+	"application/vnd.ms-powerpoint": ".ppt",
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+	"application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+	"text/csv": ".csv",
+	"text/plain": ".txt",
+	"text/markdown": ".md"
+};
+const MIME_BY_EXT = {
+	...Object.fromEntries(Object.entries(EXT_BY_MIME).map(([mime, ext]) => [ext, mime])),
+	".jpeg": "image/jpeg"
+};
+function normalizeMimeType(mime) {
+	if (!mime) return;
+	return mime.split(";")[0]?.trim().toLowerCase() || void 0;
+}
+async function sniffMime(buffer) {
+	if (!buffer) return;
+	try {
+		return (await fileTypeFromBuffer(buffer))?.mime ?? void 0;
+	} catch {
+		return;
+	}
+}
+function getFileExtension(filePath) {
+	if (!filePath) return;
+	try {
+		if (/^https?:\/\//i.test(filePath)) {
+			const url = new URL(filePath);
+			return path.extname(url.pathname).toLowerCase() || void 0;
+		}
+	} catch {}
+	return path.extname(filePath).toLowerCase() || void 0;
+}
+function detectMime(opts) {
+	return detectMimeImpl(opts);
+}
+function isGenericMime(mime) {
+	if (!mime) return true;
+	const m = mime.toLowerCase();
+	return m === "application/octet-stream" || m === "application/zip";
+}
+async function detectMimeImpl(opts) {
+	const ext = getFileExtension(opts.filePath);
+	const extMime = ext ? MIME_BY_EXT[ext] : void 0;
+	const headerMime = normalizeMimeType(opts.headerMime);
+	const sniffed = await sniffMime(opts.buffer);
+	if (sniffed && (!isGenericMime(sniffed) || !extMime)) return sniffed;
+	if (extMime) return extMime;
+	if (headerMime && !isGenericMime(headerMime)) return headerMime;
+	if (sniffed) return sniffed;
+	if (headerMime) return headerMime;
+}
+function extensionForMime(mime) {
+	const normalized = normalizeMimeType(mime);
+	if (!normalized) return;
+	return EXT_BY_MIME[normalized];
+}
+
+//#endregion
+//#region src/media/read-response-with-limit.ts
+async function readResponseWithLimit(res, maxBytes, opts) {
+	const onOverflow = opts?.onOverflow ?? ((params) => /* @__PURE__ */ new Error(`Content too large: ${params.size} bytes (limit: ${params.maxBytes} bytes)`));
+	const body = res.body;
+	if (!body || typeof body.getReader !== "function") {
+		const fallback = Buffer.from(await res.arrayBuffer());
+		if (fallback.length > maxBytes) throw onOverflow({
+			size: fallback.length,
+			maxBytes,
+			res
+		});
+		return fallback;
+	}
+	const reader = body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (value?.length) {
+				total += value.length;
+				if (total > maxBytes) {
+					try {
+						await reader.cancel();
+					} catch {}
+					throw onOverflow({
+						size: total,
+						maxBytes,
+						res
+					});
+				}
+				chunks.push(value);
+			}
+		}
+	} finally {
+		try {
+			reader.releaseLock();
+		} catch {}
+	}
+	return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+}
+
+//#endregion
+//#region src/media/fetch.ts
+var MediaFetchError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "MediaFetchError";
+	}
+};
+function stripQuotes(value) {
+	return value.replace(/^["']|["']$/g, "");
+}
+function parseContentDispositionFileName(header) {
+	if (!header) return;
+	const starMatch = /filename\*\s*=\s*([^;]+)/i.exec(header);
+	if (starMatch?.[1]) {
+		const cleaned = stripQuotes(starMatch[1].trim());
+		const encoded = cleaned.split("''").slice(1).join("''") || cleaned;
+		try {
+			return path.basename(decodeURIComponent(encoded));
+		} catch {
+			return path.basename(encoded);
+		}
+	}
+	const match = /filename\s*=\s*([^;]+)/i.exec(header);
+	if (match?.[1]) return path.basename(stripQuotes(match[1].trim()));
+}
+async function readErrorBodySnippet(res, maxChars = 200) {
+	try {
+		const text = await res.text();
+		if (!text) return;
+		const collapsed = text.replace(/\s+/g, " ").trim();
+		if (!collapsed) return;
+		if (collapsed.length <= maxChars) return collapsed;
+		return `${collapsed.slice(0, maxChars)}…`;
+	} catch {
+		return;
+	}
+}
+async function fetchRemoteMedia(options) {
+	const { url, fetchImpl, filePathHint, maxBytes, maxRedirects, ssrfPolicy, lookupFn } = options;
+	let res;
+	let finalUrl = url;
+	let release = null;
+	try {
+		const result = await fetchWithSsrFGuard({
+			url,
+			fetchImpl,
+			maxRedirects,
+			policy: ssrfPolicy,
+			lookupFn
+		});
+		res = result.response;
+		finalUrl = result.finalUrl;
+		release = result.release;
+	} catch (err) {
+		throw new MediaFetchError("fetch_failed", `Failed to fetch media from ${url}: ${String(err)}`);
+	}
+	try {
+		if (!res.ok) {
+			const statusText = res.statusText ? ` ${res.statusText}` : "";
+			const redirected = finalUrl !== url ? ` (redirected to ${finalUrl})` : "";
+			let detail = `HTTP ${res.status}${statusText}`;
+			if (!res.body) detail = `HTTP ${res.status}${statusText}; empty response body`;
+			else {
+				const snippet = await readErrorBodySnippet(res);
+				if (snippet) detail += `; body: ${snippet}`;
+			}
+			throw new MediaFetchError("http_error", `Failed to fetch media from ${url}${redirected}: ${detail}`);
+		}
+		const contentLength = res.headers.get("content-length");
+		if (maxBytes && contentLength) {
+			const length = Number(contentLength);
+			if (Number.isFinite(length) && length > maxBytes) throw new MediaFetchError("max_bytes", `Failed to fetch media from ${url}: content length ${length} exceeds maxBytes ${maxBytes}`);
+		}
+		const buffer = maxBytes ? await readResponseWithLimit(res, maxBytes, { onOverflow: ({ maxBytes, res }) => new MediaFetchError("max_bytes", `Failed to fetch media from ${res.url || url}: payload exceeds maxBytes ${maxBytes}`) }) : Buffer.from(await res.arrayBuffer());
+		let fileNameFromUrl;
+		try {
+			const parsed = new URL(finalUrl);
+			fileNameFromUrl = path.basename(parsed.pathname) || void 0;
+		} catch {}
+		const headerFileName = parseContentDispositionFileName(res.headers.get("content-disposition"));
+		let fileName = headerFileName || fileNameFromUrl || (filePathHint ? path.basename(filePathHint) : void 0);
+		const filePathForMime = headerFileName && path.extname(headerFileName) ? headerFileName : filePathHint ?? finalUrl;
+		const contentType = await detectMime({
+			buffer,
+			headerMime: res.headers.get("content-type"),
+			filePath: filePathForMime
+		});
+		if (fileName && !path.extname(fileName) && contentType) {
+			const ext = extensionForMime(contentType);
+			if (ext) fileName = `${fileName}${ext}`;
+		}
+		return {
+			buffer,
+			contentType: contentType ?? void 0,
+			fileName
+		};
+	} finally {
+		if (release) await release();
+	}
+}
+
+//#endregion
+//#region src/middleware/media-resolver.ts
+/** Max download size for inbound channel media (100 MB). */
+const MAX_INBOUND_MEDIA_BYTES = 100 * 1024 * 1024;
+/**
+* Resolve an array of media URLs (HTTP or local paths) into MediaAttachment
+* objects suitable for passing to {@link AgentRuntime.execute}.
+*
+* Remote URLs are downloaded into `tempDir` so that CLI runtimes can access
+* them as local files.  Local paths are validated for MIME type only.
+*
+* Individual resolution failures are silently skipped — a single bad URL
+* should not prevent the rest of the message from being processed.
+*/
+async function resolveMediaAttachments(mediaUrls, tempDir) {
+	const results = [];
+	for (const [index, url] of mediaUrls.entries()) try {
+		const attachment = await resolveOne(url, tempDir, index);
+		if (attachment) {
+			logDebug(`[media-resolver] resolved: url=${url} mime=${attachment.mimeType} path=${attachment.filePath}`);
+			results.push(attachment);
+		}
+	} catch (err) {
+		logDebug(`[media-resolver] failed: url=${url} error=${String(err)}`);
+	}
+	return results;
+}
+async function resolveOne(url, tempDir, index) {
+	if (/^https?:\/\//i.test(url)) return downloadRemote(url, tempDir, index);
+	return resolveLocal(url);
+}
+async function downloadRemote(url, tempDir, index) {
+	const fetched = await fetchRemoteMedia({
+		url,
+		maxBytes: MAX_INBOUND_MEDIA_BYTES
+	});
+	const mimeType = fetched.contentType ?? "application/octet-stream";
+	const fileName = `inbound-media-${index}${extensionForMime(mimeType) ?? ""}`;
+	const filePath = join(tempDir, fileName);
+	await writeFile(filePath, fetched.buffer);
+	return {
+		mimeType,
+		filePath,
+		sourceUrl: url,
+		fileName: fetched.fileName ?? fileName
+	};
+}
+async function resolveLocal(filePath) {
+	return {
+		mimeType: await detectMime({ filePath }) ?? "application/octet-stream",
+		filePath
+	};
+}
+
 //#endregion
 //#region src/middleware/cli-runtime-base.ts
 /**
@@ -10088,11 +10877,18 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 	}
 	async *execute(params) {
 		const args = this.buildArgs(params);
+		if (params.extraArgs && params.extraArgs.length > 0) args.push(...params.extraArgs);
+		const runtimeEnv = this.buildEnv(params);
+		const callerEnv = params.env ?? {};
 		const env = {
 			...process.env,
-			...this.buildEnv(params),
-			...params.env
+			...runtimeEnv,
+			...callerEnv
 		};
+		logDebug(`[agent-runtime] spawn: ${this.command} ${args.map((a) => JSON.stringify(a)).join(" ")}`);
+		logDebug(`[agent-runtime] cwd: ${params.workingDirectory ?? process.cwd()}`);
+		if (Object.keys(runtimeEnv).length > 0) logDebug(`[agent-runtime] runtime env keys: ${Object.keys(runtimeEnv).join(", ")}`);
+		if (Object.keys(callerEnv).length > 0) logDebug(`[agent-runtime] caller env keys: ${Object.keys(callerEnv).join(", ")}`);
 		const child = spawn(this.command, args, {
 			cwd: params.workingDirectory,
 			env,
@@ -10102,9 +10898,11 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 				"pipe"
 			]
 		});
+		logDebug(`[agent-runtime] spawned pid=${child.pid}`);
 		const startMs = Date.now();
 		const stderrChunks = [];
 		let aborted = false;
+		let yieldedEvents = false;
 		let escalationTimer;
 		const killWithEscalation = () => {
 			if (escalationTimer === void 0) escalationTimer = setTimeout(() => {
@@ -10126,6 +10924,7 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 			if (watchdogTimer !== void 0) clearTimeout(watchdogTimer);
 			watchdogTimer = setTimeout(() => {
 				watchdogFired = true;
+				logDebug(`[agent-runtime] pid=${child.pid}: watchdog timeout after ${this.timeoutMs}ms`);
 				killWithEscalation();
 			}, this.timeoutMs);
 		};
@@ -10165,10 +10964,14 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 				});
 			});
 		});
-		if (this.supportsStdinPrompt && params.prompt.length > CLIRuntimeBase.STDIN_PROMPT_THRESHOLD && child.stdin) child.stdin.write(params.prompt);
+		if (this.supportsStdinPrompt && params.prompt.length > CLIRuntimeBase.STDIN_PROMPT_THRESHOLD && child.stdin) {
+			logDebug(`[agent-runtime] pid=${child.pid}: delivering prompt via stdin (${params.prompt.length} chars)`);
+			child.stdin.write(params.prompt);
+		}
 		child.stdin?.end();
 		const onAbort = () => {
 			aborted = true;
+			logDebug(`[agent-runtime] pid=${child.pid}: abort signal received`);
 			killWithEscalation();
 		};
 		if (params.abortSignal) if (params.abortSignal.aborted) {
@@ -10183,6 +10986,7 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 				while (eventQueue.length > 0) {
 					const event = eventQueue.shift();
 					if (event === null || event === void 0) break;
+					yieldedEvents = true;
 					yield event;
 				}
 			}
@@ -10190,9 +10994,16 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 			if (watchdogTimer !== void 0) clearTimeout(watchdogTimer);
 			params.abortSignal?.removeEventListener("abort", onAbort);
 		}
-		await exitPromise;
+		const { code: exitCode, signal: exitSignal } = await exitPromise;
 		if (escalationTimer !== void 0) clearTimeout(escalationTimer);
 		const durationMs = Date.now() - startMs;
+		logDebug(`[agent-runtime] pid=${child.pid}: exited code=${exitCode} signal=${exitSignal} duration=${durationMs}ms`);
+		const stderr = stderrChunks.join("");
+		if (stderr && (exitCode !== 0 || !yieldedEvents)) yield {
+			type: "error",
+			message: stderr.trim(),
+			code: "CLI_STDERR"
+		};
 		if (watchdogFired) yield {
 			type: "error",
 			message: `Watchdog timeout: no output for ${this.timeoutMs}ms`,
@@ -10210,7 +11021,8 @@ var CLIRuntimeBase = class CLIRuntimeBase {
 				sessionId: void 0,
 				durationMs,
 				usage: void 0,
-				aborted
+				aborted,
+				stderr: stderr || void 0
 			}
 		};
 	}
@@ -10261,6 +11073,11 @@ var ClaudeCliRuntime = class extends CLIRuntimeBase {
 		}
 		if (parsed.type === "result") {
 			this.storeResultData(parsed);
+			if (parsed.is_error === true && typeof parsed.result === "string" && parsed.result) return {
+				type: "error",
+				message: parsed.result,
+				code: "CLI_ERROR"
+			};
 			return null;
 		}
 		return null;
@@ -11075,12 +11892,42 @@ const SUPPORTED_PROVIDERS = [
 	"codex",
 	"opencode"
 ];
+const validatedCommands = /* @__PURE__ */ new Set();
+/**
+* Verify that a CLI binary exists on PATH.
+*
+* Results are cached per process lifetime so the `which` lookup runs at most
+* once per command.
+*/
+function validateExecutable(command) {
+	if (validatedCommands.has(command)) {
+		logDebug(`[runtime-factory] executable already validated: ${command}`);
+		return;
+	}
+	try {
+		execFileSync("which", [command], { stdio: "ignore" });
+		logDebug(`[runtime-factory] executable validated: ${command}`);
+		validatedCommands.add(command);
+	} catch {
+		throw new Error(`Runtime '${command}' is configured but the '${command}' binary was not found on PATH. Install it or set agents.defaults.runtime to a different provider.`);
+	}
+}
 function createCliRuntime(provider) {
-	switch (provider.trim().toLowerCase()) {
-		case "claude": return new ClaudeCliRuntime();
-		case "gemini": return new GeminiCliRuntime();
-		case "codex": return new CodexCliRuntime();
-		case "opencode": return new OpenCodeCliRuntime();
+	const normalized = provider.trim().toLowerCase();
+	logDebug(`[runtime-factory] creating runtime: provider=${normalized}`);
+	switch (normalized) {
+		case "claude":
+			validateExecutable(normalized);
+			return new ClaudeCliRuntime();
+		case "gemini":
+			validateExecutable(normalized);
+			return new GeminiCliRuntime();
+		case "codex":
+			validateExecutable(normalized);
+			return new CodexCliRuntime();
+		case "opencode":
+			validateExecutable(normalized);
+			return new OpenCodeCliRuntime();
 		default: throw new Error(`Unknown runtime provider "${provider}". Supported providers: ${SUPPORTED_PROVIDERS.join(", ")}`);
 	}
 }
@@ -11231,6 +12078,8 @@ var ChannelBridge = class {
 	#workspaceDir;
 	#chunkLimit;
 	#mcpServerPath;
+	#runtimeArgs;
+	#runtimeEnv;
 	constructor(options) {
 		this.#provider = options.provider;
 		this.#sessionMap = options.sessionMap;
@@ -11239,6 +12088,8 @@ var ChannelBridge = class {
 		this.#workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
 		this.#chunkLimit = options.chunkLimit;
 		this.#mcpServerPath = options.mcpServerPath ?? DEFAULT_MCP_SERVER_PATH;
+		this.#runtimeArgs = options.runtimeArgs;
+		this.#runtimeEnv = options.runtimeEnv;
 	}
 	/**
 	* Process an incoming channel message through the full agent execution pipeline.
@@ -11248,7 +12099,9 @@ var ChannelBridge = class {
 	*/
 	async handle(message, callbacks, abortSignal) {
 		const sessionKey = buildSessionKey(message);
+		logDebug(`[channel-bridge] handle: channel=${message.provider} from=${message.from} channelId=${message.channelId} threadId=${message.replyToId ?? "none"} agentId=${message.agentId ?? "default"} media=${message.mediaUrls?.length ?? 0}`);
 		const existingSessionId = await this.#sessionMap.get(sessionKey);
+		logDebug(`[channel-bridge] session lookup: key=${formatSessionKeyString(sessionKey)} ${existingSessionId ? `hit=${existingSessionId}` : "miss"}`);
 		const hookRunner = getGlobalHookRunner();
 		if (existingSessionId && hookRunner?.hasHooks("session_resumed")) await hookRunner.runSessionResumed({
 			sessionId: existingSessionId,
@@ -11275,9 +12128,10 @@ var ChannelBridge = class {
 		const sideEffectsFile = join(invocationDir, "side-effects.ndjson");
 		try {
 			const mcpServers = this.#buildMcpConfig(message, sessionKey, sideEffectsFile);
+			logDebug(`[channel-bridge] creating runtime: provider=${this.#provider}`);
 			const runtime = createCliRuntime(this.#provider);
 			let workspaceDir = this.#workspaceDir;
-			let extraEnv;
+			let hookEnv;
 			const runId = randomUUID();
 			if (hookRunner?.hasHooks("before_runtime_spawn")) {
 				const spawnResult = await hookRunner.runBeforeRuntimeSpawn({
@@ -11293,9 +12147,17 @@ var ChannelBridge = class {
 					channelId: message.channelId,
 					runtimeName: this.#provider
 				});
-				if (spawnResult?.workspaceDir) workspaceDir = spawnResult.workspaceDir;
-				if (spawnResult?.env) extraEnv = spawnResult.env;
+				if (spawnResult?.workspaceDir) {
+					logDebug(`[channel-bridge] hook overrode workspaceDir: ${this.#workspaceDir} -> ${spawnResult.workspaceDir}`);
+					workspaceDir = spawnResult.workspaceDir;
+				}
+				if (spawnResult?.env) {
+					logDebug(`[channel-bridge] hook injected env keys: ${Object.keys(spawnResult.env).join(", ")}`);
+					hookEnv = spawnResult.env;
+				}
 			}
+			const media = message.mediaUrls?.length ? await resolveMediaAttachments(message.mediaUrls, invocationDir) : void 0;
+			if (media?.length) logDebug(`[channel-bridge] resolved ${media.length}/${message.mediaUrls.length} media attachments`);
 			const adapter = new DeliveryAdapter(this.#chunkLimit !== void 0 ? { chunkLimit: this.#chunkLimit } : void 0);
 			let runResult;
 			let lastError;
@@ -11303,11 +12165,16 @@ var ChannelBridge = class {
 			try {
 				const captured = captureResult(runtime.execute({
 					prompt: systemPrompt + (message.extraContext ? "\n\n" + message.extraContext : "") + "\n\n" + message.text,
+					media: media?.length ? media : void 0,
 					sessionId: existingSessionId,
 					mcpServers,
 					abortSignal,
 					workingDirectory: workspaceDir,
-					env: extraEnv
+					env: this.#runtimeEnv || hookEnv ? {
+						...this.#runtimeEnv,
+						...hookEnv
+					} : void 0,
+					extraArgs: this.#runtimeArgs
 				}));
 				payloads = await adapter.process(captured.events, callbacks);
 				runResult = captured.getResult();
@@ -11315,6 +12182,7 @@ var ChannelBridge = class {
 			} catch (err) {
 				const errMsg = String(err);
 				const category = classifyError(errMsg);
+				logDebug(`[channel-bridge] runtime threw: category=${category} error=${errMsg.slice(0, 500)}`);
 				lastError = errMsg;
 				payloads = [];
 				runResult = {
@@ -11328,7 +12196,11 @@ var ChannelBridge = class {
 			} catch {
 				mcp = { ...EMPTY_SIDE_EFFECTS };
 			}
-			if (runResult?.sessionId) await this.#sessionMap.set(sessionKey, runResult.sessionId);
+			logDebug(`[channel-bridge] side effects: sentTexts=${mcp.sentTexts.length} sentMedia=${mcp.sentMediaUrls.length} cronAdds=${mcp.cronAdds}`);
+			if (runResult?.sessionId) {
+				logDebug(`[channel-bridge] session update: key=${formatSessionKeyString(sessionKey)} sessionId=${runResult.sessionId}`);
+				await this.#sessionMap.set(sessionKey, runResult.sessionId);
+			}
 			const finalResult = runResult ?? { ...DEFAULT_RUN_RESULT };
 			if (hookRunner) {
 				const runtimeCtx = {
@@ -11356,6 +12228,7 @@ var ChannelBridge = class {
 					durationMs: finalResult.durationMs
 				}, runtimeCtx);
 			}
+			logDebug(`[channel-bridge] complete: runId=${runId} duration=${finalResult.durationMs}ms payloads=${payloads.length} error=${lastError ?? "none"}`);
 			return {
 				payloads,
 				run: finalResult,
@@ -11517,4 +12390,4 @@ function resolveGatewayCredentialsFromConfig(params) {
 }
 
 //#endregion
-export { ChannelBridge, DEFAULT_MODEL, DEFAULT_PROVIDER, ensureAgentWorkspace, loadSessionStore, resolveAgentDir, resolveAgentIdentity, resolveAgentTimeoutMs, resolveAgentWorkspaceDir, resolveGatewayCredentialsFromConfig, resolveGatewayPort, resolveSessionFilePath, resolveStorePath, saveSessionStore };
+export { ChannelBridge, ensureAgentWorkspace, loadSessionStore, resolveAgentDir, resolveAgentIdentity, resolveAgentTimeoutMs, resolveAgentWorkspaceDir, resolveGatewayCredentialsFromConfig, resolveGatewayPort, resolveSessionFilePath, resolveStorePath, saveSessionStore };