@workerdeck/server 2.14.0 → 3.0.1

package/build/index.d.mts

@@ -1,5 +1,5 @@
 import { IncomingMessage, Server, ServerResponse } from "node:http";
-import { AttachmentInput, BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, CostLedgerState, EngineAdapter, EngineSessionOptions, HostToolDefinition, LanguageModel, LocalShellSource, McpConnection, ParkedExecution, Runner, RunnerSnapshot, SHELL_REFUSAL, SessionInstructions, SessionRunnerConfig, ToolExecutionCall, ToolExecutionResult, ToolExecutor, ToolSet } from "@workerdeck/core";
+import { AttachmentInput, BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, CostLedgerState, EngineAdapter, EngineSessionOptions, HostToolDefinition, LanguageModel, LocalShellSource, McpConnection, ParkedExecution, Runner, RunnerSnapshot, SHELL_REFUSAL, SessionInstructions, SessionRunnerConfig, ShellDirectory, ToolExecutionCall, ToolExecutionResult, ToolExecutor, ToolSet } from "@workerdeck/core";
 import { JobQueue, QueueAdapter } from "@workerdeck/queue";
 import { ByModel, CreateSessionRequest, JobEvent, MessageAttachment, ModelRate, ProfileEngine, ProfileInfo, ProfileSpend, ProfileUsage, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig, ShellEndReason, ShellInfo, ShellOwner } from "@workerdeck/protocol";
 //#region src/services/bridge.d.ts
