@workerdeck/server 3.1.0 → 3.3.0

package/build/index.d.mts

@@ -2,6 +2,7 @@ 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, ShellDirectory, ToolExecutionCall, ToolExecutionResult, ToolExecutor, ToolSet } from "@workerdeck/core";
 import { JobQueue, QueueAdapter } from "@workerdeck/queue";
 import { ByModel, CreateSessionRequest, JobEvent, MessageAttachment, ModelRate, PricingTable, ProfileEngine, ProfileInfo, ProfileSpend, ProfileUsage, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig, ShellEndReason, ShellInfo, ShellOwner } from "@workerdeck/protocol";
+import { RelayOp } from "@workerdeck/relay-client";
 //#region src/services/bridge.d.ts
 type BridgeHubOptions = {
   timeoutMs?: number;
@@ -154,6 +155,20 @@ type PeerServiceOptions = {
   maxHops?: number;
 };
 //#endregion
+//#region src/services/peer-relay.d.ts
+type RelayLinkOptions = {
+  url: string;
+  gateway: string;
+  key?: string;
+  keyFile?: string;
+  caFile?: string;
+  expose?: {
+    scope?: Record<string, string>;
+    allow?: RelayOp[];
+  };
+  log?: (message: string) => void;
+};
+//#endregion
 //#region src/services/profile-store.d.ts
 type ProfileStore = {
   list(): ProfileInfo[] | Promise<ProfileInfo[]>;
@@ -354,6 +369,7 @@ type WorkerServerOptions = {
   listSdkSessions?: SdkSessionLister;
   queue?: QueueServerOptions;
   peers?: PeerServiceOptions;
+  relay?: RelayLinkOptions;
   notifications?: SessionNotificationOptions;
   bridge?: BridgeHubOptions;
   parking?: {
@@ -430,6 +446,7 @@ type WorkerServer = {
   drain: (options?: DrainOptions) => Promise<DrainReport>;
   releaseSession: (id: string) => CarriedSession | undefined;
   adoptSession: (carried: CarriedSession) => boolean;
+  releaseRelay: () => void;
   close: () => Promise<void>;
 };
 //#endregion
@@ -536,5 +553,5 @@ declare class ProfileUsageTracker {
   usage(profile: string, now?: number): ProfileUsage | undefined;
 }
 //#endregion
-export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type CarriedSession, type DiagnosticSink, type EngineRunnerContext, type FileSessionStoreOptions, type JsonWriteOptions, MemorySessionStore, type NotificationErrorContext, 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, isMissing, readJsonOr, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord, writeFileAtomic, writeJsonAtomic };
+export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type CarriedSession, type DiagnosticSink, type EngineRunnerContext, type FileSessionStoreOptions, type JsonWriteOptions, MemorySessionStore, type NotificationErrorContext, type ParkedSessionRecord, type ProcessRow, type ProcessTable, type ProducedFile, ProducedFileStore, type ProfileStore, ProfileUsageTracker, type ProviderRunnerOptions, type QueueServerOptions, type RelayLinkOptions, 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, isMissing, readJsonOr, reloadPlan, sandboxedProviderProfile, shellPermitted, toDurableRecord, writeFileAtomic, writeJsonAtomic };
 //# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -10,6 +10,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { chmod, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
 import xtermHeadless from "@xterm/headless";
+import { connectRelay, parseRelayPeerId } from "@workerdeck/relay-client";
 //#region src/lifecycle.ts
 const SOCKET_CLOSE_GRACE_MS = 250;
 const CLOSE_DEADLINE_MS = 1e3;
@@ -4625,6 +4626,163 @@ function createFileSpendStore(path, onError) {
 	};
 }
 //#endregion
+//#region src/services/peer-relay.ts
+const CARRIED = Symbol.for("workerdeck.relay.carried");
+const slots = globalThis;
+const UNAVAILABLE = "Remote gateways are unavailable right now; only sessions on this gateway are listed.";
+function expandHome(path) {
+	return path === "~" || path.startsWith("~/") ? `${homedir()}${path.slice(1)}` : path;
+}
+function identityOf(options) {
+	return JSON.stringify([
+		options.url,
+		options.gateway,
+		options.keyFile ?? "",
+		options.key ? "inline" : "",
+		options.caFile ?? "",
+		options.expose?.allow ?? null
+	]);
+}
+function remoteSummary(row) {
+	return {
+		id: `${row.gateway}:${row.id}`,
+		gateway: row.gateway,
+		engine: row.engine,
+		status: row.status,
+		title: row.title,
+		project: row.project?.name,
+		projectRoot: row.project?.root,
+		cwd: row.cwd,
+		profile: row.profile,
+		model: row.model,
+		contextUsage: row.contextUsage,
+		lastActivityAt: row.lastActivityAt,
+		pendingPermissionCount: row.pendingPermissionCount,
+		allow: row.allow
+	};
+}
+function remotePeek(gateway, peek) {
+	const { allow: _allow, ...summary } = remoteSummary({
+		...peek,
+		gateway,
+		allow: []
+	});
+	return {
+		...summary,
+		live: peek.live,
+		checklist: peek.checklistItems,
+		pendingApprovals: peek.pendingApprovals,
+		recent: peek.recent
+	};
+}
+async function readRelayKey(options) {
+	if (options.key) return options.key;
+	if (!options.keyFile) throw new Error("relay: set relay.keyFile (or WORKERDECK_RELAY_KEY) to the key `workerdeck relay enroll` printed");
+	const key = (await readFile(expandHome(options.keyFile), "utf8")).trim();
+	if (!key) throw new Error(`relay: ${options.keyFile} is empty`);
+	return key;
+}
+function createRelayLink(options, peers, log) {
+	const identity = identityOf(options);
+	const exposed = options.expose?.scope;
+	let connection;
+	let closed = false;
+	let released = false;
+	const host = {
+		snapshot: () => peers.relayEntries(exposed),
+		peek: (_origin, sessionId, recent) => peers.relayPeek(sessionId, recent, exposed),
+		send: (origin, sessionId, text) => peers.relaySend(origin, sessionId, text, exposed)
+	};
+	const carried = slots[CARRIED];
+	if (carried) {
+		delete slots[CARRIED];
+		if (carried.identity === identity && carried.connection.state() !== "stopped") {
+			carried.connection.setHost(host);
+			connection = carried.connection;
+		} else carried.connection.close();
+	}
+	if (!connection) (async () => {
+		const key = await readRelayKey(options);
+		const ca = options.caFile ? await readFile(expandHome(options.caFile)) : void 0;
+		if (!closed) connection = connectRelay({
+			url: options.url,
+			gateway: options.gateway,
+			key,
+			ca,
+			allow: options.expose?.allow,
+			log
+		}, host);
+	})().catch((error) => log(error instanceof Error ? error.message : String(error)));
+	const remoteTarget = parseRelayPeerId;
+	const reachesRemote = async (from) => {
+		const me = await peers.relaySender(from);
+		return me.scope === void 0 || Object.keys(me.scope).length === 0;
+	};
+	return {
+		directory: {
+			list: async (from) => {
+				const local = await peers.list(from);
+				if (!connection || connection.state() !== "online" || !await reachesRemote(from)) return local;
+				try {
+					return [...local, ...(await connection.list(from)).map(remoteSummary)];
+				} catch {
+					return local;
+				}
+			},
+			notice: async (from) => {
+				if (!await reachesRemote(from)) return;
+				return connection?.state() === "online" ? void 0 : UNAVAILABLE;
+			},
+			peek: async (from, sessionId, peekOptions) => {
+				const target = remoteTarget(sessionId);
+				if (!target) return peers.peek(from, sessionId, peekOptions);
+				if (!connection || !await reachesRemote(from)) return;
+				const peek = await connection.peek(from, target, peekOptions?.recent);
+				return peek ? remotePeek(target.gateway, peek) : void 0;
+			},
+			send: async (from, sessionId, text, sendOptions) => {
+				const target = remoteTarget(sessionId);
+				if (!target) return peers.send(from, sessionId, text, sendOptions);
+				if (!await reachesRemote(from)) return {
+					delivered: false,
+					reason: `no such session: ${sessionId}`
+				};
+				if (!connection || connection.state() !== "online") return {
+					delivered: false,
+					reason: "remote gateways are unavailable right now; try again later"
+				};
+				try {
+					const result = await connection.send(from, target, text, sendOptions?.hops ?? peers.relayChain(from));
+					return result.delivered ? {
+						...result,
+						sessionId
+					} : result;
+				} catch (error) {
+					return {
+						delivered: false,
+						reason: error instanceof Error ? error.message : String(error)
+					};
+				}
+			}
+		},
+		nudge: () => connection?.nudge(),
+		release: () => {
+			if (connection && !closed) {
+				released = true;
+				slots[CARRIED] = {
+					identity,
+					connection
+				};
+			}
+		},
+		close: () => {
+			closed = true;
+			if (!released) connection?.close();
+			connection = void 0;
+		}
+	};
+}
+//#endregion
 //#region src/services/peers.ts
 const DEFAULT_PER_MINUTE = 10;
 const DEFAULT_MAX_HOPS = 12;
@@ -4632,6 +4790,33 @@ const WINDOW_MS = 6e4;
 function visible(from, to) {
 	return to.id !== from.id && scopeMatches(from.scope, to.scope);
 }
+function relayEntry(info, live) {
+	const items = info.checklist;
+	return {
+		id: info.id,
+		engine: info.engine,
+		status: info.status,
+		title: info.title,
+		project: info.project ? {
+			name: info.project.name,
+			root: info.project.root
+		} : void 0,
+		cwd: info.cwd,
+		profile: info.profile,
+		model: info.model,
+		permissionMode: info.permissionMode,
+		contextUsage: info.contextUsage,
+		checklist: items?.length ? {
+			done: items.filter((item) => item.status === "completed").length,
+			total: items.length
+		} : void 0,
+		numTurns: info.numTurns,
+		createdAt: info.createdAt,
+		lastActivityAt: info.lastActivityAt,
+		pendingPermissionCount: info.pendingPermissionCount,
+		live
+	};
+}
 function createPeerService(deps) {
 	const perMinute = deps.options?.perMinute ?? DEFAULT_PER_MINUTE;
 	const maxChars = deps.options?.maxMessageChars ?? PEER_MESSAGE_MAX_CHARS;
@@ -4659,6 +4844,19 @@ function createPeerService(deps) {
 		if (!info) throw new Error(`unknown sender session: ${from}`);
 		return info;
 	};
+	const recentOf = (sessionId, recent) => {
+		const limit = Math.min(Math.max(recent ?? PEER_RECENT_DEFAULT, 0), PEER_RECENT_MAX);
+		const runner = registry().get(sessionId);
+		const events = [];
+		if (runner && limit > 0) runner.subscribe((event) => events.push(event), 0, {
+			truncateResults: true,
+			imageRefs: true
+		})();
+		return {
+			runner,
+			lines: recentLines(events, limit)
+		};
+	};
 	const underRateLimit = (from, to) => {
 		const key = `${from}->${to}`;
 		const now = Date.now();
@@ -4679,19 +4877,13 @@ function createPeerService(deps) {
 		const me = await sender(from);
 		const info = await infoOf(sessionId);
 		if (!info || !visible(me, info)) return;
-		const limit = Math.min(Math.max(options?.recent ?? PEER_RECENT_DEFAULT, 0), PEER_RECENT_MAX);
-		const runner = registry().get(sessionId);
-		const events = [];
-		if (runner && limit > 0) runner.subscribe((event) => events.push(event), 0, {
-			truncateResults: true,
-			imageRefs: true
-		})();
+		const { runner, lines } = recentOf(sessionId, options?.recent);
 		return {
 			...peerSummary(info),
 			live: runner !== void 0,
 			checklist: info.checklist,
 			pendingApprovals: runner ? runner.pendingApprovals.map((request) => request.title ?? request.toolName) : [],
-			recent: recentLines(events, limit)
+			recent: lines
 		};
 	};
 	const send = async (from, sessionId, text, options) => {
@@ -4709,16 +4901,27 @@ function createPeerService(deps) {
 			delivered: false,
 			reason: `no such session: ${sessionId}`
 		};
+		const hops = [...options?.hops ?? inbound.get(from) ?? [], from];
+		return deliver(target, text, {
+			kind: "peer",
+			sessionId: from,
+			name: me.title,
+			engine: me.engine,
+			hops
+		}, from);
+	};
+	const deliver = async (target, text, origin, rateKey) => {
+		const sessionId = target.id;
 		if (target.status === "closed" || target.status === "failed") return {
 			delivered: false,
 			reason: `session ${sessionId} is ${target.status}`
 		};
-		const hops = [...options?.hops ?? inbound.get(from) ?? [], from];
+		const hops = origin.hops ?? [];
 		if (hops.length > maxHops) return {
 			delivered: false,
 			reason: `${hops.length} messages have passed between sessions without a person speaking; stop and ask your user before continuing.`
 		};
-		if (!underRateLimit(from, sessionId)) return {
+		if (!underRateLimit(rateKey, sessionId)) return {
 			delivered: false,
 			reason: `rate limit: at most ${perMinute} messages a minute to one session. Batch what you have to say.`
 		};
@@ -4728,13 +4931,6 @@ function createPeerService(deps) {
 			reason: `session ${sessionId} could not be woken`
 		};
 		const before = runner.info().status;
-		const origin = {
-			kind: "peer",
-			sessionId: from,
-			name: me.title,
-			engine: me.engine,
-			hops
-		};
 		try {
 			runner.sendMessage(text, void 0, { origin });
 		} catch (error) {
@@ -4751,6 +4947,45 @@ function createPeerService(deps) {
 			queued: before === "running" || before === "awaiting_approval"
 		};
 	};
+	const exposedInfo = async (sessionId, exposed) => {
+		const info = await infoOf(sessionId);
+		return info && info.status !== "closed" && scopeMatches(exposed, info.scope) ? info : void 0;
+	};
+	const relayEntries = async (exposed) => {
+		const live = new Set(registry().list().map((info) => info.id));
+		return (await allSessions()).filter((info) => info.status !== "closed" && scopeMatches(exposed, info.scope)).map((info) => relayEntry(info, live.has(info.id)));
+	};
+	const relayPeek = async (sessionId, recent, exposed) => {
+		const info = await exposedInfo(sessionId, exposed);
+		if (!info) return;
+		const { runner, lines } = recentOf(sessionId, recent);
+		return {
+			...relayEntry(info, runner !== void 0),
+			checklistItems: info.checklist,
+			pendingApprovals: runner ? runner.pendingApprovals.map((request) => request.title ?? request.toolName) : [],
+			recent: lines
+		};
+	};
+	const relaySend = async (origin, sessionId, text, exposed) => {
+		if (text.length === 0 || text.length > maxChars) return {
+			delivered: false,
+			reason: `message is ${text.length} characters; the limit is ${maxChars}. Write it to a file and send the path.`
+		};
+		const target = await exposedInfo(sessionId, exposed);
+		if (!target) return {
+			delivered: false,
+			reason: `no such session: ${sessionId}`
+		};
+		const from = `${origin.gateway}:${origin.sessionId}`;
+		return deliver(target, text, {
+			kind: "peer",
+			sessionId: from,
+			hostId: origin.gateway,
+			name: origin.name,
+			engine: origin.engine,
+			hops: origin.hops
+		}, from);
+	};
 	const mentions = async (from, text) => {
 		const tokens = scanPeerMentions(text);
 		if (tokens.length === 0) return [];
@@ -4797,7 +5032,12 @@ function createPeerService(deps) {
 		peek,
 		send,
 		mentions,
-		watch
+		watch,
+		relaySender: sender,
+		relayChain: (from) => [...inbound.get(from) ?? [], from],
+		relayEntries,
+		relayPeek,
+		relaySend
 	};
 }
 //#endregion
@@ -5222,9 +5462,10 @@ function createWorkerServer(options = {}) {
 		options: options.peers
 	});
 	const shellDirectory = shells ? createShellDirectory(shells, { runnerFor: (id) => registry.get(id) }) : void 0;
-	let ownPeers = peers;
+	const relay = peers && options.relay ? createRelayLink(options.relay, peers, options.relay.log ?? ((message) => diagnose(new Error(message), "relay"))) : void 0;
+	let ownPeers = relay?.directory ?? peers;
 	let ownShells = shellDirectory;
-	if (peers) installPeerDirectory(peers);
+	if (ownPeers) installPeerDirectory(ownPeers);
 	installShellDirectory(shellDirectory);
 	const factory = createSessionFactory({
 		adapterFor,
@@ -5341,6 +5582,7 @@ function createWorkerServer(options = {}) {
 		closeQueueSockets: queueSockets.clear,
 		diagnose,
 		releaseDirectories: () => {
+			relay?.close();
 			ownPeers = void 0;
 			ownShells = void 0;
 		}
@@ -5383,6 +5625,7 @@ function createWorkerServer(options = {}) {
 			parking.adopt(runner, config);
 			return true;
 		},
+		releaseRelay: () => relay?.release(),
 		drain: lifecycle.drain,
 		close: lifecycle.close
 	};