@workerdeck/core 2.12.0 → 2.14.0

package/build/index.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { createHash, randomUUID } from "node:crypto";
 import { createSdkMcpServer, getSessionInfo, getSessionMessages, listSessions, query, tool } from "@anthropic-ai/claude-agent-sdk";
-import { CHECKLIST_TEXT_MAX, ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SUBAGENT_HISTORY, TOOL_RESULT_HEAD_CHARS, addTokenUsage, byModelTotalTokens, canonicalModel, contextReading, costOfByModel, emptyTokenUsage, imagePartRef, mergeByModel, parseTodoWriteInput, peerDeliveredPrefix, replayCoalesceKey, replayRetains, sanitizeToolTitle, snapshotRetains, tokenUsageFromWire, totalTokens, transcriptActivity, transcriptContent, transcriptProse } from "@workerdeck/protocol";
+import { CHECKLIST_TEXT_MAX, ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_CONTEXT_FLUSH_MAX_CHARS, SHELL_CONTEXT_HEAD_CHARS, SHELL_CONTEXT_HEAD_LINES, SHELL_CONTEXT_TAIL_CHARS, SHELL_CONTEXT_TAIL_LINES, SHELL_INLINE_CHARS, SHELL_INLINE_LINES, SHELL_INLINE_LINE_CHARS, SHELL_READ_DEFAULT_LINES, SHELL_READ_MAX_LINES, SUBAGENT_HISTORY, TOOL_RESULT_HEAD_CHARS, addTokenUsage, byModelTotalTokens, canonicalModel, contextReading, costOfByModel, emptyTokenUsage, imagePartRef, logCoalesceKey, mergeByModel, parseTodoWriteInput, peerDeliveredPrefix, replayCoalesceKey, replayRetains, sanitizeToolTitle, snapshotRetains, tokenUsageFromWire, totalTokens, transcriptActivity, transcriptContent, transcriptProse } from "@workerdeck/protocol";
 import { z } from "zod";
 import { ToolLoopAgent, generateText, isStepCount, tool as tool$1 } from "ai";
 import { execFile, spawn } from "node:child_process";
@@ -275,7 +275,110 @@ var InputQueue = class {
 	}
 };
 //#endregion
