@workerdeck/server 0.7.0 → 0.10.0

package/build/index.mjs

@@ -1,13 +1,12 @@
-import { createHash } from "node:crypto";
-import { closeSync, constants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { WebSocketServer } from "ws";
-import { listSessions } from "@anthropic-ai/claude-agent-sdk";
-import { BrowserBridgeExecutor, SessionRunner, checkClaudeAuth } from "@workerdeck/core";
+import { BrowserBridgeExecutor, SessionRunner, attachmentKind, checkClaudeAuth, getEngineAdapter, normalizeMediaType } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, supportsPermissionMode } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, supportsPermissionMode } from "@workerdeck/protocol";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 //#region src/host-files.ts
 /**
@@ -267,7 +266,8 @@ const DEFAULT_IGNORED_DIRS = [
 	".pytest_cache",
 	".gradle",
 	"Pods",
-	"DerivedData"
+	"DerivedData",
+	".build"
 ];
 /**
 * Breadth-first so shallow files rank first before scoring even runs — for a bare
@@ -364,6 +364,193 @@ function subsequenceScore(haystack, needle) {
 	return score - haystack.length / 100;
 }
 //#endregion
+//#region src/attachments.ts
+const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_SESSION_BYTES = 64 * 1024 * 1024;
+/**
+* Per-session hold for files the user attached to a message.
+*
+* In memory, and deliberately so. An attachment is only *needed* for the instant
+* between the upload and the message that names it; everything after that is
+* convenience (a client re-rendering a thumbnail after a reattach). That is the
+* same bargain `GET /sessions/:id/files` makes — the session's lifetime, no
+* durability tier — and it keeps the gateway from accumulating a photo library
+* on disk that nobody asked it to look after.
+*
+* Both caps are enforced here rather than at the route, so a host embedding the
+* server cannot forget one: a single file that is too big is a 413, and so is a
+* session whose total would go over.
+*/
+var AttachmentStore = class {
+	#bySession = /* @__PURE__ */ new Map();
+	#maxFileBytes;
+	#maxSessionBytes;
+	constructor(options = {}) {
+		this.#maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+		this.#maxSessionBytes = options.maxSessionBytes ?? DEFAULT_MAX_SESSION_BYTES;
+	}
+	get maxFileBytes() {
+		return this.#maxFileBytes;
+	}
+	put(sessionId, name, mediaType, body) {
+		if (body.length === 0) return {
+			ok: false,
+			error: {
+				code: "empty",
+				message: "attachment is empty"
+			}
+		};
+		if (body.length > this.#maxFileBytes) return {
+			ok: false,
+			error: {
+				code: "too_large",
+				message: `attachment is larger than the ${this.#maxFileBytes}-byte limit`
+			}
+		};
+		const type = normalizeMediaType(mediaType);
+		if (!attachmentKind(type)) return {
+			ok: false,
+			error: {
+				code: "unsupported_type",
+				message: `unsupported media type: ${type}`
+			}
+		};
+		const held = this.#bySession.get(sessionId) ?? /* @__PURE__ */ new Map();
+		const heldBytes = [...held.values()].reduce((sum, a) => sum + a.bytes, 0);
+		if (heldBytes + body.length > this.#maxSessionBytes) return {
+			ok: false,
+			error: {
+				code: "session_full",
+				message: `session is already holding ${heldBytes} bytes of attachments (limit ${this.#maxSessionBytes})`
+			}
+		};
+		const attachment = {
+			id: randomUUID(),
+			name: safeName(name),
+			mediaType: type,
+			bytes: body.length,
+			data: body.toString("base64")
+		};
+		held.set(attachment.id, attachment);
+		this.#bySession.set(sessionId, held);
+		return {
+			ok: true,
+			attachment: ref(attachment)
+		};
+	}
+	/** The stored record, bytes included — for the download route and for the send
+	* path that turns ids into content blocks. */
+	get(sessionId, id) {
+		return this.#bySession.get(sessionId)?.get(id);
+	}
+	/**
+	* Resolve the ids a `user_message` named, in the order given.
+	*
+	* Missing ids are reported rather than skipped: a message that quietly lost its
+	* picture reads as the model ignoring it, which is a far worse failure than a
+	* command that errors.
+	*/
+	resolve(sessionId, ids) {
+		const held = this.#bySession.get(sessionId);
+		const attachments = [];
+		const missing = [];
+		for (const id of ids) {
+			const found = held?.get(id);
+			if (found) attachments.push(found);
+			else missing.push(id);
+		}
+		return missing.length ? {
+			ok: false,
+			missing
+		} : {
+			ok: true,
+			attachments
+		};
+	}
+	drop(sessionId) {
+		this.#bySession.delete(sessionId);
+	}
+};
+function ref(attachment) {
+	return {
+		id: attachment.id,
+		name: attachment.name,
+		mediaType: attachment.mediaType,
+		bytes: attachment.bytes
+	};
+}
+/**
+* A display name, not a path. The name is echoed back to clients and put in front
+* of the model in the text-attachment envelope, so directory separators, control
+* characters and unbounded length all come off here.
+*/
+function safeName(name) {
+	const cleaned = (name.split(/[/\\]/).pop() ?? "").replace(/[\u0000-\u001f\u007f"<>]/g, "").trim();
+	if (cleaned === "" || cleaned === "." || cleaned === "..") return "attachment";
+	return cleaned.length > 120 ? cleaned.slice(0, 120) : cleaned;
+}
+//#endregion
+//#region src/produced-files.ts
+/**
+* The paths this gateway will serve from `GET /sessions/:id/produced/:fileId`.
+*
+* **This is the whole access-control model, so it is worth being precise about
+* what it is.** The store is an allowlist built from one source and one only:
+* `file_produced` events, which a runner emits about a file its own engine just
+* wrote. It is not a directory grant. Nothing else can add to it — not a
+* request, not a config, and in particular not the agent, whose own path claims
+* go through `/fs/*` and that route's root allowlist.
+*
+* That is why the route needs neither `hostFiles.roots` nor `maxFileBytes`:
+* "somewhere under a root the operator declared" is a guess about which paths
+* are safe, while "the exact path this session's runner reported producing" is
+* a fact about one file. A 2 MB generated PNG is the common case, and making
+* the operator raise a byte cap to see their own picture was the bug this
+* replaces.
+*
+* Lifetime is the session's, like `AttachmentStore`'s: in memory, dropped when
+* the session is removed. The bytes are never held here — only the path, so a
+* gateway serving a long session accumulates a few hundred bytes per picture
+* rather than the pictures.
+*/
+var ProducedFileStore = class {
+	#bySession = /* @__PURE__ */ new Map();
+	/**
+	* Register a runner's produced files for its lifetime.
+	*
+	* Subscribes from seq 0, which is the opposite of what `SessionNotifier` wants
+	* and correct for the same reason: registration is idempotent (a `fileId` is
+	* derived from its path, so re-registering overwrites with itself), and a
+	* session rebuilt from a park must re-learn every file it produced before the
+	* park — otherwise a client's transcript keeps rendering image cards whose
+	* bytes have quietly become unreachable.
+	*/
+	watch(runner) {
+		runner.subscribe((event) => {
+			if (event.type !== "file_produced") return;
+			const held = this.#bySession.get(runner.id) ?? /* @__PURE__ */ new Map();
+			held.set(event.fileId, {
+				fileId: event.fileId,
+				path: event.path,
+				...event.mediaType ? { mediaType: event.mediaType } : {},
+				...event.bytes !== void 0 ? { bytes: event.bytes } : {},
+				sessionId: runner.id
+			});
+			this.#bySession.set(runner.id, held);
+		}, 0);
+	}
+	get(sessionId, fileId) {
+		return this.#bySession.get(sessionId)?.get(fileId);
+	}
+	/** Everything one session has produced, newest registration last. */
+	list(sessionId) {
+		return [...this.#bySession.get(sessionId)?.values() ?? []];
+	}
+	drop(sessionId) {
+		this.#bySession.delete(sessionId);
+	}
+};
+//#endregion
 //#region src/registry.ts
 /** In-memory session table. Terminal sessions stay listed until removed or the process exits. */
 var SessionRegistry = class {
@@ -1092,18 +1279,6 @@ function parseRecord(value) {
 }
 //#endregion
 //#region src/server.ts
-const defaultSdkSessionLister = async (options) => {
-	return (await listSessions(options)).map((s) => ({
-		sessionId: s.sessionId,
-		summary: s.summary,
-		lastModified: s.lastModified,
-		createdAt: s.createdAt,
-		customTitle: s.customTitle,
-		firstPrompt: s.firstPrompt,
-		gitBranch: s.gitBranch,
-		cwd: s.cwd
-	}));
-};
 function json(res, status, body) {
 	const payload = JSON.stringify(body);
 	res.writeHead(status, {
@@ -1123,6 +1298,18 @@ async function readJsonBody(req, maxBytes) {
 	if (size === 0) return {};
 	return JSON.parse(Buffer.concat(chunks).toString("utf8"));
 }
+/** Body as bytes, refusing anything over `maxBytes`. Attachments are the one
+* thing this server takes that isn't JSON. */
+async function readRawBody(req, maxBytes) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		size += chunk.length;
+		if (size > maxBytes) throw new Error("request body too large");
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks);
+}
 /**
 * Curated, view-only snapshot of a profile's config dir for GET /profiles/:name.
 * Best-effort: a missing or unparseable settings.json just omits the settings block.
@@ -1210,6 +1397,10 @@ function contentTypeFor(filename) {
 function isProviderProfile(profile) {
 	return profile.engine === "provider";
 }
+/** The engine a profile runs, absent meaning 'claude' (pre-provider profiles). */
+function engineOf(profile) {
+	return profile?.engine ?? "claude";
+}
 /** Where the CLI's own resolution lands for a given environment: an explicit
 * CLAUDE_CONFIG_DIR, else ~/.claude. */
 function cliConfigDir(env) {
@@ -1264,6 +1455,8 @@ function createWorkerServer(options = {}) {
 	const basePath = options.basePath ?? "/v1";
 	const fallback = options.fallback;
 	const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+	/** The engine's adapter, honoring the test-only `engines` override. */
+	const adapterFor = (engine) => options.engines?.[engine ?? "claude"] ?? getEngineAdapter(engine);
 	const hostBuildRunnerConfig = options.buildRunnerConfig ?? ((req) => req);
 	const declared = options.profiles ?? detectDefaultProfiles();
 	const declaredByName = new Map(declared.map((p) => [p.name, p]));
@@ -1277,10 +1470,13 @@ function createWorkerServer(options = {}) {
 		if (isProviderProfile(p)) {
 			if (!p.provider?.id) return `provider profile '${p.name}' is missing provider.id`;
 			if (!options.createEngineRunner) return `profile '${p.name}' uses engine 'provider' but no \`createEngineRunner\` was provided to build one`;
+		} else if (p.engine === "codex") {
+			if (p.codexHome && !existsSync(p.codexHome)) return `profile '${p.name}' codexHome does not exist: ${p.codexHome}`;
+			if (p.session?.instructions) return `profile '${p.name}' declares session.instructions, which the codex engine cannot deliver — put instructions in the target repo’s AGENTS.md instead`;
 		} else if (!p.configDir || !existsSync(p.configDir)) return `profile '${p.name}' configDir does not exist: ${p.configDir}`;
 		if (options.disableBypassPermissions && p.defaults?.permissionMode === "bypassPermissions") return `profile '${p.name}' defaults to bypassPermissions but disableBypassPermissions is set`;
 		const fallbackMode = p.defaults?.permissionMode;
-		if (fallbackMode && !supportsPermissionMode(p.engine, fallbackMode)) return `profile '${p.name}' defaults to permission mode '${fallbackMode}', which engine '${p.engine}' does not support (supported: ${PROVIDER_PERMISSION_MODES.join(", ")})`;
+		if (fallbackMode && !supportsPermissionMode(p.engine, fallbackMode)) return `profile '${p.name}' defaults to permission mode '${fallbackMode}', which engine '${engineOf(p)}' does not support (supported: ${adapterFor(engineOf(p)).capabilities.permissionModes.join(", ")})`;
 		return null;
 	};
 	for (const p of options.profiles ?? []) {
@@ -1304,6 +1500,31 @@ function createWorkerServer(options = {}) {
 		...p,
 		managed: true
 	};
+	/**
+	* Response shape for a profile: the managed marker, the engine's capability
+	* record, its static model catalog (correct from the first request — no
+	* warm-up session, no process spawned), the availability verdict when one
+	* has been probed, and the learned default model (the one thing a static
+	* catalog cannot know: a claude profile's default is the operator's CLI
+	* config, so it stays absent until a session on the profile reports it).
+	* Read-only decoration — never persisted.
+	*/
+	const forResponse = (p) => {
+		const adapter = adapterFor(p.engine);
+		const base = {
+			...withManagedFlag(p),
+			capabilities: adapter.capabilities
+		};
+		if (adapter.catalog.models.length > 0) base.models = adapter.catalog.models;
+		const defaultModel = profileDefaultModels.get(p.name);
+		if (defaultModel) base.defaultModel = defaultModel;
+		const probed = availability.get(p.name)?.verdict;
+		if (probed && probed.available !== "unknown") {
+			base.available = probed.available;
+			if (probed.available === false) base.unavailableReason = probed.reason;
+		}
+		return base;
+	};
 	/** Declared profiles first: a name collision means the code wins, and the stored
 	* one is unreachable rather than silently overriding server options. */
 	const allProfiles = () => [...declared, ...[...stored.values()].filter((p) => !declaredByName.has(p.name))];
@@ -1377,28 +1598,42 @@ function createWorkerServer(options = {}) {
 	* into 'default' by whatever assembles its runner. Returns an error message. */
 	const checkPermissionMode = (mode, profile) => {
 		if (mode === void 0 || supportsPermissionMode(profile?.engine, mode)) return null;
-		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${profile.engine}') — supported: ${PROVIDER_PERMISSION_MODES.join(", ")}`;
+		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${engineOf(profile)}') — supported: ` + adapterFor(profile?.engine).capabilities.permissionModes.join(", ");
 	};
 	/**
-	* Enforce the provider engine's grant rules on a create request. Two of them:
-	*
-	* - Capabilities narrow, never widen. A request may run with fewer than the
-	*   profile grants; naming one it doesn't is refused rather than quietly
-	*   downgraded, so a caller learns instead of wondering where the tool went.
-	* - MCP servers are the profile's to declare. MCP tools are authoritative —
-	*   server-side, with server credentials, never bridged — so honoring a
-	*   client-supplied server would let a caller point an authoritative tool
-	*   anywhere it liked. The profile names servers; the host holds their configs.
+	* Refuse the request fields the resolved profile's engine cannot honor —
+	* read off its capability record, so the create form's filtering and the
+	* API boundary can never disagree. Refusing beats coercing: a caller who
+	* asked for something the engine has no meaning for should be told, not
+	* left wondering where the option went. Also enforces the provider grant
+	* rules (capabilities narrow, never widen; MCP servers are the profile's to
+	* declare — MCP tools are authoritative, server-side, with server
+	* credentials, so honoring a client-supplied server would let a caller
+	* point an authoritative tool anywhere it liked).
 	*/
 	const checkEngineGrants = (req, profile) => {
+		const engine = engineOf(profile);
+		const caps = adapterFor(profile?.engine).capabilities;
+		const name = profile?.name ?? "default";
+		if (!caps.sessionMcpServers && req.mcpServers && Object.keys(req.mcpServers).length > 0) return `profile '${name}' runs the ${engine} engine, whose MCP servers are declared outside the session request — a request cannot add its own`;
+		if (!caps.budgets && (req.maxTurns !== void 0 || req.maxBudgetUsd !== void 0)) return `the ${engine} engine does not honor maxTurns/maxBudgetUsd`;
+		if (!caps.settingSources && req.settingSources !== void 0) return `the ${engine} engine does not load settingSources`;
+		if (!caps.resume && req.resume !== void 0) return `the ${engine} engine cannot resume a session`;
+		if (req.forkSession && engine !== "claude") return `the ${engine} engine cannot fork a resumed session`;
+		if (req.reasoningEffort !== void 0 && (!caps.reasoningEfforts || caps.reasoningEfforts.length === 0)) return `the ${engine} engine does not take a reasoningEffort`;
 		if (!profile || !isProviderProfile(profile)) return null;
-		if (req.mcpServers && Object.keys(req.mcpServers).length > 0) return `profile '${profile.name}' runs the provider engine, whose MCP servers are declared on the profile (session.mcpServers) — a session request cannot add its own`;
 		const granted = profile.session?.capabilities;
 		if (!req.capabilities || !granted) return null;
 		const ungranted = req.capabilities.filter((c) => !granted.includes(c));
 		if (ungranted.length === 0) return null;
 		return `profile '${profile.name}' does not grant: ${ungranted.join(", ")} (granted: ${granted.join(", ") || "none"}) — a request may narrow capabilities, not widen them`;
 	};
+	/** Drop request fields that are meaningless (not wrong) for the engine —
+	* today just `questionBehavior` where no approval channel exists, so job
+	* webhooks never grow phantom permission_requested expectations. */
+	const stripInertFields = (req, profile) => {
+		if (!adapterFor(profile?.engine).capabilities.interactiveApprovals) delete req.questionBehavior;
+	};
 	/** Profile-aware config hook: fill the profile's defaults into unset request fields,
 	* run the host hook, then pin CLAUDE_CONFIG_DIR — the profile wins even when the
 	* host hook set its own env (see `claudeSessionEnv` for the one case the pin is
@@ -1411,7 +1646,7 @@ function createWorkerServer(options = {}) {
 			model: req.model ?? profile.defaults?.model ?? profile.provider?.model,
 			permissionMode: req.permissionMode ?? profile.defaults?.permissionMode
 		});
-		if (isProviderProfile(profile)) return config;
+		if (engineOf(profile) !== "claude") return config;
 		const base = config.env ?? process.env;
 		const env = claudeSessionEnv(profile, base);
 		return env === base ? config : {
@@ -1435,8 +1670,11 @@ function createWorkerServer(options = {}) {
 			bridge,
 			restore
 		});
-		if (restore) throw new Error("the Claude engine cannot rebuild a parked session");
-		return new Promise((resolve) => resolve(registry.prepare(config)));
+		return adapterFor(profile?.engine).createRunner({
+			config,
+			profile,
+			restore
+		});
 	};
 	const createRunner = async (config) => {
 		const runner = registry.register(await buildRunner(config));
@@ -1483,7 +1721,26 @@ function createWorkerServer(options = {}) {
 		};
 	};
 	const notifier = new SessionNotifier(options.notifications ?? {});
-	const registry = new SessionRegistry({ onRegister: (runner) => notifier.watch(runner) });
+	/**
+	* What each claude profile's *default* model resolves to, learned from the
+	* `capabilities` events of sessions that ran on it. The model *list* is the
+	* adapter's static catalog now; the default is the one thing a catalog
+	* cannot know (it is the operator's CLI config), so it alone is still
+	* learned — and still absent on a cold server, the accepted regression.
+	*/
+	const profileDefaultModels = /* @__PURE__ */ new Map();
+	const producedFiles = new ProducedFileStore();
+	const registry = new SessionRegistry({ onRegister: (runner) => {
+		notifier.watch(runner);
+		producedFiles.watch(runner);
+		const profile = runner.info().profile;
+		if (!profile) return;
+		runner.subscribe((event) => {
+			if (event.type !== "capabilities" || !event.defaultModel) return;
+			profileDefaultModels.set(profile, event.defaultModel);
+		});
+	} });
+	const attachmentStore = new AttachmentStore(options.attachments);
 	const bridge = new BridgeHub({
 		...options.bridge,
 		onResult: (sessionId, executionId, result) => {
@@ -1556,31 +1813,70 @@ function createWorkerServer(options = {}) {
 		});
 	};
 	/**
-	* Probe each Claude profile's credentials the way its sessions will actually
-	* experience them: the env the real assembly path produces, so anything the
-	* host hook injects (a CLAUDE_CODE_OAUTH_TOKEN, say) counts as logged in.
-	* Provider profiles resolve credentials in the engine factory and are not
-	* probed. Fire-and-forget by design — see the `checkCredentials` option doc.
+	* Availability, per profile: the adapter's probe run over the env the real
+	* assembly path produces (so anything the host hook injects — a
+	* CLAUDE_CODE_OAUTH_TOKEN, say — counts as logged in). Cached, and served on
+	* `GET /profiles` as `available`/`unavailableReason`.
+	*
+	* Gated on `checkCredentials` like the old claude-only preflight (this is a
+	* library; `pnpm test` must spawn nothing unless a test injects fake
+	* adapters or probes). 'unknown' stays out of the cache's answers: a probe
+	* that couldn't run is not evidence of a missing login. **Display-only**
+	* downstream — session create against an unavailable profile still proceeds
+	* and fails with the engine's own error, because the probe can be stale in
+	* both directions and refusing on it would turn a probe bug into an outage.
 	*/
-	const preflightCredentials = () => {
+	const availability = /* @__PURE__ */ new Map();
+	const AVAILABILITY_TTL_MS = 6e4;
+	/** Profiles already warned about on the console, so re-probes don't spam. */
+	const availabilityWarned = /* @__PURE__ */ new Set();
+	const sessionEnvFor = (profile) => {
+		try {
+			return buildRunnerConfig({
+				cwd: process.cwd(),
+				profile: profile.name
+			}).env ?? process.env;
+		} catch {
+			return engineOf(profile) === "claude" ? claudeSessionEnv(profile, process.env) : process.env;
+		}
+	};
+	const probeProfile = (profile) => {
 		if (!options.checkCredentials) return;
 		const conf = options.checkCredentials === true ? {} : options.checkCredentials;
-		const probe = conf.probe ?? ((env) => checkClaudeAuth(env, { timeoutMs: conf.timeoutMs }));
-		for (const profile of allProfiles()) {
-			if (isProviderProfile(profile)) continue;
-			let env;
-			try {
-				env = buildRunnerConfig({
-					cwd: process.cwd(),
-					profile: profile.name
-				}).env ?? process.env;
-			} catch {
-				env = claudeSessionEnv(profile, process.env);
+		availability.set(profile.name, {
+			verdict: availability.get(profile.name)?.verdict ?? { available: "unknown" },
+			at: Date.now()
+		});
+		const adapter = adapterFor(profile.engine);
+		const claudeProbe = engineOf(profile) !== "claude" ? void 0 : conf.probe ?? (conf.timeoutMs !== void 0 ? (env) => checkClaudeAuth(env, { timeoutMs: conf.timeoutMs }) : void 0);
+		(claudeProbe ? claudeProbe(sessionEnvFor(profile)).then((status) => status === "logged_in" ? { available: true } : status === "logged_out" ? {
+			available: false,
+			reason: "no usable Claude credentials for this profile"
+		} : { available: "unknown" }) : adapter.checkAvailability(profile, sessionEnvFor(profile))).then((verdict) => {
+			availability.set(profile.name, {
+				verdict,
+				at: Date.now()
+			});
+			if (verdict.available === false && !availabilityWarned.has(profile.name)) {
+				availabilityWarned.add(profile.name);
+				console.warn(`[workerdeck] Profile '${profile.name}' is unavailable: ${verdict.reason} (\`checkCredentials: false\` disables this check)`);
 			}
-			probe(env).then((status) => {
-				if (status !== "logged_out") return;
-				console.warn(`[workerdeck] Profile '${profile.name}' (${profile.configDir}) has no usable Claude credentials: \`claude auth status\` reports logged out for the environment its sessions run with, so they will fail with "Not logged in". Log in under that dir (CLAUDE_CONFIG_DIR=${profile.configDir} claude auth login), inject a long-lived token via buildRunnerConfig (CLAUDE_CODE_OAUTH_TOKEN), or set ANTHROPIC_API_KEY. \`checkCredentials: false\` disables this check.`);
-			}).catch(() => {});
+			if (verdict.available === true) availabilityWarned.delete(profile.name);
+		}).catch(() => {});
+	};
+	/** Launch-time sweep, concurrent and fire-and-forget. */
+	const preflightCredentials = () => {
+		for (const profile of allProfiles()) probeProfile(profile);
+	};
+	/** Lazy re-probe on reads, so an operator who just ran `codex login` (or
+	* exported a key) sees the profile go green without a restart. Serves the
+	* cached verdict now; the refreshed one lands on the next request. */
+	const refreshAvailability = (profiles) => {
+		if (!options.checkCredentials) return;
+		const now = Date.now();
+		for (const profile of profiles) {
+			const cached = availability.get(profile.name);
+			if (!cached || now - cached.at > AVAILABILITY_TTL_MS) probeProfile(profile);
 		}
 	};
 	const authenticate = async (req) => {
@@ -1609,6 +1905,21 @@ function createWorkerServer(options = {}) {
 			id: decodeURIComponent(parts[0]),
 			permissionId: decodeURIComponent(parts[2])
 		};
+		if (parts.length <= 3 && parts[1] === "attachments") return {
+			id: decodeURIComponent(parts[0]),
+			attachments: true,
+			attachmentId: parts[2] === void 0 ? void 0 : decodeURIComponent(parts[2])
+		};
+		if (parts.length <= 3 && parts[1] === "produced") return {
+			id: decodeURIComponent(parts[0]),
+			produced: true,
+			producedFileId: parts[2] === void 0 ? void 0 : decodeURIComponent(parts[2])
+		};
+		if (parts.length <= 3 && parts[1] === "mcp") return {
+			id: decodeURIComponent(parts[0]),
+			mcp: true,
+			mcpServer: parts[2] === void 0 ? void 0 : decodeURIComponent(parts[2])
+		};
 		if (parts.length >= 2 && parts[1] === "files") {
 			const filePath = parts.slice(2).map(decodeURIComponent).join("/");
 			return {
@@ -1625,6 +1936,172 @@ function createWorkerServer(options = {}) {
 	const maxHostFileBytes = options.hostFiles?.maxFileBytes ?? 1024 * 1024;
 	const maxHostDirEntries = options.hostFiles?.maxEntries ?? 5e3;
 	/**
+	* `{basePath}/sessions/:id/attachments` — the files a client sends with a message.
+	*
+	* `POST ?name=<name>` takes the raw bytes as the body and the media type from
+	* the `content-type` header; there is no multipart parsing here on purpose, so
+	* a phone and a browser both upload with one plain request and this file stays
+	* dependency-free. `GET /:attachmentId` hands the bytes back for thumbnails.
+	*
+	* The download always answers `content-disposition: attachment` and `nosniff`,
+	* the same as `/files`: an upload is client-supplied content served from the
+	* gateway's own origin, and it must never render as a document there. (An
+	* `<img src>` is unaffected — disposition does not apply to subresources.)
+	*/
+	const handleAttachments = async (req, res, sessionId, session, attachmentId) => {
+		if (req.method === "POST" && attachmentId === void 0) {
+			const url = new URL(req.url ?? "/", "http://internal");
+			const mediaType = req.headers["content-type"];
+			if (!mediaType) {
+				json(res, 400, { error: "content-type header is required" });
+				return;
+			}
+			const accepted = (session.capabilities ?? ENGINE_CAPABILITIES[session.engine ?? "claude"]).attachments;
+			const kind = attachmentKind(mediaType);
+			if (kind && !accepted.includes(kind === "document" ? "pdf" : kind)) {
+				json(res, 415, { error: `the ${session.engine ?? "claude"} engine does not accept ${kind} attachments` });
+				return;
+			}
+			let body;
+			try {
+				body = await readRawBody(req, attachmentStore.maxFileBytes);
+			} catch {
+				json(res, 413, { error: "attachment is larger than the limit" });
+				return;
+			}
+			const result = attachmentStore.put(sessionId, url.searchParams.get("name") ?? "attachment", mediaType, body);
+			if (!result.ok) {
+				json(res, result.error.code === "unsupported_type" ? 415 : result.error.code === "empty" ? 400 : 413, { error: result.error.message });
+				return;
+			}
+			json(res, 201, { attachment: result.attachment });
+			return;
+		}
+		if (req.method === "GET" && attachmentId !== void 0) {
+			const found = attachmentStore.get(sessionId, attachmentId);
+			if (!found) {
+				json(res, 404, { error: "attachment not found" });
+				return;
+			}
+			const bytes = Buffer.from(found.data, "base64");
+			res.writeHead(200, {
+				"content-type": found.mediaType,
+				"content-length": bytes.length,
+				"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(found.name)}`,
+				"x-content-type-options": "nosniff"
+			});
+			res.end(bytes);
+			return;
+		}
+		json(res, 405, { error: "method not allowed" });
+	};
+	/**
+	* `{basePath}/sessions/:id/mcp` — the session's MCP servers, and the three
+	* things the CLI's own `/mcp` screen can do to one (reconnect, enable, disable).
+	*
+	* Every answer goes through `mcpStatusInfo`, which is where the servers' `env`
+	* and `headers` are dropped: reading this route must not be a way to read the
+	* operator's API tokens.
+	*/
+	const handleMcp = async (req, res, runner, serverName) => {
+		const listServers = async () => {
+			const servers = await runner.mcpServers?.();
+			if (!servers) {
+				json(res, 501, { error: "this session does not report MCP servers" });
+				return false;
+			}
+			json(res, 200, { servers });
+			return true;
+		};
+		if (req.method === "GET" && serverName === void 0) {
+			await listServers();
+			return;
+		}
+		if (req.method === "POST" && serverName !== void 0) {
+			const body = await readJsonBody(req, maxBodyBytes);
+			if (body?.action !== "reconnect" && body?.action !== "enable" && body?.action !== "disable") {
+				json(res, 400, { error: "action must be 'reconnect', 'enable' or 'disable'" });
+				return;
+			}
+			if (!(body.action === "reconnect" ? typeof runner.reconnectMcpServer === "function" : typeof runner.setMcpServerEnabled === "function")) {
+				json(res, 501, { error: `this session's engine cannot ${body.action} an MCP server` });
+				return;
+			}
+			try {
+				if (body.action === "reconnect") await runner.reconnectMcpServer?.(serverName);
+				else await runner.setMcpServerEnabled?.(serverName, body.action === "enable");
+			} catch (error) {
+				json(res, 400, { error: error instanceof Error ? error.message : "MCP action failed" });
+				return;
+			}
+			await listServers();
+			return;
+		}
+		json(res, 405, { error: "method not allowed" });
+	};
+	/**
+	* `{basePath}/sessions/:id/produced[/:fileId]` — files this session's ENGINE
+	* wrote on the host (codex's generated images), listed and served.
+	*
+	* The one route here with no root allowlist and no byte cap, and the comment
+	* on {@link ProducedFileStore} is the argument for why that is right rather
+	* than lax: the allowlist is the exact set of paths this session's own runner
+	* announced producing. It is emphatically NOT a hole in `/fs/*` — a path the
+	* *agent* named is not a produced file and never enters this store.
+	*
+	* Everything else matches the attachment download: `nosniff` and an attachment
+	* disposition, because these bytes are model-authored and must not render as a
+	* document on the gateway's origin. (`<img src>` is unaffected — disposition
+	* does not apply to subresources, which is the whole point.)
+	*/
+	const handleProducedFiles = async (req, res, sessionId, fileId) => {
+		if (req.method !== "GET") {
+			json(res, 405, { error: "method not allowed" });
+			return;
+		}
+		if (fileId === void 0) {
+			json(res, 200, { files: producedFiles.list(sessionId).map(({ fileId: id, path, mediaType, bytes }) => ({
+				fileId: id,
+				path,
+				...mediaType ? { mediaType } : {},
+				...bytes !== void 0 ? { bytes } : {}
+			})) });
+			return;
+		}
+		const found = producedFiles.get(sessionId, fileId);
+		if (!found) {
+			json(res, 404, { error: "no such produced file" });
+			return;
+		}
+		let stat;
+		try {
+			stat = statSync(found.path);
+		} catch {
+			json(res, 404, { error: "produced file is no longer on disk" });
+			return;
+		}
+		if (!stat.isFile()) {
+			json(res, 404, { error: "produced file is not a regular file" });
+			return;
+		}
+		const filename = basename(found.path) || "file";
+		res.writeHead(200, {
+			"content-type": found.mediaType ?? contentTypeFor(filename),
+			"content-length": stat.size,
+			"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`,
+			"x-content-type-options": "nosniff"
+		});
+		await new Promise((done) => {
+			const stream = createReadStream(found.path);
+			stream.on("error", () => {
+				res.destroy();
+				done();
+			});
+			stream.on("close", () => done());
+			stream.pipe(res);
+		});
+	};
+	/**
 	* `{basePath}/fs/*` — the operator's real tree. Authorized by the auth key alone
 	* and deliberately outside the agent permission flow: the caller is the operator.
 	*
@@ -1847,8 +2324,19 @@ function createWorkerServer(options = {}) {
 		}
 		json(res, 404, { error: "not found" });
 	};
-	const listSdkSessions = options.listSdkSessions ?? defaultSdkSessionLister;
-	const handleSdkSessions = async (req, res) => {
+	/**
+	* `GET /sdk-sessions`, engine-aware: `?profile=` names whose on-disk store to
+	* list, and the profile's engine adapter answers (for codex, over a
+	* short-lived `thread/list` child — no live session involved). Absent
+	* `profile`, the choice is implicit when the server declares exactly one
+	* profile (the resolveProfile rule); with several, the Claude engine's
+	* global store is listed — the pre-engine-aware behavior every existing
+	* caller already gets, kept because old clients cannot answer a new 400.
+	* The injectable `listSdkSessions` option predates the adapter layer and is
+	* honored for the claude engine only (existing tests and hosts wire it),
+	* exactly like the injectable claude auth probe.
+	*/
+	const handleSdkSessions = async (req, res, auth) => {
 		if (req.method !== "GET") {
 			json(res, 405, { error: "method not allowed" });
 			return;
@@ -1856,21 +2344,58 @@ function createWorkerServer(options = {}) {
 		const url = new URL(req.url ?? "/", "http://internal");
 		const dir = url.searchParams.get("dir") ?? void 0;
 		const roots = options.allowedCwdRoots;
-		if (roots && roots.length > 0) {
-			if (!dir) {
-				json(res, 400, { error: "dir is required when allowedCwdRoots is set" });
+		const limit = Number(url.searchParams.get("limit") ?? "") || void 0;
+		const offset = Number(url.searchParams.get("offset") ?? "") || void 0;
+		const requested = url.searchParams.get("profile") ?? void 0;
+		let profile;
+		if (requested !== void 0) {
+			const resolved = resolveProfile(requested, auth.allowedProfiles);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
 				return;
 			}
-			if (!cwdAllowed(dir, roots)) {
-				json(res, 403, { error: "dir is outside the allowed roots" });
+			profile = resolved.profile;
+		} else {
+			const all = allProfiles();
+			if (all.length === 1 && (!auth.allowedProfiles || auth.allowedProfiles.includes(all[0].name))) profile = all[0];
+		}
+		const adapter = adapterFor(profile?.engine);
+		if (!adapter.capabilities.listSessions) {
+			json(res, 400, { error: `profile '${profile?.name ?? "default"}' runs the ${engineOf(profile)} engine, which has no browsable session store` });
+			return;
+		}
+		const lister = engineOf(profile) === "claude" && options.listSdkSessions ? options.listSdkSessions : (params) => {
+			if (!adapter.listSessions) throw new Error(`the ${engineOf(profile)} engine does not implement session listing`);
+			return adapter.listSessions({
+				...params,
+				profile,
+				env: profile ? sessionEnvFor(profile) : process.env
+			});
+		};
+		try {
+			if (roots && roots.length > 0) if (dir) {
+				if (!cwdAllowed(dir, roots)) {
+					json(res, 403, { error: "dir is outside the allowed roots" });
+					return;
+				}
+			} else {
+				json(res, 200, { sdkSessions: withinRoots(await lister({}), roots, limit, offset) });
 				return;
 			}
+			json(res, 200, { sdkSessions: await lister({
+				dir,
+				limit,
+				offset
+			}) });
+		} catch (error) {
+			json(res, 500, { error: error instanceof Error ? error.message : "failed to list sessions" });
 		}
-		json(res, 200, { sdkSessions: await listSdkSessions({
-			dir,
-			limit: Number(url.searchParams.get("limit") ?? "") || void 0,
-			offset: Number(url.searchParams.get("offset") ?? "") || void 0
-		}) });
+	};
+	/** The sessions whose `cwd` is inside the roots, newest first, then paged. A
+	* summary with no `cwd` cannot be shown to be inside them, so it is dropped. */
+	const withinRoots = (sessions, roots, limit, offset = 0) => {
+		const allowed = sessions.filter((s) => s.cwd !== void 0 && cwdAllowed(s.cwd, roots)).sort((a, b) => b.lastModified - a.lastModified);
+		return limit === void 0 ? allowed.slice(offset) : allowed.slice(offset, offset + limit);
 	};
 	const handleJobs = async (req, res, pathname, auth) => {
 		if (!queue) {
@@ -1924,6 +2449,7 @@ function createWorkerServer(options = {}) {
 					json(res, 400, { error: badRequest });
 					return;
 				}
+				stripInertFields(body.session, resolved.profile);
 				body.session.profile = resolved.profile?.name;
 				try {
 					json(res, 201, { job: await queue.submit(body) });
@@ -2041,8 +2567,10 @@ function createWorkerServer(options = {}) {
 			const rest = pathname.slice((basePath + "/profiles").length).replace(/^\//, "");
 			if (rest === "") {
 				if (req.method === "GET") {
+					const visible = auth.allowedProfiles ? allProfiles().filter((p) => auth.allowedProfiles.includes(p.name)) : allProfiles();
+					refreshAvailability(visible);
 					json(res, 200, {
-						profiles: (auth.allowedProfiles ? allProfiles().filter((p) => auth.allowedProfiles.includes(p.name)) : allProfiles()).map(withManagedFlag),
+						profiles: visible.map(forResponse),
 						canManage: manageGuard(auth) === null
 					});
 					return;
@@ -2118,11 +2646,12 @@ function createWorkerServer(options = {}) {
 			return;
 		}
 		if (pathname === basePath + "/sdk-sessions") {
-			if (!(await authenticate(req)).ok) {
+			const auth = await authenticate(req);
+			if (!auth.ok) {
 				json(res, 401, { error: "unauthorized" });
 				return;
 			}
-			await handleSdkSessions(req, res);
+			await handleSdkSessions(req, res, auth);
 			return;
 		}
 		if (pathname.startsWith(basePath + "/fs/")) {
@@ -2173,6 +2702,7 @@ function createWorkerServer(options = {}) {
 					json(res, 400, { error: badRequest });
 					return;
 				}
+				stripInertFields(body, resolved.profile);
 				body.profile = resolved.profile?.name;
 				const runner = await createRunner(buildRunnerConfig(body));
 				watchAuthSource(runner);
@@ -2188,6 +2718,18 @@ function createWorkerServer(options = {}) {
 			json(res, 404, { error: "session not found" });
 			return;
 		}
+		if (route.attachments) {
+			await handleAttachments(req, res, route.id, runner?.info() ?? parked.info, route.attachmentId);
+			return;
+		}
+		if (route.mcp) {
+			if (!runner) {
+				json(res, 409, { error: "session is parked (wake it before asking about MCP)" });
+				return;
+			}
+			await handleMcp(req, res, runner, route.mcpServer);
+			return;
+		}
 		if (route.files) {
 			if (req.method !== "GET") {
 				json(res, 405, { error: "method not allowed" });
@@ -2224,6 +2766,10 @@ function createWorkerServer(options = {}) {
 			res.end(content);
 			return;
 		}
+		if (route.produced) {
+			await handleProducedFiles(req, res, route.id, route.producedFileId);
+			return;
+		}
 		if (route.permissionId) {
 			if (req.method !== "POST") {
 				json(res, 405, { error: "method not allowed" });
@@ -2253,6 +2799,8 @@ function createWorkerServer(options = {}) {
 			registry.remove(route.id);
 			bridge.remove(route.id);
 			await parking.discard(route.id);
+			attachmentStore.drop(route.id);
+			producedFiles.drop(route.id);
 			json(res, 200, { session: runner?.info() ?? {
 				...parked.info,
 				status: "closed"
@@ -2356,9 +2904,16 @@ function createWorkerServer(options = {}) {
 	};
 	const handleCommand = async (frame, runner) => {
 		switch (frame.type) {
-			case "user_message":
-				runner.sendMessage(frame.text);
+			case "user_message": {
+				if (!frame.attachmentIds?.length) {
+					runner.sendMessage(frame.text);
+					return;
+				}
+				const resolved = attachmentStore.resolve(runner.id, frame.attachmentIds);
+				if (!resolved.ok) throw new Error(`unknown attachment(s): ${resolved.missing.join(", ")}`);
+				runner.sendMessage(frame.text, resolved.attachments);
 				return;
+			}
 			case "permission_decision":
 				if (frame.behavior === "allow") runner.resolvePermission(frame.requestId, {
 					behavior: "allow",
@@ -2478,6 +3033,6 @@ function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profi
 	};
 }
 //#endregion
-export { BridgeHub, MemorySessionStore, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, toDurableRecord };
+export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map