@workerdeck/client 0.23.0 → 1.1.0

package/build/index.mjs

@@ -1,94 +1,39 @@
-//#region src/host-url.ts
-/** Normalized REST base for `WorkerDeckClient`, or undefined if unparseable. */
-function apiUrl(host) {
-	let text = host.baseUrl.trim();
-	while (text.endsWith("/")) text = text.slice(0, -1);
-	if (text === "") return void 0;
-	if (!text.includes("://")) text = "http://" + text;
-	if (!text.endsWith("/v1")) text += "/v1";
-	try {
-		new URL(text);
-	} catch {
-		return;
-	}
-	return text;
-}
+//#region src/lib/emitter.ts
 /**
-* Whether this gateway is the machine the caller runs on. Decided from the URL,
-* never by probing paths for existence — two checkouts of the same repo would
-* lie. In a remote development window the caller runs on the remote box, so
-* "loopback" correctly means *that* machine and its paths are real files there.
+* The handles' listener registry. A throwing listener must never stop the ones queued behind it:
+* these fire from a socket callback, where an escaping error would take the connection with it.
 */
-function isLoopbackHost(host) {
-	const api = apiUrl(host);
-	if (!api) return false;
-	try {
-		const { hostname } = new URL(api);
-		return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1" || hostname === "[::1]";
-	} catch {
-		return false;
+var Emitter = class {
+	#listeners = /* @__PURE__ */ new Map();
+	on(kind, listener) {
+		let set = this.#listeners.get(kind);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.#listeners.set(kind, set);
+		}
+		set.add(listener);
+		return () => set.delete(listener);
 	}
-}
-//#endregion
-//#region src/host-auth.ts
-/**
-* The `ClientOptions` a **browser** needs to reach a gateway that is not its own
-* origin.
-*
-* Here, beside `apiUrl`, for the same reason that is here: every host that lets
-* someone type a gateway address and a key has to present them identically, or
-* the same gateway works in one client and not another. It is browser-shaped on
-* purpose — a Node host (the VS Code extension) sends the key as a header on
-* both transports and needs none of this.
-*
-* Two transports, because a browser has no choice:
-*
-* - **REST** takes `Authorization: Bearer <key>`, like any service client.
-* - **WebSocket** takes `?key=<key>`, because a tab cannot put a header on an
-*   upgrade handshake and the gateway's cookie belongs to another origin. The
-*   CLI's auth accepts the key this way on upgrades *only*.
-*
-* The query-string transport is the weaker one and is worth naming: unlike a
-* header it is a permanent credential that lands in reverse-proxy access logs.
-* It is confined to the upgrade so what a leaked URL buys is one attach. If a
-* gateway later mints short-lived tickets, only the body of `buildWsUrl`
-* changes — callers of this function do not.
-*/
-function hostAuth(options) {
-	const { baseUrl, key } = options;
-	if (key === "") return {};
-	const wsRoot = baseUrl.replace(/^http/, "ws");
-	const withKey = (url) => `${url}${url.includes("?") ? "&" : "?"}key=${encodeURIComponent(key)}`;
-	return {
-		headers: { authorization: `Bearer ${key}` },
-		buildWsUrl: (sessionId, afterSeq) => withKey(`${wsRoot}/sessions/${encodeURIComponent(sessionId)}/ws?afterSeq=${afterSeq}`),
-		buildQueueWsUrl: () => withKey(`${wsRoot}/queue/ws`)
-	};
-}
-//#endregion
-//#region src/index.ts
-/**
-* A REST call the gateway refused, carrying the status alongside the message.
-*
-* An `Error` subclass on purpose: every existing `e instanceof Error` check and
-* every `e.message` read keeps working unchanged. The status is what lets a
-* caller tell "this server doesn't have that route" (404 — stop asking) from
-* "that file was too big" (413 — tell the user), which a message string can't.
-*/
-var WorkerDeckError = class extends Error {
-	status;
-	constructor(message, status) {
-		super(message);
-		this.name = "WorkerDeckError";
-		this.status = status;
+	emit(kind, payload) {
+		const set = this.#listeners.get(kind);
+		if (!set) return;
+		for (const listener of set) try {
+			listener(payload);
+		} catch {}
 	}
 };
+/** 500ms doubling from a zero-based attempt count, capped at 10s. */
+function reconnectDelay(retries) {
+	return Math.min(500 * 2 ** retries, 1e4);
+}
+//#endregion
+//#region src/session-handle.ts
 var SessionHandle = class {
 	sessionId;
 	#client;
 	#options;
 	#ws;
-	#listeners = /* @__PURE__ */ new Map();
+	#events = new Emitter();
 	#lastSeq;
 	#closed = false;
 	#retries = 0;
@@ -108,18 +53,8 @@ var SessionHandle = class {
 		return this.#lastSeq;
 	}
 	on(kind, listener) {
-		let set = this.#listeners.get(kind);
-		if (!set) {
-			set = /* @__PURE__ */ new Set();
-			this.#listeners.set(kind, set);
-		}
-		set.add(listener);
-		return () => set.delete(listener);
+		return this.#events.on(kind, listener);
 	}
-	/** Send a message, optionally naming attachments uploaded ahead of it with
-	* {@link WorkerDeckClient.uploadAttachment} (ids in the order they should reach
-	* the model). An unknown id fails the whole command — the server will not send a
-	* message that quietly lost its picture. */
 	send(text, attachmentIds) {
 		this.#sendFrame({
 			type: "user_message",
@@ -147,14 +82,6 @@ var SessionHandle = class {
 	interrupt() {
 		this.#sendFrame({ type: "interrupt" });
 	}
-	/**
-	* Reset the conversation in place: same session, empty context. The server
-	* answers with a `conversation_reset` event.
-	*
-	* Gate the affordance on `EngineCapabilities.clearContext` (absent = false)
-	* rather than calling this blindly — an engine or a server that cannot do it
-	* answers with an error frame, which is the wrong way for a user to find out.
-	*/
 	clearContext() {
 		this.#sendFrame({ type: "clear_context" });
 	}
@@ -164,14 +91,12 @@ var SessionHandle = class {
 			mode
 		});
 	}
-	/** Switch the model for subsequent responses; omit `model` for the default. */
 	setModel(model) {
 		this.#sendFrame({
 			type: "set_model",
 			model
 		});
 	}
-	/** Answer a bridged tool call (see the `toolCallRequest` event). */
 	sendToolCallResult(executionId, output, logs) {
 		this.#sendFrame({
 			type: "tool_call_result",
@@ -180,8 +105,6 @@ var SessionHandle = class {
 			logs
 		});
 	}
