@workerdeck/core 0.9.0 → 0.10.0

package/build/index.d.mts

@@ -1118,6 +1118,32 @@ type AppServerWebSearchItem = {
   type: 'webSearch';
   query: string;
 };
+/**
+ * A picture the model made with codex's built-in `image_gen` tool.
+ *
+ * `savedPath` is an absolute path on the **host** — by default under
+ * `$CODEX_HOME/generated_images/`, or inside the workspace when the model was
+ * told the asset belongs to the project. It is the only reference we get: the
+ * app-server never sends the bytes, and neither do we (the event log carries
+ * references, never base64 — see the protocol's note on attachments).
+ *
+ * `result` is an undocumented free-form string. Treated as untrusted length:
+ * short values are shown, anything long enough to be an encoded image is not.
+ */
+type AppServerImageGenerationItem = {
+  id: string;
+  type: 'imageGeneration';
+  status: string;
+  revisedPrompt?: string | null;
+  result: string;
+  savedPath?: string;
+};
+/** The model *looked at* an image on disk (`path`, host-absolute). */
+type AppServerImageViewItem = {
+  id: string;
+  type: 'imageView';
+  path: string;
+};
 /** The user's own message, echoed back as an item — dropped (the runner
  * already emitted its `user_message`). */
 type AppServerUserMessageItem = {
@@ -1125,7 +1151,7 @@ type AppServerUserMessageItem = {
   type: 'userMessage';
   content?: unknown;
 };
-type AppServerItem = AppServerAgentMessageItem | AppServerReasoningItem | AppServerCommandExecutionItem | AppServerFileChangeItem | AppServerMcpToolCallItem | AppServerWebSearchItem | AppServerUserMessageItem;
+type AppServerItem = AppServerAgentMessageItem | AppServerReasoningItem | AppServerCommandExecutionItem | AppServerFileChangeItem | AppServerMcpToolCallItem | AppServerWebSearchItem | AppServerImageGenerationItem | AppServerImageViewItem | AppServerUserMessageItem;
 /** The `Turn` object of `turn/started` / `turn/completed`. */
 type AppServerTurn = {
   id: string; /** 'inProgress' | 'completed' | 'failed' | 'interrupted' — open. */
@@ -1330,6 +1356,32 @@ declare class CodexRunner implements Runner {
   fail(message: string): void;
   close(reason?: 'client' | 'server' | 'error'): void;
   subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
+  /**
+   * The session's MCP servers, live from the binary.
+   *
+   * Two sources merged, because codex splits them: `mcpServerStatus/list` says
+   * what is configured and what each server exposes (including every tool's
+   * full JSON Schema, which the Agent SDK does not give us), and the
+   * `mcpServer/startupStatus/updated` notifications say which of them are
+   * actually up.
+   *
+   * Answers **before the session has connected**, over a throwaway child, for
+   * the same reason the skill list does: a codex session spawns nothing until
+   * it has work, and a panel that said "no MCP servers configured" until the
+   * first turn would be stating something false about the operator's config.
+   * The request blocks until the servers are enumerated (measured: complete on
+   * the very first call), so there is no half-populated answer to race.
+   *
+   * Resolves undefined only when there is genuinely nothing to say — the
+   * session is closed, or the child could not be spoken to. The route turns
+   * that into a 501.
+   *
+   * **Listing only.** There is no per-server reconnect or toggle on this
+   * transport — hence no `reconnectMcpServer`/`setMcpServerEnabled` here, and
+   * `ENGINE_CAPABILITIES.codex.mcpServerActions: false` so clients render the
+   * panel read-only instead of offering buttons that cannot work.
+   */
+  mcpServers(): Promise<McpServerStatusInfo[] | undefined>;
 }
 //#endregion
 //#region src/engines/codex/process.d.ts

package/build/index.mjs

@@ -1,10 +1,10 @@
 import { createRequire } from "node:module";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { getSessionMessages, listSessions, query } from "@anthropic-ai/claude-agent-sdk";
 import { ENGINE_CAPABILITIES, PROTOCOL_VERSION } from "@workerdeck/protocol";
 import { ToolLoopAgent, generateText, isStepCount, tool } from "ai";
 import { execFile, spawn } from "node:child_process";
-import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createVfs, runScript } from "@workerdeck/sandbox";
 import { z } from "zod";
 import { lookup } from "node:dns/promises";
@@ -2987,6 +2987,118 @@ const APPROVAL_POLICY_BY_MODE = {
 * default, so unattended codex sessions land the same way Claude ones do. */
 const DEFAULT_APPROVAL_TIMEOUT_MS = 3e5;
 /**
+* Tool name for codex's built-in `image_gen`. A stable string because it is a
+* rendering contract: both clients key an icon (and, where they can reach the
+* host filesystem, an inline preview) off it.
+*/
+const CODEX_IMAGE_TOOL = "CodexImageGeneration";
+/** Longest `result` worth putting in a tool card. The field is free-form and
+* undocumented; anything past this is assumed to be an encoded image rather
+* than a sentence, and encoded images do not go in the event log. */
+const MAX_IMAGE_RESULT_CHARS = 512;
+const shortResult = (result) => result.length > 0 && result.length <= MAX_IMAGE_RESULT_CHARS && !result.startsWith("data:");
+/**
+* `file_produced.fileId` — derived from the path, not minted fresh.
+*
+* Two properties fall out of that and both are load-bearing: codex reports the
+* same `savedPath` on the progress item and again on the completed one, so a
+* derived id makes the second emission a no-op instead of a duplicate row; and
+* a session rebuilt from a snapshot re-derives the same ids, so a client's
+* cached URL still resolves after a park/restore.
+*/
+function producedFileId(path) {
+	return createHash("sha256").update(path).digest("hex").slice(0, 32);
+}
+/** Media type from the extension, for the handful a client renders inline.
+* Undefined for everything else — the route sniffs, and guessing here is how a
+* text file ends up labelled `image/png`. */
+function producedMediaType(path) {
+	return PRODUCED_MEDIA_TYPES[path.slice(path.lastIndexOf(".") + 1).toLowerCase()];
+}
+const PRODUCED_MEDIA_TYPES = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	svg: "image/svg+xml",
+	pdf: "application/pdf"
+};
+/**
+* Codex's `SkillMetadata` as the protocol states it. `interface.shortDescription`
+* beats the legacy top-level one (codex's own comment says to prefer it), and
+* `enabled` defaults to true — an entry codex listed without the field is one it
+* considers live, and defaulting to false would hide working skills.
+*/
+function skillInfo(skill) {
+	return {
+		name: skill.name,
+		...skill.description ? { description: skill.description } : {},
+		...skill.interface?.shortDescription ?? skill.shortDescription ? { shortDescription: skill.interface?.shortDescription ?? skill.shortDescription } : {},
+		...skill.interface?.displayName ? { displayName: skill.interface.displayName } : {},
+		...skill.interface?.defaultPrompt ? { defaultPrompt: skill.interface.defaultPrompt } : {},
+		...skill.scope ? { scope: skill.scope } : {},
+		enabled: skill.enabled !== false
+	};
+}
+/**
+* Codex's MCP status → the protocol's, which is Claude Code's vocabulary
+* ('connected' | 'failed' | 'needs-auth' | 'pending' | 'disabled').
+*
+* Two inputs, and the auth one wins where it applies: a server that started
+* fine but has no credential is *needs-auth*, not connected, because that is
+* the thing the operator has to act on. `notLoggedIn` is the only auth value
+* that means "unusable" — `unsupported` is the normal answer for a stdio server
+* that has no auth concept at all.
+*
+* A server with no startup notification yet is 'pending', not 'connected':
+* `mcpServerStatus/list` alone only proves it is *configured*.
+*/
+function mcpStatusOf(authStatus, update, hasTools) {
+	if (update?.status === "failed") return update.failureReason === "reauthenticationRequired" ? "needs-auth" : "failed";
+	if (update?.status === "cancelled") return "failed";
+	if (authStatus === "notLoggedIn") return "needs-auth";
+	if (update?.status === "ready") return "connected";
+	if (hasTools) return "connected";
+	return "pending";
+}
+/** One `mcpServerStatus/list` entry as the protocol states it. */
+function mcpServerInfo(server, update) {
+	const tools = Object.entries(server.tools ?? {}).flatMap(([key, tool]) => {
+		if (!tool) return [];
+		const annotations = tool.annotations;
+		return [{
+			name: tool.name ?? key,
+			...tool.description ? { description: tool.description } : {},
+			...tool.inputSchema !== void 0 ? { inputSchema: tool.inputSchema } : {},
+			...annotations ? { annotations: {
+				...annotations.readOnlyHint != null ? { readOnly: annotations.readOnlyHint } : {},
+				...annotations.destructiveHint != null ? { destructive: annotations.destructiveHint } : {},
+				...annotations.openWorldHint != null ? { openWorld: annotations.openWorldHint } : {}
+			} } : {}
+		}];
+	});
+	return {
+		name: server.name,
+		status: mcpStatusOf(server.authStatus ?? void 0, update, tools.length > 0),
+		...update?.error ? { error: update.error } : {},
+		...server.serverInfo?.name ? { serverInfo: {
+			name: server.serverInfo.name,
+			version: server.serverInfo.version ?? ""
+		} } : {},
+		...tools.length > 0 ? { tools } : {}
+	};
+}
+/** What the card shows while the picture is being made, and after. `savedPath`
+* only exists once it lands — a client keys its preview off it, so it is a
+* field rather than a sentence in the result text. */
+function imageGenerationInput(item) {
+	return {
+		...item.revisedPrompt ? { prompt: item.revisedPrompt } : {},
+		...item.savedPath ? { savedPath: item.savedPath } : {}
+	};
+}
+/**
 * The experimental per-request decision list, normalized to names: a string
 * entry is its own name, a structured entry (`{acceptWithExecpolicyAmendment:
 * …}`) is named by its key. Undefined = the request stated no list and the
@@ -3246,6 +3358,21 @@ var CodexRunner = class {
 	/** Set around history replay: {@link #emit} stamps `replay: true` onto the
 	* message events the live item mapping produces. */
 	#replayingHistory = false;
+	/** Last `skills` payload emitted, serialized — the comparison that keeps a
+	* `skills/changed` storm (the watcher fires per touched file) from filling
+	* the event log with identical lists. */
+	#skillsFingerprint;
+	/** In-flight `skills/list`, so a burst of `skills/changed` makes one call.
+	* The pending promise is reused rather than queued: the request has no
+	* arguments, so a second one would ask the same question. */
+	#skillsRefresh;
+	/** Host paths already announced via `file_produced`, so the same picture
+	* reported on both the progress and the completed item registers once. */
+	#producedPaths = /* @__PURE__ */ new Set();
+	/** Per-server liveness, accumulated from `mcpServer/startupStatus/updated`.
+	* `mcpServerStatus/list` does not carry a status field at all, so without
+	* this every server would read as "configured" and never as up or down. */
+	#mcpStatus = /* @__PURE__ */ new Map();
 	constructor(config, id = randomUUID()) {
 		const mode = config.permissionMode ?? "default";
 		if (!ENGINE_CAPABILITIES.codex.permissionModes.includes(mode)) throw new Error(`permission mode '${mode}' is not supported by the codex engine`);
@@ -3317,8 +3444,62 @@ var CodexRunner = class {
 			this.#turnChain = this.#turnChain.then(() => this.#backfillHistory());
 		} else this.#setStatus("idle");
 		if (this.#config.prompt) this.sendMessage(this.#config.prompt);
+		if (!this.#config.prompt && !this.#config.resume) this.#probeSkills();
 		return this.#turnChain;
 	}
+	/**
+	* List skills over a **throwaway** connection, for a session with nothing else
+	* to do yet.
+	*
+	* `skills/list` needs a live child but not a thread, so this spawns one, asks,
+	* and closes it — rather than bringing up the session's own child early and
+	* leaving a codex process parked behind every session someone created and
+	* never typed into. The session's real connection re-lists when it arrives;
+	* the fingerprint compare in {@link #refreshSkills} makes that a no-op.
+	*
+	* Entirely best-effort and never awaited: a missing binary, a failed spawn or
+	* a rejected handshake here must not turn a session that has not started into
+	* a session that failed.
+	*/
+	async #probeSkills() {
+		let connection;
+		try {
+			connection = await this.#openScratchConnection();
+			if (this.#closed) return;
+			await this.#refreshSkills(connection);
+		} catch {} finally {
+			connection?.close();
+		}
+	}
+	/**
+	* A handshaken child that is **not** the session's — for the questions a
+	* client can ask before the session has anything to run (its skills, its MCP
+	* servers). The caller owns it and must close it.
+	*
+	* No onNotification/onRequest/onClose wiring on purpose: this child answers
+	* one question and goes away, so its notifications are noise and its death is
+	* not the session's problem. The alternative — bringing the session's real
+	* child up early — would park a codex process behind every session someone
+	* created and never typed into.
+	*/
+	async #openScratchConnection() {
+		const connection = this.#config.connectFn({ env: this.#childEnv() });
+		try {
+			await connection.request("initialize", {
+				clientInfo: {
+					name: "workerdeck",
+					title: "WorkerDeck",
+					version: `protocol-${PROTOCOL_VERSION}`
+				},
+				capabilities: { experimentalApi: true }
+			});
+			connection.notify("initialized");
+			return connection;
+		} catch (error) {
+			connection.close();
+			throw error;
+		}
+	}
 	sendMessage(text, attachments) {
 		if (this.#closed) throw new Error("session is closed");
 		const input = this.#buildInput(text, attachments ?? []);
@@ -3534,9 +3715,117 @@ var CodexRunner = class {
 			};
 			this.#threadLoaded = true;
 		}
+		this.#refreshSkills(connection);
 		return connection;
 	}
 	/**
+	* Re-read `skills/list` and publish it, if it changed.
+	*
+	* **`cwds` is passed explicitly, and must be.** The schema documents the empty
+	* case as "the current session working directory", which reads like the
+	* thread's — it is not. Measured against 0.146.0: with no `cwds`, and *after*
+	* a `thread/start` carrying this session's cwd, the response comes back keyed
+	* to the app-server child's own process directory (for WorkerDeck, wherever
+	* the gateway was launched) and reports no repo-scoped skills at all. So a
+	* project's own `.codex/skills/**` were invisible until this argument existed.
+	*
+	* Best-effort throughout. A binary too old to know the method, a broken
+	* manifest, a child that died mid-call — none of that is worth failing a
+	* session over, and the panel simply stays absent.
+	*/
+	async #refreshSkills(connection) {
+		if (this.#skillsRefresh) return this.#skillsRefresh;
+		const run = (async () => {
+			try {
+				const result = await connection.request("skills/list", { cwds: [this.#config.cwd] });
+				if (this.#closed) return;
+				const entries = Array.isArray(result?.data) ? result.data : [];
+				const seen = /* @__PURE__ */ new Set();
+				const skills = [];
+				for (const entry of entries) for (const skill of entry?.skills ?? []) {
+					if (typeof skill?.name !== "string" || seen.has(skill.name)) continue;
+					seen.add(skill.name);
+					skills.push(skillInfo(skill));
+				}
+				skills.sort((a, b) => a.name.localeCompare(b.name));
+				const fingerprint = JSON.stringify(skills);
+				if (fingerprint === this.#skillsFingerprint) return;
+				this.#skillsFingerprint = fingerprint;
+				this.#emit({
+					type: "skills",
+					skills
+				});
+			} catch {} finally {
+				this.#skillsRefresh = void 0;
+			}
+		})();
+		this.#skillsRefresh = run;
+		return run;
+	}
+	/**
+	* The session's MCP servers, live from the binary.
+	*
+	* Two sources merged, because codex splits them: `mcpServerStatus/list` says
+	* what is configured and what each server exposes (including every tool's
+	* full JSON Schema, which the Agent SDK does not give us), and the
+	* `mcpServer/startupStatus/updated` notifications say which of them are
+	* actually up.
+	*
+	* Answers **before the session has connected**, over a throwaway child, for
+	* the same reason the skill list does: a codex session spawns nothing until
+	* it has work, and a panel that said "no MCP servers configured" until the
+	* first turn would be stating something false about the operator's config.
+	* The request blocks until the servers are enumerated (measured: complete on
+	* the very first call), so there is no half-populated answer to race.
+	*
+	* Resolves undefined only when there is genuinely nothing to say — the
+	* session is closed, or the child could not be spoken to. The route turns
+	* that into a 501.
+	*
+	* **Listing only.** There is no per-server reconnect or toggle on this
+	* transport — hence no `reconnectMcpServer`/`setMcpServerEnabled` here, and
+	* `ENGINE_CAPABILITIES.codex.mcpServerActions: false` so clients render the
+	* panel read-only instead of offering buttons that cannot work.
+	*/
+	async mcpServers() {
+		if (this.#closed) return void 0;
+		const live = this.#connection;
+		let scratch;
+		try {
+			return ((await (live ?? (scratch = await this.#openScratchConnection())).request("mcpServerStatus/list", {}))?.data ?? []).map((server) => mcpServerInfo(server, this.#mcpStatus.get(server.name)));
+		} catch {
+			return;
+		} finally {
+			scratch?.close();
+		}
+	}
+	/**
+	* Announce a file the ENGINE wrote on the host, so a client can fetch it
+	* without the operator having declared its directory as a host-file root.
+	*
+	* Deliberately narrow: only paths codex reports as *written by its own tool*
+	* belong here. A path the model merely read (`imageView`) is an agent-chosen
+	* claim, and those keep going through `/fs/*` and its root allowlist — see
+	* the note on `file_produced` in the protocol.
+	*/
+	#emitFileProduced(path, toolUseId) {
+		if (this.#producedPaths.has(path)) return;
+		this.#producedPaths.add(path);
+		let bytes;
+		try {
+			const stat = statSync(path);
+			if (stat.isFile()) bytes = stat.size;
+		} catch {}
+		this.#emit({
+			type: "file_produced",
+			fileId: producedFileId(path),
+			path,
+			...producedMediaType(path) ? { mediaType: producedMediaType(path) } : {},
+			...bytes !== void 0 ? { bytes } : {},
+			toolUseId
+		});
+	}
+	/**
 	* On resume, replay the thread's prior turns as `replay: true` events,
 	* seq'd before any live turn — the SessionRunner backfill contract, fed
 	* from `thread/resume`'s own `thread.turns`. When the resume response says
@@ -3751,6 +4040,21 @@ var CodexRunner = class {
 				active.contextWindow = update.tokenUsage?.modelContextWindow ?? void 0;
 				return;
 			}
+			case "mcpServer/startupStatus/updated": {
+				const update = params;
+				if (typeof update?.name !== "string") return;
+				this.#mcpStatus.set(update.name, {
+					status: typeof update.status === "string" ? update.status : "starting",
+					...update.error ? { error: update.error } : {},
+					...update.failureReason ? { failureReason: update.failureReason } : {}
+				});
+				return;
+			}
+			case "skills/changed": {
+				const connection = this.#connection;
+				if (connection) this.#refreshSkills(connection);
+				return;
+			}
 			case "account/rateLimits/updated":
 				this.#emitRateLimits(params?.rateLimits);
 				return;
@@ -3926,6 +4230,12 @@ var CodexRunner = class {
 		if (item.type === "mcpToolCall" && !active.toolUseEmitted.has(id)) {
 			active.toolUseEmitted.add(id);
 			this.#emitToolUse(id, `mcp__${item.server}__${item.tool}`, item.arguments);
+			return;
+		}
+		if (item.type === "imageGeneration" && !active.toolUseEmitted.has(id)) {
+			active.toolUseEmitted.add(id);
+			this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item));
+			if (item.savedPath) this.#emitFileProduced(item.savedPath, id);
 		}
 	}
 	#handleItemCompleted(item, active) {
@@ -3983,6 +4293,18 @@ var CodexRunner = class {
 				this.#emitToolUse(id, "CodexWebSearch", { query: item.query });
 				this.#emitToolResult(id, "", false);
 				return;
+			case "imageGeneration": {
+				active.toolUseEmitted.add(id);
+				this.#emitToolUse(id, CODEX_IMAGE_TOOL, imageGenerationInput(item));
+				if (item.savedPath) this.#emitFileProduced(item.savedPath, id);
+				const lines = [item.savedPath ? `Saved to ${item.savedPath}` : "No saved path reported", ...shortResult(item.result) ? [item.result] : []];
+				this.#emitToolResult(id, lines.join("\n"), item.status === "failed");
+				return;
+			}
+			case "imageView":
+				this.#emitToolUse(id, "CodexImageView", { path: item.path });
+				this.#emitToolResult(id, item.path, false);
+				return;
 			default: {
 				const unknown = item;
 				this.#emit({