@workerdeck/server 2.8.0 → 2.10.0

package/build/index.d.mts

@@ -1,7 +1,7 @@
 import { IncomingMessage, Server, ServerResponse } from "node:http";
-import { AttachmentInput, BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, EngineAdapter, EngineSessionOptions, HostToolDefinition, LanguageModel, McpConnection, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionCall, ToolExecutionResult, ToolExecutor, ToolSet } from "@workerdeck/core";
+import { AttachmentInput, BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, CostLedgerState, EngineAdapter, EngineSessionOptions, HostToolDefinition, LanguageModel, McpConnection, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionCall, ToolExecutionResult, ToolExecutor, ToolSet } from "@workerdeck/core";
 import { JobQueue, QueueAdapter } from "@workerdeck/queue";
-import { CreateSessionRequest, JobEvent, MessageAttachment, ProfileEngine, ProfileInfo, ProfileUsage, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
+import { ByModel, CreateSessionRequest, JobEvent, MessageAttachment, ProfileEngine, ProfileInfo, ProfileSpend, ProfileUsage, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
 //#region src/services/bridge.d.ts
 type BridgeHubOptions = {
   timeoutMs?: number;
@@ -29,21 +29,22 @@ declare class SessionNotifier {
   #private;
   constructor(options: SessionNotificationOptions);
   get idle(): boolean;
-  watch(runner: Runner, afterSeq?: number): void;
+  watch(runner: Runner, afterSeq?: number): () => void;
 }
 //#endregion
 //#region src/services/registry.d.ts
 type SessionRegistryOptions = {
-  onRegister?: (runner: Runner) => void;
+  onRegister?: (runner: Runner) => unknown;
 };
 declare class SessionRegistry {
   #private;
   constructor(options?: SessionRegistryOptions);
-  observe(listener: (runner: Runner) => void): () => void;
+  observe(listener: (runner: Runner) => unknown): () => void;
   create(config: SessionRunnerConfig): Runner;
   prepare(config: SessionRunnerConfig): Runner;
   adopt(runner: Runner): Runner;
   register(runner: Runner): Runner;
+  retain(id: string, detach: () => void): void;
   get(id: string): Runner | undefined;
   list(): SessionInfo[];
   remove(id: string): boolean;
@@ -60,6 +61,7 @@ type ParkedSessionRecord = {
   config: SessionRunnerConfig;
   snapshot: RunnerSnapshot;
   executions: ParkedExecution[];
+  cost?: CostLedgerState;
   parkedAt: number;
 };
 type DormantSessionRecord = {
@@ -69,9 +71,11 @@ type DormantSessionRecord = {
   profile?: string;
   config: SessionRunnerConfig;
   sdkSessionId: string;
+  cost?: CostLedgerState;
   savedAt: number;
 };
 type StoredSessionRecord = ParkedSessionRecord | DormantSessionRecord;
+declare function isDormant(record: StoredSessionRecord): record is DormantSessionRecord;
 interface SessionStore {
   save(record: StoredSessionRecord): Promise<void>;
   get(id: string): Promise<StoredSessionRecord | null>;
@@ -119,6 +123,9 @@ declare class SessionParkManager {
   touch(runner: Runner): void;
   hydrate(): Promise<void>;
   watch(runner: Runner, afterSeq?: number): () => void;
+  release(sessionId: string): SessionRunnerConfig | undefined;
+  adopt(runner: Runner, config?: SessionRunnerConfig): void;
+  flush(sessionId?: string): Promise<void>;
   onDetach(sessionId: string): void;
   sessionFor(executionId: string): string | undefined;
   get(id: string): Promise<StoredSessionRecord | null>;
@@ -141,6 +148,33 @@ type ProfileStore = {
 declare function createMemoryProfileStore(seed?: ProfileInfo[]): ProfileStore;
 declare function createFileProfileStore(path?: string): ProfileStore;
 //#endregion
+//#region src/services/spend-ledger.d.ts
+type SpendRecord = {
+  days: Record<string, Record<string, ByModel>>;
+};
+type SpendStore = {
+  load(): Promise<SpendRecord | undefined>;
+  save(record: SpendRecord): Promise<void>;
+};
+type SpendLedgerOptions = {
+  store?: SpendStore;
+  monthlySubscriptionUsd?: (profile: string) => number | undefined;
+  retentionDays?: number;
+  saveDebounceMs?: number;
+  onError?: (error: unknown) => void;
+};
+declare function dayKey(at: number): string;
+declare class SpendLedger {
+  #private;
+  constructor(options?: SpendLedgerOptions);
+  load(): Promise<void>;
+  watch(runner: Runner): () => void;
+  spend(profile: string, now?: number): ProfileSpend | undefined;
+  flush(): Promise<void>;
+  close(): void;
+}
+declare function createFileSpendStore(path: string, onError?: (error: unknown) => void): SpendStore;
+//#endregion
 //#region src/options.d.ts
 type SdkSessionLister = (options: {
   dir?: string;
@@ -198,6 +232,11 @@ type WorkerServerOptions = {
     persistLive?: boolean;
     onError?: (error: unknown, context: ParkErrorContext) => void;
   };
+  spend?: {
+    store?: SpendStore;
+    monthlySubscriptionUsd?: Record<string, number>;
+    onError?: (error: unknown) => void;
+  };
   createEngineRunner?: (context: EngineRunnerContext) => Runner | Promise<Runner>;
   engines?: Partial<Record<ProfileEngine, EngineAdapter>>;
 };
@@ -223,6 +262,10 @@ type QueueServerOptions = {
   webhookRetryDelayMs?: number;
   onEvent?: (event: JobEvent) => void;
 };
+type CarriedSession = {
+  runner: Runner;
+  config?: SessionRunnerConfig;
+};
 type DrainReport = {
   working: string[];
   awaitingHuman: string[];
@@ -243,6 +286,8 @@ type WorkerServer = {
     port: number;
   }>;
   drain: (options?: DrainOptions) => Promise<DrainReport>;
+  releaseSession: (id: string) => CarriedSession | undefined;
+  adoptSession: (carried: CarriedSession) => boolean;
   close: () => Promise<void>;
 };
 //#endregion
@@ -281,6 +326,10 @@ type ProviderRunnerOptions = {
 };
 declare function createProviderRunner(ctx: EngineRunnerContext, options: ProviderRunnerOptions): Promise<Runner>;
 //#endregion
+//#region src/lib/reload-plan.d.ts
+type ReloadPlan = 'carry' | 'persist' | 'drop';
+declare function reloadPlan(runner: Runner): ReloadPlan;
+//#endregion
 //#region src/services/attachments.d.ts
 type AttachmentStoreOptions = {
   maxFileBytes?: number;
@@ -332,7 +381,7 @@ type ProducedFile = {
 };
 declare class ProducedFileStore {
   #private;
-  watch(runner: Runner): void;
+  watch(runner: Runner): () => void;
   get(sessionId: string, fileId: string): ProducedFile | undefined;
   list(sessionId: string): ProducedFile[];
   drop(sessionId: string): void;
@@ -341,9 +390,9 @@ declare class ProducedFileStore {
 //#region src/services/profile-usage.d.ts
 declare class ProfileUsageTracker {
   #private;
-  watch(runner: Runner): void;
+  watch(runner: Runner): () => void;
   usage(profile: string, now?: number): ProfileUsage | undefined;
 }
 //#endregion
-export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProducedFile, ProducedFileStore, type ProfileStore, ProfileUsageTracker, type ProviderRunnerOptions, type QueueServerOptions, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, sandboxedProviderProfile, toDurableRecord };
+export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type CarriedSession, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProducedFile, ProducedFileStore, type ProfileStore, ProfileUsageTracker, type ProviderRunnerOptions, type QueueServerOptions, type ReloadPlan, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, SpendLedger, type SpendRecord, type SpendStore, type StoredSessionRecord, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, toDurableRecord };
 //# sourceMappingURL=index.d.mts.map

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, costOfByModel, imagePartRef, isJobRun, mergeByModel, sessionState, subscriptionComparison, 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;
@@ -526,7 +535,7 @@ function subsequenceScore(haystack, needle) {
 	return score - haystack.length / 100;
 }
 //#endregion
-//#region src/routes/host-files.ts
+//#region src/routes/fs.ts
 function kindRank(type) {
 	return type === "dir" ? 0 : 1;
 }
@@ -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);
@@ -2451,6 +2493,7 @@ var SessionParkManager = class {
 				meta: info.meta
 			},
 			sdkSessionId,
+			cost: runner.costState?.(),
 			savedAt: Date.now()
 		};
 		try {
@@ -2498,6 +2541,7 @@ var SessionParkManager = class {
 						meta: info.meta
 					},
 					snapshot,
+					cost: runner.costState?.(),
 					executions: snapshot.parked,
 					parkedAt: Date.now()
 				};
@@ -2521,6 +2565,7 @@ var SessionParkManager = class {
 		const config = this.#configs.get(id);
 		if (!config) return;
 		if (this.#options.onParking && !this.#options.onParking(id, executions[0])) return;
+		const cost = runner.costState?.();
 		const snapshot = runner.park();
 		if (!snapshot) return;
 		const info = {
@@ -2536,6 +2581,7 @@ var SessionParkManager = class {
 			config,
 			snapshot,
 			executions: snapshot.parked,
+			cost,
 			parkedAt: Date.now()
 		};
 		for (const execution of snapshot.parked) this.#track(id, execution);
@@ -2581,6 +2627,10 @@ var SessionParkManager = class {
 			});
 			throw error;
 		}
+		runner.carryCost?.(record.cost ?? {
+			byModel: record.info.usageByModel,
+			reportedCostUsd: record.info.totalCostUsd
+		});
 		this.#options.registry.register(runner);
 		this.remember(id, {
 			...record.config,
@@ -2639,7 +2689,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, {
@@ -2723,6 +2773,8 @@ var ProfileService = class {
 		}
 		const usage = decorate.usage(p.name);
 		if (usage) base.usage = usage;
+		const spend = decorate.spend?.(p.name);
+		if (spend) base.spend = spend;
 		return base;
 	}
 	all() {
@@ -2790,8 +2842,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;
@@ -2830,17 +2882,166 @@ function serveWindow(held, now) {
 	};
 }
 //#endregion
+//#region src/services/spend-ledger.ts
+const DEFAULT_RETENTION_DAYS = 92;
+const DEFAULT_SAVE_DEBOUNCE_MS = 2e3;
+function dayKey(at) {
+	const d = new Date(at);
+	return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+function daysBack(now, count) {
+	const out = [];
+	for (let i = 0; i < count; i += 1) out.push(dayKey(now - i * 864e5));
+	return out;
+}
+function subtract(current, previous) {
+	const delta = {};
+	for (const [model, usage] of Object.entries(current)) {
+		const was = previous[model];
+		const row = {
+			input: usage.input - (was?.input ?? 0),
+			output: usage.output - (was?.output ?? 0),
+			cacheWrite5m: usage.cacheWrite5m - (was?.cacheWrite5m ?? 0),
+			cacheWrite1h: usage.cacheWrite1h - (was?.cacheWrite1h ?? 0),
+			cacheRead: usage.cacheRead - (was?.cacheRead ?? 0)
+		};
+		if (Object.values(row).some((value) => value < 0)) continue;
+		if (Object.values(row).some((value) => value > 0)) delta[model] = row;
+	}
+	return delta;
+}
+var SpendLedger = class {
+	#days = {};
+	#lastBanked = /* @__PURE__ */ new Map();
+	#options;
+	#saveTimer;
+	#loaded;
+	constructor(options = {}) {
+		this.#options = options;
+	}
+	load() {
+		this.#loaded ??= this.#load();
+		return this.#loaded;
+	}
+	async #load() {
+		const store = this.#options.store;
+		if (!store) return;
+		try {
+			const record = await store.load();
+			if (record?.days) this.#days = record.days;
+		} catch (error) {
+			this.#options.onError?.(error);
+		}
+	}
+	watch(runner) {
+		const info = runner.info();
+		const profile = info.profile;
+		if (!profile) return () => {};
+		this.#lastBanked.set(runner.id, info.usageByModel ?? {});
+		const unsubscribe = runner.subscribe((event) => {
+			if (event.type !== "turn_result" || !event.usageByModel) return;
+			this.#bank(profile, event.usageByModel, runner.id, event.ts);
+		});
+		return () => {
+			unsubscribe();
+			this.#lastBanked.delete(runner.id);
+		};
+	}
+	#bank(profile, cumulative, sessionId, at) {
+		const delta = subtract(cumulative, this.#lastBanked.get(sessionId) ?? {});
+		this.#lastBanked.set(sessionId, cumulative);
+		if (Object.keys(delta).length === 0) return;
+		const key = dayKey(at);
+		const day = this.#days[key] ??= {};
+		day[profile] = mergeByModel(day[profile] ?? {}, delta);
+		this.#scheduleSave();
+	}
+	spend(profile, now = Date.now()) {
+		const week = this.#window(profile, daysBack(now, 7));
+		const month = this.#window(profile, daysBack(now, 30));
+		if (Object.keys(month).length === 0) return;
+		const weekCost = costOfByModel(week);
+		const monthlySubscriptionUsd = this.#options.monthlySubscriptionUsd?.(profile);
+		return {
+			weekUsd: weekCost.total,
+			monthUsd: costOfByModel(month).total,
+			weekByModel: week,
+			unpricedShare: weekCost.unpricedShare,
+			monthlySubscriptionUsd,
+			subscription: monthlySubscriptionUsd ? subscriptionComparison(weekCost.total, monthlySubscriptionUsd) : void 0
+		};
+	}
+	#window(profile, keys) {
+		let out = {};
+		for (const key of keys) {
+			const day = this.#days[key]?.[profile];
+			if (day) out = mergeByModel(out, day);
+		}
+		return out;
+	}
+	#scheduleSave() {
+		if (!this.#options.store || this.#saveTimer) return;
+		this.#saveTimer = setTimeout(() => {
+			this.#saveTimer = void 0;
+			this.flush();
+		}, this.#options.saveDebounceMs ?? DEFAULT_SAVE_DEBOUNCE_MS);
+		this.#saveTimer.unref?.();
+	}
+	async flush() {
+		const store = this.#options.store;
+		if (!store) return;
+		this.#prune();
+		try {
+			await store.save({ days: this.#days });
+		} catch (error) {
+			this.#options.onError?.(error);
+		}
+	}
+	#prune() {
+		const keep = new Set(daysBack(Date.now(), this.#options.retentionDays ?? DEFAULT_RETENTION_DAYS));
+		for (const key of Object.keys(this.#days)) if (!keep.has(key)) delete this.#days[key];
+	}
+	close() {
+		clearTimeout(this.#saveTimer);
+		this.#saveTimer = void 0;
+	}
+};
+function createFileSpendStore(path, onError) {
+	return {
+		async load() {
+			try {
+				const parsed = JSON.parse(await readFile(path, "utf8"));
+				if (parsed === null || typeof parsed !== "object" || typeof parsed.days !== "object") return;
+				return parsed;
+			} catch {
+				return;
+			}
+		},
+		async save(record) {
+			try {
+				await mkdir(dirname(path), { recursive: true });
+				const temp = `${path}.${process.pid}.tmp`;
+				await writeFile(temp, JSON.stringify(record));
+				await rename(temp, path);
+			} catch (error) {
+				onError?.(error);
+			}
+		}
+	};
+}
+//#endregion
 //#region src/services/registry.ts
 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 +3059,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 +3077,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
@@ -3052,7 +3272,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;
@@ -3084,6 +3304,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 +3332,25 @@ function createWorkerServer(options = {}) {
 	const adapterFor = (engine) => options.engines?.[engine ?? "claude"] ?? getEngineAdapter(engine);
 	const profileDefaultModels = /* @__PURE__ */ new Map();
 	const profileUsage = new ProfileUsageTracker();
+	const spendLedger = new SpendLedger({
+		store: options.spend?.store,
+		monthlySubscriptionUsd: (name) => options.spend?.monthlySubscriptionUsd?.[name] ?? options.spend?.monthlySubscriptionUsd?.["*"],
+		onError: (error) => options.spend?.onError?.(error)
+	});
+	spendLedger.load();
+	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 +3363,11 @@ 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);
+			},
+			spend: (name) => spendLedger.spend(name)
 		}
 	});
 	for (const p of options.profiles ?? []) {
@@ -3155,16 +3400,21 @@ 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),
+			spendLedger.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 +3695,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 +3745,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 +3850,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, SpendLedger, createFileProfileStore, createFileSessionStore, createFileSpendStore, createMemoryProfileStore, createProviderRunner, createWorkerServer, dayKey, isDormant, reloadPlan, sandboxedProviderProfile, toDurableRecord };
 
 //# sourceMappingURL=index.mjs.map