-	/** Report that a bridged tool call could not be executed. The failure is fed
-	* to the model as tool output, so the agent can adapt rather than stall. */
 	sendToolCallError(executionId, reason, error, logs) {
 		this.#sendFrame({
 			type: "tool_call_error",
@@ -191,34 +114,22 @@ var SessionHandle = class {
 			logs
 		});
 	}
-	/** Ask the server to terminate the session (the handle disconnects too). */
 	closeSession() {
 		this.#sendFrame({ type: "close" });
 		this.detach();
 	}
-	/** Skip the reconnect backoff and try again now — what a tab returning to the
-	* foreground should do, rather than sitting out the remaining delay. No-op
-	* while connected or after {@link SessionHandle.detach}. */
 	reconnectNow() {
 		if (this.#closed || this.#ws && this.#ws.readyState === 1) return;
 		clearTimeout(this.#connectTimer);
 		this.#retries = 0;
 		this.#connect();
 	}
-	/** Disconnect this handle without touching the session. */
 	detach() {
 		this.#closed = true;
 		clearTimeout(this.#connectTimer);
 		this.#ws?.close();
 		this.#ws = void 0;
 	}
-	#emit(kind, payload) {
-		const set = this.#listeners.get(kind);
-		if (!set) return;
-		for (const listener of set) try {
-			listener(payload);
-		} catch {}
-	}
 	#sendFrame(frame) {
 		const payload = JSON.stringify(frame);
 		if (this.#ws && this.#ws.readyState === 1) this.#ws.send(payload);
@@ -230,43 +141,40 @@ var SessionHandle = class {
 		this.#ws = ws;
 		ws.onopen = () => {
 			this.#retries = 0;
-			this.#emit("connectionChange", true);
+			this.#events.emit("connectionChange", true);
 			for (const payload of this.#outbox.splice(0)) ws.send(payload);
 		};
 		ws.onmessage = (msg) => {
 			const frame = JSON.parse(String(msg.data));
-			if (frame.type === "attached") this.#emit("attached", frame);
+			if (frame.type === "attached") this.#events.emit("attached", frame);
 			else if (frame.type === "event") {
 				if (frame.event.seq <= this.#lastSeq) return;
 				this.#lastSeq = frame.event.seq;
-				this.#emit("event", frame.event);
-			} else if (frame.type === "tool_call_request") this.#emit("toolCallRequest", frame);
-			else if (frame.type === "tool_call_canceled") this.#emit("toolCallCanceled", {
+				this.#events.emit("event", frame.event);
+			} else if (frame.type === "tool_call_request") this.#events.emit("toolCallRequest", frame);
+			else if (frame.type === "tool_call_canceled") this.#events.emit("toolCallCanceled", {
 				executionId: frame.executionId,
 				reason: frame.reason
 			});
-			else if (frame.type === "protocol_error") this.#emit("protocolError", frame.message);
+			else if (frame.type === "protocol_error") this.#events.emit("protocolError", frame.message);
 		};
 		ws.onclose = () => {
-			this.#emit("connectionChange", false);
+			this.#events.emit("connectionChange", false);
 			if (this.#closed || !this.#options.reconnect) return;
-			const delay = Math.min(500 * 2 ** this.#retries++, 1e4);
-			this.#emit("reconnectAttempt", this.#retries);
+			const delay = reconnectDelay(this.#retries++);
+			this.#events.emit("reconnectAttempt", this.#retries);
 			this.#connectTimer = setTimeout(() => this.#connect(), delay);
 		};
 		ws.onerror = () => {};
 	}
 };
-/**
-* Live view of the server's job queue over `{basePath}/queue/ws`. The stream is
-* read-only — submit/cancel stay on the REST methods. There is no replay: on
-* (re)connect, re-list jobs and treat the stream as updates from there.
-*/
+//#endregion
+//#region src/queue-handle.ts
 var QueueHandle = class {
 	#client;
 	#reconnect;
 	#ws;
-	#listeners = /* @__PURE__ */ new Map();
+	#events = new Emitter();
 	#closed = false;
 	#retries = 0;
 	#connectTimer;
@@ -276,13 +184,7 @@ var QueueHandle = class {
 		this.#connectTimer = setTimeout(() => this.#connect(), 0);
 	}
 	on(kind, listener) {
-		let set = this.#listeners.get(kind);
-		if (!set) {
-			set = /* @__PURE__ */ new Set();
-			this.#listeners.set(kind, set);
-		}
-		set.add(listener);
-		return () => set.delete(listener);
+		return this.#events.on(kind, listener);
 	}
 	detach() {
 		this.#closed = true;
@@ -290,38 +192,79 @@ var QueueHandle = class {
 		this.#ws?.close();
 		this.#ws = void 0;
 	}
-	#emit(kind, payload) {
-		const set = this.#listeners.get(kind);
-		if (!set) return;
-		for (const listener of set) try {
-			listener(payload);
-		} catch {}
-	}
 	#connect() {
 		if (this.#closed) return;
 		const ws = this.#client.openQueueSocket();
 		this.#ws = ws;
 		ws.onopen = () => {
 			this.#retries = 0;
-			this.#emit("connectionChange", true);
+			this.#events.emit("connectionChange", true);
 		};
 		ws.onmessage = (msg) => {
 			const frame = JSON.parse(String(msg.data));
 			if (frame.type === "queue_attached") {
-				this.#emit("attached", frame.stats);
-				this.#emit("stats", frame.stats);
-			} else if (frame.type === "job_event") this.#emit("event", frame.event);
-			else if (frame.type === "queue_stats") this.#emit("stats", frame.stats);
+				this.#events.emit("attached", frame.stats);
+				this.#events.emit("stats", frame.stats);
+			} else if (frame.type === "job_event") this.#events.emit("event", frame.event);
+			else if (frame.type === "queue_stats") this.#events.emit("stats", frame.stats);
 		};
 		ws.onclose = () => {
-			this.#emit("connectionChange", false);
+			this.#events.emit("connectionChange", false);
 			if (this.#closed || !this.#reconnect) return;
-			const delay = Math.min(500 * 2 ** this.#retries++, 1e4);
+			const delay = reconnectDelay(this.#retries++);
 			this.#connectTimer = setTimeout(() => this.#connect(), delay);
 		};
 		ws.onerror = () => {};
 	}
 };
+//#endregion
+//#region src/host-url.ts
+function apiUrl(host) {
+	let text = host.baseUrl.trim();
+	while (text.endsWith("/")) text = text.slice(0, -1);
+	if (text === "") return;
+	if (!text.includes("://")) text = "http://" + text;
+	if (!text.endsWith("/v1")) text += "/v1";
+	try {
+		new URL(text);
+	} catch {
+		return;
+	}
+	return text;
+}
+function isLoopbackHost(host) {
+	const api = apiUrl(host);
+	if (!api) return false;
+	try {
+		const { hostname } = new URL(api);
+		return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1" || hostname === "[::1]";
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/host-auth.ts
+function hostAuth(options) {
+	const { baseUrl, key } = options;
+	if (key === "") return {};
+	const wsRoot = baseUrl.replace(/^http/, "ws");
+	const withKey = (url) => `${url}${url.includes("?") ? "&" : "?"}key=${encodeURIComponent(key)}`;
+	return {
+		headers: { authorization: `Bearer ${key}` },
+		buildWsUrl: (sessionId, afterSeq) => withKey(`${wsRoot}/sessions/${encodeURIComponent(sessionId)}/ws?afterSeq=${afterSeq}`),
+		buildQueueWsUrl: () => withKey(`${wsRoot}/queue/ws`)
+	};
+}
+//#endregion
+//#region src/index.ts
+var WorkerDeckError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "WorkerDeckError";
+		this.status = status;
+	}
+};
 var WorkerDeckClient = class {
 	#options;
 	#fetch;
@@ -331,19 +274,6 @@ var WorkerDeckClient = class {
 		this.#fetch = options.fetchImpl ?? fetch.bind(globalThis);
 		this.#WebSocketImpl = options.WebSocketImpl ?? WebSocket;
 	}
-	/**
-	* Stable identity of the (gateway, principal) pair this client speaks as:
-	* the base URL plus the auth headers it sends, order-insensitively.
-	*
-	* Exists for client-side caches that must survive the client *instance*
-	* being rebuilt (a `useMemo` recreating it when a view switches gateways)
-	* without ever sharing an entry across gateways — a session id is unique
-	* only within one — or across credentials. Auth that rides outside
-	* `headers` (a same-origin cookie, a fetch shim adding the key host-side)
-	* is chosen per origin in every such host, so the base URL still separates
-	* principals there; an embedder whose principal varies some other way on
-	* one base URL should not key anything on this.
-	*/
 	get identityKey() {
 		const headers = Object.entries(this.#options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]);
 		headers.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
@@ -358,176 +288,75 @@ var WorkerDeckClient = class {
 	async getSession(id) {
 		return (await this.#call("GET", `/sessions/${encodeURIComponent(id)}`)).session;
 	}
-	/** Rename a session (or clear the name with `null`, restoring the derived
-	* title). 409 when the session is parked. */
 	async updateSession(id, patch) {
 		return (await this.#call("PATCH", `/sessions/${encodeURIComponent(id)}`, patch)).session;
 	}
 	async deleteSession(id) {
 		return (await this.#call("DELETE", `/sessions/${encodeURIComponent(id)}`)).session;
 	}
-	/** List the files currently in a session's scratch filesystem (deliverables the
-	* agent wrote; see the `file_delivered` event). 404s when the session's engine
-	* has no file store (Claude-engine sessions). */
 	async listSessionFiles(sessionId) {
 		return (await this.#call("GET", `/sessions/${encodeURIComponent(sessionId)}/files`)).files;
 	}
-	/** Download one session file as text. */
 	async fetchSessionFile(sessionId, path) {
-		const res = await this.#fetch(this.sessionFileUrl(sessionId, path), { headers: this.#options.headers });
-		if (!res.ok) throw new WorkerDeckError((await res.json().catch(() => ({}))).error ?? `GET file failed with ${res.status}`, res.status);
-		return await res.text();
-	}
-	/**
-	* Upload one file for the session, ahead of the message that will carry it.
-	* The returned `id` goes to {@link SessionHandle.send}.
-	*
-	* The body is the raw bytes — no multipart — so anything `fetch` accepts as a
-	* body works: a `File`/`Blob` from a picker, a `Uint8Array`, a string.
-	*/
+		return await (await this.#callRaw(this.sessionFileUrl(sessionId, path), { headers: this.#options.headers }, "GET file failed")).text();
+	}
 	async uploadAttachment(sessionId, file) {
 		const url = `${this.#options.baseUrl}/sessions/${encodeURIComponent(sessionId)}/attachments?name=${encodeURIComponent(file.name)}`;
-		const res = await this.#fetch(url, {
+		return (await (await this.#callRaw(url, {
 			method: "POST",
 			headers: {
 				...this.#options.headers,
 				"content-type": file.mediaType
 			},
 			body: file.data
-		});
-		if (!res.ok) throw new WorkerDeckError((await res.json().catch(() => ({}))).error ?? `upload failed with ${res.status}`, res.status);
-		return (await res.json()).attachment;
+		}, "upload failed")).json()).attachment;
 	}
-	/** Direct URL for an uploaded attachment — an `<img src>` on a cookie-authenticated
-	* same-origin server. Header-authenticated clients must fetch it themselves. */
 	attachmentUrl(sessionId, attachmentId) {
 		return `${this.#options.baseUrl}/sessions/${encodeURIComponent(sessionId)}/attachments/${encodeURIComponent(attachmentId)}`;
 	}
-	/**
-	* Direct URL for a file the session's ENGINE produced on the host — the
-	* `fileId` of a `file_produced` event. Same caveat as `attachmentUrl`: usable
-	* as an `<img src>` only where the credential is a same-origin cookie; a
-	* header-authenticated client (the phone) fetches it and makes its own blob.
-	*
-	* Unlike `/fs/read`, this needs no host-file roots and no raised byte cap —
-	* see the `file_produced` note in the protocol for why that is sound.
-	*/
 	producedFileUrl(sessionId, fileId) {
 		return `${this.#options.baseUrl}/sessions/${encodeURIComponent(sessionId)}/produced/${encodeURIComponent(fileId)}`;
 	}
-	/** Fetch a produced file's bytes. For clients that cannot put a credential on
-	* an `<img src>`. Throws {@link WorkerDeckError} with the response status —
-	* a 404 means the file is gone from disk, not that the route is missing. */
 	async readProducedFile(sessionId, fileId) {
-		const res = await this.#fetch(this.producedFileUrl(sessionId, fileId), { headers: { ...this.#options.headers } });
-		if (!res.ok) throw new WorkerDeckError((await res.json().catch(() => ({}))).error ?? `produced file request failed with ${res.status}`, res.status);
-		return await res.blob();
-	}
-	/**
-	* The URL behind a `ProjectIcon.image`. Session-scoped, like
-	* {@link producedFileUrl}: the fetch rides the same `canSee` gate as every
-	* other `/sessions/:id/*` route, and it takes **no path** — the gateway
-	* serves whatever its own discovery resolved for this session's cwd.
-	*/
+		return await (await this.#callRaw(this.producedFileUrl(sessionId, fileId), { headers: { ...this.#options.headers } }, "produced file request failed")).blob();
+	}
 	projectIconUrl(sessionId) {
 		return `${this.#options.baseUrl}/sessions/${encodeURIComponent(sessionId)}/project/icon`;
 	}
-	/**
-	* Fetch a project icon's bytes.
-	*
-	* Here rather than left to each client for the reason `readProducedFile`
-	* exists, plus one this route makes sharper: a VS Code webview has **no
-	* external `connect-src` at all**, so it cannot point an `<img src>` at a
-	* gateway even in principle — the bytes have to come back through a bridged
-	* fetch, which is exactly what this wraps. Three clients building the same
-	* URL from `baseUrl` was the other half of the argument.
-	*
-	* Cache the result by `ProjectIcon.image.hash`, never by session: two
-	* sessions in one project serve identical bytes, and the hash is on the wire
-	* precisely so a client fetches once per project.
-	*
-	* A 404 is the uniform "no icon" — no project, a glyph-only project, or an
-	* icon the gateway refused. It is deliberately not distinguishable, so treat
-	* it as "draw no image", never as an error worth reporting.
-	*/
 	async projectIcon(sessionId) {
-		const res = await this.#fetch(this.projectIconUrl(sessionId), { headers: { ...this.#options.headers } });
-		if (!res.ok) throw new WorkerDeckError((await res.json().catch(() => ({}))).error ?? `project icon request failed with ${res.status}`, res.status);
-		return await res.blob();
+		return await (await this.#callRaw(this.projectIconUrl(sessionId), { headers: { ...this.#options.headers } }, "project icon request failed")).blob();
 	}
-	/** The session's MCP servers and their tools, live from the engine. 501 when the
-	* session's engine has no MCP surface; 409 while the session is parked. */
 	async listMcpServers(sessionId) {
 		return (await this.#call("GET", `/sessions/${encodeURIComponent(sessionId)}/mcp`)).servers;
 	}
-	/** Reconnect, enable or disable one MCP server; answers with the refreshed list. */
 	async mcpServerAction(sessionId, serverName, action) {
 		return (await this.#call("POST", `/sessions/${encodeURIComponent(sessionId)}/mcp/${encodeURIComponent(serverName)}`, { action })).servers;
 	}
-	/** Direct download URL for a session file (e.g. an <a download> href). Carries
-	* no headers — on authenticated servers, use fetchSessionFile instead. */
 	sessionFileUrl(sessionId, path) {
 		const encoded = path.split("/").filter(Boolean).map(encodeURIComponent).join("/");
 		return `${this.#options.baseUrl}/sessions/${encodeURIComponent(sessionId)}/files/${encoded}`;
 	}
-	/** Resolve a pending permission over REST — the remote-controller counterpart of the
-	* WS `permission_decision` command (e.g. answering a job's AskUserQuestion from a
-	* webhook consumer; the request rides on job_progress deliveries). Throws if the
-	* request is unknown, already resolved, or expired. */
 	async resolvePermission(sessionId, requestId, decision) {
 		await this.#call("POST", `/sessions/${encodeURIComponent(sessionId)}/permissions/${encodeURIComponent(requestId)}`, decision);
 	}
-	/**
-	* Deliver the result of a deferred tool execution — the callback a remote
-	* worker (or a human) makes when the work a session parked on is done. The
-	* session is rehydrated if its runner was torn down, and the agent loop
-	* continues with this as the tool's output.
-	*
-	* Applied idempotently by `executionId`: a duplicate, or one racing the
-	* execution watchdog, resolves with `applied: false` instead of applying twice.
-	* Throws (404) when no session is waiting on that id.
-	*/
 	async submitExecutionResult(executionId, result) {
 		return await this.#call("POST", `/executions/${encodeURIComponent(executionId)}/result`, result);
 	}
-	/** List the profiles (named Claude Code config dirs) this server declares, filtered
-	* to what the caller may use. Feed a result's `name` to createSession({ profile }).
-	* Servers predating profiles 404 here — catch and treat as none declared. */
-	/** The profiles this caller may use, plus whether it may create new ones.
-	* Each profile carries `managed: true` when it is store-backed and therefore
-	* editable; profiles declared in server options are not. */
 	async listProfiles() {
 		return await this.#call("GET", "/profiles");
 	}
-	/** One profile plus a fresh, view-only snapshot of its config directory (settings,
-	* skills, agents, commands — env var names only, never values). */
 	async getProfile(name) {
 		return await this.#call("GET", `/profiles/${encodeURIComponent(name)}`);
 	}
-	/**
-	* Create a managed profile. Requires a server with a profile store and a
-	* principal allowed to manage profiles; 409 if the name is already taken by a
-	* managed or a startup-declared profile.
-	*/
 	async createProfile(profile) {
 		return (await this.#call("POST", "/profiles", profile)).profile;
 	}
-	/** Merge into a managed profile. The name is the route: profiles cannot be
-	* renamed, since sessions and jobs are already pinned to the old one. */
 	async updateProfile(name, patch) {
 		return (await this.#call("PATCH", `/profiles/${encodeURIComponent(name)}`, patch)).profile;
 	}
-	/** Delete a managed profile. Startup-declared profiles are refused (403) —
-	* they live in the server's options. */
 	async deleteProfile(name) {
 		await this.#call("DELETE", `/profiles/${encodeURIComponent(name)}`);
 	}
-	/** List an engine's on-disk sessions (for resume across server restarts).
-	* Feed a result's `sessionId` to createSession({ resume }) — under a profile
-	* of the same engine. `profile` names whose store to list (claude profiles →
-	* the Agent SDK store, codex profiles → CODEX_HOME threads); absent, the
-	* server resolves it implicitly when it declares exactly one profile, else
-	* lists the Claude engine's store. */
 	async listSdkSessions(params) {
 		const search = new URLSearchParams();
 		if (params?.dir) search.set("dir", params.dir);
@@ -537,28 +366,13 @@ var WorkerDeckClient = class {
 		const qs = search.size > 0 ? `?${search.toString()}` : "";
 		return (await this.#call("GET", `/sdk-sessions${qs}`)).sdkSessions;
 	}
-	/**
-	* The host directories this server will let a client browse, and whether it
-	* accepts writes. Servers without host-file access configured 404 here — catch
-	* and treat as "no file browser", the same way `listProfiles` handles an older
-	* server.
-	*
-	* These are operator-privileged routes: the auth key is the whole authorization
-	* story, and they bypass the agent permission flow entirely. See the protocol
-	* package's `HostFileRoot` for why that framing is deliberate.
-	*/
 	async listHostRoots() {
 		return await this.#call("GET", "/fs/roots");
 	}
-	/** One host directory, not recursive. Symlinks are reported as symlinks, never
-	* followed here — read one to find out whether it resolves somewhere allowed. */
 	async listHostDir(path) {
 		const qs = `?path=${encodeURIComponent(path)}`;
 		return await this.#call("GET", `/fs/list${qs}`);
 	}
-	/** Recursive fuzzy file search under one host directory — the `@file` picker's
-	* query. Cheap enough to call per keystroke: build directories are skipped and
-	* the walk is bounded, truncating rather than erroring. */
 	async findHostFiles(path, query = "", limit) {
 		const search = new URLSearchParams({
 			path,
@@ -567,23 +381,13 @@ var WorkerDeckClient = class {
 		if (limit !== void 0) search.set("limit", String(limit));
 		return await this.#call("GET", `/fs/find?${search.toString()}`);
 	}
-	/** Read one host file. Binary content comes back base64-encoded; the returned
-	* `hash` is what a later `writeHostFile` needs as its `expectedHash`. */
 	async readHostFile(path) {
 		const qs = `?path=${encodeURIComponent(path)}`;
 		return await this.#call("GET", `/fs/read${qs}`);
 	}
-	/**
-	* Write one host file, conditionally — always. Pass the `hash` from the read this
-	* edit is based on; a 409 means the agent (or anything else) changed the file
-	* underneath you, and the edit must be rebased rather than forced. Omit
-	* `expectedHash` only to create a file that does not exist yet.
-	*/
 	async writeHostFile(request) {
 		return await this.#call("PUT", "/fs/write", request);
 	}
-	/** Schedule a one-shot run. The returned job's `sessionId` (once running) can be
-	* fed to `attach()` to watch the run live. */
 	async createJob(request) {
 		return (await this.#call("POST", "/jobs", request)).job;
 	}
@@ -593,7 +397,6 @@ var WorkerDeckClient = class {
 	async getJob(id) {
 		return (await this.#call("GET", `/jobs/${encodeURIComponent(id)}`)).job;
 	}
-	/** Cancel a queued or running job. */
 	async cancelJob(id) {
 		return (await this.#call("DELETE", `/jobs/${encodeURIComponent(id)}`)).job;
 	}
@@ -603,58 +406,31 @@ var WorkerDeckClient = class {
 	attach(sessionId, options) {
 		return new SessionHandle(this, sessionId, options);
 	}
-	/** Stream the job queue live (requires the server to be configured with `queue`).
-	* Servers without a queue refuse the socket — check REST first or expect retries. */
 	attachQueue(options) {
 		return new QueueHandle(this, options);
 	}
-	/** @internal used by SessionHandle */
 	openSocket(sessionId, afterSeq, truncateResults = false, imageRefs = false) {
 		const query = `afterSeq=${afterSeq}` + (truncateResults ? "&truncateResults=1" : "") + (imageRefs ? "&imageRefs=1" : "");
 		const url = this.#options.buildWsUrl?.(sessionId, afterSeq, truncateResults, imageRefs) ?? `${this.#options.baseUrl.replace(/^http/, "ws")}/sessions/${encodeURIComponent(sessionId)}/ws?${query}`;
 		return new this.#WebSocketImpl(url);
 	}
-	/**
-	* The whole of a tool result whose replay delivered only its head.
-	*
-	* `toolUseId` is required and the gateway verifies it against the block: a
-	* woken dormant session has a fresh log with fresh seqs, so a `sourceSeq`
-	* cached across a gateway restart can name a different event, and being handed
-	* another tool's output under the row you pressed is the exact failure this
-	* feature exists to remove. A 404 here means "ask again with a fresh attach",
-	* not "empty".
-	*/
 	async toolResult(sessionId, seq, toolUseId, options) {
 		return await this.#call("GET", `/sessions/${encodeURIComponent(sessionId)}/events/${seq}/result?toolUseId=${encodeURIComponent(toolUseId)}` + (options?.imageRefs ? "&imageRefs=1" : ""));
 	}
-	/**
-	* One image part's bytes, addressed by the `image_ref` a replay delivered in
-	* its place.
-	*
-	* A `Blob` and not a URL, and that is the whole reason this method exists: an
-	* `<img src>` pointing at the gateway carries a credential in exactly one of
-	* this project's four clients (the dashboard's same-origin implicit host,
-	* where the cookie rides along). Everywhere else — an added cross-origin
-	* gateway on a Bearer header, the VS Code webview whose every byte crosses a
-	* postMessage bridge, iOS — the URL is unauthenticated and the picture is a
-	* broken icon. Fetched rather than pointed at, then handed to
-	* `URL.createObjectURL`; `readProducedFile` is the shipped precedent.
-	*
-	* A 404 means "ask again with a fresh attach": a woken dormant session has a
-	* fresh log with fresh seqs, and the gateway refuses a stale address rather
-	* than serving another call's pixels under the row you are looking at.
-	*/
 	async toolResultImage(sessionId, seq, toolUseId, partIndex) {
 		const path = `/sessions/${encodeURIComponent(sessionId)}/events/${seq}/result?toolUseId=${encodeURIComponent(toolUseId)}&part=${partIndex}`;
-		const res = await this.#fetch(`${this.#options.baseUrl}${path}`, { headers: { ...this.#options.headers } });
-		if (!res.ok) throw new WorkerDeckError((await res.json().catch(() => ({}))).error ?? `image part request failed with ${res.status}`, res.status);
-		return await res.blob();
+		return await (await this.#callRaw(`${this.#options.baseUrl}${path}`, { headers: { ...this.#options.headers } }, "image part request failed")).blob();
 	}
-	/** @internal used by QueueHandle */
 	openQueueSocket() {
 		const url = this.#options.buildQueueWsUrl?.() ?? `${this.#options.baseUrl.replace(/^http/, "ws")}/queue/ws`;
 		return new this.#WebSocketImpl(url);
 	}
+	/** The byte-serving routes' shared failure arm: `#call` owns the same rule for JSON routes. */
+	async #callRaw(url, init, failure) {
+		const res = await this.#fetch(url, init);
+		if (!res.ok) throw new WorkerDeckError((await res.json().catch(() => ({}))).error ?? `${failure} with ${res.status}`, res.status);
+		return res;
+	}
 	async #call(method, path, body) {
 		const res = await this.#fetch(`${this.#options.baseUrl}${path}`, {
 			method,