@@ -188,7 +188,7 @@ type ShellAttachment = {
   detach: () => void;
 };
 type ShellOutputQuery = {
-  view: 'text' | 'raw';
+  view: 'text' | 'raw' | 'screen';
   tail?: number;
 };
 type ShellErrorContext = {
@@ -196,6 +196,9 @@ type ShellErrorContext = {
   sessionId?: string;
   shellId?: string;
 };
+type ShellDirectoryDeps = {
+  runnerFor?: (sessionId: string) => Runner | undefined;
+};
 type ShellRegistryOptions = {
   generation: string;
   artifactDir: string | null;
@@ -228,18 +231,22 @@ type ShellRegistry = {
   list: (sessionId: string) => ShellInfo[];
   running: () => ShellInfo[];
   kill: (sessionId: string, shellId: string, reason?: ShellEndReason) => ShellInfo | undefined;
+  setAgentWrite: (sessionId: string, shellId: string, enabled: boolean) => ShellInfo | undefined;
   killAll: (reason: ShellEndReason) => number;
   killAllSync: () => void;
   attach: (sessionId: string, shellId: string, sink: ShellSink) => Promise<ShellAttachment>;
   write: (sessionId: string, shellId: string, data: string) => void;
   resize: (sessionId: string, shellId: string, size: ShellSize) => ShellSize;
   output: (sessionId: string, shellId: string, query: ShellOutputQuery) => Promise<string | undefined>;
+  applicationCursorKeys: (sessionId: string, shellId: string) => Promise<boolean>;
+  changed: (sessionId: string, shellId: string, timeoutMs: number) => Promise<void>;
   hydrate: () => Promise<void>;
   sweep: () => Promise<void>;
   flush: () => Promise<void>;
   decorate: (info: SessionInfo) => SessionInfo;
   watch: (runner: Runner) => () => void;
 };
+declare function createShellDirectory(registry: ShellRegistry, deps?: ShellDirectoryDeps): ShellDirectory;
 declare function shellPermitted(shells: ShellRegistry | null, runner: Runner, operator: boolean): boolean;
 declare function createShellRegistry(options: ShellRegistryOptions): ShellRegistry;
 //#endregion
@@ -271,6 +278,7 @@ declare class SpendLedger {
 declare function createFileSpendStore(path: string, onError?: (error: unknown) => void): SpendStore;
 //#endregion
 //#region src/options.d.ts
+type ShellAgentWriteOption = 'read-only' | 'gated' | 'allow';
 type SdkSessionLister = (options: {
   dir?: string;
   limit?: number;
@@ -296,6 +304,7 @@ type WorkerServerOptions = {
     artifactMaxBytes?: number;
     artifactTtlMs?: number;
     maxRunningPerSession?: number;
+    agentWrite?: ShellAgentWriteOption;
   };
   attachments?: {
     maxFileBytes?: number;
@@ -502,5 +511,5 @@ declare class ProfileUsageTracker {
   usage(profile: string, now?: number): ProfileUsage | undefined;
 }
 //#endregion
-export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type CarriedSession, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProcessRow, type ProcessTable, type ProducedFile, ProducedFileStore, type ProfileStore, ProfileUsageTracker, type ProviderRunnerOptions, type QueueServerOptions, type ReloadPlan, SHELL_REFUSAL, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, type ShellRegistry, type ShellRegistryOptions, type ShellSink, SpendLedger, type SpendRecord, type SpendStore, type StoredSessionRecord, type StoredShellIndex, type StoredShellRecord, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createShellRegistry, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord };
+export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type CarriedSession, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProcessRow, type ProcessTable, type ProducedFile, ProducedFileStore, type ProfileStore, ProfileUsageTracker, type ProviderRunnerOptions, type QueueServerOptions, type ReloadPlan, SHELL_REFUSAL, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, type ShellAgentWriteOption, type ShellDirectoryDeps, type ShellRegistry, type ShellRegistryOptions, type ShellSink, SpendLedger, type SpendRecord, type SpendStore, type StoredSessionRecord, type StoredShellIndex, type StoredShellRecord, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createShellDirectory, createShellRegistry, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord };
 //# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -1,13 +1,14 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
-import { BrowserBridgeExecutor, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, SHELL_REFUSAL, SessionRunner, attachmentKind, checkClaudeAuth, clampShellTail, createEngineSession, getEngineAdapter, installPeerDirectory, installShellDirectory, isSlashCommand, normalizeMediaType, peerDirectoryHandle, peerSummary, recentLines, shellDirectoryHandle, shellSummary, shellTail, ttyText } from "@workerdeck/core";
+import { BrowserBridgeExecutor, PEER_MESSAGE_MAX_CHARS, PEER_RECENT_DEFAULT, PEER_RECENT_MAX, SHELL_REFUSAL, SessionRunner, TTY_REDRAW_CARRY, agentMayWrite, attachmentKind, checkClaudeAuth, clampShellTail, createEngineSession, encodeShellKeys, getEngineAdapter, installPeerDirectory, installShellDirectory, isSlashCommand, normalizeMediaType, peerDirectoryHandle, peerSummary, recentLines, shellDirectoryHandle, shellOwnershipRefusal, shellSummary, shellTail, shellToolNeedsCard, ttyRedraws, ttyText } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_ARTIFACT_MAX_BYTES, SHELL_ARTIFACT_TTL_MS, SHELL_ATTACH_REPLAY_BYTES, SHELL_COLS, SHELL_COMMAND_MAX, SHELL_INPUT_MAX, SHELL_LABEL_MAX, SHELL_LINGER_MS, SHELL_MAX_COLS, SHELL_MAX_ROWS, SHELL_MAX_RUNNING_PER_SESSION, SHELL_MAX_RUNNING_TOTAL, SHELL_MIN_COLS, SHELL_MIN_ROWS, SHELL_ROWS, SHELL_SPILL_BYTES, SHELL_TAIL_FLUSH_MS, SHELL_TAIL_RING_BYTES, costOfByModel, imagePartRef, isJobRun, mergeByModel, peerMentionKey, peerMentionSlug, pickCreateSessionRequest, scanPeerMentions, sessionState, setPricingOverrides, subscriptionComparison, supportsPermissionMode } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PEER_MENTION_MAX, PROTOCOL_VERSION, SHELL_ARTIFACT_MAX_BYTES, SHELL_ARTIFACT_TTL_MS, SHELL_ATTACH_REPLAY_BYTES, SHELL_COLS, SHELL_COMMAND_MAX, SHELL_INPUT_MAX, SHELL_LABEL_MAX, SHELL_LINGER_MS, SHELL_MAX_COLS, SHELL_MAX_ROWS, SHELL_MAX_RUNNING_PER_SESSION, SHELL_MAX_RUNNING_TOTAL, SHELL_MIN_COLS, SHELL_MIN_ROWS, SHELL_READ_MAX_LINES, SHELL_ROWS, SHELL_SPILL_BYTES, SHELL_TAIL_FLUSH_MS, SHELL_TAIL_RING_BYTES, SHELL_WAIT_DEFAULT_MS, SHELL_WAIT_MAX_MS, costOfByModel, imagePartRef, isJobRun, mergeByModel, peerMentionKey, peerMentionSlug, pickCreateSessionRequest, scanPeerMentions, sessionState, setPricingOverrides, subscriptionComparison, supportsPermissionMode } from "@workerdeck/protocol";
 import { arch, homedir, hostname, platform, tmpdir } from "node:os";
 import { closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import xtermHeadless from "@xterm/headless";
 import { spawnSync } from "node:child_process";
 //#region src/lib/http.ts
 const CONTENT_TYPES = {
@@ -197,7 +198,7 @@ function parseSessionRoute(basePath, url) {
 	};
 	if (parts[1] === "shells" && parts.length <= 4) {
 		const action = parts[3];
-		if (action !== void 0 && action !== "output" && action !== "kill") return null;
+		if (action !== void 0 && action !== "output" && action !== "kill" && action !== "agent-write") return null;
 		return {
 			id: decodeURIComponent(parts[0]),
 			shells: true,
@@ -786,6 +787,8 @@ const HOST_ONLY_KEYS = new Set(Object.keys({
 	sessionInfoFn: true,
 	peers: true,
 	shells: true,
+	shellAgentWrite: true,
+	createdByOperator: true,
 	connectFn: true,
 	codexHome: true,
 	codexPathOverride: true,
@@ -1114,7 +1117,9 @@ const EPHEMERAL_CONFIG_KEYS = [
 	"extraOptions",
 	"env",
 	"peers",
-	"instructions"
+	"instructions",
+	"shells",
+	"shellAgentWrite"
 ];
 function toDurableRecord(record) {
 	const config = { ...record.config };
@@ -1543,6 +1548,68 @@ function handleProjectIcon(projects, req, res, cwd) {
 	res.end(read.data);
 }
 //#endregion
+//#region src/services/shell-screen.ts
+var ShellScreen = class {
+	#term;
+	#closing;
+	#final;
+	constructor(cols, rows) {
+		this.#term = new xtermHeadless.Terminal({
+			cols,
+			rows,
+			scrollback: 0,
+			allowProposedApi: true
+		});
+	}
+	write(data) {
+		this.#term?.write(data);
+	}
+	resize(cols, rows) {
+		try {
+			this.#term?.resize(cols, rows);
+		} catch {}
+	}
+	async snapshot() {
+		if (this.#closing) await this.#closing;
+		if (this.#final !== void 0) return this.#final;
+		const term = this.#term;
+		if (!term) return "";
+		await drained(term);
+		return render(term);
+	}
+	async applicationCursorKeys() {
+		const term = this.#term;
+		if (!term) return false;
+		await drained(term);
+		return term.modes.applicationCursorKeysMode;
+	}
+	close() {
+		const term = this.#term;
+		if (!term || this.#closing) return;
+		this.#term = void 0;
+		this.#closing = drained(term).then(() => {
+			this.#final = render(term);
+			term.dispose();
+		});
+	}
+};
+async function renderScreen(raw, cols, rows) {
+	const screen = new ShellScreen(cols, rows);
+	screen.write(raw);
+	screen.close();
+	return screen.snapshot();
+}
+function drained(term) {
+	return new Promise((resolve) => term.write("", resolve));
+}
+function render(term) {
+	const buffer = term.buffer.active;
+	const lines = [];
+	for (let y = 0; y < term.rows; y++) lines.push(buffer.getLine(buffer.viewportY + y)?.translateToString(true) ?? "");
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.join("\n");
+}
+//#endregion
 //#region src/services/process-tree.ts
 const PS_ARGS = ["-eo", "pid=,ppid=,pgid="];
 const PS_TIMEOUT_MS = 2e3;
@@ -1687,18 +1754,147 @@ async function loadPty() {
 	}
 	return ptyModule;
 }
-function createShellDirectory(registry) {
+function createShellDirectory(registry, deps = {}) {
+	const take = async (from, shellId, options) => {
+		const info = registry.get(from, shellId);
+		if (!info) return;
+		const view = options.view ?? (info.interactive ? "screen" : "lines");
+		const fresh = options.since === void 0 ? void 0 : await freshText(from, shellId, info.bytes - options.since);
+		if (view === "screen") {
+			const text = await registry.output(from, shellId, { view: "screen" });
+			if (text === void 0) return;
+			const lines = text === "" ? 0 : text.split("\n").length;
+			return {
+				info,
+				read: {
+					view,
+					text,
+					lines,
+					totalLines: lines,
+					truncated: false
+				},
+				haystack: fresh ?? text
+			};
+		}
+		const text = await registry.output(from, shellId, { view: "text" });
+		if (text === void 0) return;
+		return {
+			info,
+			read: shellTail(text, clampShellTail(options.tail)),
+			haystack: fresh ?? shellTail(text, SHELL_READ_MAX_LINES).text
+		};
+	};
+	const freshText = async (from, shellId, bytes) => {
+		if (bytes <= 0) return "";
+		const raw = await registry.output(from, shellId, {
+			view: "raw",
+			tail: bytes
+		});
+		return raw === void 0 ? "" : ttyText(raw);
+	};
+	const settle = async (from, shellId, options) => {
+		const needles = options.waitFor ?? [];
+		const started = Date.now();
+		const timeoutMs = Math.max(0, Math.min(options.timeoutMs ?? SHELL_WAIT_DEFAULT_MS, SHELL_WAIT_MAX_MS));
+		for (;;) {
+			const taken = await take(from, shellId, options);
+			if (!taken) return;
+			const result = {
+				shell: shellSummary(taken.info),
+				...taken.read
+			};
+			if (needles.length === 0) return result;
+			const ms = Date.now() - started;
+			const match = needles.find((needle) => taken.haystack.includes(needle));
+			if (match !== void 0) return {
+				...result,
+				wait: {
+					outcome: "matched",
+					match,
+					ms
+				}
+			};
+			if (taken.info.status !== "running") return {
+				...result,
+				wait: {
+					outcome: "exited",
+					ms
+				}
+			};
+			if (ms >= timeoutMs) return {
+				...result,
+				wait: {
+					outcome: "timeout",
+					ms
+				}
+			};
+			await registry.changed(from, shellId, timeoutMs - ms);
+		}
+	};
+	const writable = (from, shellId) => {
+		const info = registry.get(from, shellId);
+		if (!info) return;
+		if (!agentMayWrite(info, from)) throw new Error(shellOwnershipRefusal(shellId));
+		return info;
+	};
 	return {
 		list: async (from) => registry.list(from).map(shellSummary),
-		read: async (from, shellId, options) => {
-			const info = registry.get(from, shellId);
+		read: (from, shellId, options) => settle(from, shellId, { ...options }),
+		run: async (from, options) => {
+			const runner = deps.runnerFor?.(from);
+			if (!runner?.queueLocalCommand) throw new Error(SHELL_REFUSAL);
+			const { shell, source } = await registry.spawn({
+				runner,
+				command: options.command,
+				owner: "agent"
+			});
+			try {
+				runner.queueLocalCommand(source);
+			} catch (error) {
+				registry.kill(from, shell.id);
+				throw error;
+			}
+			const result = await settle(from, shell.id, {
+				waitFor: options.waitFor,
+				timeoutMs: options.timeoutMs
+			});
+			if (!result) throw new Error(`shell ${shell.id} vanished as it started`);
+			return result;
+		},
+		write: async (from, shellId, options) => {
+			const info = writable(from, shellId);
 			if (!info) return;
-			const text = await registry.output(from, shellId, { view: "text" });
-			if (text === void 0) return;
-			return {
+			if (info.status !== "running") throw new Error(`shell ${shellId} has already ended; there is nothing to type into`);
+			const application = await registry.applicationCursorKeys(from, shellId);
+			const data = (options.data ?? "") + encodeShellKeys(options.keys ?? [], { applicationCursorKeys: application });
+			if (data.length === 0) throw new Error("nothing to write: give data, keys or both");
+			const since = registry.get(from, shellId)?.bytes ?? info.bytes;
+			registry.write(from, shellId, data);
+			return settle(from, shellId, {
+				waitFor: options.waitFor,
+				timeoutMs: options.timeoutMs,
+				since
+			});
+		},
+		kill: async (from, shellId) => {
+			const info = writable(from, shellId);
+			if (!info) return;
+			if (info.status !== "running") return {
 				shell: shellSummary(info),
-				...shellTail(text, clampShellTail(options?.tail))
+				killed: false
+			};
+			const killed = registry.kill(from, shellId, "killed") ?? info;
+			return {
+				shell: shellSummary(killed),
+				killed: true
 			};
+		},
+		grant: async (from, shellId) => {
+			const info = registry.get(from, shellId);
+			if (!info) return;
+			if (info.owner === "agent") return shellSummary(info);
+			const granted = registry.setAgentWrite(from, shellId, true);
+			return granted ? shellSummary(granted) : void 0;
 		}
 	};
 }
@@ -1861,6 +2057,7 @@ function createShellRegistry(options) {
 		entry.info.status = "exited";
 		entry.info.endedAt = Date.now();
 		entry.info.endReason = reason;
+		delete entry.info.agentWrite;
 		clearTimeout(entry.clock);
 		clearTimeout(entry.notify);
 		clearInterval(entry.tailTimer);
@@ -1868,6 +2065,7 @@ function createShellRegistry(options) {
 		entry.child = void 0;
 		entry.pid = void 0;
 		if (entry.artifact instanceof LiveArtifact) entry.artifact.close();
+		entry.screen?.close();
 		for (const sink of entry.sinks) try {
 			sink.end(reason);
 		} catch {}
@@ -1959,6 +2157,7 @@ function createShellRegistry(options) {
 			sinks: /* @__PURE__ */ new Set(),
 			listeners: /* @__PURE__ */ new Set()
 		};
+		entry.screen = new ShellScreen(info.cols, info.rows);
 		state.entries.set(id, entry);
 		const env = shellChildEnv(process.env);
 		env.TERM = TERM;
@@ -1988,6 +2187,15 @@ function createShellRegistry(options) {
 			if (entry.info.status !== "running") return;
 			const changed = artifact.append(data);
 			entry.info.bytes = artifact.bytes;
+			entry.screen?.write(data);
+			if (!entry.info.interactive) {
+				const scanned = (entry.redrawCarry ?? "") + data;
+				if (ttyRedraws(scanned)) {
+					entry.info.interactive = true;
+					entry.redrawCarry = void 0;
+					persist(state);
+				} else entry.redrawCarry = scanned.slice(-TTY_REDRAW_CARRY);
+			}
 			if (changed) {
 				if (artifact.capped && !entry.info.capped) {
 					entry.info.capped = true;
@@ -2060,6 +2268,22 @@ function createShellRegistry(options) {
 			kill(state, entry, reason);
 			return { ...entry.info };
 		},
+		setAgentWrite: (sessionId, shellId, enabled) => {
+			const state = sessions.get(sessionId);
+			const entry = state?.entries.get(shellId);
+			if (!state || !entry) return;
+			if (enabled) {
+				if (entry.info.owner !== "user") throw new Error(`shell ${shellId} was started by the agent, which may already type into it`);
+				if (entry.info.status !== "running") throw new Error(`shell ${shellId} has already ended; there is nothing to grant`);
+			}
+			if (entry.info.agentWrite === true !== enabled) {
+				if (enabled) entry.info.agentWrite = true;
+				else delete entry.info.agentWrite;
+				persist(state);
+				fire(entry);
+			}
+			return { ...entry.info };
+		},
 		killAll: (reason) => {
 			stopped = true;
 			if (sweeper) {
@@ -2128,16 +2352,36 @@ function createShellRegistry(options) {
 				} catch {}
 				entry.info.cols = next.cols;
 				entry.info.rows = next.rows;
+				entry.screen?.resize(next.cols, next.rows);
 			}
 			return next;
 		},
 		output: async (sessionId, shellId, query) => {
 			const entry = find(sessionId, shellId);
 			if (!entry) return;
+			if (query.view === "screen") {
+				if (entry.screen) return entry.screen.snapshot();
+				return renderScreen((await entry.artifact.replay(SHELL_ATTACH_REPLAY_BYTES)).toString("utf8"), entry.info.cols, entry.info.rows);
+			}
 			if (query.tail === void 0 && query.view === "text") return entry.artifact.textView();
 			const text = (await entry.artifact.read(query.tail)).toString("utf8");
 			return query.view === "raw" ? text : ttyText(text);
 		},
+		applicationCursorKeys: (sessionId, shellId) => find(sessionId, shellId)?.screen?.applicationCursorKeys() ?? Promise.resolve(false),
+		changed: (sessionId, shellId, timeoutMs) => {
+			const entry = find(sessionId, shellId);
+			if (!entry || entry.info.status !== "running") return Promise.resolve();
+			return new Promise((resolve) => {
+				const done = () => {
+					clearTimeout(timer);
+					entry.listeners.delete(done);
+					resolve();
+				};
+				const timer = setTimeout(done, Math.max(0, timeoutMs));
+				timer.unref();
+				entry.listeners.add(done);
+			});
+		},
 		hydrate: async () => {
 			if (dir) {
 				let names = [];
@@ -2529,6 +2773,7 @@ async function readRange(path, start, end) {
 }
 //#endregion
 //#region src/routes/shells.ts
+const AGENT_WRITE_BODY_MAX = 1024;
 async function handleShells(ctx, req, res, route, runner, operator) {
 	const { shells } = ctx;
 	const sessionId = route.id;
@@ -2565,13 +2810,52 @@ async function handleShells(ctx, req, res, route, runner, operator) {
 		json(res, 200, { shell });
 		return;
 	}
+	if (route.shellAction === "agent-write") {
+		if (req.method !== "POST") {
+			json(res, 405, { error: "method not allowed" });
+			return;
+		}
+		if (!runner || !shellPermitted(shells, runner, operator)) {
+			json(res, 403, { error: SHELL_REFUSAL });
+			return;
+		}
+		let body;
+		try {
+			body = await readJsonBody(req, AGENT_WRITE_BODY_MAX);
+		} catch {
+			json(res, 400, { error: "invalid JSON body" });
+			return;
+		}
+		if (typeof body.enabled !== "boolean") {
+			json(res, 400, { error: "enabled must be a boolean" });
+			return;
+		}
+		if (body.enabled && runner.info().shellAgentWrite === void 0) {
+			json(res, 409, { error: "the agent has no shell write tools on this session (shell.agentWrite is read-only)" });
+			return;
+		}
+		let shell;
+		try {
+			shell = shells.setAgentWrite(sessionId, route.shellId, body.enabled);
+		} catch (error) {
+			json(res, 409, { error: error instanceof Error ? error.message : String(error) });
+			return;
+		}
+		if (!shell) {
+			json(res, 404, { error: "shell not found" });
+			return;
+		}
+		json(res, 200, { shell });
+		return;
+	}
 	if (req.method !== "GET") {
 		json(res, 405, { error: "method not allowed" });
 		return;
 	}
 	if (route.shellAction === "output") {
 		const url = new URL(req.url ?? "/", "http://internal");
-		const view = url.searchParams.get("view") === "raw" ? "raw" : "text";
+		const requested = url.searchParams.get("view");
+		const view = requested === "raw" || requested === "screen" ? requested : "text";
 		const tailParam = url.searchParams.get("tail");
 		const tail = tailParam === null ? void 0 : Number(tailParam);
 		if (tail !== void 0 && (!Number.isInteger(tail) || tail <= 0)) {
@@ -2666,7 +2950,7 @@ async function handleSessions(ctx, req, res, route, auth) {
 				json(res, vetted.status, { error: vetted.error });
 				return;
 			}
-			const runner = await factory.createRunner(factory.buildRunnerConfig(vetted.request));
+			const runner = await factory.createRunner(factory.buildRunnerConfig(vetted.request, { operator: authSvc.isOperator(auth) }));
 			factory.watchAuthSource(runner);
 			json(res, 201, { session: projects.withProject(runner.info()) });
 			return;
@@ -4393,6 +4677,12 @@ var SessionRegistry = class {
 };
 //#endregion
 //#region src/services/session-factory.ts
+function withPrincipal(config, operator) {
+	return operator === void 0 ? config : {
+		...config,
+		createdByOperator: operator
+	};
+}
 function createSessionFactory(deps) {
 	const { adapterFor, profiles, refs } = deps;
 	const subscriptionNoticeShown = /* @__PURE__ */ new Set();
@@ -4472,14 +4762,15 @@ function createSessionFactory(deps) {
 		...config,
 		defaultApprovalTimeoutMs: deps.approvalTimeoutMs
 	};
-	const buildRunnerConfig = (req) => {
+	const buildRunnerConfig = (req, principal) => {
 		const profile = req.profile !== void 0 ? profiles.get(req.profile) : void 0;
-		if (!profile) return withApprovalDefault(withScope(deps.hostBuildRunnerConfig(req), req.scope));
-		const config = withApprovalDefault(withScope(deps.hostBuildRunnerConfig({
+		const operator = principal?.operator ?? req.createdByOperator;
+		if (!profile) return withApprovalDefault(withPrincipal(withScope(deps.hostBuildRunnerConfig(req), req.scope), operator));
+		const config = withApprovalDefault(withPrincipal(withScope(deps.hostBuildRunnerConfig({
 			...req,
 			model: req.model ?? profile.defaults?.model ?? profile.provider?.model,
 			permissionMode: req.permissionMode ?? profile.defaults?.permissionMode
-		}), req.scope));
+		}), req.scope), operator));
 		if (engineOf(profile) !== "claude") return config;
 		const base = config.env ?? process.env;
 		const env = claudeSessionEnv(profile, base);
@@ -4505,9 +4796,15 @@ function createSessionFactory(deps) {
 		const capabilities = profile?.capabilities ?? adapterFor(profile?.engine).capabilities;
 		const config = {
 			...built,
-			...deps.peers ? { peers: deps.peers } : {},
-			...deps.shells && capabilities.hostCwd === true ? { shells: deps.shells } : {}
+			...deps.peers ? { peers: deps.peers } : {}
 		};
+		delete config.shells;
+		delete config.shellAgentWrite;
+		if (deps.shells && capabilities.hostCwd === true) {
+			config.shells = deps.shells;
+			const write = deps.shellAgentWrite ?? "read-only";
+			if (write !== "read-only" && built.createdByOperator === true) config.shellAgentWrite = write;
+		}
 		if (config.instructions !== void 0 && capabilities.systemInstructions === false) throw new Error(`the ${engineOf(profile)} engine cannot deliver system instructions`);
 		const runner = profile && isProviderProfile(profile) ? await deps.createEngineRunner({
 			config,
@@ -4695,7 +4992,7 @@ function createWorkerServer(options = {}) {
 		options: options.peers
 	});
 	if (peers) installPeerDirectory(peers);
-	installShellDirectory(shells ? createShellDirectory(shells) : void 0);
+	installShellDirectory(shells ? createShellDirectory(shells, { runnerFor: (id) => refs.registry?.get(id) }) : void 0);
 	const factory = createSessionFactory({
 		adapterFor,
 		profiles,
@@ -4707,6 +5004,7 @@ function createWorkerServer(options = {}) {
 		requireApiKey: options.requireApiKey,
 		peers: peers ? peerDirectoryHandle() : void 0,
 		shells: shells ? shellDirectoryHandle() : void 0,
+		shellAgentWrite: options.shell?.agentWrite,
 		refs
 	});
 	const availability = new AvailabilityTracker({
@@ -5128,6 +5426,7 @@ async function createProviderRunner(ctx, options) {
 	const backend = isPerCall ? (call) => {
 		return options.executor(call) === "browser" ? "browser" : "server";
 	} : options.executor === "browser" ? "browser" : "server";
+	const shouldApprove = config.shellAgentWrite === void 0 ? options.shouldApprove : (call) => shellToolNeedsCard(call.toolName, config.shellAgentWrite) || options.shouldApprove?.(call) === true;
 	return createEngineSession({
 		config: {
 			...config,
@@ -5146,7 +5445,7 @@ async function createProviderRunner(ctx, options) {
 		mcpTools: options.mcpTools,
 		instructions: options.instructions,
 		executionLimits: options.executionLimits,
-		shouldApprove: options.shouldApprove,
+		shouldApprove,
 		approvalTimeoutMs: config.defaultApprovalTimeoutMs === void 0 ? options.approvalTimeoutMs : config.defaultApprovalTimeoutMs,
 		seedVfs: options.seedVfs
 	});
@@ -5191,6 +5490,6 @@ function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profi
 	};
 }
 //#endregion
-export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SHELL_REFUSAL, SessionNotifier, SessionParkManager, SessionRegistry, SpendLedger, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createShellRegistry, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord };
+export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SHELL_REFUSAL, SessionNotifier, SessionParkManager, SessionRegistry, SpendLedger, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createShellDirectory, createShellRegistry, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map