@workerdeck/server 0.23.0 → 1.0.0

package/build/index.d.mts

@@ -5,212 +5,79 @@ import { CreateSessionRequest, JobEvent, MessageAttachment, ProfileEngine, Profi
 
 //#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. */
+  timeoutMs?: number;
   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;
-  /**
-   * 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/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
-   * configured — the in-process seam a host (or the CLI's APNs forwarder) hooks.
-   * Unfiltered: `webhook.events` narrows POST deliveries, not this. */
-  onNotification?: (notification: SessionNotification) => void; /** Delivery attempts per notification (exponential backoff). Default 3. */
-  attempts?: number; /** Initial backoff between attempts. Default 500ms. */
+  webhook?: SessionWebhookConfig;
+  onNotification?: (notification: SessionNotification) => void;
+  attempts?: number;
   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
- * screen cares about, and delivers them to a webhook and/or a local observer.
- *
- * This is the *primitive*, deliberately transport-agnostic: the server stays
- * credential-free and knows nothing about APNs, Slack or email. Turning a
- * notification into a push is a forwarder's job (the turnkey CLI's), and one that
- * needs credentials, so it does not live here.
- *
- * Delivery is best-effort and ordered per session, mirroring the job queue's
- * webhook behaviour — a consumer that missed one can always attach to the session
- * WS with `afterSeq` and see the truth.
- */
 declare class SessionNotifier {
   #private;
   constructor(options: SessionNotificationOptions);
-  /** True when nothing is listening — lets the caller skip subscribing at all. */
   get idle(): boolean;
-  /**
-   * Subscribe to a runner for its lifetime.
-   *
-   * `afterSeq` defaults to whatever the runner has already emitted, which is what
-   * makes this safe on a *rehydrated* session: `subscribe` replays the log from
-   * `afterSeq`, so subscribing at 0 to a session rebuilt from a park would
-   * re-announce every permission request it ever made.
-   */
   watch(runner: Runner, afterSeq?: number): void;
 }
 //#endregion
 //#region src/services/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;
 };
-/** 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/services/session-store.d.ts
-/**
- * A session captured whole: its wire-visible info, 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' | 'live';
+  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). */
+  profile?: string;
   config: SessionRunnerConfig;
   snapshot: RunnerSnapshot;
-  /** 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. */
+  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. */
+  config: SessionRunnerConfig;
   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}
- * (it survives both, on one host); a redis/sqlite/table store implements the same
- * four operations.
- *
- * Two things to know before writing one: the record holds the session's whole
- * transcript and tool I/O, and `config` may carry host-injected values (env, hooks,
- * injected functions) that a JSON round-trip silently drops or, worse, persists.
- * {@link toDurableRecord} is the filter the bundled file store applies — reuse it.
- */
 interface SessionStore {
   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: StoredSessionRecord): Promise<void>;
