@workerdeck/server 0.13.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, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionResult } from "@workerdeck/core";
+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, SdkSessionSummary, ServerFrame, 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.
  *
@@ -118,6 +118,7 @@ declare class BridgeHub {
  * snapshot, and what it is waiting for.
  */
 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'`. */
   info: SessionInfo;
   profile?: string; /** The config the session was created with (profile defaults already applied). */
@@ -126,6 +127,46 @@ type ParkedSessionRecord = {
   executions: ParkedExecution[];
   parkedAt: number;
 };
+/**
+ * A live session, remembered so it can be brought back after a gateway restart.
+ *
+ * The counterpart to a park, and deliberately not the same mechanism. A park
+ * preserves *mid-task* state, which means a `RunnerSnapshot` — and only the
+ * provider engine can produce one, because the claude and codex engines run
+ * behind a binary that owns its own process state. What those two have instead
+ * is a session store of their own: the transcript is already on disk under an
+ * engine session id, and `CreateSessionRequest.resume` is how you get it back.
+ *
+ * So this record holds no transcript at all. It holds the id (every client keys
+ * its watermarks and routes on it), the engine session id to resume from, and
+ * the config to rebuild with — and rehydration is an ordinary create with
+ * `resume` set, done **lazily on first attach**, because eagerly respawning
+ * every session at boot is a fork bomb wearing a feature's clothes.
+ *
+ * Written only for engines whose capability record says `resume`, and only once
+ * an `sdkSessionId` exists: a record that would come back with an empty
+ * transcript is worse than no record.
+ */
+type DormantSessionRecord = {
+  kind: 'dormant';
+  id: string;
+  /** Session info as of the last save, with `status: 'idle'` — whatever it was
+   * doing, it is not doing it now. */
+  info: SessionInfo;
+  profile?: string;
+  /**
+   * The config the session was built from, minus the ephemeral keys. Fed back
+   * through the server's `buildRunnerConfig` on wake rather than used as-is, so
+   * the profile's env pin and the host hook's injections are **re-derived**
+   * instead of persisted (see {@link EPHEMERAL_CONFIG_KEYS}).
+   */
+  config: SessionRunnerConfig; /** Where the transcript actually lives. Without one there is nothing to resume. */
+  sdkSessionId: string;
+  savedAt: number;
+};
+/** What a {@link SessionStore} holds: a session waiting on deferred work, or one
+ * waiting to be asked for again. */
+type StoredSessionRecord = ParkedSessionRecord | DormantSessionRecord;
 /**
  * Where parked sessions live. Two implementations ship: {@link MemorySessionStore}
  * (a park survives a disconnect, not a restart) and {@link createFileSessionStore}
@@ -138,22 +179,22 @@ type ParkedSessionRecord = {
  * {@link toDurableRecord} is the filter the bundled file store applies — reuse it.
  */
 interface SessionStore {
-  save(record: ParkedSessionRecord): Promise<void>;
-  get(id: string): Promise<ParkedSessionRecord | null>;
-  list(): Promise<ParkedSessionRecord[]>;
+  save(record: StoredSessionRecord): Promise<void>;
+  get(id: string): Promise<StoredSessionRecord | null>;
+  list(): Promise<StoredSessionRecord[]>;
   delete(id: string): Promise<boolean>;
 }
 /** Single-process, no persistence: parks survive a client disconnect, not a restart. */
 declare class MemorySessionStore implements SessionStore {
   #private;
-  save(record: ParkedSessionRecord): Promise<void>;
-  get(id: string): Promise<ParkedSessionRecord | null>;
-  list(): Promise<ParkedSessionRecord[]>;
+  save(record: StoredSessionRecord): Promise<void>;
+  get(id: string): Promise<StoredSessionRecord | null>;
+  list(): Promise<StoredSessionRecord[]>;
   delete(id: string): Promise<boolean>;
 }
 /** The record as it may be persisted: same session, config narrowed to what is
  * safe and meaningful to keep (see {@link EPHEMERAL_CONFIG_KEYS}). */
-declare function toDurableRecord(record: ParkedSessionRecord): ParkedSessionRecord;
+declare function toDurableRecord<T extends StoredSessionRecord>(record: T): T;
 type FileSessionStoreOptions = {
   /** Directory holding one JSON file per parked session.
    * Default `<cwd>/.workerdeck/parked`. */
@@ -187,13 +228,18 @@ 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;
-  /** Rebuild a parked session's runner. The snapshot rides in on
-   * `config.restore`, so the engine adopts the id, event log, and history. */
-  rebuild: (record: ParkedSessionRecord) => Promise<Runner>;
+  /**
+   * Rebuild a stored session's runner. For a park the snapshot rides in on
+   * `config.restore`, so the engine adopts the id, event log, and history; for a
+   * dormant record there is no snapshot and the engine is asked to resume its
+   * own session under the stored id. Either way the runner it returns must carry
+   * `record.id` — {@link SessionParkManager} refuses one that does not.
+   */
+  rebuild: (record: StoredSessionRecord) => Promise<Runner>;
   /** How many clients are attached to this session. A watched session stays live:
    * parking would pull the runner out from under the socket. */
   attachedCount: (sessionId: string) => number;
@@ -212,17 +258,25 @@ type SessionParkOptions = {
   /** The session is live again under a NEW runner object — anything holding the
    * old reference must rebind. */
   onResumed?: (sessionId: string, runner: Runner) => void;
-  /** Park/resume failures. These are not session errors — the session is intact,
-   * the host's storage or engine assembly isn't. */
+  /** Park/remember/resume failures. These are not session errors — the session
+   * is intact, the host's storage or engine assembly isn't. */
   onError?: (error: unknown, context: {
     sessionId: string;
-    phase: 'park' | 'resume';
+    phase: 'park' | 'remember' | 'resume';
   }) => void;
 };
 /**
- * Deferred execution's other half: parking a session that is waiting on work no
+ * Two ways a session outlives its runner, behind one door.
+ *
+ * **Parking** is deferred execution's other half: a session waiting on work no
  * process in this server is doing.
  *
+ * **Dormancy** is the restart story for the engines that cannot park. Every live
+ * claude or codex session leaves a small record naming its engine session id, so
+ * a gateway that comes back up lists them and resumes one the first time someone
+ * attaches. Both kinds live in the same store and come back through the same
+ * `ensureLive`, which is why there is one class here and not two.
+ *
  * The runner announces the moment with `status_changed: 'parked'` — emitted only
  * once every dispatch of the batch has been handed over, so the snapshot can never
  * miss a call that was still being dispatched. From there this class snapshots,
@@ -236,9 +290,27 @@ 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;
-  /** Adopt the store's contents (a durable store after a restart): re-index the
+  /**
+   * 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
-   * window — nothing could have been delivered while the process was down. */
+   * window — nothing could have been delivered while the process was down.
+   *
+   * Dormant records need nothing here, which is the point of them. They list
+   * from the store (`listInfo`) and come back on first attach (`ensureLive`), so
+   * a boot with fifty remembered sessions spawns nothing at all.
+   */
   hydrate(): Promise<void>;
   /**
    * Follow a session's lifecycle: index its deferred executions, park it when the
@@ -251,9 +323,9 @@ declare class SessionParkManager {
   onDetach(sessionId: string): void;
   /** Which session this execution belongs to — still waiting, or already settled. */
   sessionFor(executionId: string): string | undefined;
-  /** The parked session's record, for the read paths (GET, list, attach). */
-  get(id: string): Promise<ParkedSessionRecord | null>;
-  /** Every parked session's info, to merge into `GET {basePath}/sessions`. */
+  /** The stored session's record, for the read paths (GET, list, attach). */
+  get(id: string): Promise<StoredSessionRecord | null>;
+  /** Every stored session's info, to merge into `GET {basePath}/sessions`. */
   listInfo(): Promise<SessionInfo[]>;
   /** The live runner for a session, rehydrating a parked one on demand. Undefined
    * when the session is neither live nor parked. */
@@ -275,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
@@ -307,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;
@@ -321,11 +393,64 @@ type SdkSessionLister = (options: {
  * without it the caller may use every declared profile. It may also carry
  * `canManageProfiles: true` to allow creating/editing/deleting managed profiles
  * (requires the `profileStore` option); anything else means no.
+ *
+ * It may also carry `scope: Record<string, string>` — the opaque tags deciding
+ * which *sessions* this caller may see at all (see
+ * {@link WorkerServerOptions.authorizeSession}). A principal carrying a scope is
+ * an embedded end user rather than the operator, and is refused the
+ * operator-privileged surfaces outright: `/fs/*`, `/sdk-sessions`, `/queue` and
+ * `/queue/ws`.
+ *
+ * **This is the place to be expensive.** It is already async and already runs
+ * once per request, so a lookup (which spaces is this user in?) belongs here,
+ * landing its answer on the principal. The visibility check itself is
+ * synchronous by design: it runs on every route and every row of every list.
  */
 type Authenticator = (req: IncomingMessage) => unknown | Promise<unknown>;
 type WorkerServerOptions = {
   /** Required unless `allowUnauthenticated: true` — the worker must never be exposed bare. */authenticate?: Authenticator; /** Explicit opt-in to run without auth (local dev only). */
-  allowUnauthenticated?: boolean; /** If set, session cwd must resolve inside one of these roots. Strongly recommended. */
+  allowUnauthenticated?: boolean;
+  /**
+   * Whether a principal may see one session — the policy half of
+   * {@link CreateSessionRequest.scope}. WorkerDeck stores the opaque tags and
+   * enforces the answer at every door; what the tags *mean* is the host's, and
+   * has to be, because "space" and "user" are one app's vocabulary and the next
+   * embedder has tenants or projects or nothing.
+   *
+   * **Synchronous, deliberately.** It runs per route and per row of every list,
+   * so resolving it against a database per request is the failure mode this
+   * signature designs out: do the lookup in {@link Authenticator} and put the
+   * answer on the principal.
+   *
+   * Unset, the default rule applies: every key the principal's `scope` pins must
+   * equal the session's, and a principal with no scope (`undefined` or `{}`) is
+   * unrestricted — the same "unset means all" rule `allowedProfiles` uses, so an
+   * operator's dashboard is unaffected. A consequence worth stating: a session
+   * carrying *no* scope is invisible to a scoped principal, which is the right
+   * fail direction — sessions predating this feature never leak into an
+   * end user's list.
+   *
+   * **False means the session does not exist**: every refusal answers 404, never
+   * 403, matching `host-files.ts`' uniform-disclosure discipline. A predicate
+   * that *throws* has not said yes — it is caught and read as false, so one
+   * surprising row cannot turn a hundred-row list into a page-wide error.
+   *
+   * **Declaring this withdraws the unscoped-means-operator default.** The
+   * gateway-wide surfaces (`/fs/*`, `/sdk-sessions`, `/queue`, `/queue/ws`) key
+   * on {@link Authenticator}'s principal carrying no `scope` — but a host may
+   * well write this predicate over its own principal shape and never set one,
+   * and reading that as "everyone is the operator" would serve the host
+   * filesystem to every end user whose sessions this correctly walls off. So
+   * with a policy declared, operator principals must say `operator: true`.
+   *
+   * **True means full control, not read access.** An attach can send
+   * `user_message`, `permission_decision`, `interrupt` and `close`, and a
+   * bridged client can settle a tool call — so this is one boolean over "may
+   * drive this session", not a visibility level. A read-only-for-my-team policy
+   * is not expressible here yet; do not approximate it with `readOnly`, which is
+   * affordance removal in a client and not an authorization boundary.
+   */
+  authorizeSession?: (principal: unknown, session: SessionInfo) => boolean; /** If set, session cwd must resolve inside one of these roots. Strongly recommended. */
   allowedCwdRoots?: string[];
   /**
    * The host filesystem routes (`{basePath}/fs/*`) — browse and read the
@@ -489,6 +614,24 @@ type WorkerServerOptions = {
     probe?: ClaudeAuthProbe;
     timeoutMs?: number;
   };
+  /**
+   * Refuse to create a session or submit a job on a profile the credential
+   * probe has reported **unavailable** — 503 with the probe's own reason —
+   * rather than letting the run start and die mid-turn on a raw provider error.
+   *
+   * Off by default, and that default is right for an operator's own gateway:
+   * the verdict can be stale in both directions, the operator may be three
+   * seconds from finishing a login, and turning a probe bug into an outage is
+   * worse than one confusing failure. It is wrong in front of an **end user**,
+   * who cannot read a provider stack trace and did not choose the deployment's
+   * credentials — which is why every embedder otherwise grows its own
+   * `available` flag in front of the create button.
+   *
+   * Requires `checkCredentials`; without probes nothing is ever unavailable.
+   * A profile whose verdict is 'unknown' (never probed, probe couldn't run) is
+   * always allowed through — "couldn't check" is not "not available".
+   */
+  requireAvailableProfile?: boolean;
   /** Injectable lister for GET /sdk-sessions (tests) — honored for the CLAUDE
    * engine only, like the injectable claude auth probe (it predates the adapter
    * layer). Defaults to the claude adapter's lister (the SDK's on-disk session
@@ -532,10 +675,13 @@ type WorkerServerOptions = {
     parkDelayMs?: number;
     /** 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; /** Park/resume failures — storage or engine-assembly problems, not session errors. */
+    expiredGraceMs?: number;
+    /** 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. */
     onError?: (error: unknown, context: {
       sessionId: string;
-      phase: 'park' | 'resume';
+      phase: 'park' | 'remember' | 'resume';
     }) => void;
   };
   /**
@@ -576,6 +722,13 @@ type EngineRunnerContext = {
    * numbering, history, and scratch filesystem instead of starting fresh.
    */
   restore?: RunnerSnapshot;
+  /**
+   * Set when rehydrating a session across a gateway restart: build the runner
+   * under exactly this id rather than a fresh one. Never set together with
+   * `restore` (a snapshot carries its own id). Ignoring it strands every
+   * client's watermarks and routes, and the rebuild is refused.
+   */
+  id?: string;
 };
 type QueueServerOptions = {
   /** Concurrent job sessions. Default 1. */maxConcurrency?: number; /** Token cap per job session (input+output+cache tokens); exceeding it kills the run. */
@@ -612,9 +765,138 @@ type WorkerServer = {
   }>;
   close: () => Promise<void>;
 };
+//#endregion
+//#region src/server.d.ts
 declare function createWorkerServer(options?: WorkerServerOptions): WorkerServer;
 //#endregion
-//#region src/attachments.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.
+ *
+ * This adds no mechanism. `capabilities: []` and `mcpServers: []` already mean
+ * what they mean, and `createToolContext` already withholds a tool whose backend
+ * the host did not inject. What the helper buys is that the locked-down profile
+ * is one call rather than three fields an operator has to get right together —
+ * the failure mode being a profile that *looks* sandboxed and still grants
+ * `deliver_file` because nobody wrote the empty array.
+ *
+ * What a session under it can do:
+ * - run untrusted JavaScript in the WASM guest, under the interpreter's own
+ *   timeout and memory limits (`eval_script`),
+ * - read and write the session's in-memory VFS, which is a map and not a
+ *   filesystem — no host path is reachable from it.
+ *
+ * What it cannot do: read or write a host path, spawn a process, reach the
+ * network (`web_fetch`/`download`/`web_search` are capabilities, and none is
+ * granted), deliver a file, or use an MCP server.
+ *
+ * Two things this helper does **not** do, because they are not a profile's to
+ * decide. It does not authorize anyone — visibility is
+ * `CreateSessionRequest.scope` plus the gateway's `authorizeSession`. And it
+ * does not make the model's *input* trustworthy: content the loop reads is
+ * attacker-influenced by default, and a sandbox bounds what a tool can reach,
+ * not what a prompt can talk the model into asking for.
+ *
+ * @param name Profile name clients name in `CreateSessionRequest.profile`.
+ * @param provider Which model to run (credentials stay in the operator's
+ *   environment and are resolved by the host's `createEngineRunner` — never
+ *   here, and never on the wire).
+ */
+declare function sandboxedProviderProfile(name: string, provider: ProviderConfig, options?: {
+  description?: string; /** Prepended to the session's system prompt. */
+  instructions?: string;
+  /** Profile-level run defaults (model, permission mode) — see
+   * {@link ProfileInfo.defaults}. */
+  defaults?: ProfileInfo['defaults'];
+  /**
+   * Capabilities to grant on top of the floor. Default `[]` — the floor is
+   * nothing, and every entry here is a deliberate widening you are writing
+   * down: `web_fetch` gives the loop egress (SSRF-guarded, but egress),
+   * `download` and `web_search` reach whatever backends you injected, and
+   * `deliver_file` lets it hand a file to the client.
+   */
+  capabilities?: SessionCapability[];
+  /**
+   * MCP servers, **by name**, whose tools sessions may use. Default `[]`.
+   * MCP tools are authoritative — they run with the host's credentials and
+   * are never bridged — so naming one here is a larger grant than any
+   * capability above it.
+   */
+  mcpServers?: string[];
+}): ProfileInfo;
+//#endregion
+//#region src/lib/provider-runner.d.ts
+type ProviderRunnerOptions = {
+  /**
+   * The model to run. A function is called per turn with the session's
+   * requested model id (undefined = the profile's default), which is what makes
+   * the in-session model switcher work; a bare instance pins one model.
+   */
+  model: LanguageModel | ((modelId: string | undefined) => LanguageModel);
+  /**
+   * Where sandboxed tools (`eval_script` and any `sandboxed` entry in `tools`)
+   * execute. This is a real architectural choice, not a default worth guessing
+   * at, so it is required:
+   *
+   * - a {@link ToolExecutor} — an in-process guest (`new QuickJsExecutor(...)`
+   *   from `@workerdeck/core`), which is right when the data the loop reasons
+   *   over lives in this process. It is also the only option that works when no
+   *   client is attached, which is every unattended job.
+   * - `'browser'` — the attached tab, resolved per call from the bridge. Right
+   *   when the data is *there* (a document the user is editing) and it should
+   *   not travel to the gateway at all. Note the trade: it hands an executor to
+   *   the party being sandboxed against, so its results are untrusted input.
+   */
+  executor: ToolExecutor | 'browser';
+  /** Capability backends — the same shape {@link createEngineSession} takes.
+   * Wiring one only offers it; the profile and request decide the grant. */
+  capabilities?: EngineSessionOptions['capabilities']; /** Host tools at explicit trust levels (`@workerdeck/core`'s `withHostTools`). */
+  tools?: Record<string, HostToolDefinition>;
+  /** A live MCP connection from `connectMcpTools`. Prefer this over `mcpTools`:
+   * it is what lets a profile's unhonoured `mcpServers` refuse the build, and
+   * what makes `GET /sessions/:id/mcp` answer for this session. */
+  mcp?: McpConnection; /** A bare MCP tool set, for a host assembling one itself. */
+  mcpTools?: ToolSet; /** System-prompt addition, unless the profile declares its own. */
+  instructions?: string; /** Sandbox limits per execution. */
+  executionLimits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  };
+  /** Scratch-filesystem seed for a new session. Ignored on a rehydration, so a
+   * parked turn's files are never overwritten. */
+  seedVfs?: Record<string, string>;
+  /** Release per-session resources: the MCP connection, an issued token, a
+   * watcher. Runs on close **and on park** — parking releases the same things. */
+  onClose?: () => void | Promise<void>;
+};
+/**
+ * Build a provider-engine runner from the server's `createEngineRunner` context.
+ *
+ * `createEngineRunner` is a blank sheet: it hands you a context and wants a
+ * `Runner`, and four of the five things a correct one must do are invisible in
+ * the types — forward `restore`, adopt `id`, seed the VFS only when *not*
+ * restoring, and dispose per-session resources. Each is a runtime-only failure
+ * (a woken session that starts empty, a refused rebuild, an overwritten
+ * filesystem, a connection leaked per session), and each is handled here.
+ *
+ * ```ts
+ * createEngineRunner: (ctx) =>
+ *   createProviderRunner(ctx, {
+ *     model: (id) => openai(id ?? 'gpt-5.6-luna'),
+ *     executor: quickjs,
+ *     capabilities: { webFetch: {} },
+ *     mcp,
+ *     onClose: () => mcp.close(),
+ *   }),
+ * ```
+ *
+ * The hook itself stays open for anything this does not cover — this is the
+ * 80% case, not a replacement for it.
+ */
+declare function createProviderRunner(ctx: EngineRunnerContext, options: ProviderRunnerOptions): Promise<Runner>;
+//#endregion
+//#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;
@@ -678,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. */
@@ -728,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 QueueServerOptions, type SdkSessionLister, type SessionNotificationOptions, SessionNotifier, SessionParkManager, type SessionParkOptions, SessionRegistry, type SessionRegistryOptions, type SessionStore, type WorkerServer, type WorkerServerOptions, createFileProfileStore, createFileSessionStore, createMemoryProfileStore, createWorkerServer, 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