@workerdeck/server 0.15.0 → 0.16.0

package/build/index.d.mts

@@ -1,40 +1,45 @@
 import { IncomingMessage, Server, ServerResponse } from "node:http";
 import { AttachmentInput, BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, EngineAdapter, EngineSessionOptions, HostToolDefinition, LanguageModel, McpConnection, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionResult, ToolExecutor, ToolSet } from "@workerdeck/core";
 import { JobQueue, QueueAdapter } from "@workerdeck/queue";
-import { CreateSessionRequest, JobEvent, MessageAttachment, ProfileEngine, ProfileInfo, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
+import { CreateSessionRequest, JobEvent, MessageAttachment, ProfileEngine, ProfileInfo, ProfileUsage, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
 
-//#region src/registry.d.ts
-type SessionRegistryOptions = {
-  /**
-   * Called once per runner as it enters the table, before it starts — the one
-   * seam every path goes through (create, prepare, adopt, and the rebuild of a
-   * parked session), which is what a watcher that must not miss a session needs.
-   */
-  onRegister?: (runner: Runner) => void;
+//#region src/services/bridge.d.ts
+type BridgeHubOptions = {
+  /** How long a bridged call may stay unanswered before it fails. Default 60000. */timeoutMs?: number;
+  /** Called when a bridged execution reaches a terminal result — the host feeds
+   * it back into the runner's loop. */
+  onResult?: (sessionId: string, executionId: string, result: ToolExecutionResult) => void;
 };
-/** In-memory session table. Terminal sessions stay listed until removed or the process exits. */
-declare class SessionRegistry {
+/**
+ * Routes tool executions between a session and the browser tabs attached to it.
+ *
+ * A session may have several clients attached (dashboard plus embedded panel);
+ * the bridge asks the **first attached** one, which is the closest thing to "the
+ * client driving this session". If none is attached, dispatch fails fast rather
+ * than hanging — an autonomous job simply never bridges, it uses the server
+ * executor instead.
+ */
+declare class BridgeHub {
   #private;
-  constructor(options?: SessionRegistryOptions);
-  create(config: SessionRunnerConfig): Runner;
-  /** Build and list a Claude-engine runner without starting it, so watchers can
-   * subscribe first. Call `start()` once they have. */
-  prepare(config: SessionRunnerConfig): Runner;
-  /** Register an already-built runner (a non-Claude engine) and start it. */
-  adopt(runner: Runner): Runner;
-  /** List a runner without starting it — for a rehydrated session, whose watchers
-   * must be subscribed before it comes back up. */
-  register(runner: Runner): Runner;
-  get(id: string): Runner | undefined;
-  list(): SessionInfo[];
-  remove(id: string): boolean;
-  /** Drop a runner WITHOUT closing it: the session isn't ending, it parked and
-   * lives on in its snapshot. Closing here would tell every client it was over. */
-  evict(id: string): boolean;
-  closeAll(): void;
+  constructor(options?: BridgeHubOptions);
+  /** The executor to hand a runner for this session. Created on first use and
+   * reused, so results routed back always reach the same pending table. */
+  executorFor(sessionId: string): BrowserBridgeExecutor;
+  /** How many clients are watching this session. Parking consults it: a session
+   * someone is watching stays live. */
+  attachedCount(sessionId: string): number;
+  /** Register an attached client. Returns a detach function. */
+  attach(sessionId: string, send: (frame: ServerFrame) => void): () => void;
+  /**
+   * Deliver a client's answer to a bridged call. Returns false when the id is
+   * unknown or already settled — late and duplicate answers are ignored.
+   */
+  resolve(sessionId: string, executionId: string, answer: BridgeAnswer): boolean;
+  /** Drop a session's bridge, failing anything still in flight. */
+  remove(sessionId: string): void;
 }
 //#endregion
-//#region src/notifications.d.ts
+//#region src/services/notifications.d.ts
 type SessionNotificationOptions = {
   /** POST target for every notification. */webhook?: SessionWebhookConfig;
   /** Local observer, invoked for every notification whether or not a webhook is
@@ -73,43 +78,38 @@ declare class SessionNotifier {
   watch(runner: Runner, afterSeq?: number): void;
 }
 //#endregion
-//#region src/bridge.d.ts
-type BridgeHubOptions = {
-  /** How long a bridged call may stay unanswered before it fails. Default 60000. */timeoutMs?: number;
-  /** Called when a bridged execution reaches a terminal result — the host feeds
-   * it back into the runner's loop. */
-  onResult?: (sessionId: string, executionId: string, result: ToolExecutionResult) => void;
-};
-/**
- * Routes tool executions between a session and the browser tabs attached to it.
- *
- * A session may have several clients attached (dashboard plus embedded panel);
- * the bridge asks the **first attached** one, which is the closest thing to "the
- * client driving this session". If none is attached, dispatch fails fast rather
- * than hanging — an autonomous job simply never bridges, it uses the server
- * executor instead.
- */
-declare class BridgeHub {
-  #private;
-  constructor(options?: BridgeHubOptions);
-  /** The executor to hand a runner for this session. Created on first use and
-   * reused, so results routed back always reach the same pending table. */
-  executorFor(sessionId: string): BrowserBridgeExecutor;
-  /** How many clients are watching this session. Parking consults it: a session
-   * someone is watching stays live. */
-  attachedCount(sessionId: string): number;
-  /** Register an attached client. Returns a detach function. */
-  attach(sessionId: string, send: (frame: ServerFrame) => void): () => void;
+//#region src/services/registry.d.ts
+type SessionRegistryOptions = {
   /**
-   * Deliver a client's answer to a bridged call. Returns false when the id is
-   * unknown or already settled — late and duplicate answers are ignored.
+   * Called once per runner as it enters the table, before it starts — the one
+   * seam every path goes through (create, prepare, adopt, and the rebuild of a
+   * parked session), which is what a watcher that must not miss a session needs.
    */
-  resolve(sessionId: string, executionId: string, answer: BridgeAnswer): boolean;
-  /** Drop a session's bridge, failing anything still in flight. */
-  remove(sessionId: string): void;
+  onRegister?: (runner: Runner) => void;
+};
+/** In-memory session table. Terminal sessions stay listed until removed or the process exits. */
+declare class SessionRegistry {
+  #private;
+  constructor(options?: SessionRegistryOptions);
+  create(config: SessionRunnerConfig): Runner;
+  /** Build and list a Claude-engine runner without starting it, so watchers can
+   * subscribe first. Call `start()` once they have. */
+  prepare(config: SessionRunnerConfig): Runner;
+  /** Register an already-built runner (a non-Claude engine) and start it. */
+  adopt(runner: Runner): Runner;
+  /** List a runner without starting it — for a rehydrated session, whose watchers
+   * must be subscribed before it comes back up. */
+  register(runner: Runner): Runner;
+  get(id: string): Runner | undefined;
+  list(): SessionInfo[];
+  remove(id: string): boolean;
+  /** Drop a runner WITHOUT closing it: the session isn't ending, it parked and
+   * lives on in its snapshot. Closing here would tell every client it was over. */
+  evict(id: string): boolean;
+  closeAll(): void;
 }
 //#endregion
-//#region src/session-store.d.ts
+//#region src/services/session-store.d.ts
 /**
  * A session with its live runner torn down, waiting on deferred executions.
  *
@@ -228,7 +228,7 @@ type FileSessionStoreOptions = {
  */
 declare function createFileSessionStore(options?: FileSessionStoreOptions): SessionStore;
 //#endregion
-//#region src/parking.d.ts
+//#region src/services/parking.d.ts
 type SessionParkOptions = {
   registry: SessionRegistry;
   store: SessionStore;
@@ -290,6 +290,18 @@ declare class SessionParkManager {
   /** Record the config a session was created with. Only sessions the host
    * remembers can be parked — there is no way to rebuild the others. */
   remember(sessionId: string, config: SessionRunnerConfig): void;
+  /**
+   * Re-save a live session's dormant record because something outside the event
+   * stream changed it.
+   *
+   * `#rememberDormant` is otherwise driven by `status_changed` and `system_init`
+   * alone, and a rename (`PATCH /sessions/:id`) fires neither — so without this
+   * a renamed session that is never touched again keeps its old title on disk
+   * and comes back under it. Safe to call for anything: every gate in
+   * `#rememberDormant` still applies, so a session that cannot be resumed, has
+   * no engine session yet, or is no longer the registry's writes nothing.
+   */
+  touch(runner: Runner): void;
   /**
    * Adopt the store's contents (a durable store after a restart): re-index the
    * executions and re-arm their watchdogs, no deadline sooner than the grace
@@ -335,7 +347,7 @@ declare class SessionParkManager {
   close(): void;
 }
 //#endregion
-//#region src/profile-store.d.ts
+//#region src/services/profile-store.d.ts
 /**
  * Where dashboard-managed profiles live. The seam exists for the same reason
  * `QueueAdapter` does: a single-host deployment wants the bundled file store and
@@ -367,7 +379,7 @@ declare function createMemoryProfileStore(seed?: ProfileInfo[]): ProfileStore;
  */
 declare function createFileProfileStore(path?: string): ProfileStore;
 //#endregion
-//#region src/server.d.ts
+//#region src/options.d.ts
 type SdkSessionLister = (options: {
   dir?: string;
   limit?: number;
@@ -753,9 +765,11 @@ type WorkerServer = {
   }>;
   close: () => Promise<void>;
 };
+//#endregion
+//#region src/server.d.ts
 declare function createWorkerServer(options?: WorkerServerOptions): WorkerServer;
 //#endregion
-//#region src/sandboxed-profile.d.ts
+//#region src/lib/sandboxed-profile.d.ts
 /**
  * A `provider` profile that grants a session nothing but the sandbox: the
  * QuickJS guest, the in-memory VFS, and the model.
@@ -812,7 +826,7 @@ declare function sandboxedProviderProfile(name: string, provider: ProviderConfig
   mcpServers?: string[];
 }): ProfileInfo;
 //#endregion
-//#region src/provider-runner.d.ts
+//#region src/lib/provider-runner.d.ts
 type ProviderRunnerOptions = {
   /**
    * The model to run. A function is called per turn with the session's
@@ -882,7 +896,7 @@ type ProviderRunnerOptions = {
  */
 declare function createProviderRunner(ctx: EngineRunnerContext, options: ProviderRunnerOptions): Promise<Runner>;
 //#endregion
-//#region src/attachments.d.ts
+//#region src/services/attachments.d.ts
 type AttachmentStoreOptions = {
   /** Largest single upload. Default 10 MiB. */maxFileBytes?: number; /** Ceiling on everything one session is holding. Default 64 MiB. */
   maxSessionBytes?: number;
@@ -946,7 +960,7 @@ declare class AttachmentStore {
   drop(sessionId: string): void;
 }
 //#endregion
-//#region src/produced-files.d.ts
+//#region src/services/produced-files.d.ts
 /** One host file an engine reported writing, as the store holds it. */
 type ProducedFile = {
   fileId: string; /** Absolute host path, exactly as the runner reported it. */
@@ -996,5 +1010,54 @@ declare class ProducedFileStore {
   drop(sessionId: string): void;
 }
 //#endregion
-export { AttachmentStore, type AttachmentStoreOptions, type Authenticator, BridgeHub, type BridgeHubOptions, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, type ProducedFile, ProducedFileStore, type ProfileStore, 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 };
+//#region src/services/profile-usage.d.ts
+/**
+ * The gateway's single plan-usage state per profile, fed from every session's
+ * `rate_limit` events and served on `GET /profiles` (`ProfileInfo.usage`).
+ *
+ * Why this exists at all: usage had only ever lived in session transcripts, so
+ * a client attaching to a session that idled since yesterday replayed
+ * yesterday's reading as if current — and a session opened today knew nothing
+ * of what a sibling session on the same account spent an hour ago. The profile
+ * is the account boundary (one config dir / codex home / provider key = one
+ * plan), so the newest reading across all of a profile's sessions is the one
+ * usage state that is ever worth showing. No history: last-write-wins per
+ * window, exactly the reducer's rule on the client side.
+ *
+ * Last-write-wins goes by the **event's own clock**, not arrival order:
+ * `watch()` subscribes from seq 0 (a replayed log is how a rebuilt session's
+ * readings arrive at all), and a replayed yesterday-reading must not clobber
+ * the fresher one another session on the same profile reported live. All
+ * events are stamped by this gateway's clock at emit time, so the comparison
+ * is sound across sessions.
+ *
+ * In-memory on purpose, like the learned default models and the availability
+ * cache: display-only state may start empty after a restart (absent = unknown,
+ * never 0%), and the first session to report refills it.
+ */
+declare class ProfileUsageTracker {
+  #private;
+  /** Follow a runner's `rate_limit` events for its lifetime. Sessions without a
+   * profile have no account to attribute usage to and are skipped. */
+  watch(runner: Runner): void;
+  /**
+   * The profile's windows as they should be served *now*. Undefined until any
+   * session on the profile has reported (unknown, never 0%).
+   *
+   * The 0%-after-reset inference lives here — at serve time — and nowhere
+   * else, because it is a function of the wall clock: a window whose own
+   * `resetsAt` has passed with no newer reading has provably rolled, so the
+   * pre-reset utilization is no longer merely stale but *wrong*. It cannot be
+   * a producer's job (the producers only relay what the engine said, and the
+   * whole problem is the engine's silence; a fabricated 0% event would be
+   * replayed from transcripts forever as if reported) and must not be every
+   * renderer's (N clients would each reimplement the clock math). The held
+   * reading stays untouched, so a late fresh report still lands by ts, and the
+   * served zero is labeled `inferredReset` — it is a floor, not a report: the
+   * account may have been used outside this gateway since the reset.
+   */
+  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 };
 //# sourceMappingURL=index.d.mts.map