@workerdeck/server 0.12.0 → 0.15.0

package/README.md

@@ -186,6 +186,32 @@ services and any unattended use. Without it the server logs a one-time notice in
 OAuth, never reads or forwards tokens — see the repo README's
 ["Auth & Anthropic's terms"](https://github.com/workerdeck/workerdeck#auth--anthropics-terms).
 
+## Rules you cannot infer from the types
+
+- **A scope miss answers 404, never 403.** Whether a session exists in another scope is not the
+  caller's business, so the out-of-scope answer is byte-identical to the unknown-id one.
+- **Visibility is full control.** There is no read-only attach: a client that can see a session can
+  send `user_message`, `permission_decision`, `interrupt` and `close`. `SessionPanel`'s `readOnly`
+  removes the affordance, not the authority — enforce at the gateway or not at all.
+- **`authorizeSession` is synchronous on purpose.** It runs per route and per row of every list. An
+  expensive lookup belongs in `authenticate`, where it happens once and lands on the principal.
+- **`sandboxedProviderProfile()`'s empty arrays are load-bearing.** `capabilities: []` and
+  `mcpServers: []` mean "nothing"; *absent* means "whatever the host wired". Do not normalise one
+  into the other.
+- **A Claude profile does not pin `CLAUDE_CONFIG_DIR` when that would be a no-op.** Setting the
+  variable at all moves the CLI off the macOS Keychain, so pinning the default directory breaks a
+  working `claude login`. "Pin the default dir" and "don't pin" are different logins.
+- **`checkCredentials` is display-only** unless you also set `requireAvailableProfile`. A create
+  against an unavailable profile otherwise proceeds and fails with the engine's own error — right
+  for an operator (the probe can be stale), wrong in front of an end user.
+- **`createEngineRunner` has four invisible obligations**: forward `restore`, adopt `id`, seed the
+  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.
+- **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.
+
 ## License
 
 MIT © Tobias Strebitzer —

package/build/index.d.mts

@@ -1,7 +1,7 @@
 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, ProviderConfig, SdkSessionSummary, ServerFrame, SessionCapability, SessionInfo, SessionNotification, SessionWebhookConfig } from "@workerdeck/protocol";
 
 //#region src/registry.d.ts
 type SessionRegistryOptions = {
@@ -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`. */
@@ -191,9 +232,14 @@ declare function createFileSessionStore(options?: FileSessionStoreOptions): Sess
 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,15 @@ 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
+  /**
+   * 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 +311,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. */
@@ -321,11 +381,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
@@ -433,7 +546,27 @@ type WorkerServerOptions = {
    *
    * Upgrades are not routed here: anything outside `basePath` is still refused.
    */
-  fallback?: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>; /** Max JSON body size in bytes. Default 1 MiB. */
+  fallback?: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+  /**
+   * Browser origins allowed to call this API cross-origin — for a dashboard
+   * served somewhere other than this gateway.
+   *
+   * Off unless configured, and even then it is *sharing policy, not a
+   * credential*: preflights are answered before auth (browsers strip
+   * credentials from them, so they would otherwise 401), but every real request
+   * still goes through `authenticate`, and an allowlisted page that does not
+   * hold the key gets nothing.
+   *
+   * Two rules the implementation must keep: **exact origins only**, no
+   * wildcards or suffix matching; and `Access-Control-Allow-Credentials` is
+   * **never** sent, which is what keeps an ambient cookie from becoming
+   * cross-origin authority. WebSocket upgrades are exempt from CORS entirely
+   * and are unaffected by this — their credential is whatever the host's
+   * `authenticate` accepts on the handshake.
+   */
+  cors?: {
+    origins: string[];
+  }; /** Max JSON body size in bytes. Default 1 MiB. */
   maxBodyBytes?: number;
   /**
    * Server-wide bypass policy: refuse `permissionMode: 'bypassPermissions'` on
@@ -469,6 +602,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
@@ -512,10 +663,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;
   };
   /**
@@ -556,6 +710,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. */
@@ -594,6 +755,133 @@ type WorkerServer = {
 };
 declare function createWorkerServer(options?: WorkerServerOptions): WorkerServer;
 //#endregion
+//#region src/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/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/attachments.d.ts
 type AttachmentStoreOptions = {
   /** Largest single upload. Default 10 MiB. */maxFileBytes?: number; /** Ceiling on everything one session is holding. Default 64 MiB. */
@@ -708,5 +996,5 @@ 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 };
+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 };
 //# sourceMappingURL=index.d.mts.map