@workerdeck/server 2.7.2 → 2.9.0

package/build/index.mjs

@@ -2,7 +2,7 @@ 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, SHELL_COMMAND_MAX, imagePartRef, sessionState, supportsPermissionMode } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, SHELL_COMMAND_MAX, imagePartRef, isJobRun, 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 { constants as constants$1, homedir } from "node:os";
@@ -211,6 +211,15 @@ function parseSessionRoute(basePath, url) {
 	return null;
 }
 //#endregion
+//#region src/lib/reload-plan.ts
+function reloadPlan(runner) {
+	const info = runner.info();
+	if (info.status === "closed" || info.status === "failed") return "drop";
+	if (isJobRun(info)) return "drop";
+	if (runner.snapshot !== void 0) return "persist";
+	return "carry";
+}
+//#endregion
 //#region src/routes/executions.ts
 async function handleExecutionResult(ctx, req, res, pathname, auth) {
 	const { auth: authSvc, basePath, parking, registry } = ctx;
@@ -712,7 +721,7 @@ async function handleHostFiles(ctx, req, res, pathname) {
 		}
 		const existing = current.ok ? current.data : null;
 		if (existing && !body.expectedHash) {
-			json(res, 409, { error: "file exists — pass expectedHash to overwrite it" });
+			json(res, 409, { error: "file exists - pass expectedHash to overwrite it" });
 			return;
 		}
 		if (existing && hashBytes(existing) !== body.expectedHash) {
@@ -1068,7 +1077,7 @@ function createFileSessionStore(options = {}) {
 					path,
 					op: "save"
 				});
-				throw new Error(`parked session '${record.id}' is not JSON-serializable — a host-injected value reached its config or snapshot: ${String(error)}`, { cause: error });
+				throw new Error(`parked session '${record.id}' is not JSON-serializable - a host-injected value reached its config or snapshot: ${String(error)}`, { cause: error });
 			}
 			try {
 				await mkdir(dir, {
@@ -1808,6 +1817,7 @@ function attachClient(ctx, ws, runner, req, access) {
 		imageRefs
 	});
 	const detachBridge = bridge.attach(runner.id, send);
+	runner.refreshUsage?.().catch(() => {});
 	ws.on("message", (data) => {
 		let frame;
 		try {
@@ -2209,8 +2219,8 @@ var SessionNotifier = class {
 		return !this.#options.webhook && !this.#options.onNotification;
 	}
 	watch(runner, afterSeq = runner.info().lastSeq) {
-		if (this.idle) return;
-		runner.subscribe((event) => {
+		if (this.idle) return () => {};
+		return runner.subscribe((event) => {
 			switch (event.type) {
 				case "permission_requested":
 					this.#emit(runner, event.seq, event.ts, {
@@ -2301,6 +2311,7 @@ var SessionParkManager = class {
 	#configs = /* @__PURE__ */ new Map();
 	#remembered = /* @__PURE__ */ new Set();
 	#storeOps = /* @__PURE__ */ new Map();
+	#watches = /* @__PURE__ */ new Map();
 	#closed = false;
 	constructor(options) {
 		this.#options = options;
@@ -2320,7 +2331,8 @@ var SessionParkManager = class {
 		}
 	}
 	watch(runner, afterSeq = 0) {
-		return runner.subscribe((event) => {
+		this.#watches.get(runner.id)?.();
+		const unsubscribe = runner.subscribe((event) => {
 			switch (event.type) {
 				case "execution_dispatched":
 					if (!event.deferred) return;
@@ -2360,6 +2372,35 @@ var SessionParkManager = class {
 				default: return;
 			}
 		}, afterSeq);
+		const detach = () => {
+			if (this.#watches.get(runner.id) === detach) this.#watches.delete(runner.id);
+			unsubscribe();
+		};
+		this.#watches.set(runner.id, detach);
+		return detach;
+	}
+	release(sessionId) {
+		this.#watches.get(sessionId)?.();
+		this.#watches.delete(sessionId);
+		clearTimeout(this.#detachTimers.get(sessionId));
+		this.#detachTimers.delete(sessionId);
+		const config = this.#configs.get(sessionId);
+		this.#configs.delete(sessionId);
+		this.#remembered.delete(sessionId);
+		return config;
+	}
+	adopt(runner, config) {
+		this.#options.registry.register(runner);
+		if (config) this.remember(runner.id, config);
+		this.watch(runner, runner.info().lastSeq);
+		this.touch(runner);
+	}
+	async flush(sessionId) {
+		if (sessionId === void 0) {
+			await Promise.all(this.#storeOps.values());
+			return;
+		}
+		await this.#storeOps.get(sessionId);
 	}
 	onDetach(sessionId) {
 		if (this.#closed) return;
@@ -2411,6 +2452,7 @@ var SessionParkManager = class {
 		};
 	}
 	async discard(sessionId) {
+		this.#watches.delete(sessionId);
 		clearTimeout(this.#detachTimers.get(sessionId));
 		this.#detachTimers.delete(sessionId);
 		this.#configs.delete(sessionId);
@@ -2574,7 +2616,7 @@ var SessionParkManager = class {
 		}
 		if (runner.id !== id) {
 			runner.close("error");
-			const error = /* @__PURE__ */ new Error(`rebuilt session has id '${runner.id}', expected '${id}' — the engine factory must forward EngineRunnerContext.restore (or, without a snapshot, the session id) to the runner config`);
+			const error = /* @__PURE__ */ new Error(`rebuilt session has id '${runner.id}', expected '${id}' - the engine factory must forward EngineRunnerContext.restore (or, without a snapshot, the session id) to the runner config`);
 			this.#options.onError?.(error, {
 				sessionId: id,
 				phase: "resume"
@@ -2639,7 +2681,7 @@ var SessionParkManager = class {
 var ProducedFileStore = class {
 	#bySession = /* @__PURE__ */ new Map();
 	watch(runner) {
-		runner.subscribe((event) => {
+		return runner.subscribe((event) => {
 			if (event.type !== "file_produced") return;
 			const held = this.#bySession.get(runner.id) ?? /* @__PURE__ */ new Map();
 			held.set(event.fileId, {
@@ -2682,7 +2724,7 @@ var ProfileService = class {
 			if (!hasEngineRunnerFactory) return `profile '${p.name}' uses engine 'provider' but no \`createEngineRunner\` was provided to build one`;
 		} else if (p.engine === "codex") {
 			if (p.codexHome && !existsSync(p.codexHome)) return `profile '${p.name}' codexHome does not exist: ${p.codexHome}`;
-			if (p.session?.instructions) return `profile '${p.name}' declares session.instructions, which the codex engine cannot deliver — put instructions in the target repo’s AGENTS.md instead`;
+			if (p.session?.instructions) return `profile '${p.name}' declares session.instructions, which the codex engine cannot deliver - put instructions in the target repo’s AGENTS.md instead`;
 		} else if (!p.configDir || !existsSync(p.configDir)) return `profile '${p.name}' configDir does not exist: ${p.configDir}`;
 		if (disableBypassPermissions && p.defaults?.permissionMode === "bypassPermissions") return `profile '${p.name}' defaults to bypassPermissions but disableBypassPermissions is set`;
 		const fallbackMode = p.defaults?.permissionMode;
@@ -2745,7 +2787,7 @@ var ProfileService = class {
 	declaredGuard(profile) {
 		return this.#declaredByName.has(profile.name) ? {
 			status: 403,
-			error: `profile '${profile.name}' is declared in server options and cannot be changed over the API — edit the \`profiles\` option instead`
+			error: `profile '${profile.name}' is declared in server options and cannot be changed over the API - edit the \`profiles\` option instead`
 		} : null;
 	}
 	configDirGuard(profile) {
@@ -2790,8 +2832,8 @@ var ProfileUsageTracker = class {
 	#profiles = /* @__PURE__ */ new Map();
 	watch(runner) {
 		const profile = runner.info().profile;
-		if (!profile) return;
-		runner.subscribe((event) => {
+		if (!profile) return () => {};
+		return runner.subscribe((event) => {
 			if (event.type !== "rate_limit") return;
 			const type = event.info.rateLimitType;
 			if (!type) return;
@@ -2835,12 +2877,13 @@ var SessionRegistry = class {
 	#sessions = /* @__PURE__ */ new Map();
 	#options;
 	#observers = /* @__PURE__ */ new Set();
+	#detachers = /* @__PURE__ */ new Map();
 	constructor(options = {}) {
 		this.#options = options;
 	}
 	observe(listener) {
 		this.#observers.add(listener);
-		for (const runner of this.#sessions.values()) listener(runner);
+		for (const runner of this.#sessions.values()) this.#retain(runner.id, listener(runner));
 		return () => void this.#observers.delete(listener);
 	}
 	create(config) {
@@ -2858,11 +2901,14 @@ var SessionRegistry = class {
 		const existing = this.#sessions.get(runner.id);
 		this.#sessions.set(runner.id, runner);
 		if (existing !== runner) {
-			this.#options.onRegister?.(runner);
-			for (const listener of this.#observers) listener(runner);
+			this.#retain(runner.id, this.#options.onRegister?.(runner));
+			for (const listener of this.#observers) this.#retain(runner.id, listener(runner));
 		}
 		return runner;
 	}
+	retain(id, detach) {
+		this.#retain(id, detach);
+	}
 	get(id) {
 		return this.#sessions.get(id);
 	}
@@ -2873,14 +2919,30 @@ var SessionRegistry = class {
 		const runner = this.#sessions.get(id);
 		if (!runner) return false;
 		runner.close("server");
+		this.#detach(id);
 		return this.#sessions.delete(id);
 	}
 	evict(id) {
+		this.#detach(id);
 		return this.#sessions.delete(id);
 	}
 	closeAll() {
 		for (const runner of this.#sessions.values()) runner.close("server");
 	}
+	#retain(id, detach) {
+		if (typeof detach !== "function") return;
+		const run = detach;
+		const existing = this.#detachers.get(id);
+		if (existing) {
+			existing.push(run);
+			return;
+		}
+		this.#detachers.set(id, [run]);
+	}
+	#detach(id) {
+		for (const detach of this.#detachers.get(id) ?? []) detach();
+		this.#detachers.delete(id);
+	}
 };
 //#endregion
 //#region src/services/session-factory.ts
@@ -2895,13 +2957,13 @@ function createSessionFactory(deps) {
 	};
 	const checkPermissionMode = (mode, profile) => {
 		if (mode === void 0 || supportsPermissionMode(profile?.engine, mode)) return null;
-		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${engineOf(profile)}') — supported: ` + adapterFor(profile?.engine).capabilities.permissionModes.join(", ");
+		return `permission mode '${mode}' is not supported by profile '${profile.name}' (engine '${engineOf(profile)}') - supported: ` + adapterFor(profile?.engine).capabilities.permissionModes.join(", ");
 	};
 	const checkEngineGrants = (req, profile) => {
 		const engine = engineOf(profile);
 		const caps = adapterFor(profile?.engine).capabilities;
 		const name = profile?.name ?? "default";
-		if (!caps.sessionMcpServers && req.mcpServers && Object.keys(req.mcpServers).length > 0) return `profile '${name}' runs the ${engine} engine, whose MCP servers are declared outside the session request — a request cannot add its own`;
+		if (!caps.sessionMcpServers && req.mcpServers && Object.keys(req.mcpServers).length > 0) return `profile '${name}' runs the ${engine} engine, whose MCP servers are declared outside the session request - a request cannot add its own`;
 		if (!caps.budgets && (req.maxTurns !== void 0 || req.maxBudgetUsd !== void 0)) return `the ${engine} engine does not honor maxTurns/maxBudgetUsd`;
 		if (!caps.settingSources && req.settingSources !== void 0) return `the ${engine} engine does not load settingSources`;
 		if (!caps.resume && req.resume !== void 0) return `the ${engine} engine cannot resume a session`;
@@ -2912,7 +2974,7 @@ function createSessionFactory(deps) {
 		if (!req.capabilities || !granted) return null;
 		const ungranted = req.capabilities.filter((c) => !granted.includes(c));
 		if (ungranted.length === 0) return null;
-		return `profile '${profile.name}' does not grant: ${ungranted.join(", ")} (granted: ${granted.join(", ") || "none"}) — a request may narrow capabilities, not widen them`;
+		return `profile '${profile.name}' does not grant: ${ungranted.join(", ")} (granted: ${granted.join(", ") || "none"}) - a request may narrow capabilities, not widen them`;
 	};
 	const stripInertFields = (req, profile) => {
 		if (!adapterFor(profile?.engine).capabilities.interactiveApprovals) delete req.questionBehavior;
@@ -3006,7 +3068,7 @@ function createSessionFactory(deps) {
 			id
 		});
 		const reported = runner.info().scope;
-		if (!sameScope(reported, config.scope)) throw new Error(`runner for session ${runner.id} reports scope ${JSON.stringify(reported)}, expected ${JSON.stringify(config.scope)} — echo config.scope from info()`);
+		if (!sameScope(reported, config.scope)) throw new Error(`runner for session ${runner.id} reports scope ${JSON.stringify(reported)}, expected ${JSON.stringify(config.scope)} - echo config.scope from info()`);
 		return runner;
 	};
 	const createRunner = async (config) => {
@@ -3052,7 +3114,7 @@ function createSessionFactory(deps) {
 	};
 	const watchAuthSource = (runner) => {
 		let seen = false;
-		runner.subscribe((event) => {
+		return runner.subscribe((event) => {
 			if (seen || event.type !== "system_init") return;
 			seen = true;
 			if (event.apiKeySource !== "oauth") return;
@@ -3062,7 +3124,7 @@ function createSessionFactory(deps) {
 				if (subscriptionNoticeShown.has(profileName)) return;
 				subscriptionNoticeShown.add(profileName);
 				const scope = profileName ? `Sessions under profile '${profileName}'` : "Sessions";
-				console.warn(`[workerdeck] ${scope} are using claude.ai subscription credentials (apiKeySource 'oauth'), not an API key. That is only appropriate for personal, single-user use of your own account. Unattended/scheduled or multi-user use requires an API key under Anthropic's terms — set ANTHROPIC_API_KEY in the server environment, or set requireApiKey: true to fail closed.`);
+				console.warn(`[workerdeck] ${scope} are using claude.ai subscription credentials (apiKeySource 'oauth'), not an API key. That is only appropriate for personal, single-user use of your own account. Unattended/scheduled or multi-user use requires an API key under Anthropic's terms - set ANTHROPIC_API_KEY in the server environment, or set requireApiKey: true to fail closed.`);
 			}
 		});
 	};
@@ -3084,6 +3146,8 @@ function createSessionFactory(deps) {
 //#endregion
 //#region src/server.ts
 const SOCKET_CLOSE_GRACE_MS = 250;
+const CLOSE_DEADLINE_MS = 1e3;
+const USAGE_STALE_MS = 3e5;
 function surveyDrain(registry) {
 	const working = [];
 	const awaitingHuman = [];
@@ -3110,6 +3174,19 @@ function createWorkerServer(options = {}) {
 	const adapterFor = (engine) => options.engines?.[engine ?? "claude"] ?? getEngineAdapter(engine);
 	const profileDefaultModels = /* @__PURE__ */ new Map();
 	const profileUsage = new ProfileUsageTracker();
+	const refreshStaleUsage = (name) => {
+		const held = profileUsage.usage(name);
+		const newest = Math.max(0, ...Object.values(held ?? {}).map((window) => window.updatedAt ?? 0));
+		if (Date.now() - newest < USAGE_STALE_MS) return;
+		for (const info of refs.registry?.list() ?? []) {
+			if (info.profile !== name) continue;
+			const runner = refs.registry?.get(info.id);
+			if (runner?.refreshUsage) {
+				runner.refreshUsage().catch(() => {});
+				return;
+			}
+		}
+	};
 	const detected = options.profiles ? [] : detectDefaultProfiles();
 	const profiles = new ProfileService({
 		declared: options.profiles ?? (options.profileStore ? [] : detected),
@@ -3122,7 +3199,10 @@ function createWorkerServer(options = {}) {
 		decorate: {
 			defaultModel: (name) => profileDefaultModels.get(name),
 			availability: (name) => availability.get(name),
-			usage: (name) => profileUsage.usage(name)
+			usage: (name) => {
+				refreshStaleUsage(name);
+				return profileUsage.usage(name);
+			}
 		}
 	});
 	for (const p of options.profiles ?? []) {
@@ -3155,16 +3235,20 @@ function createWorkerServer(options = {}) {
 	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 detachers = [
+			notifier.watch(runner),
+			producedFiles.watch(runner),
+			profileUsage.watch(runner),
+			shell?.watch(runner)
+		];
 		const profile = runner.info().profile;
-		if (!profile) return;
-		runner.subscribe((event) => {
+		if (profile) detachers.push(runner.subscribe((event) => {
 			if (event.type !== "capabilities" || !event.defaultModel) return;
 			profileDefaultModels.set(profile, event.defaultModel);
-		});
+		}));
+		return () => {
+			for (const detach of detachers) detach?.();
+		};
 	} });
 	const attachmentStore = new AttachmentStore(options.attachments);
 	const bridge = new BridgeHub({
@@ -3445,6 +3529,24 @@ function createWorkerServer(options = {}) {
 				});
 			});
 		},
+		releaseSession: (id) => {
+			const runner = registry.get(id);
+			if (!runner) return;
+			const plan = reloadPlan(runner);
+			if (plan !== "carry") throw new Error(`session ${id} cannot be carried by identity (${plan})`);
+			const config = parking.release(id);
+			registry.evict(id);
+			return {
+				runner,
+				config
+			};
+		},
+		adoptSession: ({ runner, config }) => {
+			if (reloadPlan(runner) !== "carry") return false;
+			parking.adopt(runner, config);
+			registry.retain(runner.id, factory.watchAuthSource(runner));
+			return true;
+		},
 		drain: async (drainOptions = {}) => {
 			const { timeoutMs = 3e4, pollMs = 250, onProgress } = drainOptions;
 			draining = true;
@@ -3477,12 +3579,15 @@ function createWorkerServer(options = {}) {
 					for (const ws of wss.clients) ws.terminate();
 				}, SOCKET_CLOSE_GRACE_MS);
 				force.unref();
-				wss.close();
-				server.close(() => {
+				const deadline = setTimeout(() => resolve(), CLOSE_DEADLINE_MS);
+				deadline.unref();
+				const drained = Promise.all([new Promise((done) => wss.close(() => done())), new Promise((done) => server.close(() => done()))]);
+				server.closeAllConnections();
+				drained.then(() => {
 					clearTimeout(force);
+					clearTimeout(deadline);
 					resolve();
 				});
-				server.closeAllConnections();
 			});
 			return closing;
 		}
@@ -3579,6 +3684,6 @@ function createFileProfileStore(path = join(process.cwd(), ".workerdeck", "profi
 	};
 }
 //#endregion
-export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, sandboxedProviderProfile, toDurableRecord };
+export { AttachmentStore, BridgeHub, MemorySessionStore, ProducedFileStore, ProfileUsageTracker, SessionNotifier, SessionParkManager, SessionRegistry, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, isDormant, reloadPlan, sandboxedProviderProfile, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map