@workerdeck/server 0.15.0 → 0.17.0

package/README.md

@@ -208,6 +208,16 @@ OAuth, never reads or forwards tokens — see the repo README's
   VFS only when *not* restoring, and dispose per-session resources via `onClose`. Every one is a
   runtime-only failure. `createProviderRunner()` does all four; reach for the raw hook only when it
   genuinely doesn't fit.
+- **`parking.persistLive` is how a *provider* session survives a restart, and it needs a durable
+  store to mean anything.** Claude and codex go dormant — remembered by engine session id and
+  resumed from the engine's own store — which a provider session cannot do, so its record carries
+  the state itself, written through after every turn. With the default in-memory store the option
+  does nothing and says nothing. It is off by default: a library must not start writing sessions'
+  transcripts to disk because someone upgraded, and the record holds the whole transcript in
+  plaintext.
+- **A restored session is refreshed in place, not consumed.** A park's record *is* the session and
+  is deleted on wake; a live or dormant one is a way back the session still needs next time. If you
+  implement a `SessionStore`, do not "tidy up" a record on read.
 - **One origin is not a convenience.** A browser cannot put an `Authorization` header on a
   WebSocket upgrade, so a cookie is the only credential a tab can present on an attach, and a
   cookie is per-origin. That is what `fallback` is for — an app served from the gateway's own port.

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
@@ -43,6 +48,11 @@ type SessionNotificationOptions = {
   onNotification?: (notification: SessionNotification) => void; /** Delivery attempts per notification (exponential backoff). Default 3. */
   attempts?: number; /** Initial backoff between attempts. Default 500ms. */
   retryDelayMs?: number;
+  /** Gateway wiring, not a host option: the serve-time `SessionInfo` decoration
+   * (project identity today), so a webhook or push consumer reads the same
+   * record every REST caller does. The assembly supplies it; identity when
+   * absent. */
+  decorateInfo?: (info: SessionInfo) => SessionInfo;
 };
 /**
  * Turns session events into the handful of notifications a human away from the
@@ -73,58 +83,74 @@ 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.
+ * A session captured whole: its wire-visible info, the config to rebuild the
+ * runner, the engine's snapshot, and what it is waiting for.
  *
- * Everything needed to bring it back: the wire-visible info (so it still lists and
- * reads over REST while parked), the config to rebuild the runner, the engine's
- * snapshot, and what it is waiting for.
+ * Two things are stored in this one shape, and the discriminator is `kind`:
+ *
+ * - **`parked`** — the live runner is torn down and the session is waiting on
+ *   deferred executions. The record *is* the session, so waking consumes it.
+ * - **`live`** — the runner is up and this is a copy taken after a turn, so the
+ *   session survives a restart (`persistLive`). It is a way back that the
+ *   session still needs the *next* time the process dies, so waking **refreshes
+ *   it in place** and only `session_closed` removes it.
+ *
+ * That difference is the whole reason these are two kinds rather than one, and
+ * it is a correctness difference, not bookkeeping: consuming a live record on
+ * wake opens a window from the attach to the next turn in which the session
+ * exists nowhere durable. A user who opens a session, reads it and types nothing
+ * would lose it to a redeploy — silently, which is the failure class worth
+ * spending a discriminator on.
+ *
+ * They share the shape so a store, and an older server, need no new code: every
+ * other branch (rebuild from `config` + `snapshot`, serve `snapshot.vfs`, arm
+ * `executions`, subscribe past `snapshot.seq`) is already right for both.
  */
 type ParkedSessionRecord = {
-  /** Absent on records written before dormant sessions existed — those are all parked. */kind?: 'parked';
-  id: string; /** Session info as of the park, with `status: 'parked'`. */
+  /** Absent on records written before dormant sessions existed — those are all parked. */kind?: 'parked' | 'live';
+  id: string;
+  /** Session info as of the write: `parked` for a park, `idle` for a live copy —
+   * never `running`, which would come back as a spinner over no process. */
   info: SessionInfo;
   profile?: string; /** The config the session was created with (profile defaults already applied). */
   config: SessionRunnerConfig;
   snapshot: RunnerSnapshot;
-  executions: ParkedExecution[];
+  /** Empty for a live record: an idle session is waiting on nothing, so there is
+   * nothing for `hydrate` to arm a watchdog for. */
+  executions: ParkedExecution[]; /** When it was written. Named for the park that came first. */
   parkedAt: number;
 };
 /**
@@ -228,7 +254,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;
@@ -246,6 +272,24 @@ type SessionParkOptions = {
   /** Wait this long after the last client detaches before parking, so a reconnect
    * (a wifi blip, a page reload) doesn't cost a teardown. Default 2000. */
   parkDelayMs?: number;
+  /**
+   * Keep a live session's snapshot written through to the store, so it survives
+   * a gateway restart. **Off by default**: a library must not start writing a
+   * session's whole transcript to disk because someone upgraded.
+   *
+   * This is the restart story for the engine that cannot go dormant. Dormancy
+   * works by remembering an *engine* session id to resume from, which the
+   * provider engine does not have — there is no store behind it, the history
+   * lives in the runner. What it has instead is `snapshot()`, so the record
+   * carries the state itself and rehydration is the ordinary `restore` path.
+   * Between the two, every engine survives a restart.
+   *
+   * Written at the end of a turn, never on a shutdown hook — a `kill -9`, an OOM
+   * or a pulled power cable run no hook, and that is precisely the case this
+   * exists for. Turn-end is also a natural rate limit: one write per turn, not
+   * one per token.
+   */
+  persistLive?: boolean;
   /** Grace given at {@link SessionParkManager.hydrate} to an execution whose
    * deadline passed while the server was down. Its result could not have been
    * delivered during the outage, so failing it the instant the process is back
@@ -290,6 +334,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 +391,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 +423,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;
@@ -664,6 +720,22 @@ type WorkerServerOptions = {
     /** Grace given on boot to an execution whose deadline passed while the server
      * was down (durable stores only — nothing else survives a restart). Default 60000. */
     expiredGraceMs?: number;
+    /**
+     * Keep live `provider` sessions written through to the store after each
+     * turn, so they survive a gateway restart. **Off by default** — this writes
+     * a session's whole transcript to `store` and a library must not start doing
+     * that because someone upgraded.
+     *
+     * It is the restart story for the one engine dormancy cannot cover: claude
+     * and codex are remembered by *engine session id* and resumed from their own
+     * on-disk store, which a provider session does not have. Pair it with a
+     * durable `store` — with the default in-memory one it does nothing a park
+     * did not already do.
+     *
+     * The record is rebuilt lazily, on first attach, exactly like a dormant one;
+     * a boot with fifty remembered sessions spawns nothing.
+     */
+    persistLive?: boolean;
     /** Park/remember/resume failures — storage or engine-assembly problems, not
      * session errors. 'remember' is the write that lets a live session survive a
      * restart; losing one costs that session its way back and nothing else. */
@@ -753,9 +825,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 +886,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 +956,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 +1020,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 +1070,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