@@ -218,209 +85,60 @@ declare class MemorySessionStore implements SessionStore {
   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<T extends StoredSessionRecord>(record: T): T;
 type FileSessionStoreOptions = {
-  /** Directory holding one JSON file per parked session.
-   * Default `<cwd>/.workerdeck/parked`. */
   dir?: string;
-  /** A record that could not be read or written. Losing one is losing a session's
-   * way back, so this is worth logging — the store itself stays quiet and skips it. */
   onError?: (error: unknown, context: {
     path: string;
     op: 'save' | 'read' | 'delete';
   }) => void;
 };
-/**
- * Durable single-host store: one JSON file per parked session under `dir`, written
- * through a temp file and a rename so a crash mid-write cannot truncate a session.
- * `hydrate()` at `listen()` picks them up, re-indexes their executions, and re-arms
- * the watchdogs, so a restart no longer loses parked work.
- *
- * Know what is on that disk: **the record holds the session's entire transcript** —
- * prompts, model output, and tool I/O — in plaintext. Put it somewhere with the same
- * protection as the SDK's own transcripts (`~/.claude/projects`), not in a directory
- * that gets served, synced, or backed up somewhere looser.
- *
- * Single-process by design, exactly like the bundled queue adapter and profile
- * store: two servers sharing one directory would both hydrate the same records and
- * race to rebuild them. That is what the seam is for.
- *
- * Nothing here reaps: a record leaves only when its session wakes or is deleted.
- * An execution dispatched without a deadline (a `DeferredExecutor` with no
- * `timeoutMs`) has no watchdog to end the wait, so its record — and its transcript
- * — stays until `DELETE /sessions/:id`. Give deferred calls a deadline, or sweep.
- */
 declare function createFileSessionStore(options?: FileSessionStoreOptions): SessionStore;
 //#endregion
 //#region src/services/parking.d.ts
+type ParkErrorContext = {
+  sessionId: string;
+  phase: 'park' | 'remember' | 'resume';
+};
 type SessionParkOptions = {
   registry: SessionRegistry;
   store: SessionStore;
-  /**
-   * 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;
-  /** 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
-   * would throw away an answer that is very likely seconds behind. Extends a
-   * deadline, never shortens one. Default 60000. */
   expiredGraceMs?: number;
-  /** Veto + accounting hook, called before the teardown: the job queue frees the
-   * run's concurrency slot here, and refuses (false) when the run is finalizing. */
   onParking?: (sessionId: string, executionId: string) => boolean;
-  /** The session is live again under a NEW runner object — anything holding the
-   * old reference must rebind. */
   onResumed?: (sessionId: string, runner: Runner) => void;
-  /** 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' | 'remember' | 'resume';
-  }) => void;
+  onError?: (error: unknown, context: ParkErrorContext) => void;
 };
-/**
- * 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,
- * evicts, and persists; delivering a result rebuilds the runner under the same id
- * and hands the result to it. The session's identity, event log, and seq numbering
- * survive intact, so a client reattaching with `afterSeq` sees one unbroken stream.
- */
 declare class SessionParkManager {
   #private;
   constructor(options: SessionParkOptions);
-  /** 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
-   * 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
-   * engine says the turn has come to rest on them, and clean up when it ends.
-   * `afterSeq` skips a rehydrated runner's replayed history (re-arming a watchdog
-   * from an event whose deadline already passed would fail the execution instantly).
-   */
   watch(runner: Runner, afterSeq?: number): () => void;
-  /** A client detached: park the session if that was the last one watching. */
   onDetach(sessionId: string): void;
-  /** Which session this execution belongs to — still waiting, or already settled. */
   sessionFor(executionId: string): string | undefined;
-  /** 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. */
   ensureLive(id: string): Promise<Runner | undefined>;
-  /**
-   * Deliver a deferred execution's result. Rehydrates the session if needed and
-   * folds the result into its agent loop.
-   *
-   * Undefined = no session is waiting on that id. `applied: false` = it was already
-   * settled: a duplicate delivery, or one racing the watchdog. Both are expected,
-   * neither is an error.
-   */
   submitResult(executionId: string, result: ToolExecutionResult): Promise<{
     applied: boolean;
     sessionId: string;
   } | undefined>;
-  /** Drop a parked session for good: the run is over (closed, canceled, killed). */
   discard(sessionId: string): Promise<void>;
   close(): void;
 }
 //#endregion
 //#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
- * no configuration, while an operator with a database wants their own.
- *
- * Profiles declared in `createWorkerServer({ profiles })` never enter a store —
- * they are code, and stay immutable. The store holds only what the management
- * routes created, and the two sets are unioned by name.
- *
- * A store holds NO credentials: `ProviderConfig.apiKeyEnv` is a variable name and
- * a Claude profile's `configDir` is a path. Both are resolved by the server's own
- * environment at session time, which is what keeps a stored profile safe to write
- * to disk and safe to serve from `GET /profiles`.
- */
 type ProfileStore = {
-  /** Every stored profile. Called once at `listen()` and after each mutation. */list(): ProfileInfo[] | Promise<ProfileInfo[]>; /** Create or replace by `profile.name`. */
-  save(profile: ProfileInfo): void | Promise<void>; /** Remove by name. Removing something absent is not an error. */
+  list(): ProfileInfo[] | Promise<ProfileInfo[]>;
+  save(profile: ProfileInfo): void | Promise<void>;
   delete(name: string): void | Promise<void>;
 };
-/** Non-durable store for tests and ephemeral deployments. */
 declare function createMemoryProfileStore(seed?: ProfileInfo[]): ProfileStore;
-/**
- * JSON-file store: one array of profiles at `path` (default
- * `<cwd>/.workerdeck/profiles.json`). Writes go through a temp file and a
- * rename so a crash mid-write cannot truncate the operator's profile list.
- *
- * Single-process by design, exactly like the bundled queue adapter — two servers
- * sharing one file would race. That is what the seam is for.
- */
 declare function createFileProfileStore(path?: string): ProfileStore;
 //#endregion
 //#region src/options.d.ts
@@ -429,400 +147,105 @@ type SdkSessionLister = (options: {
   limit?: number;
   offset?: number;
 }) => Promise<SdkSessionSummary[]>;
-/**
- * Return a principal (any truthy value) to accept the request, or null/undefined to
- * reject with 401. The host app supplies this — the worker has no auth story of its
- * own. A principal object may carry `allowedProfiles: string[]` to restrict which
- * profiles the caller can create sessions/jobs under (and see in GET /profiles) —
- * 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). */
+  authenticate?: Authenticator;
   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. */
+  authorizeSession?: (principal: unknown, session: SessionInfo) => boolean;
   allowedCwdRoots?: string[];
-  /**
-   * The host filesystem routes (`{basePath}/fs/*`) — browse and read the
-   * operator's real project tree, and optionally write to it.
-   *
-   * **Reading follows {@link allowedCwdRoots} and needs no grant of its own.**
-   * A caller holding the auth key can already start a session in any allowed root
-   * and have the agent read whatever is in it, so serving those same trees over
-   * `/fs` adds no authority — it only removes the absurdity of going through a
-   * language model to `cat` a file. Set `roots` here only to *narrow* that (or to
-   * expose a tree sessions may not run in).
-   *
-   * With neither set the routes 404. That is not the same as inheriting
-   * `allowedCwdRoots`' permissive "unset means anywhere": no cwd policy means
-   * there is nothing to inherit, and "anywhere" is a statement about paths the
-   * operator types at a keyboard, not one about what a phone may read.
-   *
-   * **Writing is a separate opt-in**, because it is the one part that is not
-   * already implied. An agent's writes go through the permission flow; a `PUT` to
-   * `/fs/write` does not. These routes are operator-privileged by design — the
-   * caller is the operator — but that is a reason to make the bypass deliberate,
-   * not a reason to skip the switch.
-   *
-   * Containment is *not* `cwdAllowed`, whichever roots are in play: these routes
-   * walk paths the agent may have authored, so a symlink can escape a lexical
-   * prefix check. See `host-files.ts` — canonicalize, then re-check.
-   */
   hostFiles?: {
-    /** Absolute paths. Unset inherits {@link allowedCwdRoots}; an explicit empty
-     * array disables the routes (a policy, not an absence). */
-    roots?: string[]; /** Enable `PUT {basePath}/fs/write`. Default false — read-only. */
+    roots?: string[];
     write?: boolean;
-    /** Refuse reads above this (413) rather than streaming a gigabyte to a phone.
-     * Default 1 MiB. Writes are bounded by {@link maxBodyBytes} instead. */
     maxFileBytes?: number;
-    /** Cap on entries returned per directory (the response says `truncated`).
-     * Default 5000. */
     maxEntries?: number;
-    /** Directory names `GET /fs/find` will not descend into. Defaults to
-     * `DEFAULT_IGNORED_DIRS` (`.git`, `node_modules`, build output…) — the thing
-     * that keeps a per-keystroke search cheap on a real source tree. */
     ignore?: string[];
   };
-  /**
-   * Message attachments (`{basePath}/sessions/:id/attachments`) — the photos and
-   * files a client sends alongside a message. Always on; these knobs only size it.
-   *
-   * There is no grant to make here the way `hostFiles.write` is one: an upload
-   * lands in the session's own in-memory hold and reaches the model as message
-   * content, which is exactly what typing does. What it *can* do is cost memory,
-   * so both caps default low enough that a phone camera roll cannot fill the
-   * gateway.
-   */
   attachments?: {
-    /** Largest single upload; over it is a 413. Default 10 MiB. */maxFileBytes?: number; /** Ceiling on what one session holds at once. Default 64 MiB. */
+    maxFileBytes?: number;
     maxSessionBytes?: number;
   };
-  /**
-   * Named Claude Code config directories sessions can run under (each becomes the
-   * session's CLAUDE_CONFIG_DIR — settings, memory, skills, and the credentials the
-   * SDK resolves from it). Declared here at startup; the API only reads them
-   * (GET {basePath}/profiles). With more than one declared, every session/job create
-   * must name its profile; with exactly one it is implicit. Unset: a 'default'
-   * profile is auto-created from $CLAUDE_CONFIG_DIR or ~/.claude when that directory
-   * exists. Pass [] to run without profiles (no env pinning at all).
-   */
   profiles?: ProfileInfo[];
-  /**
-   * Persistence for dashboard-managed profiles, which mounts the profile
-   * management routes (`POST /profiles`, `PATCH`/`DELETE /profiles/:name`).
-   * Without it the profile set is startup config and the API stays read-only.
-   *
-   * Profiles declared in `profiles` are never stored and never editable over
-   * HTTP — they are code. The two sets are unioned by name, declared winning.
-   * Callers still need `canManageProfiles` on their principal.
-   */
   profileStore?: ProfileStore;
-  /**
-   * Config-dir roots a *managed* Claude profile's `configDir` must resolve inside
-   * (mirrors {@link allowedCwdRoots}). Unset — the default — means the management
-   * routes create provider profiles only: naming a config directory is choosing
-   * which credential store a session runs on, so it stays operator-bounded.
-   * Declared profiles are unaffected.
-   */
   allowedConfigDirRoots?: string[];
-  /** Map/patch the incoming CreateSessionRequest into the runner config (inject queryFn,
-   * env, tool policy, per-skill constraints...). Defaults to identity.
-   *
-   * What this hook injects is **not** durable: a session rebuilt from a parked
-   * record is built from the stored config, and a durable store persists neither
-   * `env` nor injected functions (see `toDurableRecord` in session-store.ts). That costs the
-   * Claude engine nothing, since it cannot park — but a provider host that
-   * resolves credentials into `config.env` here for its `createEngineRunner` to
-   * read back loses them on the wake. Resolve them in the factory instead. */
-  buildRunnerConfig?: (req: CreateSessionRequest) => SessionRunnerConfig; /** URL prefix for all routes. Default '/v1'. */
+  buildRunnerConfig?: (req: CreateSessionRequest) => SessionRunnerConfig;
   basePath?: string;
-  /**
-   * Handle requests that fall outside `basePath` instead of 404ing them. The
-   * turnkey CLI serves the dashboard through this, which is the whole reason it
-   * exists: a browser cannot put a header on a WebSocket handshake, so the only
-   * credential a tab can present on a session attach is a cookie — and a cookie
-   * only rides requests to the origin that set it. Serving the app and the API
-   * from one origin is therefore not a convenience, it is what makes an
-   * authenticated dashboard possible without a stamping proxy in front.
-   *
-   * Upgrades are not routed here: anything outside `basePath` is still refused.
-   */
   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
-   * session/job creation (403), and strip the `allowDangerouslySkipPermissions`
-   * pre-authorization from requests (so clients that ask for the capability by
-   * default keep working — their later switch attempt fails with the CLI's own
-   * visible error instead). Mirrors Claude Code's
-   * `permissions.disableBypassPermissionsMode` setting, enforced at the gateway.
-   */
   disableBypassPermissions?: boolean;
-  /**
-   * Fail closed on subscription credentials: if a session initializes with
-   * `apiKeySource: 'oauth'` (a claude.ai login rather than an API key / Bedrock / Vertex),
-   * it is terminated with a session_error. Recommended for services and any
-   * unattended/scheduled use — Anthropic's terms require API-key auth for those.
-   * Off by default: single-user personal deployments may legitimately run on the
-   * operator's own subscription; the server then logs a one-time notice instead.
-   */
   requireApiKey?: boolean;
-  /**
-   * Launch-time credential sanity check: once `listen()` binds, each Claude
-   * profile's session environment — exactly what `buildRunnerConfig` would hand
-   * a session, host hook included — is probed with the SDK-bundled CLI's
-   * `claude auth status`, concurrently and fire-and-forget, and a profile that
-   * reports logged-out gets one console warning. Warn, never fail: the operator
-   * may be about to log in, and a probe that cannot run at all (missing binary,
-   * a CLI without `auth status`, unparseable output) stays silent — "couldn't
-   * check" is not "not logged in". No credential material is read or logged.
-   * Off by default (this is a library; tests must spawn nothing) — the turnkey
-   * CLI turns it on. Pass an object to inject the probe (tests) or a timeout.
-   */
   checkCredentials?: boolean | {
     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
-   * store); other engines always answer through their adapter's
-   * `listSessions`. */
   listSdkSessions?: SdkSessionLister;
-  /** Enable the job queue (`/jobs` + `/queue` routes). Jobs run as ordinary registry
-   * sessions — attachable over the sessions WS — governed by these limits. */
   queue?: QueueServerOptions;
-  /**
-   * Out-of-band notification for interactive sessions: the four moments a person
-   * away from the screen needs (permission requested, turn done, error, closed)
-   * POSTed to a webhook and/or handed to a local observer. Off unless configured.
-   *
-   * Server-wide, unlike the queue's per-job webhook — the point is to hear about
-   * sessions you neither created nor are attached to, which is the situation a
-   * mobile client is in permanently (iOS will not hold a WebSocket open in the
-   * background). Every registry session qualifies, job runs included, so a job
-   * carrying its own webhook is reported on both channels.
-   *
-   * This is the primitive, and it stays transport-agnostic on purpose: the OSS
-   * server holds no push credentials. Turning a notification into an APNs push is
-   * a forwarder's job — see the turnkey CLI.
-   */
   notifications?: SessionNotificationOptions;
-  /** Browser-bridged tool execution: how long a bridged call may go unanswered
-   * before it fails (default 60000), and where terminal results are delivered.
-   * The hub is always available on the returned server as `bridge`. */
   bridge?: BridgeHubOptions;
-  /**
-   * Deferred execution: a session that parks on an execution nothing here is
-   * running has its state persisted and its runner torn down, and comes back when
-   * the result is POSTed to `{basePath}/executions/:executionId/result`.
-   *
-   * On by default with an in-memory store, so a park survives a disconnect but not
-   * a restart; pass `store: createFileSessionStore()` (or your own) to change that
-   * — read its doc first, the record holds the whole transcript.
-   */
   parking?: {
-    store?: SessionStore; /** Grace after the last client detaches before parking. Default 2000. */
+    store?: SessionStore;
     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;
-    /**
-     * 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. */
-    onError?: (error: unknown, context: {
-      sessionId: string;
-      phase: 'park' | 'remember' | 'resume';
-    }) => void;
+    onError?: (error: unknown, context: ParkErrorContext) => void;
   };
-  /**
-   * Build a runner for a `provider` profile (the model-agnostic engine).
-   * Required if any such profile is declared — the server refuses to start
-   * otherwise, rather than failing at create time.
-   *
-   * Kept as a host hook so the server package neither imports a model SDK nor
-   * decides how provider credentials are resolved: the factory reads them from
-   * the operator's environment, exactly like the Claude credential chain.
-   * `claude` and `codex` profiles never come through here — those engines ship
-   * as in-repo adapters (`@workerdeck/core`'s `getEngineAdapter`).
-   *
-   * May be async: assembly that has to await — a per-session MCP connect, a
-   * credential lookup — belongs here, with `AiSdkRunnerConfig.onClose` as the
-   * disposer. A rejection fails the create — the session POST answers 500 with
-   * the message, a job goes straight to `failed`.
-   */
   createEngineRunner?: (context: EngineRunnerContext) => Runner | Promise<Runner>;
-  /**
-   * Adapter overrides, keyed by engine — **for tests only** (the server
-   * integration suite injects a fake codex engine so `pnpm test` spawns no
-   * binary). Not a public extension point: third engines belong in core as
-   * adapters, or behind `createEngineRunner` as provider profiles.
-   */
   engines?: Partial<Record<ProfileEngine, EngineAdapter>>;
 };
 type EngineRunnerContext = {
-  /** The session config, with profile defaults already applied. */config: SessionRunnerConfig; /** The profile that selected this engine. */
+  config: SessionRunnerConfig;
   profile: ProfileInfo;
-  /** Bridge hub, for handing the runner a browser-backed ToolExecutor
-   * (`bridge.executorFor(sessionId)`). */
   bridge: BridgeHub;
-  /**
-   * Set when rebuilding a session that parked on a deferred execution. Forward it
-   * as `restore` on the engine config (`createEngineSession({ config: { ...config,
-   * restore } })`) — the engine then adopts the session's id, event log, seq
-   * 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. */
-  sessionTokenLimit?: number; /** Global job-token budget per UTC day; queued jobs are held once exhausted. */
-  dailyTokenLimit?: number; /** Wall-clock cap per job run — the watchdog against stuck CLIs. */
-  maxJobDurationMs?: number; /** Grace between interrupting a killed run and force-closing it. Default 5000. */
+  maxConcurrency?: number;
+  sessionTokenLimit?: number;
+  dailyTokenLimit?: number;
+  maxJobDurationMs?: number;
   killGraceMs?: number;
-  /** Expire terminal jobs after `maxAgeMs` (the in-memory adapter otherwise grows
-   * unboundedly). */
   retention?: {
     maxAgeMs: number;
     sweepIntervalMs?: number;
   };
-  /** Queue backend. Defaults to the bundled in-memory adapter (single process,
-   * no persistence) — redis/bullmq/pubsub adapters implement the same interface. */
-  adapter?: QueueAdapter; /** Webhook delivery attempts per event (default 3, exponential backoff). */
+  adapter?: QueueAdapter;
   webhookAttempts?: number;
-  webhookRetryDelayMs?: number; /** Local observer for job lifecycle events (in addition to per-job webhooks). */
+  webhookRetryDelayMs?: number;
   onEvent?: (event: JobEvent) => void;
 };
+/** A point-in-time answer to "is it safe to stop yet?", as reported while draining. */
+type DrainReport = {
+  /** Sessions mid-turn. These resolve on their own, so the drain waits for them. */working: string[];
+  /**
+   * Sessions blocked on a human — a pending approval. The drain names these but never waits for them: nothing about
+   * shutting down will answer the prompt, so waiting is a hang with better manners.
+   */
+  awaitingHuman: string[]; /** True when the deadline passed with work still running. */
+  timedOut: boolean;
+};
+type DrainOptions = {
+  /** Overall budget. The drain gives up and reports rather than blocking shutdown forever. */timeoutMs?: number;
+  pollMs?: number;
+  onProgress?: (report: DrainReport) => void;
+};
 type WorkerServer = {
   server: Server;
-  registry: SessionRegistry; /** The job queue, when `queue` options were provided. */
+  registry: SessionRegistry;
   queue?: JobQueue;
-  /** Routes tool executions to attached browser clients. `bridge.executorFor(id)`
-   * is the `ToolExecutor` to hand a runner that should execute in the tab. */
   bridge: BridgeHub;
-  /** Parked sessions: the store, the execution index, and the rehydration path.
-   * Deliver a deferred result with `parking.submitResult(...)` in-process, or POST
-   * it to `{basePath}/executions/:executionId/result`. */
   parking: SessionParkManager;
   listen: (port: number, host?: string) => Promise<{
     port: number;
   }>;
+  /**
+   * Let running turns finish before `close()`. A courtesy, never a correctness requirement: records are written
+   * continuously, so a hard stop already loses nothing. Refuses new sessions for as long as it runs.
+   */
+  drain: (options?: DrainOptions) => Promise<DrainReport>;
   close: () => Promise<void>;
 };
 //#endregion
@@ -830,147 +253,40 @@ type WorkerServer = {
 declare function createWorkerServer(options?: WorkerServerOptions): WorkerServer;
 //#endregion
 //#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. */
+  description?: string;
   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.
-   * - a **function** — selects per call, so `eval_script` can run in-process
-   *   while a custom tool goes to the browser. The function receives the
-   *   {@link ToolExecutionCall} and returns an executor or `'browser'`.
-   */
   executor: ToolExecutor | 'browser' | ((call: ToolExecutionCall) => 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`). */
+  capabilities?: EngineSessionOptions['capabilities'];
   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. */
+  mcp?: McpConnection;
+  mcpTools?: ToolSet;
+  instructions?: string;
   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>;
-  /**
-   * Gate tool execution behind user approval. See
-   * {@link EngineSessionOptions.shouldApprove} — this is a straight pass-through.
-   */
   shouldApprove?: (call: {
     toolName: string;
     input: unknown;
-  }) => boolean; /** Timeout for permission prompts (ms). Default 120 000. */
+  }) => boolean;
   approvalTimeoutMs?: number;
-  /** 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. */
+  maxFileBytes?: number;
   maxSessionBytes?: number;
 };
 type AttachmentRejection = {
@@ -993,35 +309,12 @@ type PutResult = {
   ok: false;
   error: AttachmentRejection;
 };
-/**
- * Per-session hold for files the user attached to a message.
- *
- * In memory, and deliberately so. An attachment is only *needed* for the instant
- * between the upload and the message that names it; everything after that is
- * convenience (a client re-rendering a thumbnail after a reattach). That is the
- * same bargain `GET /sessions/:id/files` makes — the session's lifetime, no
- * durability tier — and it keeps the gateway from accumulating a photo library
- * on disk that nobody asked it to look after.
- *
- * Both caps are enforced here rather than at the route, so a host embedding the
- * server cannot forget one: a single file that is too big is a 413, and so is a
- * session whose total would go over.
- */
 declare class AttachmentStore {
   #private;
   constructor(options?: AttachmentStoreOptions);
   get maxFileBytes(): number;
   put(sessionId: string, name: string, mediaType: string, body: Buffer): PutResult;
-  /** The stored record, bytes included — for the download route and for the send
-   * path that turns ids into content blocks. */
   get(sessionId: string, id: string): AttachmentInput | undefined;
-  /**
-   * Resolve the ids a `user_message` named, in the order given.
-   *
-   * Missing ids are reported rather than skipped: a message that quietly lost its
-   * picture reads as the model ignoring it, which is a far worse failure than a
-   * command that errors.
-   */
   resolve(sessionId: string, ids: readonly string[]): {
     ok: true;
     attachments: AttachmentInput[];
@@ -1033,101 +326,25 @@ declare class AttachmentStore {
 }
 //#endregion
 //#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. */
+  fileId: string;
   path: string;
-  mediaType?: string; /** Size when the runner announced it — advisory, and re-read at serve time. */
+  mediaType?: string;
   bytes?: number;
   sessionId: string;
 };
-/**
- * The paths this gateway will serve from `GET /sessions/:id/produced/:fileId`.
- *
- * **This is the whole access-control model, so it is worth being precise about
- * what it is.** The store is an allowlist built from one source and one only:
- * `file_produced` events, which a runner emits about a file its own engine just
- * wrote. It is not a directory grant. Nothing else can add to it — not a
- * request, not a config, and in particular not the agent, whose own path claims
- * go through `/fs/*` and that route's root allowlist.
- *
- * That is why the route needs neither `hostFiles.roots` nor `maxFileBytes`:
- * "somewhere under a root the operator declared" is a guess about which paths
- * are safe, while "the exact path this session's runner reported producing" is
- * a fact about one file. A 2 MB generated PNG is the common case, and making
- * the operator raise a byte cap to see their own picture was the bug this
- * replaces.
- *
- * Lifetime is the session's, like `AttachmentStore`'s: in memory, dropped when
- * the session is removed. The bytes are never held here — only the path, so a
- * gateway serving a long session accumulates a few hundred bytes per picture
- * rather than the pictures.
- */
 declare class ProducedFileStore {
   #private;
-  /**
-   * Register a runner's produced files for its lifetime.
-   *
-   * Subscribes from seq 0, which is the opposite of what `SessionNotifier` wants
-   * and correct for the same reason: registration is idempotent (a `fileId` is
-   * derived from its path, so re-registering overwrites with itself), and a
-   * session rebuilt from a park must re-learn every file it produced before the
-   * park — otherwise a client's transcript keeps rendering image cards whose
-   * bytes have quietly become unreachable.
-   */
   watch(runner: Runner): void;
   get(sessionId: string, fileId: string): ProducedFile | undefined;
-  /** Everything one session has produced, newest registration last. */
   list(sessionId: string): ProducedFile[];
   drop(sessionId: string): void;
 }
 //#endregion
 //#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