@workerdeck/server 0.6.0

package/build/index.d.mts

@@ -0,0 +1,530 @@
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { BridgeAnswer, BrowserBridgeExecutor, ClaudeAuthProbe, ParkedExecution, Runner, RunnerSnapshot, SessionRunnerConfig, ToolExecutionResult } from "@workerdeck/core";
+import { JobQueue, QueueAdapter } from "@workerdeck/queue";
+import { CreateSessionRequest, JobEvent, ProfileInfo, SdkSessionSummary, ServerFrame, 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;
+};
+/** 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/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. */
+  retryDelayMs?: number;
+};
+/**
+ * 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/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;
+  /**
+   * 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/session-store.d.ts
+/**
+ * A session with its live runner torn down, waiting on deferred executions.
+ *
+ * Everything needed to bring it back: the wire-visible info (so it still lists and
+ * reads over REST while parked), the config to rebuild the runner, the engine's
+ * snapshot, and what it is waiting for.
+ */
+type ParkedSessionRecord = {
+  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). */
+  config: SessionRunnerConfig;
+  snapshot: RunnerSnapshot;
+  executions: ParkedExecution[];
+  parkedAt: number;
+};
+/**
+ * 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: ParkedSessionRecord): Promise<void>;
+  get(id: string): Promise<ParkedSessionRecord | null>;
+  list(): Promise<ParkedSessionRecord[]>;
+  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[]>;
+  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;
+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/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>;
+  /** 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;
+  /** 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/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';
+  }) => void;
+};
+/**
+ * Deferred execution's other half: parking a session that is waiting on work no
+ * process in this server is doing.
+ *
+ * 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;
+  /** 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. */
+  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 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`. */
+  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/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. */
+  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/server.d.ts
+type SdkSessionLister = (options: {
+  dir?: string;
+  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.
+ */
+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. */
+  allowedCwdRoots?: string[];
+  /**
+   * 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'. */
+  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>; /** 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;
+  };
+  /** Injectable lister for GET /sdk-sessions (tests). Defaults to the SDK's listSessions,
+   * which reads the Agent SDK's on-disk session store. */
+  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. */
+    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. */
+    onError?: (error: unknown, context: {
+      sessionId: string;
+      phase: 'park' | 'resume';
+    }) => 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.
+   *
+   * 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>;
+};
+type EngineRunnerContext = {
+  /** The session config, with profile defaults already applied. */config: SessionRunnerConfig; /** The profile that selected this engine. */
+  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;
+};
+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. */
+  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). */
+  webhookAttempts?: number;
+  webhookRetryDelayMs?: number; /** Local observer for job lifecycle events (in addition to per-job webhooks). */
+  onEvent?: (event: JobEvent) => void;
+};
+type WorkerServer = {
+  server: Server;
+  registry: SessionRegistry; /** The job queue, when `queue` options were provided. */
+  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;
+  }>;
+  close: () => Promise<void>;
+};
+declare function createWorkerServer(options?: WorkerServerOptions): WorkerServer;
+//#endregion
+export { type Authenticator, BridgeHub, type BridgeHubOptions, type EngineRunnerContext, type FileSessionStoreOptions, MemorySessionStore, type ParkedSessionRecord, 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 };
+//# sourceMappingURL=index.d.mts.map