@workerdeck/server 2.0.0 → 2.2.0

package/build/index.d.mts

@@ -160,6 +160,11 @@ type WorkerServerOptions = {
     maxEntries?: number;
     ignore?: string[];
   };
+  shell?: {
+    enabled?: boolean;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+  };
   attachments?: {
     maxFileBytes?: number;
     maxSessionBytes?: number;
@@ -175,6 +180,7 @@ type WorkerServerOptions = {
   };
   maxBodyBytes?: number;
   disableBypassPermissions?: boolean;
+  approvalTimeoutMs?: number | null;
   requireApiKey?: boolean;
   checkCredentials?: boolean | {
     probe?: ClaudeAuthProbe;
@@ -270,7 +276,7 @@ type ProviderRunnerOptions = {
     toolName: string;
     input: unknown;
   }) => boolean;
-  approvalTimeoutMs?: number;
+  approvalTimeoutMs?: number | null;
   onClose?: () => void | Promise<void>;
 };
 declare function createProviderRunner(ctx: EngineRunnerContext, options: ProviderRunnerOptions): Promise<Runner>;

package/build/index.mjs

@@ -2,12 +2,13 @@ import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
 import { BrowserBridgeExecutor, SessionRunner, attachmentKind, checkClaudeAuth, createEngineSession, getEngineAdapter, normalizeMediaType } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, imagePartRef, sessionState, supportsPermissionMode } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, SHELL_COMMAND_MAX, imagePartRef, sessionState, supportsPermissionMode } from "@workerdeck/protocol";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { constants as constants$1, homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
 //#region src/lib/http.ts
 const CONTENT_TYPES = {
 	json: "application/json; charset=utf-8",
@@ -1626,9 +1627,152 @@ async function handleSessions(ctx, req, res, route, auth) {
 	}
 	json(res, 405, { error: "method not allowed" });
 }
+const TIMEOUT_EXIT_CODE = 124;
+const SPAWN_FAILURE_EXIT_CODE = 127;
+const KILLED_EXIT_CODE = 128 + constants$1.signals.SIGKILL;
+function shellPermitted(shell, runner, operator) {
+	if (shell === null || !operator) return false;
+	const info = runner.info();
+	return (info.capabilities ?? (info.engine ? ENGINE_CAPABILITIES[info.engine] : void 0))?.hostCwd === true;
+}
+function shellChildEnv(base) {
+	const env = {};
+	for (const [key, value] of Object.entries(base)) if (value !== void 0) env[key] = value;
+	return env;
+}
+function createShellService(options = {}) {
+	const timeoutMs = options.timeoutMs ?? 12e4;
+	const maxOutputBytes = options.maxOutputBytes ?? 32768;
+	const active = /* @__PURE__ */ new Map();
+	const run = async (sessionId, cwd, command) => {
+		if (active.has(sessionId)) throw new Error("a shell command is still running on this session");
+		const child = spawnShell({
+			command,
+			cwd,
+			env: shellChildEnv(process.env),
+			timeoutMs,
+			maxOutputBytes
+		});
+		active.set(sessionId, child);
+		try {
+			return await child.result;
+		} finally {
+			if (active.get(sessionId) === child) active.delete(sessionId);
+		}
+	};
+	const kill = (sessionId, reason = "session closed") => {
+		active.get(sessionId)?.kill(reason);
+	};
+	const watch = (runner) => runner.subscribe((event) => {
+		if (event.type === "session_closed") kill(runner.id, "session closed");
+		else if (event.type === "status_changed" && event.status === "parked") kill(runner.id, "session parked");
+	}, runner.info().lastSeq);
+	const killAll = () => {
+		for (const sessionId of active.keys()) kill(sessionId, "server shutting down");
+	};
+	const running = (sessionId) => active.has(sessionId);
+	return {
+		run,
+		kill,
+		watch,
+		killAll,
+		running,
+		timeoutMs,
+		maxOutputBytes
+	};
+}
+var BoundedOutput = class {
+	#chunks = [];
+	#kept = 0;
+	#dropped = 0;
+	#budget;
+	constructor(budget) {
+		this.#budget = budget;
+	}
+	push(chunk) {
+		const take = Math.min(chunk.length, this.#budget.remaining);
+		if (take > 0) {
+			this.#chunks.push(take === chunk.length ? chunk : chunk.subarray(0, take));
+			this.#kept += take;
+			this.#budget.remaining -= take;
+		}
+		this.#dropped += chunk.length - take;
+	}
+	text() {
+		const head = Buffer.concat(this.#chunks, this.#kept).toString("utf8");
+		return this.#dropped > 0 ? `${head}\n[output truncated: ${this.#dropped} more bytes dropped]` : head;
+	}
+};
+function spawnShell(input) {
+	const startedAt = Date.now();
+	const budget = { remaining: input.maxOutputBytes };
+	const stdout = new BoundedOutput(budget);
+	const stderr = new BoundedOutput(budget);
+	let settle;
+	const result = new Promise((resolve) => {
+		settle = resolve;
+	});
+	let done = false;
+	const finish = (exitCode, note) => {
+		if (done) return;
+		done = true;
+		clearTimeout(timer);
+		const captured = stderr.text();
+		const stderrText = note ? captured ? `${captured}\n[${note}]` : `[${note}]` : captured;
+		settle?.({
+			command: input.command,
+			stdout: stdout.text(),
+			stderr: stderrText,
+			exitCode,
+			durationMs: Date.now() - startedAt
+		});
+	};
+	const child = spawn("/bin/sh", ["-c", input.command], {
+		cwd: input.cwd,
+		env: {
+			...input.env,
+			PWD: input.cwd
+		},
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		detached: true
+	});
+	child.stdout.on("data", (chunk) => stdout.push(chunk));
+	child.stderr.on("data", (chunk) => stderr.push(chunk));
+	const killGroup = () => {
+		if (child.pid === void 0) return;
+		try {
+			process.kill(-child.pid, "SIGKILL");
+		} catch {
+			try {
+				child.kill("SIGKILL");
+			} catch {}
+		}
+		child.stdout.destroy();
+		child.stderr.destroy();
+	};
+	const kill = (reason, exitCode = KILLED_EXIT_CODE) => {
+		if (done) return;
+		killGroup();
+		finish(exitCode, `killed: ${reason}`);
+	};
+	const timer = setTimeout(() => kill(`timed out after ${Math.round(input.timeoutMs / 1e3)}s`, TIMEOUT_EXIT_CODE), input.timeoutMs);
+	child.on("error", (error) => finish(SPAWN_FAILURE_EXIT_CODE, error.message));
+	child.on("close", (code, signal) => {
+		const signalCode = signal ? constants$1.signals[signal] ?? 0 : 0;
+		finish(code ?? (signalCode ? 128 + signalCode : 1), signal ? `killed by ${signal}` : void 0);
+	});
+	return {
+		result,
+		kill: (reason) => kill(reason)
+	};
+}
 //#endregion
 //#region src/routes/ws.ts
-function attachClient(ctx, ws, runner, req) {
+function attachClient(ctx, ws, runner, req, access) {
 	const { bridge, parking } = ctx;
 	const url = new URL(req.url ?? "/", "http://internal");
 	const afterSeq = Number(url.searchParams.get("afterSeq") ?? "0") || 0;
@@ -1641,7 +1785,8 @@ function attachClient(ctx, ws, runner, req) {
 		type: "attached",
 		protocolVersion: PROTOCOL_VERSION,
 		session: ctx.projects.withProject(runner.info()),
-		replayingFrom: afterSeq
+		replayingFrom: afterSeq,
+		...shellPermitted(ctx.shell, runner, access.operator) ? { shell: true } : {}
 	});
 	const unsubscribe = runner.subscribe((event) => send({
 		type: "event",
@@ -1663,7 +1808,7 @@ function attachClient(ctx, ws, runner, req) {
 			});
 			return;
 		}
-		handleCommand(ctx, frame, runner).catch((error) => {
+		handleCommand(ctx, frame, runner, access).catch((error) => {
 			send({
 				type: "protocol_error",
 				message: error instanceof Error ? error.message : "command failed"
@@ -1676,7 +1821,7 @@ function attachClient(ctx, ws, runner, req) {
 		parking.onDetach(runner.id);
 	});
 }
-async function handleCommand(ctx, frame, runner) {
+async function handleCommand(ctx, frame, runner, access) {
 	const { attachmentStore, bridge } = ctx;
 	switch (frame.type) {
 		case "user_message": {
@@ -1727,6 +1872,16 @@ async function handleCommand(ctx, frame, runner) {
 				logs: frame.logs
 			});
 			return;
+		case "shell_command": {
+			if (!shellPermitted(ctx.shell, runner, access.operator) || ctx.shell === null) throw new Error("shell commands are not available on this session");
+			if (typeof frame.command !== "string" || frame.command.includes("\0")) throw new Error("shell command must be a string");
+			if (frame.command.length > SHELL_COMMAND_MAX) throw new Error(`shell command exceeds ${SHELL_COMMAND_MAX} characters`);
+			if (frame.command.trim() === "") throw new Error("shell command is empty");
+			if (!runner.queueLocalCommand) throw new Error(`the ${runner.info().engine ?? "claude"} engine cannot take shell output`);
+			const result = await ctx.shell.run(runner.id, runner.info().cwd, frame.command);
+			runner.queueLocalCommand(result);
+			return;
+		}
 		case "close":
 			runner.close("client");
 			return;
@@ -2781,14 +2936,18 @@ function createSessionFactory(deps) {
 		...config,
 		scope
 	};
+	const withApprovalDefault = (config) => deps.approvalTimeoutMs === void 0 ? config : {
+		...config,
+		defaultApprovalTimeoutMs: deps.approvalTimeoutMs
+	};
 	const buildRunnerConfig = (req) => {
 		const profile = req.profile !== void 0 ? profiles.get(req.profile) : void 0;
-		if (!profile) return withScope(deps.hostBuildRunnerConfig(req), req.scope);
-		const config = withScope(deps.hostBuildRunnerConfig({
+		if (!profile) return withApprovalDefault(withScope(deps.hostBuildRunnerConfig(req), req.scope));
+		const config = withApprovalDefault(withScope(deps.hostBuildRunnerConfig({
 			...req,
 			model: req.model ?? profile.defaults?.model ?? profile.provider?.model,
 			permissionMode: req.permissionMode ?? profile.defaults?.permissionMode
-		}), req.scope);
+		}), req.scope));
 		if (engineOf(profile) !== "claude") return config;
 		const base = config.env ?? process.env;
 		const env = claudeSessionEnv(profile, base);
@@ -2953,6 +3112,7 @@ function createWorkerServer(options = {}) {
 		createEngineRunner: options.createEngineRunner,
 		allowedCwdRoots: options.allowedCwdRoots,
 		disableBypassPermissions: options.disableBypassPermissions,
+		approvalTimeoutMs: options.approvalTimeoutMs,
 		requireApiKey: options.requireApiKey,
 		refs
 	});
@@ -2968,10 +3128,12 @@ function createWorkerServer(options = {}) {
 		decorateInfo: (info) => projects.withProject(info)
 	});
 	const producedFiles = new ProducedFileStore();
+	const shell = options.shell?.enabled === true ? createShellService(options.shell) : null;
 	const registry = new SessionRegistry({ onRegister: (runner) => {
 		notifier.watch(runner);
 		producedFiles.watch(runner);
 		profileUsage.watch(runner);
+		shell?.watch(runner);
 		const profile = runner.info().profile;
 		if (!profile) return;
 		runner.subscribe((event) => {
@@ -3073,7 +3235,8 @@ function createWorkerServer(options = {}) {
 		hostFiles,
 		hostFilesWritable: options.hostFiles?.write === true,
 		maxHostFileBytes: options.hostFiles?.maxFileBytes ?? 1048576,
-		maxHostDirEntries: options.hostFiles?.maxEntries ?? 5e3
+		maxHostDirEntries: options.hostFiles?.maxEntries ?? 5e3,
+		shell
 	};
 	const handleRequest = async (req, res) => {
 		const pathname = new URL(req.url ?? "/", "http://internal").pathname;
@@ -3231,7 +3394,7 @@ function createWorkerServer(options = {}) {
 				return;
 			}
 			wss.handleUpgrade(req, socket, head, (ws) => {
-				attachClient(ctx, ws, runner, req);
+				attachClient(ctx, ws, runner, req, { operator: auth.isOperator(authCtx) });
 			});
 		})().catch(() => socket.destroy());
 	});
@@ -3278,6 +3441,7 @@ function createWorkerServer(options = {}) {
 				queue?.close();
 				parking.close();
 				registry.closeAll();
+				shell?.killAll();
 				for (const ws of wss.clients) ws.close(1001, "server shutting down");
 				queueSockets.clear();
 				const force = setTimeout(() => {
@@ -3342,7 +3506,7 @@ async function createProviderRunner(ctx, options) {
 		instructions: options.instructions,
 		executionLimits: options.executionLimits,
 		shouldApprove: options.shouldApprove,
-		approvalTimeoutMs: options.approvalTimeoutMs,
+		approvalTimeoutMs: config.defaultApprovalTimeoutMs === void 0 ? options.approvalTimeoutMs : config.defaultApprovalTimeoutMs,
 		seedVfs: options.seedVfs
 	});
 }