@workerdeck/server 0.6.0 → 0.9.0

package/build/index.mjs

@@ -1,13 +1,494 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
-import { dirname, join, resolve, sep } from "node:path";
+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
+/**
+* Built once at startup from operator config. Roots are canonicalized here
+* because resolution produces realpath'd targets: a root that is itself a
+* symlink (`/tmp` -> `/private/tmp` on macOS) would otherwise contain nothing.
+* A misdeclared root throws rather than silently guarding the wrong tree —
+* same stance as profile config dirs in server.ts. An empty list is legal and
+* refuses everything; "no roots means allow all" is `cwdAllowed`'s contract,
+* never this module's.
+*/
+function createHostFileRoots(roots) {
+	return { roots: roots.map((configured) => {
+		if (invalidRequest(configured)) throw new Error(`createHostFileRoots: root must be an absolute path: ${JSON.stringify(configured)}`);
+		let canonical;
+		try {
+			canonical = realpathSync(configured);
+		} catch {
+			throw new Error(`createHostFileRoots: root does not exist: ${configured}`);
+		}
+		if (!lstatSync(canonical).isDirectory()) throw new Error(`createHostFileRoots: root is not a directory: ${configured}`);
+		return {
+			configured,
+			canonical
+		};
+	}) };
+}
+function refuse(status, error) {
+	return {
+		ok: false,
+		status,
+		error
+	};
+}
+/** The uniform filesystem refusal — see the disclosure policy in the header.
+* The string is deliberately constant: a distinct message is as much an oracle
+* as a distinct status. */
+function notFound() {
+	return refuse(404, "not found");
+}
+/** NUL is rejected before any fs call — Node throws a TypeError on NUL paths,
+* and that must surface as a refusal, not a 500. Relative paths are refused
+* outright rather than resolved against a cwd this API never promised. */
+function invalidRequest(requested) {
+	return requested.length === 0 || requested.includes("\0") || !isAbsolute(requested);
+}
+/** Both sides are realpath output, so this is a pure lexical question — but a
+* bare prefix check gets the boundary wrong (`/x/app` would swallow
+* `/x/application`). `relative` answers it exactly: inside iff the walk from
+* root to candidate is empty or never has to leave through `..`. */
+function contained(rootCanonical, candidate) {
+	const rel = relative(rootCanonical, candidate);
+	return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function rootContaining(roots, canonical) {
+	return roots.roots.find((root) => contained(root.canonical, canonical));
+}
+/**
+* For read/list: the target must exist. realpath is handed the request whole —
+* no lexical `..` collapsing first, because `root/link/..` is lexically `root`
+* but physically the link target's parent, and only the physical answer is the
+* true one. Symlinks that canonicalize *inside* a root are followed and served:
+* containment is a property of the canonical target, not of the route to it —
+* the operator granted the whole subtree, so nothing new becomes reachable.
+*/
+function resolveExisting(roots, requested) {
+	if (invalidRequest(requested)) return refuse(403, "invalid path");
+	let canonical;
+	try {
+		canonical = realpathSync(requested);
+	} catch {
+		return notFound();
+	}
+	const root = rootContaining(roots, canonical);
+	if (!root) return notFound();
+	let target;
+	try {
+		target = lstatSync(canonical);
+	} catch {
+		return notFound();
+	}
+	if (target.isFile()) return {
+		ok: true,
+		path: canonical,
+		root: root.canonical,
+		kind: "file"
+	};
+	if (target.isDirectory()) return {
+		ok: true,
+		path: canonical,
+		root: root.canonical,
+		kind: "dir"
+	};
+	return refuse(403, "not a regular file or directory");
+}
+/**
+* For write: the target may not exist, so realpath cannot be asked directly.
+* An existing target reuses read semantics — writing *through* a symlink that
+* canonicalizes inside a root is allowed (`root/link -> root/real.txt` edits
+* real.txt), same reasoning as {@link resolveExisting}. A missing target
+* canonicalizes its immediate parent and re-checks: only the final component
+* may be new, and anything already sitting there — in practice a dangling
+* symlink — is refused, because open(2) with O_CREAT follows it and would
+* create the file wherever it points. That refusal is `not found`, not 403: a
+* link to an existing outside file already answers 404 via the exists branch,
+* so a distinct status for the dangling case would hand back exactly the
+* existence bit the uniform 404 exists to withhold.
+*/
+function resolveForWrite(roots, requested) {
+	if (invalidRequest(requested)) return refuse(403, "invalid path");
+	try {
+		const canonical = realpathSync(requested);
+		const root = rootContaining(roots, canonical);
+		if (!root) return notFound();
+		const target = lstatSync(canonical);
+		if (target.isDirectory()) return refuse(403, "is a directory");
+		if (!target.isFile()) return refuse(403, "not a regular file");
+		return {
+			ok: true,
+			path: canonical,
+			root: root.canonical,
+			kind: "file"
+		};
+	} catch {}
+	const base = basename(requested);
+	if (base === "" || base === "." || base === "..") return refuse(403, "invalid path");
+	let parent;
+	try {
+		parent = realpathSync(dirname(requested));
+	} catch {
+		return notFound();
+	}
+	const root = rootContaining(roots, parent);
+	if (!root) return notFound();
+	try {
+		if (!lstatSync(parent).isDirectory()) return notFound();
+	} catch {
+		return notFound();
+	}
+	const path = join(parent, base);
+	if (!contained(root.canonical, path)) return notFound();
+	try {
+		lstatSync(path);
+	} catch (err) {
+		if (err.code === "ENOENT") return {
+			ok: true,
+			path,
+			root: root.canonical,
+			kind: "file"
+		};
+		return notFound();
+	}
+	return notFound();
+}
+/** lstat semantics on purpose: a listing shows a symlink AS a symlink — the
+* server never follows one while rendering a directory. Following happens only
+* when the entry is itself requested, through {@link resolveExisting}, which
+* refuses it if it escapes. `readdir(withFileTypes)` already answers without
+* following, so this is classification, not I/O. */
+function entryKind(entry) {
+	if (entry.isSymbolicLink()) return "symlink";
+	if (entry.isFile()) return "file";
+	if (entry.isDirectory()) return "dir";
+	return "other";
+}
+const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const O_NONBLOCK = constants.O_NONBLOCK ?? 0;
+/**
+* The open half of the resolve→open discipline; pass `ResolveOutcome.path`,
+* never the requested string. O_NOFOLLOW turns a final component swapped for a
+* symlink inside the race window into ELOOP instead of a follow; O_NONBLOCK
+* makes a swapped-in fifo open instantly instead of parking the request until a
+* writer appears (it is inert for regular files); the fstat gate refuses
+* anything that is not a plain file before a byte is read — `/dev/zero` would
+* otherwise be an unbounded read.
+*/
+function readContained(path) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+	} catch (err) {
+		return err.code === "ENOENT" ? notFound() : refuse(403, "refused");
+	}
+	try {
+		if (!fstatSync(fd).isFile()) return refuse(403, "not a regular file");
+		return {
+			ok: true,
+			data: readFileSync(fd)
+		};
+	} catch {
+		return refuse(403, "refused");
+	} finally {
+		closeSync(fd);
+	}
+}
+/**
+* O_CREAT|O_NOFOLLOW refuses (ELOOP) a symlink planted at the final component
+* after resolve — the exact swap that would land the write at the link's
+* target. Truncation happens via ftruncate only AFTER the fd is proven to be a
+* regular file, so a swapped-in device or fifo is never truncated or written;
+* O_NONBLOCK turns the reader-less-fifo open from a hang into ENXIO.
+*/
+function writeContained(path, data) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | O_NOFOLLOW | O_NONBLOCK, 420);
+	} catch (err) {
+		return err.code === "ENOENT" ? notFound() : refuse(403, "refused");
+	}
+	try {
+		if (!fstatSync(fd).isFile()) return refuse(403, "not a regular file");
+		ftruncateSync(fd);
+		writeFileSync(fd, data);
+		return { ok: true };
+	} catch {
+		return refuse(403, "refused");
+	} finally {
+		closeSync(fd);
+	}
+}
+//#endregion
+//#region src/host-file-search.ts
+/**
+* The recursive half of the host-file routes: what `@file` autocomplete needs and
+* `/fs/list` deliberately isn't. Listing answers "what is in this directory"; this
+* answers "which file in this tree did you mean", which is a different query and a
+* different cost model.
+*
+* Kept out of `host-files.ts` on purpose. That module is the audited containment
+* core; this one walks *inside* an already-resolved, already-contained directory
+* and never resolves a path of its own. Its one security-relevant rule is that it
+* does not follow symlinks — see the walk below.
+*/
+/**
+* Directories a source tree keeps that nobody types `@` looking for, and that are
+* usually most of the entries on disk. Skipping them is what makes the walk cheap
+* enough to run per keystroke; the operator can replace the list via
+* `hostFiles.ignore`.
+*/
+const DEFAULT_IGNORED_DIRS = [
+	".git",
+	".hg",
+	".svn",
+	"node_modules",
+	".next",
+	".nuxt",
+	".svelte-kit",
+	".turbo",
+	".cache",
+	"dist",
+	"build",
+	"out",
+	"target",
+	".venv",
+	"venv",
+	"__pycache__",
+	".pytest_cache",
+	".gradle",
+	"Pods",
+	"DerivedData"
+];
+/**
+* Breadth-first so shallow files rank first before scoring even runs — for a bare
+* `@` that ordering *is* the ranking, and for a query it breaks ties the way a
+* person expects (`src/index.ts` over `src/a/b/c/index.ts`).
+*
+* Symlinks are skipped outright, as files and as directories. As directories it is
+* the difference between a bounded walk and an unbounded one (a cycle, or a link
+* to `/`); as files it keeps this function's output within the tree it was handed,
+* so nothing it offers can be a path that `resolveExisting` would later refuse.
+* A tree that genuinely lives behind symlinks is not autocompletable — an accepted
+* cost for not having to re-derive containment here.
+*/
+function searchFiles(base, options = {}) {
+	const limit = options.limit ?? 50;
+	const maxScanned = options.maxScanned ?? 2e4;
+	const ignore = new Set(options.ignore ?? DEFAULT_IGNORED_DIRS);
+	const needle = (options.query ?? "").toLowerCase();
+	const found = [];
+	const queue = [{
+		dir: base,
+		depth: 0
+	}];
+	let scanned = 0;
+	let exhausted = true;
+	while (queue.length > 0) {
+		const { dir, depth } = queue.shift();
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (++scanned > maxScanned) {
+				exhausted = false;
+				queue.length = 0;
+				break;
+			}
+			const kind = entryKind(entry);
+			if (kind === "dir") {
+				if (!ignore.has(entry.name)) queue.push({
+					dir: join(dir, entry.name),
+					depth: depth + 1
+				});
+				continue;
+			}
+			if (kind !== "file") continue;
+			const path = join(dir, entry.name);
+			const rel = relative(base, path);
+			const score = scoreMatch(rel, entry.name, needle);
+			if (score !== null) found.push({
+				file: {
+					path,
+					relative: rel
+				},
+				score,
+				depth
+			});
+		}
+	}
+	found.sort((a, b) => b.score - a.score || a.depth - b.depth || a.file.relative.length - b.file.relative.length || a.file.relative.localeCompare(b.file.relative));
+	return {
+		matches: found.slice(0, limit).map((f) => f.file),
+		truncated: !exhausted || found.length > limit
+	};
+}
+/**
+* Subsequence matching, like every `@`-picker worth using: `seslist` finds
+* `SessionListView.swift`. Returns null for no match.
+*
+* Scored so the two things people actually mean win — a hit in the filename beats
+* one buried in the directory path, and characters typed consecutively beat the
+* same characters scattered — rather than trying to be a ranking engine.
+*/
+function scoreMatch(relativePath, name, needle) {
+	if (needle === "") return 0;
+	const inName = subsequenceScore(name.toLowerCase(), needle);
+	if (inName !== null) return inName + 1e3;
+	return subsequenceScore(relativePath.toLowerCase(), needle);
+}
+function subsequenceScore(haystack, needle) {
+	let score = 0;
+	let from = 0;
+	let previous = -2;
+	for (const char of needle) {
+		const at = haystack.indexOf(char, from);
+		if (at === -1) return null;
+		if (at === previous + 1) score += 8;
+		if (at === 0) score += 4;
+		from = at + 1;
+		previous = at;
+	}
+	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/registry.ts
 /** In-memory session table. Terminal sessions stay listed until removed or the process exits. */
 var SessionRegistry = class {
@@ -736,18 +1217,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, {
@@ -767,6 +1236,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.
@@ -831,6 +1312,21 @@ const CONTENT_TYPES = {
 	xml: "application/xml; charset=utf-8",
 	svg: "image/svg+xml; charset=utf-8"
 };
+/** sha256 hex — the currency of the conditional-write protocol on `/fs/write`. */
+function hashBytes(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+* The file's text, or null if it isn't text. Decoding never fails in Node — invalid
+* bytes become U+FFFD — so the only honest test is a round trip: if re-encoding the
+* decoded string reproduces the original bytes, nothing was lost and the client can
+* safely edit and send it back. Anything else ships base64, which an editor can
+* refuse to open rather than silently corrupt on save.
+*/
+function asUtf8(bytes) {
+	const text = bytes.toString("utf8");
+	return Buffer.from(text, "utf8").equals(bytes) ? text : null;
+}
 function contentTypeFor(filename) {
 	return CONTENT_TYPES[filename.includes(".") ? filename.split(".").pop().toLowerCase() : ""] ?? "text/plain; charset=utf-8";
 }
@@ -839,6 +1335,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) {
@@ -893,6 +1393,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]));
@@ -906,10 +1408,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 ?? []) {
@@ -933,6 +1438,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))];
@@ -1006,28 +1536,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
@@ -1040,7 +1584,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 : {
@@ -1064,8 +1608,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));
@@ -1112,7 +1659,24 @@ 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 registry = new SessionRegistry({ onRegister: (runner) => {
+		notifier.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) => {
@@ -1185,31 +1749,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) => {
@@ -1238,6 +1841,16 @@ 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] === "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 {
@@ -1248,8 +1861,347 @@ function createWorkerServer(options = {}) {
 		}
 		return null;
 	};
-	const listSdkSessions = options.listSdkSessions ?? defaultSdkSessionLister;
-	const handleSdkSessions = async (req, res) => {
+	const hostFileRootPaths = options.hostFiles?.roots ?? options.allowedCwdRoots;
+	const hostFiles = hostFileRootPaths?.length ? createHostFileRoots(hostFileRootPaths) : null;
+	const hostFilesWritable = options.hostFiles?.write === true;
+	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;
+			}
+			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}/fs/*` — the operator's real tree. Authorized by the auth key alone
+	* and deliberately outside the agent permission flow: the caller is the operator.
+	*
+	* Every path in here goes through `host-files.ts` first, which canonicalizes and
+	* *then* re-checks containment. The naive prefix compare `cwdAllowed` does would
+	* be wrong at this door — the agent writes into these trees, and a symlink it
+	* created is a path the operator never typed.
+	*/
+	const handleHostFiles = async (req, res, pathname) => {
+		if (!hostFiles) {
+			json(res, 404, { error: "host file access is not configured on this server" });
+			return;
+		}
+		const route = pathname.slice((basePath + "/fs/").length);
+		const url = new URL(req.url ?? "/", "http://internal");
+		const requested = url.searchParams.get("path");
+		if (route === "roots") {
+			if (req.method !== "GET") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			json(res, 200, {
+				roots: hostFiles.roots.map(({ canonical }) => ({
+					path: canonical,
+					name: basename(canonical) || canonical
+				})),
+				canWrite: hostFilesWritable
+			});
+			return;
+		}
+		if (route === "find") {
+			if (req.method !== "GET") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (!requested) {
+				json(res, 400, { error: "path is required" });
+				return;
+			}
+			const resolved = resolveExisting(hostFiles, requested);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
+				return;
+			}
+			if (resolved.kind !== "dir") {
+				json(res, 400, { error: "not a directory" });
+				return;
+			}
+			const asked = Number(url.searchParams.get("limit") ?? "");
+			const limit = Number.isFinite(asked) && asked > 0 ? Math.min(asked, 200) : 50;
+			const result = searchFiles(resolved.path, {
+				query: url.searchParams.get("q") ?? "",
+				limit,
+				ignore: options.hostFiles?.ignore
+			});
+			json(res, 200, {
+				base: resolved.path,
+				...result
+			});
+			return;
+		}
+		if (route === "list" || route === "read") {
+			if (req.method !== "GET") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (!requested) {
+				json(res, 400, { error: "path is required" });
+				return;
+			}
+			const resolved = resolveExisting(hostFiles, requested);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
+				return;
+			}
+			if (route === "list") {
+				if (resolved.kind !== "dir") {
+					json(res, 400, { error: "not a directory" });
+					return;
+				}
+				let names;
+				try {
+					names = readdirSync(resolved.path, { withFileTypes: true });
+				} catch {
+					json(res, 403, { error: "directory is not readable" });
+					return;
+				}
+				const truncated = names.length > maxHostDirEntries;
+				const entries = names.slice(0, maxHostDirEntries).map((entry) => {
+					const path = join(resolved.path, entry.name);
+					const type = entryKind(entry);
+					let bytes;
+					let modifiedAt;
+					if (type === "file") try {
+						const s = lstatSync(path);
+						bytes = s.size;
+						modifiedAt = s.mtimeMs;
+					} catch {}
+					return {
+						name: entry.name,
+						path,
+						type,
+						bytes,
+						modifiedAt
+					};
+				});
+				entries.sort((a, b) => {
+					const rank = (t) => t === "dir" ? 0 : 1;
+					return rank(a.type) - rank(b.type) || a.name.localeCompare(b.name);
+				});
+				json(res, 200, {
+					path: resolved.path,
+					entries,
+					...truncated ? { truncated } : {}
+				});
+				return;
+			}
+			if (resolved.kind !== "file") {
+				json(res, 400, { error: "not a regular file" });
+				return;
+			}
+			let modifiedAt = 0;
+			try {
+				const stats = lstatSync(resolved.path);
+				if (stats.size > maxHostFileBytes) {
+					json(res, 413, { error: `file is larger than ${maxHostFileBytes} bytes` });
+					return;
+				}
+				modifiedAt = stats.mtimeMs;
+			} catch {
+				json(res, 404, { error: "not found" });
+				return;
+			}
+			const read = readContained(resolved.path);
+			if (!read.ok) {
+				json(res, read.status, { error: read.error });
+				return;
+			}
+			if (read.data.length > maxHostFileBytes) {
+				json(res, 413, { error: `file is larger than ${maxHostFileBytes} bytes` });
+				return;
+			}
+			const text = asUtf8(read.data);
+			json(res, 200, {
+				path: resolved.path,
+				content: text ?? read.data.toString("base64"),
+				encoding: text === null ? "base64" : "utf8",
+				bytes: read.data.length,
+				hash: hashBytes(read.data),
+				modifiedAt
+			});
+			return;
+		}
+		if (route === "write") {
+			if (req.method !== "PUT") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (!hostFilesWritable) {
+				json(res, 403, { error: "host file writes are not enabled on this server" });
+				return;
+			}
+			const body = await readJsonBody(req, maxBodyBytes);
+			if (!body.path || typeof body.path !== "string") {
+				json(res, 400, { error: "path is required" });
+				return;
+			}
+			if (typeof body.content !== "string") {
+				json(res, 400, { error: "content is required" });
+				return;
+			}
+			if (body.encoding !== void 0 && body.encoding !== "utf8" && body.encoding !== "base64") {
+				json(res, 400, { error: "encoding must be 'utf8' or 'base64'" });
+				return;
+			}
+			const resolved = resolveForWrite(hostFiles, body.path);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
+				return;
+			}
+			const next = Buffer.from(body.content, body.encoding ?? "utf8");
+			if (next.length > maxHostFileBytes) {
+				json(res, 413, { error: `content is larger than ${maxHostFileBytes} bytes` });
+				return;
+			}
+			const current = readContained(resolved.path);
+			if (!current.ok && current.status !== 404) {
+				json(res, current.status, { error: current.error });
+				return;
+			}
+			const existing = current.ok ? current.data : null;
+			if (existing && !body.expectedHash) {
+				json(res, 409, { error: "file exists — pass expectedHash to overwrite it" });
+				return;
+			}
+			if (existing && hashBytes(existing) !== body.expectedHash) {
+				json(res, 409, { error: "file changed on disk since it was read" });
+				return;
+			}
+			if (!existing && body.expectedHash) {
+				json(res, 409, { error: "file no longer exists" });
+				return;
+			}
+			const written = writeContained(resolved.path, next);
+			if (!written.ok) {
+				json(res, written.status, { error: written.error });
+				return;
+			}
+			let writtenAt = 0;
+			try {
+				writtenAt = lstatSync(resolved.path).mtimeMs;
+			} catch {}
+			json(res, 200, {
+				path: resolved.path,
+				bytes: next.length,
+				hash: hashBytes(next),
+				modifiedAt: writtenAt
+			});
+			return;
+		}
+		json(res, 404, { error: "not found" });
+	};
+	/**
+	* `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;
@@ -1257,21 +2209,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) {
@@ -1325,6 +2314,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) });
@@ -1442,8 +2432,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;
@@ -1519,11 +2511,20 @@ function createWorkerServer(options = {}) {
 			return;
 		}
 		if (pathname === basePath + "/sdk-sessions") {
+			const auth = await authenticate(req);
+			if (!auth.ok) {
+				json(res, 401, { error: "unauthorized" });
+				return;
+			}
+			await handleSdkSessions(req, res, auth);
+			return;
+		}
+		if (pathname.startsWith(basePath + "/fs/")) {
 			if (!(await authenticate(req)).ok) {
 				json(res, 401, { error: "unauthorized" });
 				return;
 			}
-			await handleSdkSessions(req, res);
+			await handleHostFiles(req, res, pathname);
 			return;
 		}
 		const route = parseRoute(req.url ?? "/");
@@ -1566,6 +2567,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);
@@ -1581,6 +2583,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" });
@@ -1646,6 +2660,7 @@ function createWorkerServer(options = {}) {
 			registry.remove(route.id);
 			bridge.remove(route.id);
 			await parking.discard(route.id);
+			attachmentStore.drop(route.id);
 			json(res, 200, { session: runner?.info() ?? {
 				...parked.info,
 				status: "closed"
@@ -1749,9 +2764,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",
@@ -1871,6 +2893,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, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map