+//#region src/lib/tty-text.ts
+const OSC_SEQUENCE = /(?:\x1b\]|\x9d)[\s\S]*?(?:\x07|\x1b\\|\x9c)/g;
+const STRING_SEQUENCE = /(?:\x1b[PX^_]|[\x90\x98\x9e\x9f])[\s\S]*?(?:\x1b\\|\x9c)/g;
+const CSI_SEQUENCE = /(?:\x1b\[|\x9b)[0-?]*[ -/]*[@-~]/g;
+const ESCAPE_SEQUENCE = /\x1b[ -/]*[0-~]/g;
+const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+function ttyText(raw) {
+	return raw.replace(OSC_SEQUENCE, "").replace(STRING_SEQUENCE, "").replace(CSI_SEQUENCE, "").replace(ESCAPE_SEQUENCE, "").replace(CONTROL_CHARS, "").replace(/\r\n/g, "\n").split("\n").map((line) => overwritten(line).trimEnd()).join("\n");
+}
+function splitLines(text) {
+	if (text === "") return [];
+	return (text.endsWith("\n") ? text.slice(0, -1) : text).split("\n");
+}
+function countLines(text) {
+	if (text === "") return 0;
+	let count = 1;
+	for (let at = text.indexOf("\n"); at !== -1; at = text.indexOf("\n", at + 1)) count++;
+	return text.endsWith("\n") ? count - 1 : count;
+}
+function headTail(text, opts) {
+	const lines = splitLines(text);
+	const totalLines = lines.length;
+	const totalBytes = Buffer.byteLength(text, "utf8");
+	const body = lines.join("\n");
+	if (totalLines <= opts.headLines + opts.tailLines && body.length <= opts.headChars + opts.tailChars) return {
+		head: body,
+		tail: "",
+		omittedLines: 0,
+		totalLines,
+		totalBytes
+	};
+	const tail = takeTail(lines, Math.min(opts.tailLines, totalLines), opts.tailChars);
+	const head = takeHead(lines, Math.min(opts.headLines, totalLines - tail.lines), opts.headChars);
+	return {
+		head: head.text,
+		tail: tail.text,
+		omittedLines: totalLines - head.lines - tail.lines,
+		totalLines,
+		totalBytes
+	};
+}
+function overwritten(line) {
+	if (!line.includes("\r")) return line;
+	const segments = line.split("\r");
+	for (let i = segments.length - 1; i >= 0; i--) if (segments[i] !== "") return segments[i];
+	return "";
+}
+function takeHead(lines, maxLines, maxChars) {
+	let taken = 0;
+	let length = 0;
+	while (taken < maxLines) {
+		const next = length + lines[taken].length + (taken > 0 ? 1 : 0);
+		if (next > maxChars) break;
+		length = next;
+		taken++;
+	}
+	if (taken === 0) return {
+		text: maxLines > 0 ? lines[0].slice(0, maxChars) : "",
+		lines: 0
+	};
+	return {
+		text: lines.slice(0, taken).join("\n"),
+		lines: taken
+	};
+}
+function takeTail(lines, maxLines, maxChars) {
+	let taken = 0;
+	let length = 0;
+	while (taken < maxLines) {
+		const next = length + lines[lines.length - 1 - taken].length + (taken > 0 ? 1 : 0);
+		if (next > maxChars) break;
+		length = next;
+		taken++;
+	}
+	if (taken === 0) {
+		const last = lines[lines.length - 1];
+		return {
+			text: maxLines > 0 && maxChars > 0 ? last.slice(-maxChars) : "",
+			lines: 0
+		};
+	}
+	return {
+		text: lines.slice(lines.length - taken).join("\n"),
+		lines: taken
+	};
+}
+//#endregion
 //#region src/lib/local-command.ts
+const OUTPUT_POINTER = "the full output is in the transcript";
+const INLINE_MORE = "[... more output ...]";
+const INLINE_CLIPPED = " [...]";
+const INLINE_SCAN_CHARS = SHELL_INLINE_LINES * (SHELL_INLINE_LINE_CHARS + 1);
+const TAIL_ONLY = {
+	headLines: 0,
+	headChars: 0,
+	tailLines: SHELL_CONTEXT_TAIL_LINES,
+	tailChars: SHELL_CONTEXT_TAIL_CHARS
+};
+const HEAD_AND_TAIL = {
+	headLines: SHELL_CONTEXT_HEAD_LINES,
+	headChars: SHELL_CONTEXT_HEAD_CHARS,
+	tailLines: SHELL_CONTEXT_TAIL_LINES,
+	tailChars: SHELL_CONTEXT_TAIL_CHARS
+};
 const LOCAL_COMMAND_CAVEAT = "<local-command-caveat>Caveat: the messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>";
 function localCommandTranscript(result) {
 	const tag = result.exitCode === 0 ? "local-command-stdout" : "local-command-stderr";
@@ -294,6 +397,222 @@ function localCommandContext(pending) {
 function isSlashCommand(text) {
 	return /^\s*\/[A-Za-z]/.test(text);
 }
+function isLocalShellSource(input) {
+	return typeof input.subscribe === "function";
+}
+function localCommandEvent(text, uuid, shell) {
+	return {
+		type: "user_message",
+		message: {
+			role: "user",
+			content: text
+		},
+		parentToolUseId: null,
+		synthetic: true,
+		uuid,
+		...shell ? { shell } : {}
+	};
+}
+function shellInlineText(shell, text) {
+	const head = inlineHead(text);
+	const body = [`$ ${shell.command}`, ...head.lines];
+	if (head.more) body.push(INLINE_MORE);
+	const end = shellEndLine(shell);
+	if (end) body.push(end);
+	return frame(shellTag(shell), body);
+}
+function shellContextText(shell, text, options = {}) {
+	const body = [`$ ${shell.command}`];
+	if (shell.status === "running") {
+		body.push(runningStatusLine(shell, text, options));
+		if (!options.collapsed && !options.previous) {
+			const part = headTail(text, TAIL_ONLY);
+			const shown = part.omittedLines > 0 ? part.tail : part.head;
+			if (part.omittedLines > 0) body.push(`[last ${count(part.totalLines - part.omittedLines)} of ${count(part.totalLines)} lines]`);
+			if (shown) body.push(shown);
+		}
+	} else if (options.collapsed) {
+		const part = headTail(text, {
+			headLines: 0,
+			headChars: 0,
+			tailLines: 0,
+			tailChars: 0
+		});
+		if (part.totalLines > 0) body.push(omissionLine(shell, part.totalLines, part.totalLines, part.totalBytes));
+	} else {
+		const part = headTail(text, HEAD_AND_TAIL);
+		if (part.head) body.push(part.head);
+		if (part.omittedLines > 0) body.push(omissionLine(shell, part.omittedLines, part.totalLines, part.totalBytes));
+		if (part.tail) body.push(part.tail);
+	}
+	const end = shellEndLine(shell);
+	if (end) body.push(end);
+	return frame(shellTag(shell), body);
+}
+var LocalCommandQueue = class {
+	#entries = [];
+	#emit;
+	constructor(emit) {
+		this.#emit = emit;
+	}
+	push(input) {
+		if (!isLocalShellSource(input)) {
+			const text = localCommandTranscript(input);
+			this.#entries.push({
+				kind: "text",
+				text
+			});
+			this.#emit(text, randomUUID(), void 0);
+			return;
+		}
+		const uuid = randomUUID();
+		const row = () => {
+			const info = { ...input.info() };
+			this.#emit(shellInlineText(info, input.text()), uuid, info);
+		};
+		row();
+		const unsubscribe = input.subscribe(row);
+		this.#entries.push({
+			kind: "shell",
+			source: input,
+			unsubscribe
+		});
+	}
+	take() {
+		if (this.#entries.length === 0) return;
+		const rendered = this.#entries.map((entry) => render(entry));
+		const texts = capped(rendered);
+		const remaining = [];
+		this.#entries.forEach((entry, i) => {
+			if (entry.kind === "text") return;
+			if (rendered[i].settled) {
+				entry.unsubscribe();
+				return;
+			}
+			entry.flushedLines = rendered[i].lines;
+			remaining.push(entry);
+		});
+		this.#entries = remaining;
+		return localCommandContext(texts);
+	}
+	materialize() {
+		return capped(this.#entries.map((entry) => render(entry)));
+	}
+	restore(texts) {
+		for (const text of texts) this.#entries.push({
+			kind: "text",
+			text
+		});
+	}
+	clear() {
+		for (const entry of this.#entries) if (entry.kind === "shell") entry.unsubscribe();
+		this.#entries = [];
+	}
+};
+function render(entry) {
+	if (entry.kind === "text") return {
+		full: entry.text,
+		settled: true,
+		lines: 0
+	};
+	const info = entry.source.info();
+	const text = entry.source.text();
+	const previous = entry.flushedLines === void 0 ? void 0 : { lines: entry.flushedLines };
+	return {
+		full: shellContextText(info, text, { previous }),
+		collapsed: () => shellContextText(info, text, {
+			previous,
+			collapsed: true
+		}),
+		settled: info.status !== "running",
+		lines: countLines(text)
+	};
+}
+function capped(rendered) {
+	const texts = Array.from({ length: rendered.length });
+	let budget = SHELL_CONTEXT_FLUSH_MAX_CHARS;
+	for (let i = rendered.length - 1; i >= 0; i--) {
+		const entry = rendered[i];
+		const text = entry.collapsed === void 0 || entry.full.length <= budget ? entry.full : entry.collapsed();
+		texts[i] = text;
+		budget -= text.length;
+	}
+	return texts;
+}
+function frame(tag, body) {
+	return `<${tag}>${body.join("\n")}</${tag}>`;
+}
+function inlineHead(text) {
+	const total = text.length;
+	const window = total > INLINE_SCAN_CHARS ? text.slice(0, INLINE_SCAN_CHARS) : text;
+	const lines = [];
+	let at = 0;
+	let chars = 0;
+	while (lines.length < SHELL_INLINE_LINES && at < total) {
+		const segment = window.slice(at, at + SHELL_INLINE_LINE_CHARS + 1);
+		const newline = segment.indexOf("\n");
+		const clipped = newline === -1 && segment.length > SHELL_INLINE_LINE_CHARS;
+		const line = clipped ? segment.slice(0, SHELL_INLINE_LINE_CHARS) + INLINE_CLIPPED : newline === -1 ? segment : segment.slice(0, newline);
+		const next = chars + line.length + (lines.length > 0 ? 1 : 0);
+		if (lines.length > 0 && next > SHELL_INLINE_CHARS) return {
+			lines,
+			more: true
+		};
+		lines.push(line);
+		chars = next;
+		if (clipped) return {
+			lines,
+			more: true
+		};
+		at = newline === -1 ? total : at + newline + 1;
+	}
+	return {
+		lines,
+		more: at < total
+	};
+}
+function shellTag(shell) {
+	return shell.status === "running" || shell.exitCode === 0 ? "local-command-stdout" : "local-command-stderr";
+}
+function shellName(shell) {
+	return `shell #${shell.ordinal} (${shell.id})`;
+}
+function shellEndLine(shell) {
+	if (shell.status === "running" || shell.exitCode === 0) return;
+	if (typeof shell.exitCode === "number") return `[exit ${shell.exitCode}]`;
+	switch (shell.endReason) {
+		case "killed": return "[killed]";
+		case "timeout": return "[timed out]";
+		case "server_stopped": return "[killed: the gateway stopped]";
+		case "server_restarted": return "[ended: the gateway restarted; the process may still be running]";
+		case "spawn_failed": return "[failed to start]";
+		default: return "[ended]";
+	}
+}
+function omissionLine(shell, omitted, total, bytes) {
+	const span = omitted === total ? `all ${count(total)} lines omitted (${size(bytes)})` : `${count(omitted)} of ${count(total)} lines omitted (${size(bytes)} in all)`;
+	return `[${shellName(shell)}: ${span}; ${OUTPUT_POINTER}]`;
+}
+function runningStatusLine(shell, text, options) {
+	const lines = countLines(text);
+	const progress = options.previous ? lines > options.previous.lines ? `${count(lines - options.previous.lines)} new lines since the last message` : "no new lines since the last message" : `${count(lines)} lines so far`;
+	return `[${shellName(shell)} is still running as of the time this was written (started ${elapsed(Date.now() - shell.startedAt)} ago, ${progress}). Nothing from it streams into this conversation; ${OUTPUT_POINTER}.]`;
+}
+function count(n) {
+	return n.toLocaleString("en-US");
+}
+function size(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${Math.round(bytes / 1024)} KiB`;
+	return `${(bytes / 1048576).toFixed(1)} MiB`;
+}
+function elapsed(ms) {
+	const seconds = Math.max(0, Math.floor(ms / 1e3));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+	return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
 //#endregion
 //#region src/lib/patch.ts
 const MAX_PATCH_LINES = 400;
@@ -774,23 +1093,36 @@ var EventLog = class {
 		};
 		this.#lastActivityAt = event.ts;
 		this.#fold(event);
-		this.#events.push(event);
+		this.#retain(event);
 		return event;
 	}
 	at(seq) {
 		return this.#events.find((event) => event.seq === seq);
 	}
 	restore(events, seq, lastActivityAt) {
-		this.#events = [...events];
+		this.#events = [];
 		this.#seq = seq;
 		this.#activityCount = 0;
 		this.#proseCount = 0;
 		this.#contextUsage = void 0;
 		this.#checklist = void 0;
 		this.#resetSeq = 0;
-		for (const event of this.#events) this.#fold(event);
+		for (const event of events) {
+			this.#fold(event);
+			this.#retain(event);
+		}
 		this.#lastActivityAt = lastActivityAt;
 	}
+	#retain(event) {
+		const key = logCoalesceKey(event);
+		if (key !== void 0) {
+			for (let index = this.#events.length - 1; index >= 0; index--) if (logCoalesceKey(this.#events[index]) === key) {
+				this.#events.splice(index, 1);
+				break;
+			}
+		}
+		this.#events.push(event);
+	}
 	#fold(event) {
 		this.#activityCount += transcriptActivity(event);
 		this.#proseCount += transcriptProse(event);
@@ -971,6 +1303,19 @@ function withTitle(config, title) {
 	};
 }
 //#endregion
+//#region src/lib/instructions.ts
+function resolveInstructions(instructions, context) {
+	if (instructions === void 0) return;
+	const text = (typeof instructions === "function" ? instructions(context) : instructions).trim();
+	return text === "" ? void 0 : text;
+}
+function composeInstructions(...parts) {
+	const present = parts.filter((part) => part !== void 0 && part !== "");
+	if (present.length <= 1) return present[0];
+	if (present.every((part) => typeof part === "string")) return present.join("\n\n");
+	return (context) => present.map((part) => resolveInstructions(part, context)).filter((text) => text !== void 0).join("\n\n");
+}
+//#endregion
 //#region src/lib/peers.ts
 const PEER_MCP_SERVER = "workerdeck";
 const PEER_MESSAGE_MAX_CHARS = 16e3;
@@ -1028,7 +1373,7 @@ async function runPeerTool(peers, from, name, args) {
 			}
 			case "peers_peek": {
 				const input = z.object(PEER_TOOL_SHAPES.peers_peek.shape).safeParse(args ?? {});
-				if (!input.success) return invalidArguments(name, input.error);
+				if (!input.success) return invalidArguments$1(name, input.error);
 				const peek = await peers.peek(from, input.data.sessionId, { recent: input.data.recent });
 				if (!peek) return {
 					text: `no such session: ${input.data.sessionId}`,
@@ -1041,7 +1386,7 @@ async function runPeerTool(peers, from, name, args) {
 			}
 			case "peers_send": {
 				const input = z.object(PEER_TOOL_SHAPES.peers_send.shape).safeParse(args ?? {});
-				if (!input.success) return invalidArguments(name, input.error);
+				if (!input.success) return invalidArguments$1(name, input.error);
 				const result = await peers.send(from, input.data.sessionId, input.data.text);
 				if (!result.delivered) return {
 					text: `not delivered: ${result.reason}`,
@@ -1061,7 +1406,7 @@ async function runPeerTool(peers, from, name, args) {
 		};
 	}
 }
-function invalidArguments(name, error) {
+function invalidArguments$1(name, error) {
 	return {
 		text: `invalid arguments for ${name}: ${error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ")}`,
 		isError: true
@@ -1152,6 +1497,138 @@ function peerDirectoryHandle() {
 	};
 }
 //#endregion
+//#region src/lib/shells.ts
+const SHELL_REFUSAL = "shell commands are not available on this session";
+const SHELL_DIRECTORY_SLOT = Symbol.for("workerdeck.shells.directory");
+const SHELL_TOOL_SHAPES = {
+	shell_list: {
+		description: "List the shell commands your user has run in this session with `$`: id, command, whether it is still running, its exit code and how much output it produced. Call this before shell_read to find the shell id.",
+		shape: {}
+	},
+	shell_read: {
+		description: "Read the end of one shell command's output, as a terminal would show it. Use it to answer \"what is the dev server printing now\" or to see more of a command whose output was summarised in the conversation. Reading never writes to the shell and never interrupts it.",
+		shape: {
+			shellId: z.string().describe("The shell id from shell_list"),
+			tail: z.number().int().min(1).optional().describe(`How many trailing lines to return (default ${SHELL_READ_DEFAULT_LINES}, capped at ${SHELL_READ_MAX_LINES})`)
+		}
+	}
+};
+const SHELL_TOOL_NAMES = Object.keys(SHELL_TOOL_SHAPES);
+function shellToolSpecs() {
+	return SHELL_TOOL_NAMES.map((name) => {
+		const { description, shape } = SHELL_TOOL_SHAPES[name];
+		return {
+			name,
+			description,
+			inputSchema: z.toJSONSchema(z.object(shape))
+		};
+	});
+}
+function isShellToolName(name) {
+	return Object.hasOwn(SHELL_TOOL_SHAPES, name);
+}
+function clampShellTail(tail) {
+	if (tail === void 0 || !Number.isFinite(tail)) return SHELL_READ_DEFAULT_LINES;
+	return Math.max(1, Math.min(Math.floor(tail), SHELL_READ_MAX_LINES));
+}
+function shellSummary(info) {
+	return {
+		id: info.id,
+		ordinal: info.ordinal,
+		command: info.command,
+		label: info.label,
+		cwd: info.cwd,
+		owner: info.owner,
+		status: info.status,
+		startedAt: info.startedAt,
+		endedAt: info.endedAt,
+		exitCode: info.exitCode,
+		endReason: info.endReason,
+		bytes: info.bytes,
+		capped: info.capped
+	};
+}
+function shellTail(text, tail) {
+	const body = text.endsWith("\n") ? text.slice(0, -1) : text;
+	const all = body.length === 0 ? [] : body.split("\n");
+	const kept = all.slice(Math.max(0, all.length - tail));
+	return {
+		text: kept.join("\n"),
+		lines: kept.length,
+		totalLines: all.length,
+		truncated: kept.length < all.length
+	};
+}
+async function runShellTool(shells, from, name, args) {
+	if (!isShellToolName(name)) return {
+		text: `unknown shell tool: ${name}`,
+		isError: true
+	};
+	try {
+		switch (name) {
+			case "shell_list": {
+				const rows = await shells.list(from);
+				return {
+					text: rows.length ? JSON.stringify(rows, null, 2) : "No shell commands have run in this session.",
+					isError: false
+				};
+			}
+			case "shell_read": {
+				const input = z.object(SHELL_TOOL_SHAPES.shell_read.shape).safeParse(args ?? {});
+				if (!input.success) return invalidArguments(name, input.error);
+				const result = await shells.read(from, input.data.shellId, { tail: clampShellTail(input.data.tail) });
+				if (!result) return {
+					text: `no such shell: ${input.data.shellId}`,
+					isError: true
+				};
+				return {
+					text: shellReadText(result),
+					isError: false
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			text: error instanceof Error ? error.message : String(error),
+			isError: true
+		};
+	}
+}
+function invalidArguments(name, error) {
+	return {
+		text: `invalid arguments for ${name}: ${error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ")}`,
+		isError: true
+	};
+}
+function shellReadText(result) {
+	const { shell } = result;
+	const scope = result.truncated ? `showing the last ${result.lines} of ${result.totalLines} lines` : `showing all ${result.lines} lines`;
+	const head = `[shell #${shell.ordinal} ${shell.id}: $ ${shell.command}, ${shellState(shell)}, ${scope}]`;
+	return result.text ? `${head}\n${result.text}` : `${head}\n(no output)`;
+}
+function shellState(shell) {
+	if (shell.status === "running") return "still running";
+	if (shell.exitCode !== void 0) return `exited ${shell.exitCode}`;
+	return `ended (${shell.endReason ?? "exit"})`;
+}
+function installShellDirectory(directory) {
+	globalThis[SHELL_DIRECTORY_SLOT] = directory;
+}
+function installedShellDirectory() {
+	return globalThis[SHELL_DIRECTORY_SLOT];
+}
+function shellDirectoryHandle() {
+	const resolve = () => {
+		const directory = installedShellDirectory();
+		if (!directory) throw new Error(SHELL_REFUSAL);
+		return directory;
+	};
+	return {
+		list: async (from) => resolve().list(from),
+		read: async (from, shellId, options) => resolve().read(from, shellId, options)
+	};
+}
+//#endregion
 //#region src/engines/claude/subagents.ts
 const SPAWNER_NAMES = /* @__PURE__ */ new Set(["Task", "Agent"]);
 var SubagentTracker = class {
@@ -1343,6 +1820,7 @@ var SessionRunner = class {
 	createdAt;
 	#config;
 	#cwd;
+	#instructions;
 	#log = new EventLog();
 	#subscribers = new SubscriberSet();
 	#tasks = new TaskChecklist();
@@ -1358,7 +1836,7 @@ var SessionRunner = class {
 	#cost = new CostLedger();
 	#numTurns;
 	#input = new InputQueue();
-	#pendingLocalCommands = [];
+	#localCommands = new LocalCommandQueue((text, uuid, shell) => this.#emit(localCommandEvent(text, uuid, shell)));
 	#compactionId;
 	#compactionTurns = 0;
 	#idleWhileCompacting = false;
@@ -1379,6 +1857,12 @@ var SessionRunner = class {
 		this.#permissionMode = config.permissionMode;
 		this.id = id;
 		this.createdAt = Date.now();
+		this.#instructions = resolveInstructions(config.instructions, {
+			sessionId: id,
+			cwd: config.cwd,
+			profile: config.profile
+		});
+		if (this.#instructions !== void 0 && config.extraOptions?.systemPrompt !== void 0) throw new Error("instructions and extraOptions.systemPrompt both set - the host must pick one");
 	}
 	get status() {
 		return this.#status;
@@ -1477,25 +1961,12 @@ var SessionRunner = class {
 			...options?.origin ? { origin: options.origin } : {}
 		});
 	}
-	queueLocalCommand(result) {
+	queueLocalCommand(input) {
 		if (this.#closed) throw new Error("session is closed");
-		const text = localCommandTranscript(result);
-		this.#pendingLocalCommands.push(text);
-		this.#emit({
-			type: "user_message",
-			message: {
-				role: "user",
-				content: text
-			},
-			parentToolUseId: null,
-			synthetic: true,
-			uuid: randomUUID()
-		});
+		this.#localCommands.push(input);
 	}
 	#takeLocalCommands() {
-		const context = localCommandContext(this.#pendingLocalCommands);
-		this.#pendingLocalCommands = [];
-		return context;
+		return this.#localCommands.take();
 	}
 	async mcpServers() {
 		const query = this.#query;
@@ -1523,7 +1994,7 @@ var SessionRunner = class {
 	}
 	async clearContext() {
 		if (this.#status === "closed" || this.#status === "failed") throw new Error("session is closed");
-		this.#pendingLocalCommands = [];
+		this.#localCommands.clear();
 		this.sendMessage("/clear");
 	}
 	async setPermissionMode(mode) {
@@ -1554,7 +2025,7 @@ var SessionRunner = class {
 	close(reason = "client") {
 		if (this.#closed) return;
 		this.#closed = true;
-		this.#pendingLocalCommands = [];
+		this.#localCommands.clear();
 		for (const [id, pending] of this.#pending) this.#settleApproval(id, pending, {
 			behavior: "deny",
 			message: "Session closed"
@@ -1661,14 +2132,20 @@ var SessionRunner = class {
 			env: c.env,
 			pathToClaudeCodeExecutable: c.pathToClaudeCodeExecutable,
 			...c.permissionMode === "bypassPermissions" || c.allowDangerouslySkipPermissions ? { allowDangerouslySkipPermissions: true } : {},
-			...c.extraOptions
+			...c.extraOptions,
+			...this.#instructions === void 0 ? {} : { systemPrompt: {
+				type: "preset",
+				preset: "claude_code",
+				append: this.#instructions
+			} }
 		};
 	}
 	#mcpServersOption() {
 		const declared = this.#config.mcpServers;
 		const peers = this.#config.peers;
-		if (!peers) return declared;
-		const tools = PEER_TOOL_NAMES.map((name) => tool(name, PEER_TOOL_SHAPES[name].description, PEER_TOOL_SHAPES[name].shape, async (args) => {
+		const shells = this.#config.shells;
+		if (!peers && !shells) return declared;
+		const tools = [...peers ? PEER_TOOL_NAMES.map((name) => tool(name, PEER_TOOL_SHAPES[name].description, PEER_TOOL_SHAPES[name].shape, async (args) => {
 			const output = await runPeerTool(peers, this.id, name, args);
 			return {
 				content: [{
@@ -1677,7 +2154,16 @@ var SessionRunner = class {
 				}],
 				isError: output.isError
 			};
-		}));
+		})) : [], ...shells ? SHELL_TOOL_NAMES.map((name) => tool(name, SHELL_TOOL_SHAPES[name].description, SHELL_TOOL_SHAPES[name].shape, async (args) => {
+			const output = await runShellTool(shells, this.id, name, args);
+			return {
+				content: [{
+					type: "text",
+					text: output.text
+				}],
+				isError: output.isError
+			};
+		})) : []];
 		return {
 			...declared,
 			[PEER_MCP_SERVER]: createSdkMcpServer({
@@ -1744,7 +2230,7 @@ var SessionRunner = class {
 			this.#emit(body);
 			if (body.type === "conversation_reset") {
 				this.#cost.rollover();
-				this.#pendingLocalCommands = [];
+				this.#localCommands.clear();
 				if (body.sdkSessionId) this.#sdkSessionId = body.sdkSessionId;
 				this.#fetchContextUsage();
 			}
@@ -2046,6 +2532,7 @@ var AiSdkRunner = class {
 	id;
 	createdAt;
 	#config;
+	#instructions;
 	#model;
 	#log = new EventLog();
 	#subscribers = new SubscriberSet();
@@ -2053,7 +2540,7 @@ var AiSdkRunner = class {
 	#statusDetail;
 	#permissionMode;
 	#messages = [];
-	#pendingLocalCommands = [];
+	#localCommands = new LocalCommandQueue((text, uuid, shell) => this.#emit(localCommandEvent(text, uuid, shell)));
 	#pendingToolCalls = /* @__PURE__ */ new Map();
 	#dispatched = /* @__PURE__ */ new Set();
 	#turnChain = Promise.resolve();
@@ -2075,6 +2562,11 @@ var AiSdkRunner = class {
 		this.#modelAlias = config.model;
 		this.id = config.restore?.id ?? id;
 		this.createdAt = config.restore?.createdAt ?? Date.now();
+		this.#instructions = resolveInstructions(config.instructions, {
+			sessionId: this.id,
+			cwd: config.cwd,
+			profile: config.profile
+		});
 		if (config.restore) this.#restore(config.restore);
 	}
 	#restore(snapshot) {
@@ -2083,7 +2575,7 @@ var AiSdkRunner = class {
 		if (!state || !Array.isArray(state.messages)) throw new Error("session snapshot is missing its provider-engine state");
 		this.#log.restore(snapshot.events, snapshot.seq, state.lastActivityAt);
 		this.#messages = [...state.messages];
-		this.#pendingLocalCommands = [...state.pendingLocalCommands ?? []];
+		this.#localCommands.restore(state.pendingLocalCommands ?? []);
 		for (const call of state.pendingToolCalls) {
 			const legacy = call.deferred;
 			this.#pendingToolCalls.set(call.toolCallId, legacy === void 0 ? call : {
@@ -2175,6 +2667,7 @@ var AiSdkRunner = class {
 		const snapshot = this.#buildSnapshot();
 		this.#parked = true;
 		this.#subscribers.clear();
+		this.#localCommands.clear();
 		try {
 			Promise.resolve(this.#config.onClose?.()).catch(() => {});
 		} catch {}
@@ -2191,6 +2684,7 @@ var AiSdkRunner = class {
 			toolName: call.toolName,
 			expiresAt: call.expiresAt
 		}));
+		const pendingLocalCommands = this.#localCommands.materialize();
 		const state = {
 			messages: this.#messages,
 			pendingToolCalls: [...this.#pendingToolCalls.values()],
@@ -2201,7 +2695,7 @@ var AiSdkRunner = class {
 			model: this.#modelAlias,
 			lastActivityAt: this.#log.lastActivityAt,
 			parkedAt: Date.now(),
-			...this.#pendingLocalCommands.length ? { pendingLocalCommands: [...this.#pendingLocalCommands] } : {}
+			...pendingLocalCommands.length ? { pendingLocalCommands } : {}
 		};
 		return {
 			engine: "provider",
@@ -2224,8 +2718,7 @@ var AiSdkRunner = class {
 			mediaType: normalizeMediaType(attachment.mediaType),
 			filename: attachment.name
 		}));
-		const context = localCommandContext(this.#pendingLocalCommands);
-		this.#pendingLocalCommands = [];
+		const context = this.#localCommands.take();
 		const content = files.length || context ? [
 			...context ? [{
 				type: "text",
@@ -2254,21 +2747,10 @@ var AiSdkRunner = class {
 		});
 		this.#scheduleTurn();
 	}
-	queueLocalCommand(result) {
+	queueLocalCommand(input) {
 		if (this.#parked) throw new Error("session is parked");
 		if (this.#closed) throw new Error("session is closed");
-		const text = localCommandTranscript(result);
-		this.#pendingLocalCommands.push(text);
-		this.#emit({
-			type: "user_message",
-			message: {
-				role: "user",
-				content: text
-			},
-			parentToolUseId: null,
-			synthetic: true,
-			uuid: randomUUID()
-		});
+		this.#localCommands.push(input);
 	}
 	resolveToolCall(toolCallId, output, options) {
 		if (!this.#settlePendingCall(toolCallId, output, options?.isError === true)) return false;
@@ -2370,7 +2852,7 @@ var AiSdkRunner = class {
 			if (this.#closed) throw new Error("session is closed");
 			if (this.#pendingToolCalls.size > 0) throw new Error("cannot clear context while tool calls are outstanding");
 			this.#messages = [];
-			this.#pendingLocalCommands = [];
+			this.#localCommands.clear();
 			this.#emit({ type: "conversation_reset" });
 		});
 		this.#turnChain = run.then(() => void 0, () => void 0);
@@ -2452,7 +2934,7 @@ var AiSdkRunner = class {
 		if (this.#closed || this.#parked) return;
 		this.#closed = true;
 		this.#abort?.abort();
-		this.#pendingLocalCommands = [];
+		this.#localCommands.clear();
 		this.#pendingToolCalls.clear();
 		this.#dispatched.clear();
 		for (const { timer } of this.#pendingApprovals.values()) clearTimeout(timer);
@@ -2646,7 +3128,7 @@ var AiSdkRunner = class {
 		const agent = new ToolLoopAgent({
 			model: this.#model,
 			tools: this.#config.tools ?? {},
-			instructions: this.#config.instructions,
+			instructions: this.#instructions,
 			stopWhen: isStepCount(this.#config.maxSteps ?? 20)
 		});
 		const abort = new AbortController();
@@ -3347,6 +3829,22 @@ function createToolContext(options) {
 			})
 		});
 	}
+	if (options.shells) {
+		const shells = options.shells;
+		const selfId = options.selfId ?? (() => options.sessionId);
+		for (const name of SHELL_TOOL_NAMES) definitions.push({
+			name,
+			trust: "authoritative",
+			tool: tool$1({
+				description: SHELL_TOOL_SHAPES[name].description,
+				inputSchema: z.object(SHELL_TOOL_SHAPES[name].shape),
+				execute: async (args) => {
+					const output = await runShellTool(shells, selfId(), name, args);
+					return output.isError ? { error: output.text } : { result: output.text };
+				}
+			})
+		});
+	}
 	if (options.search) {
 		const search = options.search;
 		definitions.push({
@@ -3707,6 +4205,7 @@ function createEngineSession(options) {
 		webFetch,
 		onFileDelivered: options.capabilities?.deliverFiles === false || !isGranted("deliverFiles") ? void 0 : (file) => runner?.emitFileDelivered(file),
 		peers: options.config.peers,
+		shells: options.config.shells,
 		selfId: () => runner?.id ?? "pending"
 	});
 	const declaredServers = options.profile?.session?.mcpServers;
@@ -3718,7 +4217,7 @@ function createEngineSession(options) {
 	runner = new AiSdkRunner({
 		...options.config,
 		languageModel: options.resolveModel(options.profile, options.config),
-		instructions: options.profile?.session?.instructions ?? options.instructions ?? options.config.instructions,
+		instructions: composeInstructions(options.profile?.session?.instructions, options.instructions, options.config.instructions),
 		tools: context.tools,
 		vfs,
 		executor,
@@ -3954,9 +4453,12 @@ const claudeAdapter = {
 		};
 		return { available: "unknown" };
 	},
-	createRunner({ config, restore, id }) {
+	createRunner({ config, profile, restore, id }) {
 		if (restore) throw new Error("the Claude engine cannot rebuild a parked session");
-		return new SessionRunner(config, id);
+		return new SessionRunner({
+			...config,
+			instructions: composeInstructions(profile?.session?.instructions, config.instructions)
+		}, id);
 	},
 	async listSessions({ dir, limit, offset }) {
 		return (await listSessions({
@@ -4771,6 +5273,7 @@ var CodexRunner = class {
 	createdAt;
 	#config;
 	#cwd;
+	#instructions;
 	#log = new EventLog();
 	#subscribers = new SubscriberSet();
 	#status = "starting";
@@ -4783,7 +5286,7 @@ var CodexRunner = class {
 	#planType;
 	#resolvedEffort;
 	#queue = [];
-	#pendingLocalCommands = [];
+	#localCommands = new LocalCommandQueue((text, uuid, shell) => this.#emit(localCommandEvent(text, uuid, shell)));
 	#turnChain = Promise.resolve();
 	#activeTurn;
 	#connection;
@@ -4827,6 +5330,11 @@ var CodexRunner = class {
 		this.#threadMaterialized = config.resume !== void 0;
 		this.id = id;
 		this.createdAt = Date.now();
+		this.#instructions = resolveInstructions(config.instructions, {
+			sessionId: id,
+			cwd: config.cwd,
+			profile: config.profile
+		});
 	}
 	#childEnv() {
 		return codexChildEnv(this.#config.env ?? process.env, this.#config.codexHome);
@@ -5037,28 +5545,16 @@ var CodexRunner = class {
 			type: "text",
 			text
 		});
-		const context = localCommandContext(this.#pendingLocalCommands);
-		this.#pendingLocalCommands = [];
+		const context = this.#localCommands.take();
 		if (context) parts.unshift({
 			type: "text",
 			text: context
 		});
 		return withSkillItems(parts, this.#skillPaths);
 	}
-	queueLocalCommand(result) {
+	queueLocalCommand(input) {
 		if (this.#closed) throw new Error("session is closed");
-		const text = localCommandTranscript(result);
-		this.#pendingLocalCommands.push(text);
-		this.#emit({
-			type: "user_message",
-			message: {
-				role: "user",
-				content: text
-			},
-			parentToolUseId: null,
-			synthetic: true,
-			uuid: randomUUID()
-		});
+		this.#localCommands.push(input);
 	}
 	resolvePermission(requestId, decision) {
 		const pending = this.#approvals.get(requestId);
@@ -5106,7 +5602,7 @@ var CodexRunner = class {
 			message: "the conversation was cleared"
 		}, "policy");
 		this.#resumedHistory = void 0;
-		this.#pendingLocalCommands = [];
+		this.#localCommands.clear();
 		this.#emit({
 			type: "conversation_reset",
 			sdkSessionId: this.#resumableThreadId()
@@ -5160,7 +5656,7 @@ var CodexRunner = class {
 		if (this.#closed) return;
 		this.#closed = true;
 		this.#queue.length = 0;
-		this.#pendingLocalCommands = [];
+		this.#localCommands.clear();
 		for (const [id, pending] of this.#approvals) this.#settleApproval(id, pending, {
 			behavior: "deny",
 			message: "Session closed"
@@ -5252,7 +5748,9 @@ var CodexRunner = class {
 				approvalsReviewer: APPROVALS_REVIEWER_BY_MODE[this.#permissionMode]
 			};
 			if (this.#model) options.model = this.#model;
-			if (this.#config.peers) options.dynamicTools = peerToolSpecs().map((spec) => ({
+			if (this.#instructions !== void 0) options.developerInstructions = this.#instructions;
+			const dynamic = [...this.#config.peers ? peerToolSpecs() : [], ...this.#config.shells ? shellToolSpecs() : []];
+			if (dynamic.length) options.dynamicTools = dynamic.map((spec) => ({
 				type: "function",
 				...spec
 			}));
@@ -5674,16 +6172,30 @@ var CodexRunner = class {
 	async #answerServerRequest(method, params, wireId) {
 		const channel = APPROVAL_CHANNELS[method];
 		if (channel) return this.#requestApproval(channel, method, params, wireId);
-		if (method === "item/tool/call" && this.#config.peers) {
+		if (method === "item/tool/call") {
 			const call = params;
-			const output = await runPeerTool(this.#config.peers, this.id, call.tool, call.arguments);
-			return {
-				success: !output.isError,
-				contentItems: [{
-					type: "inputText",
-					text: output.text
-				}]
-			};
+			const peers = this.#config.peers;
+			const shells = this.#config.shells;
+			if (peers && isPeerToolName(call.tool)) {
+				const output = await runPeerTool(peers, this.id, call.tool, call.arguments);
+				return {
+					success: !output.isError,
+					contentItems: [{
+						type: "inputText",
+						text: output.text
+					}]
+				};
+			}
+			if (shells && isShellToolName(call.tool)) {
+				const output = await runShellTool(shells, this.id, call.tool, call.arguments);
+				return {
+					success: !output.isError,
+					contentItems: [{
+						type: "inputText",
+						text: output.text
+					}]
+				};
+			}
 		}
 		throw new JsonRpcError(-32601, `workerdeck does not handle server request '${method}'`);
 	}
@@ -6391,6 +6903,7 @@ const codexAdapter = {
 		return new CodexRunner({
 			...config,
 			codexHome: profile?.codexHome,
+			instructions: composeInstructions(profile?.session?.instructions, config.instructions),
 			connectFn: (options) => connectAppServer({
 				executable,
 				...options
@@ -6443,6 +6956,6 @@ function getEngineAdapter(engine) {
 	return ADAPTERS[engine ?? "claude"];
 }
 //#endregion
-export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, CostLedger, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, PEER_MCP_SERVER, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, PEER_TOOL_NAMES, PendingRequestRegistry, QuickJsExecutor, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, installPeerDirectory, installedPeerDirectory, isHostAllowed, isPrivateAddress, isSlashCommand, listCodexSessions, localCommandContext, localCommandTranscript, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, peerDirectoryHandle, peerMentionsEnvelope, peerMessageEnvelope, peerSummary, peerToolSpecs, providerAdapter, recentLines, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, runPeerTool, toApiMessage, toExecutionResult, truncateResultBlocks, withHostTools, withMcpTools, withPeerContext };
+export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, CostLedger, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, LocalCommandQueue, PEER_MCP_SERVER, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, PEER_TOOL_NAMES, PendingRequestRegistry, QuickJsExecutor, SHELL_REFUSAL, SHELL_TOOL_NAMES, SHELL_TOOL_SHAPES, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, clampShellTail, claudeAdapter, codexAdapter, composeInstructions, connectAppServer, connectMcpTools, countLines, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, headTail, htmlToMarkdown, installPeerDirectory, installShellDirectory, installedPeerDirectory, installedShellDirectory, isHostAllowed, isLocalShellSource, isPrivateAddress, isShellToolName, isSlashCommand, listCodexSessions, localCommandContext, localCommandEvent, localCommandTranscript, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, peerDirectoryHandle, peerMentionsEnvelope, peerMessageEnvelope, peerSummary, peerToolSpecs, providerAdapter, recentLines, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, resolveInstructions, runPeerTool, runShellTool, shellContextText, shellDirectoryHandle, shellInlineText, shellReadText, shellSummary, shellTail, shellToolSpecs, splitLines, toApiMessage, toExecutionResult, truncateResultBlocks, ttyText, withHostTools, withMcpTools, withPeerContext };
 
 //# sourceMappingURL=index.mjs.map