@workerdeck/protocol 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Strebitzer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @workerdeck/protocol
+
+The WorkerDeck wire protocol: typed session events, commands, and REST shapes shared by the
+server and every client. Dependency-free, browser-safe. This protocol is the product boundary —
+versioned from day one.
+
+Part of [WorkerDeck](https://github.com/workerdeck/workerdeck), the web-controlled
+Agent SDK session runner. Everything else in the stack depends on this package; it depends on
+nothing. [`@workerdeck/core`](https://www.npmjs.com/package/@workerdeck/core) produces these
+events, [`@workerdeck/server`](https://www.npmjs.com/package/@workerdeck/server) puts them
+on the wire, and [`@workerdeck/client`](https://www.npmjs.com/package/@workerdeck/client)
+consumes them. Anthropic API message content is modeled structurally (`ApiMessage`,
+`ContentBlock`) so browsers can render transcripts without the Agent SDK.
+
+## Install
+
+```bash
+npm install @workerdeck/protocol
+```
+
+Type-only for most consumers; the runtime exports are `PROTOCOL_VERSION` and
+`supportsPermissionMode()`.
+
+## Usage
+
+One session = one ordered stream of `SessionEvent`s, each stamped with a monotonically increasing
+`seq`, plus a small `SessionCommand` set. Clients attach over WebSocket, optionally replaying from
+a known `seq`, and drive the session with commands:
+
+```ts
+import {
+  PROTOCOL_VERSION,
+  type ServerFrame,
+  type SessionCommand,
+} from '@workerdeck/protocol'
+
+ws.onmessage = ({ data }) => {
+  const frame = JSON.parse(data) as ServerFrame
+  if (frame.type === 'attached' && frame.protocolVersion !== PROTOCOL_VERSION) {
+    throw new Error('protocol mismatch')
+  }
+  if (frame.type === 'event' && frame.event.type === 'assistant_message') {
+    render(frame.event.message) // ApiMessage — plain Anthropic content blocks
+  }
+}
+
+const approve: SessionCommand = { type: 'permission_decision', requestId, behavior: 'allow' }
+ws.send(JSON.stringify(approve))
+```
+
+`PROTOCOL_VERSION` is bumped on any breaking change to events, commands, or REST shapes; the
+server reports it in the `attached` (and `queue_attached`) frame so clients can detect skew.
+
+## At a glance
+
+**Events (server → client)** — `system_init`, `status_changed`, `capabilities`, `model_changed`,
+`permission_mode_changed`, `context_usage`, `rate_limit`, `assistant_message`, `user_message`,
+`stream_delta`, `turn_result`, `permission_requested`, `permission_resolved`,
+`execution_dispatched` / `execution_result` / `execution_failed` (tool-execution lifecycle,
+correlated by `executionId`), `file_delivered`, `sdk_event` (forward-compatible passthrough for
+unmodeled SDK messages), `session_error`, `session_closed`.
+
+**Commands (client → server)** — `user_message`, `permission_decision`, `interrupt`,
+`set_permission_mode`, `set_model`, `tool_call_result` (answering a bridged execution), `close`.
+
+**Other server frames** — `attached`, `event`, `tool_call_request` / `tool_call_canceled` (the
+browser tool bridge: the server asks an attached client to run a *sandboxed* tool call), and
+`protocol_error`.
+
+**REST shapes** — `CreateSessionRequest` / `SessionInfo` and their response wrappers,
+`ResolvePermissionRequest` (the REST counterpart of `permission_decision`),
+`SdkSessionSummary` for listing the Agent SDK's on-disk sessions to offer resume,
+`ProfileInfo` for what a session may run as, `ListSessionFilesResponse` for a session's
+deliverables, and `SubmitExecutionResultRequest` for delivering a deferred execution's result.
+
+**Job queue** — `CreateJobRequest` / `JobInfo` / `JobEvent` (including `job_parked` /
+`job_resumed`) / `QueueStats` and the `QueueServerFrame` union for the one-way queue WebSocket,
+used when the server mounts the
+[`@workerdeck/queue`](https://www.npmjs.com/package/@workerdeck/queue) routes.
+
+Two engines ride this one protocol: `SessionInfo.engine` says which (`claude` or `provider`), and
+`supportsPermissionMode(engine, mode)` — a real runtime export, the single source of truth for the
+restriction — is what create forms filter with and the gateway rejects with.
+
+Forward compatibility is deliberate: unknown content blocks fall back to `UnknownBlock`, unions
+the SDK may grow (`apiKeySource`, rate-limit fields) stay `string`, and unmodeled SDK messages
+ride through as `sdk_event` rather than breaking older clients.
+
+## License
+
+MIT © Tobias Strebitzer —
+[LICENSE](https://github.com/workerdeck/workerdeck/blob/master/LICENSE)

package/build/index.d.mts

@@ -0,0 +1,899 @@
+//#region src/index.d.ts
+/**
+ * @workerdeck/protocol — the wire protocol between a workerdeck server and its clients.
+ *
+ * One session = one ordered stream of {@link SessionEvent}s (each stamped with a monotonically
+ * increasing `seq`) plus a small command set ({@link SessionCommand}). Clients attach over
+ * WebSocket, optionally replaying from a known `seq`, and drive the session with commands.
+ *
+ * This package is dependency-free and browser-safe. Anthropic API message content is modeled
+ * structurally (see {@link ApiMessage}) so clients don't need the Agent SDK to render transcripts.
+ */
+/** Bumped on any breaking change to events, commands, or REST shapes. */
+declare const PROTOCOL_VERSION = 4;
+/**
+ * - `starting` — runner spawned, waiting for the SDK init handshake
+ * - `running` — a turn is in progress
+ * - `awaiting_approval` — blocked on at least one pending permission request
+ * - `idle` — between turns; accepting user messages
+ * - `parked` — waiting on a deferred tool execution. The live runner has been torn
+ *   down and the session's state persisted; delivering the execution's result
+ *   (`POST {basePath}/executions/:executionId/result`) rehydrates it under the same
+ *   id and the run continues. Not terminal.
+ * - `failed` — the underlying query errored; terminal
+ * - `closed` — closed by a client or the host; terminal
+ */
+type SessionStatus = 'starting' | 'running' | 'awaiting_approval' | 'idle' | 'parked' | 'failed' | 'closed';
+type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto';
+type TextBlock = {
+  type: 'text';
+  text: string;
+};
+type ThinkingBlock = {
+  type: 'thinking';
+  thinking: string;
+};
+type ToolUseBlock = {
+  type: 'tool_use';
+  id: string;
+  name: string;
+  input: unknown;
+};
+type ToolResultBlock = {
+  type: 'tool_result';
+  tool_use_id: string;
+  content?: string | Array<{
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+  }>;
+  is_error?: boolean;
+};
+/** Forward-compatible fallback for block types this protocol version doesn't model. */
+type UnknownBlock = {
+  type: string;
+  [key: string]: unknown;
+};
+type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock;
+type ApiMessage = {
+  role: 'user' | 'assistant';
+  content: string | ContentBlock[];
+  model?: string;
+  stop_reason?: string | null;
+  /** Per-API-call token usage when the message carries it (assistant messages do).
+   * Enables mid-run token accounting; result-message usage stays authoritative. */
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+  };
+};
+/** A tool call promoted into a pending approval by the runner's canUseTool hook. */
+type PermissionRequest = {
+  /** Server-assigned id; used by the `permission_decision` command. */id: string;
+  toolName: string;
+  input: Record<string, unknown>;
+  toolUseId: string; /** Full prompt sentence from the SDK, e.g. "Claude wants to read foo.txt". */
+  title?: string; /** Short noun phrase for the tool action, e.g. "Read file". */
+  displayName?: string; /** Human-readable subtitle, e.g. "Claude will have read access to ~/x". */
+  description?: string; /** Why this permission request was triggered. */
+  decisionReason?: string; /** If raised from within a subagent, that subagent's id. */
+  agentId?: string; /** Epoch ms after which the server resolves it via its timeout policy. */
+  expiresAt?: number;
+};
+type PermissionDecisionSource = 'client' | 'timeout' | 'policy';
+/** One choice of an AskUserQuestion question (SDK tool-input mirror). */
+type UserQuestionOption = {
+  label: string;
+  description?: string;
+  /** Optional preview content (markdown unless the session configures html)
+   * rendered when the option is focused. */
+  preview?: string;
+};
+/** One question from the AskUserQuestion tool's input. By the tool's convention the
+ * first option is the model's recommended choice. */
+type UserQuestion = {
+  question: string; /** Short chip/tag label (max ~12 chars), e.g. "Auth method". */
+  header: string;
+  options: UserQuestionOption[];
+  multiSelect?: boolean;
+};
+/** How a session treats the AskUserQuestion tool:
+ * - 'ask' (default) — a pending permission like any other: interactive UIs render the
+ *   question form; job webhooks carry the full request so a remote controller can
+ *   answer over REST (POST /sessions/:id/permissions/:requestId).
+ * - 'auto' — resolved immediately with each question's first (recommended) option.
+ * - 'deny' — the tool is refused with guidance to decide autonomously (unattended runs).
+ * Answers ride a permission allow as `updatedInput.answers`: question text → chosen
+ * option label(s), multi-select labels comma-joined — the shape the CLI's own UI uses. */
+type QuestionBehavior = 'ask' | 'auto' | 'deny';
+/** A model the session can switch to (SDK ModelInfo mirror; fields it may grow stay unknown). */
+type ModelOption = {
+  /** Model id for createSession.model / set_model. */value: string;
+  displayName: string;
+  description?: string;
+};
+/** A slash command the CLI accepts as user-message text (SDK SlashCommand mirror). */
+type SlashCommandInfo = {
+  /** Command name without the leading slash. */name: string;
+  description?: string; /** Hint for arguments, e.g. "<file>". */
+  argumentHint?: string; /** Alternate names resolving to this command. */
+  aliases?: string[];
+};
+/** One category row from the CLI's context-usage breakdown (system prompt, tools, ...). */
+type ContextUsageCategory = {
+  name: string;
+  tokens: number;
+  /** Color the CLI assigns the category. Often a CLI theme token name ('inactive',
+   * 'promptBorder', ...), not a CSS color — validate before styling with it. */
+  color: string;
+};
+/** Context-window usage snapshot (SDK getContextUsage mirror), polled after each turn. */
+type ContextUsage = {
+  categories: ContextUsageCategory[];
+  totalTokens: number;
+  maxTokens: number; /** Used share of the window, 0–100. */
+  percentage: number; /** Model the window sizing applies to. */
+  model?: string;
+};
+/**
+ * One rate-limit window snapshot (SDK SDKRateLimitInfo mirror). Emitted only for
+ * claude.ai subscription sessions — API-key sessions may never produce one, so
+ * clients must render nothing (not 0%) until data arrives.
+ */
+type RateLimitInfo = {
+  /** 'allowed' | 'allowed_warning' | 'rejected' — kept as string, the SDK union may grow. */status: string;
+  /** Which window: 'five_hour' (session), 'seven_day' (weekly), 'seven_day_opus',
+   * 'seven_day_sonnet', 'overage', ... — kept as string, the SDK union may grow. */
+  rateLimitType?: string;
+  /** Used share of the window, 0–100. The CLI omits it on some updates — treat
+   * absent as unknown, not 0. */
+  utilization?: number; /** Epoch **seconds** when the window resets (render countdowns client-side). */
+  resetsAt?: number;
+  isUsingOverage?: boolean;
+};
+/**
+ * Lifecycle of one tool execution, correlated by `executionId` end to end.
+ *
+ * - `pending` — dispatched, result not in yet (bridged to a client, or queued).
+ * - `deferred` — parked beyond this turn/process; may outlive the session's
+ *   liveness and be applied on rehydration.
+ * - `settled` / `failed` — terminal. Results are applied idempotently by id, so
+ *   a duplicate delivery is a no-op rather than a second application.
+ */
+type ToolExecutionStatus = 'pending' | 'deferred' | 'settled' | 'failed';
+/** Where a tool execution ran (or is running). Advisory: for display and routing. */
+type ToolExecutionBackend = 'server' | 'browser' | 'managed' | 'remote';
+/** Result payload of a tool execution, by value — never a live host reference. */
+type ToolExecutionOutput = {
+  type: 'text';
+  value: string;
+} | {
+  type: 'json';
+  value: unknown;
+};
+type SessionEventBody = /** SDK init handshake: what this session actually is. */{
+  type: 'system_init';
+  sdkSessionId: string;
+  model: string;
+  cwd: string;
+  /** Where the session's Anthropic auth came from: 'oauth' means a claude.ai
+   * subscription login; other values ('user' | 'project' | 'org' | 'temporary')
+   * are API-key provenance. Kept as string — the SDK union may grow. */
+  apiKeySource: string;
+  tools: string[];
+  skills: string[];
+  slashCommands: string[];
+  permissionMode: PermissionMode;
+  claudeCodeVersion: string;
+  mcpServers: Array<{
+    name: string;
+    status: string;
+  }>;
+} | {
+  type: 'status_changed';
+  status: SessionStatus;
+  detail?: string;
+}
+/** Models and slash commands available to this session; fetched from the CLI after
+ * init. Late attachers get it via replay like any other event. */
+| {
+  type: 'capabilities';
+  models: ModelOption[];
+  commands: SlashCommandInfo[];
+} /** The session's model changed via `set_model`. `model` undefined = back to default. */ | {
+  type: 'model_changed';
+  model?: string;
+} /** The session's permission mode changed via `set_permission_mode`. */ | {
+  type: 'permission_mode_changed';
+  mode: PermissionMode;
+} /** Context-window usage snapshot; the runner polls it after each turn. */ | {
+  type: 'context_usage';
+  usage: ContextUsage;
+} /** Subscription rate-limit update for one window (see {@link RateLimitInfo}). */ | {
+  type: 'rate_limit';
+  info: RateLimitInfo;
+} | {
+  type: 'assistant_message';
+  message: ApiMessage; /** Set when the message was produced inside a subagent (Task tool). */
+  parentToolUseId: string | null; /** True when backfilled from a resumed session's history. */
+  replay?: boolean;
+  uuid: string;
+} | {
+  type: 'user_message';
+  message: ApiMessage;
+  parentToolUseId: string | null; /** True when replayed from a resumed session's history. */
+  replay?: boolean; /** True for tool results and other synthetic user-role messages. */
+  synthetic?: boolean;
+  uuid?: string;
+}
+/** Raw Anthropic streaming event (message_start/content_block_delta/...); emitted only
+ * when the session was created with `includePartialMessages`. */
+| {
+  type: 'stream_delta';
+  event: {
+    type: string;
+    [key: string]: unknown;
+  };
+  parentToolUseId: string | null;
+  uuid: string;
+} | {
+  type: 'turn_result';
+  subtype: 'success' | 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd' | 'error_max_structured_output_retries';
+  isError: boolean;
+  durationMs: number;
+  numTurns: number;
+  totalCostUsd: number; /** Final text of the turn (success only). */
+  result?: string;
+  errors?: string[];
+  usage?: unknown;
+} | {
+  type: 'permission_requested';
+  request: PermissionRequest;
+} | {
+  type: 'permission_resolved';
+  requestId: string;
+  behavior: 'allow' | 'deny';
+  resolvedBy: PermissionDecisionSource; /** Denial message, when denied. */
+  message?: string;
+}
+/** A tool execution was dispatched to a backend. For bridged executions this
+ * precedes the `tool_call_request` frame; for deferred ones it is the record
+ * that survives a teardown. */
+| {
+  type: 'execution_dispatched';
+  executionId: string;
+  toolName: string;
+  backend: ToolExecutionBackend; /** True when the execution may outlive this turn or process. */
+  deferred?: boolean; /** Epoch ms after which the server applies its timeout policy. */
+  expiresAt?: number;
+} /** A dispatched execution produced a result. Applied idempotently by `executionId`. */ | {
+  type: 'execution_result';
+  executionId: string;
+  output: ToolExecutionOutput; /** Guest/agent-visible logs, if the backend captured any. */
+  logs?: string[];
+  durationMs?: number;
+}
+/** A dispatched execution failed, timed out, or was orphaned. The failure is fed
+ * back into the loop as tool output so the agent can adapt — it is not a session error. */
+| {
+  type: 'execution_failed';
+  executionId: string; /** Machine-readable cause: 'timeout' | 'oom' | 'exception' | 'orphaned' | backend-specific. */
+  reason: string;
+  error: string;
+  logs?: string[];
+  durationMs?: number;
+}
+/** The agent handed over a file from its session scratch filesystem (the
+ * `deliver_file` tool). Download it via `GET {basePath}/sessions/:id/files/<path>`
+ * for as long as the session lives (the VFS is in-memory). */
+| {
+  type: 'file_delivered';
+  path: string;
+  bytes: number;
+  description?: string;
+}
+/** Any SDKMessage this protocol version doesn't model first-class (task progress,
+ * compaction boundaries, auth status, ...). Payload is the raw SDK message. */
+| {
+  type: 'sdk_event';
+  payload: {
+    type: string;
+    [key: string]: unknown;
+  };
+} | {
+  type: 'session_error';
+  message: string;
+} | {
+  type: 'session_closed';
+  reason: 'client' | 'server' | 'error';
+};
+type SessionEvent = SessionEventBody & {
+  /** Monotonic per-session sequence number, starting at 1. */seq: number; /** Epoch ms when the server emitted the event. */
+  ts: number;
+};
+type SessionCommand = {
+  type: 'user_message';
+  text: string;
+} | {
+  type: 'permission_decision';
+  requestId: string;
+  behavior: 'allow' | 'deny'; /** allow only: modified tool input to run instead of the original. */
+  updatedInput?: Record<string, unknown>; /** deny only: reason surfaced to the model. */
+  message?: string; /** deny only: also interrupt the running turn. */
+  interrupt?: boolean;
+} | {
+  type: 'interrupt';
+} | {
+  type: 'set_permission_mode';
+  mode: PermissionMode;
+} /** Switch the model for subsequent responses; omit `model` for the default. */ | {
+  type: 'set_model';
+  model?: string;
+}
+/**
+ * Result of a tool execution the server bridged to this client (see
+ * {@link ToolCallRequestFrame}). Unknown or already-settled `executionId`s are
+ * ignored — delivery is idempotent, and a late result after a timeout must not
+ * re-open a settled call.
+ *
+ * Browser-returned results are UNTRUSTED input: acceptable for the user's own
+ * data, never a source for server-authoritative state.
+ */
+| {
+  type: 'tool_call_result';
+  executionId: string;
+  output: ToolExecutionOutput;
+  logs?: string[];
+}
+/** The client could not execute a bridged call (unsupported tool, guest error,
+ * tab closing). Fed back to the agent as tool output. */
+| {
+  type: 'tool_call_error';
+  executionId: string;
+  reason: string;
+  error: string;
+  logs?: string[];
+} | {
+  type: 'close';
+};
+/** First frame the server sends after a successful attach. */
+type AttachedFrame = {
+  type: 'attached';
+  protocolVersion: number;
+  session: SessionInfo; /** Events with seq > the client's `afterSeq` follow as `event` frames. */
+  replayingFrom: number;
+};
+/**
+ * Ask the attached client to execute a tool call in its own sandbox (browser
+ * bridge). The client answers with `tool_call_result` or `tool_call_error`
+ * carrying the same `executionId`.
+ *
+ * Only sandbox-benefiting tools are ever bridged. Authenticated/authoritative
+ * tools (MCP, secret-bearing APIs) execute server-side and never appear here.
+ */
+type ToolCallRequestFrame = {
+  type: 'tool_call_request';
+  executionId: string;
+  toolName: string;
+  input: unknown; /** Files to seed the client's scratch VFS with, path → contents. */
+  vfsSeed?: Record<string, string>;
+  limits?: {
+    timeoutMs?: number;
+    memoryLimitBytes?: number;
+  }; /** Epoch ms after which the server gives up and fails the execution. */
+  expiresAt?: number;
+};
+type ServerFrame = AttachedFrame | {
+  type: 'event';
+  event: SessionEvent;
+} | ToolCallRequestFrame
+/** A bridged execution no longer needs an answer (turn interrupted, timed out,
+ * or the session closed) — the client should abandon it. */
+| {
+  type: 'tool_call_canceled';
+  executionId: string;
+  reason: string;
+} | {
+  type: 'protocol_error';
+  message: string;
+};
+type ClientFrame = SessionCommand;
+/** Per-profile fallbacks filled into session/job requests that leave the field
+ * unset. Defaults, not enforced caps — an explicit request value always wins. */
+type ProfileDefaults = {
+  model?: string;
+  permissionMode?: PermissionMode;
+};
+/**
+ * A named Claude Code config directory sessions can run under: the session's CLI
+ * process gets it as CLAUDE_CONFIG_DIR, so the profile carries that directory's
+ * settings, memory, skills, and whatever credentials the SDK/CLI resolves from it.
+ * Profiles are declared in server options at startup (or a 'default' one is
+ * auto-created from the operator's own config dir) — the API only reads them.
+ */
+/**
+ * Which engine a profile runs on.
+ * - `claude` (default) — Claude Code via the Agent SDK, configured by a config dir.
+ * - `provider` — a model-agnostic provider (OpenAI-compatible, Anthropic, Moonshot),
+ *   configured by provider id and credentials from the operator's environment.
+ */
+type ProfileEngine = 'claude' | 'provider';
+/**
+ * Permission modes the model-agnostic provider engine understands. The rest of
+ * {@link PermissionMode}'s vocabulary is Claude Code's: `acceptEdits`, `plan` and
+ * `auto` name CLI-side behaviours a provider session has no equivalent of.
+ */
+declare const PROVIDER_PERMISSION_MODES: readonly PermissionMode[];
+/**
+ * Whether a profile's engine can run a permission mode. The single source of
+ * truth for the restriction: create forms filter what they offer with it, the
+ * gateway rejects with it. An absent `engine` means 'claude' (every mode).
+ */
+declare function supportsPermissionMode(engine: ProfileEngine | undefined, mode: PermissionMode): boolean;
+/**
+ * A model provider a `provider` profile can run on. Credentials are ALWAYS
+ * resolved from the operator's environment — never carried on the wire, never
+ * stored here. `apiKeyEnv` names the variable to read, it does not hold a key.
+ */
+type ProviderConfig = {
+  /** Provider adapter to use, e.g. 'anthropic' | 'openai' | 'moonshotai' |
+   * 'openai-compatible'. Kept as a string: the set is host-extensible. */
+  id: string; /** Default model id, e.g. 'kimi-k3'. Overridable per session. */
+  model?: string;
+  /** Model ids this profile offers, for the dashboard's picker. Operator-declared
+   * rather than discovered: provider engines have no equivalent of the CLI's
+   * `supportedModels()`, and only the operator knows which ids their endpoint and
+   * key actually serve. Unset → the picker offers {@link ProviderConfig.model} alone. */
+  models?: string[]; /** Base URL for OpenAI-compatible providers. */
+  baseUrl?: string; /** Environment variable the operator put the key in. Never the key itself. */
+  apiKeyEnv?: string;
+};
+/**
+ * A grantable capability of the model-agnostic engine, named after the tool it
+ * yields. The always-present tools (`fs_*`, `eval_script`) are not listed: they
+ * are the engine's scratch filesystem and sandbox, not a grant.
+ */
+type SessionCapability = 'web_search' | 'download' | 'web_fetch' | 'deliver_file';
+/**
+ * What sessions under a `provider` profile get, declared by the operator. Meaning-
+ * less for `claude` profiles, whose equivalents live in the config directory.
+ *
+ * MCP servers are named, never configured, here: a server's transport config can
+ * carry credentials in its headers, and this type is served by `GET /profiles`.
+ * The names refer to servers the host connected in `createEngineRunner`, which is
+ * where the configs (and the credentials) stay.
+ */
+type ProfileSessionDefaults = {
+  /** Capabilities granted to sessions under this profile. Absent = no
+   * declaration, so a session gets whatever backends the host wired. A session
+   * request may narrow this set, never widen it. */
+  capabilities?: SessionCapability[];
+  /** MCP servers, by name, whose tools sessions under this profile may use.
+   * Absent = no declaration (every server the host connected). */
+  mcpServers?: string[]; /** Prepended to the session's system prompt. */
+  instructions?: string;
+};
+type ProfileInfo = {
+  /** Unique name, used as {@link CreateSessionRequest.profile}. */name: string;
+  /** Engine this profile runs on. Defaults to 'claude' when absent, so profiles
+   * written before provider support keep working unchanged. */
+  engine?: ProfileEngine;
+  /** Absolute path set as CLAUDE_CONFIG_DIR for the session's CLI process.
+   * Required for 'claude' profiles; meaningless for 'provider' ones. */
+  configDir?: string; /** Provider wiring for 'provider' profiles. */
+  provider?: ProviderConfig;
+  description?: string;
+  defaults?: ProfileDefaults; /** Provider-engine session grants (capabilities, MCP servers, instructions). */
+  session?: ProfileSessionDefaults;
+  /** Response-only, computed by the server: this profile came from the profile
+   * store and can be edited or deleted through the API. Profiles declared in
+   * server options are absent/false — they are code. Ignored on the way in. */
+  managed?: boolean;
+};
+/**
+ * Curated, read-only snapshot of what a profile's config directory contains —
+ * the parts relevant to running worker sessions. Values that could carry secrets
+ * (env var values) never leave the server; only names are listed.
+ */
+type ProfileConfigSnapshot = {
+  /** From the config dir's settings.json; absent when missing or unparseable. */settings?: {
+    /** Configured default model. */model?: string; /** permissions.defaultMode — the CLI's default permission mode. */
+    defaultPermissionMode?: string; /** Rule counts from permissions.allow / ask / deny. */
+    permissionRules?: {
+      allow: number;
+      ask: number;
+      deny: number;
+    }; /** Env var NAMES declared in settings.json env (values never included). */
+    envKeys?: string[]; /** Hook event names with at least one hook configured. */
+    hooks?: string[];
+  }; /** CLAUDE.md (user memory) present in the config dir. */
+  hasUserMemory: boolean; /** Skill names (skills/<name>/). */
+  skills: string[]; /** Agent names (agents/<name>.md). */
+  agents: string[]; /** Custom slash-command names (commands/<name>.md). */
+  commands: string[];
+};
+type McpServerConfigWire = {
+  type?: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+} | {
+  type: 'http';
+  url: string;
+  headers?: Record<string, string>;
+} | {
+  type: 'sse';
+  url: string;
+  headers?: Record<string, string>;
+};
+type CreateSessionRequest = {
+  /** Directory the session is rooted at. Required: `cwd` is per-query in the SDK
+   * and the server re-pins it on every call. */
+  cwd: string;
+  /** Profile (named Claude Code config dir) to run under. Required when the server
+   * declares more than one profile; implicit when exactly one exists. */
+  profile?: string; /** Optional initial prompt (may be a skill invocation like "/verify-content 123"). */
+  prompt?: string;
+  permissionMode?: PermissionMode;
+  /** Pre-authorize 'bypassPermissions' (the CLI's --dangerously-skip-permissions
+   * capability) so the mode can be switched on mid-session. Without it the CLI
+   * rejects `set_permission_mode: 'bypassPermissions'` on a running session.
+   * Implied when `permissionMode` is already 'bypassPermissions'. */
+  allowDangerouslySkipPermissions?: boolean;
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  mcpServers?: Record<string, McpServerConfigWire>;
+  /** Which filesystem settings the session loads. Include 'project' to pick up the
+   * target repo's skills and CLAUDE.md ("close-to-real" fidelity). */
+  settingSources?: Array<'user' | 'project' | 'local'>;
+  model?: string;
+  maxTurns?: number;
+  maxBudgetUsd?: number; /** Resume an existing SDK session by id. */
+  resume?: string; /** With `resume`: fork to a new session id instead of continuing. */
+  forkSession?: boolean; /** Emit `stream_delta` events for token-by-token rendering. Default true. */
+  includePartialMessages?: boolean; /** Per-session override of the server's permission-request timeout (ms). */
+  approvalTimeoutMs?: number; /** AskUserQuestion handling (see {@link QuestionBehavior}). Default 'ask'. */
+  questionBehavior?: QuestionBehavior;
+  /** Provider engine only: run with fewer capabilities than the profile grants
+   * (see {@link ProfileSessionDefaults.capabilities}). Narrowing only — naming a
+   * capability the profile does not grant is a 400, not a silent upgrade. */
+  capabilities?: SessionCapability[]; /** Free-form metadata echoed back on SessionInfo (host app bookkeeping). */
+  meta?: Record<string, unknown>;
+};
+type SessionInfo = {
+  /** Server-assigned id (stable across SDK session forks/resumes). */id: string; /** Underlying Agent SDK session id, once known; use for `resume`. */
+  sdkSessionId?: string;
+  status: SessionStatus;
+  cwd: string; /** Profile the session runs under (resolved name, present even when implicit). */
+  profile?: string;
+  /** Engine actually running this session, reported by the runner itself. Lets a
+   * session surface gate CLI-only affordances (permission modes, context usage,
+   * rate limits) without looking the profile back up. Absent = 'claude'. */
+  engine?: ProfileEngine;
+  model?: string;
+  permissionMode?: PermissionMode; /** See the `system_init` event; 'oauth' = claude.ai subscription credentials. */
+  apiKeySource?: string;
+  createdAt: number; /** Highest event seq emitted so far; attach with `afterSeq` to catch up. */
+  lastSeq: number;
+  pendingPermissionCount: number;
+  meta?: Record<string, unknown>; /** Display title: `meta.title` if the host set one, else derived (e.g. first prompt). */
+  title?: string; /** Cumulative cost across all turns so far (sum of turn_result totals). */
+  totalCostUsd?: number; /** Cumulative turn count across the session. */
+  numTurns?: number; /** Epoch ms of the most recent emitted event. */
+  lastActivityAt?: number;
+};
+/**
+ * A session in the Agent SDK's on-disk store (independent of this server's registry).
+ * Listed so hosts can offer "resume" across server restarts: feed `sessionId` to
+ * CreateSessionRequest.resume. Mirrors the SDK's SDKSessionInfo, kept browser-safe.
+ */
+type SdkSessionSummary = {
+  sessionId: string; /** Custom title, auto summary, or first prompt — whichever the SDK has. */
+  summary: string; /** Epoch ms of last modification. */
+  lastModified: number;
+  createdAt?: number;
+  customTitle?: string;
+  firstPrompt?: string;
+  gitBranch?: string;
+  cwd?: string;
+};
+/** One deliverable in the session's scratch filesystem (see the `file_delivered` event). */
+type SessionFileInfo = {
+  path: string;
+  bytes: number;
+};
+/** `GET {basePath}/sessions/:id/files` — every file currently in the session's VFS.
+ * `GET {basePath}/sessions/:id/files/<path>` downloads one (attachment disposition).
+ * 404 when the session's engine exposes no VFS (Claude-engine sessions). */
+type ListSessionFilesResponse = {
+  files: SessionFileInfo[];
+};
+type ListSessionsResponse = {
+  sessions: SessionInfo[];
+};
+type CreateSessionResponse = {
+  session: SessionInfo;
+};
+type GetSessionResponse = {
+  session: SessionInfo;
+};
+/** Body of `POST {basePath}/sessions/:id/permissions/:requestId` — the REST counterpart
+ * of the WS `permission_decision` command, for remote controllers without a socket
+ * (e.g. answering a job's AskUserQuestion from a webhook consumer). 404 = the request
+ * is unknown, already resolved, or expired. */
+type ResolvePermissionRequest = {
+  behavior: 'allow';
+  updatedInput?: Record<string, unknown>;
+} | {
+  behavior: 'deny';
+  message?: string;
+  interrupt?: boolean;
+};
+type ResolvePermissionResponse = {
+  resolved: true;
+};
+/**
+ * Body of `POST {basePath}/executions/:executionId/result` — the way a deferred
+ * executor (a remote worker, a batch job, a human) delivers the outcome of an
+ * execution the session parked on. The session is rehydrated if its runner was
+ * torn down, and the result is folded back into the agent loop; a `failed` result
+ * is ordinary tool output the agent adapts to, not a session error.
+ *
+ * Applied **idempotently by `executionId`**: a duplicate or late delivery (one
+ * racing the execution watchdog) answers 200 with `applied: false` rather than
+ * erroring or applying twice. 404 means no session is parked on that id.
+ */
+type SubmitExecutionResultRequest = {
+  status: 'ok';
+  output: ToolExecutionOutput;
+  logs?: string[];
+} | {
+  status: 'failed';
+  reason: string;
+  error: string;
+  logs?: string[];
+};
+type SubmitExecutionResultResponse = {
+  /** False when the id was already settled — the delivery was a no-op. */applied: boolean; /** Session the execution belonged to. */
+  sessionId: string;
+};
+type ListSdkSessionsResponse = {
+  sdkSessions: SdkSessionSummary[];
+};
+/** `GET {basePath}/profiles` — filtered to the profiles the caller may use. */
+type ListProfilesResponse = {
+  profiles: ProfileInfo[];
+  /** Whether this caller may create profiles here — true only when the server has
+   * a profile store AND the principal carries `canManageProfiles`. Lets a UI hide
+   * controls that would always be refused. */
+  canManage?: boolean;
+};
+/**
+ * `POST {basePath}/profiles` — create a managed profile. Available only when the
+ * server was given a profile store, and only to a principal with
+ * `canManageProfiles`. Profiles declared in server options are code, not data:
+ * they cannot be created, edited, or deleted through these routes.
+ */
+type CreateProfileRequest = ProfileInfo;
+/** `PATCH {basePath}/profiles/:name` — merge into a managed profile. The name is
+ * the route, not the body; pass `null` to clear an optional field. */
+type UpdateProfileRequest = Omit<Partial<ProfileInfo>, 'name'>;
+type SaveProfileResponse = {
+  profile: ProfileInfo;
+};
+/** `GET {basePath}/profiles/:name` — the profile plus a fresh config snapshot. */
+type GetProfileResponse = {
+  profile: ProfileInfo;
+  config: ProfileConfigSnapshot;
+};
+type ErrorResponse = {
+  error: string;
+};
+/**
+ * The moments in an *interactive* session a person needs to hear about when they
+ * are not watching it — the whole point being that a phone cannot hold a
+ * WebSocket open in the background, so the server has to reach out.
+ *
+ * Deliberately four: this is a human-attention channel, not an event mirror. The
+ * event log stays on the session WS (attach with `afterSeq` to catch up); if you
+ * want every assistant message, subscribe there instead.
+ */
+type SessionNotificationType = /** The agent is blocked on an approval — the one that matters most. */'permission_requested' /** A turn finished; the session is idle and waiting for the human. */ | 'turn_completed' /** The session failed (`session_error`). */ | 'session_error' /** The session ended (`session_closed`), whoever ended it. */ | 'session_closed';
+/** One delivery on the session-notification channel (JSON body of a webhook POST). */
+type SessionNotification = {
+  type: SessionNotificationType;
+  sessionId: string; /** Snapshot at notification time — status, title, cwd, cost, `lastSeq`. */
+  session: SessionInfo;
+  /** Seq of the event behind this notification; attach with `afterSeq: seq - 1` to
+   * land on it. */
+  seq: number;
+  ts: number;
+  /** One line fit for a notification body: the permission title, the turn's final
+   * text, the error message. */
+  preview?: string;
+  /** `permission_requested` only: the full request, so a consumer can answer it via
+   * `POST {basePath}/sessions/:id/permissions/:requestId` — which is what makes an
+   * Approve/Deny action on a lock-screen notification possible. */
+  request?: PermissionRequest; /** `turn_completed` only. */
+  result?: {
+    isError: boolean;
+    durationMs: number;
+    numTurns: number;
+    totalCostUsd: number;
+  }; /** `session_closed` only. */
+  reason?: 'client' | 'server' | 'error';
+};
+/** Where session notifications are POSTed (JSON body = {@link SessionNotification}).
+ * Server-wide, not per session: the point is to hear about sessions you did not
+ * create yourself and are not attached to. */
+type SessionWebhookConfig = {
+  url: string; /** Extra headers sent with every delivery (auth tokens etc.). */
+  headers?: Record<string, string>; /** Types to deliver. Default: all of them. */
+  events?: SessionNotificationType[];
+};
+/**
+ * - `queued` — accepted, waiting for a concurrency slot (or the daily token budget)
+ * - `running` — a session is executing the prompt
+ * - `parked` — waiting on an external event (a deferred tool execution). Not
+ *   terminal and not consuming a concurrency slot; resumes to `running` when the
+ *   result arrives, or fails via the execution watchdog if it never does.
+ * - `succeeded` / `failed` — terminal; `result` (and `error` on failure) are set
+ * - `canceled` — terminal; canceled by a client before or during the run
+ */
+type JobStatus = 'queued' | 'running' | 'parked' | 'succeeded' | 'failed' | 'canceled';
+/** Where job progress/completion deliveries are POSTed (JSON body = {@link JobEvent}). */
+type WebhookConfig = {
+  url: string; /** Extra headers sent with every delivery (auth tokens etc.). */
+  headers?: Record<string, string>;
+  /** Delivery granularity: 'messages' also POSTs job_progress per assistant message /
+   * permission request; 'completion' only job_started + job_completed. Default 'messages'. */
+  progress?: 'messages' | 'completion';
+};
+/**
+ * Schedule a one-shot run: the session executes `prompt` unattended and the job
+ * completes with that run's result. `session.prompt` is the task and is required;
+ * `resume`/`forkSession` are not supported for queued jobs.
+ */
+type CreateJobRequest = {
+  session: CreateSessionRequest & {
+    prompt: string;
+  };
+  webhook?: WebhookConfig; /** Per-job token cap; the effective cap is min(this, the server's sessionTokenLimit). */
+  maxTokens?: number; /** Per-job wall-clock cap; the effective cap is min(this, the server's maxJobDurationMs). */
+  maxDurationMs?: number;
+  /** Total run attempts: failed (not canceled) runs re-queue until this many attempts
+   * have been made. Default 1 (no retries). */
+  attempts?: number; /** Delay before the first retry, doubled for each subsequent one. Default 5000. */
+  retryDelayMs?: number; /** Host bookkeeping echoed back on JobInfo. */
+  meta?: Record<string, unknown>;
+};
+/** Cumulative resource usage of a job's run. `tokens` counts input + output +
+ * cache-creation + cache-read tokens across all turns. */
+type JobUsage = {
+  tokens: number;
+  totalCostUsd: number;
+  numTurns: number;
+};
+/** Terminal outcome of the job's run (mirrors the final turn_result). */
+type JobResult = {
+  subtype: string;
+  isError: boolean; /** Final text of the run (success only). */
+  result?: string;
+  errors?: string[];
+  durationMs: number;
+};
+type JobInfo = {
+  id: string;
+  status: JobStatus;
+  cwd: string; /** Profile the run executes under (resolved name, present even when implicit). */
+  profile?: string;
+  prompt: string; /** Server session id once started — attach via the sessions WS to watch the run live. */
+  sessionId?: string;
+  sdkSessionId?: string;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number; /** 1-based run attempt this info reflects. */
+  attempt?: number; /** Total attempts configured on the request (see CreateJobRequest.attempts). */
+  maxAttempts?: number; /** For a job re-queued by retry backoff: earliest time the next attempt may start. */
+  nextRunAt?: number;
+  /** Set while `status` is 'parked': when the run parked, and the execution it is
+   * waiting on — the id to POST a result to. Cleared when it resumes. */
+  parkedAt?: number;
+  parkedExecutionId?: string; /** Cumulative across attempts. */
+  usage: JobUsage;
+  result?: JobResult; /** Failure or cancellation reason (for a queued retry: the previous attempt's error). */
+  error?: string;
+  meta?: Record<string, unknown>;
+};
+/** Latest mid-run activity, carried on job_progress deliveries. */
+type JobProgress = {
+  kind: 'assistant_text' | 'tool_use' | 'permission_requested' | 'permission_resolved'; /** Short human-readable preview (message excerpt, tool name, permission title). */
+  preview?: string;
+  /** 'permission_requested' only: the full request (including AskUserQuestion input) so
+   * webhook consumers can answer via POST /sessions/:sessionId/permissions/:requestId. */
+  request?: PermissionRequest;
+};
+/** Webhook delivery payload (also the queue's local event shape). `job_submitted` goes
+ * to local observers and the queue WS only — the submitter already has the POST
+ * response, so webhooks start at `job_started`. `job_retrying` marks a failed run that
+ * was re-queued (`job.nextRunAt` says when); `job_completed` is always terminal. */
+type JobEvent = {
+  type: 'job_submitted';
+  job: JobInfo;
+  ts: number;
+} | {
+  type: 'job_started';
+  job: JobInfo;
+  ts: number;
+} | {
+  type: 'job_progress';
+  job: JobInfo;
+  progress: JobProgress;
+  ts: number;
+}
+/** The run parked on a deferred execution; `executionId` says what it waits on —
+ * the id to POST a result to. The *work itself* (tool name, input, VFS seed) went
+ * to the executor's own dispatch hook, not over this channel: a webhook consumer
+ * learns that a run is waiting, the worker learns what to do. */
+| {
+  type: 'job_parked';
+  job: JobInfo;
+  executionId: string;
+  ts: number;
+} /** A parked run resumed because its execution result arrived. */ | {
+  type: 'job_resumed';
+  job: JobInfo;
+  executionId: string;
+  ts: number;
+} | {
+  type: 'job_retrying';
+  job: JobInfo;
+  ts: number;
+} | {
+  type: 'job_completed';
+  job: JobInfo;
+  ts: number;
+};
+type QueueStats = {
+  maxConcurrency: number;
+  running: number;
+  queued: number;
+  /** Jobs waiting on a deferred execution. They hold no concurrency slot and
+   * their wall-clock budget is not ticking. */
+  parked: number;
+  sessionTokenLimit?: number;
+  dailyTokenLimit?: number; /** Tokens consumed by queue jobs in the current UTC day. */
+  dailyTokensUsed: number; /** True when the daily budget is exhausted and queued jobs are being held. */
+  paused: boolean;
+};
+/** Frames sent on the queue WS (`{basePath}/queue/ws`). The stream is one-way
+ * (server→client): every job's lifecycle as it happens, plus refreshed stats after
+ * lifecycle changes. Clients send nothing; job mutations stay on REST. */
+type QueueServerFrame = {
+  type: 'queue_attached';
+  protocolVersion: number;
+  stats: QueueStats;
+} | {
+  type: 'job_event';
+  event: JobEvent;
+} | {
+  type: 'queue_stats';
+  stats: QueueStats;
+};
+type CreateJobResponse = {
+  job: JobInfo;
+};
+type GetJobResponse = {
+  job: JobInfo;
+};
+type ListJobsResponse = {
+  jobs: JobInfo[];
+};
+type QueueStatsResponse = {
+  stats: QueueStats;
+};
+//#endregion
+export { ApiMessage, AttachedFrame, ClientFrame, ContentBlock, ContextUsage, ContextUsageCategory, CreateJobRequest, CreateJobResponse, CreateProfileRequest, CreateSessionRequest, CreateSessionResponse, ErrorResponse, GetJobResponse, GetProfileResponse, GetSessionResponse, JobEvent, JobInfo, JobProgress, JobResult, JobStatus, JobUsage, ListJobsResponse, ListProfilesResponse, ListSdkSessionsResponse, ListSessionFilesResponse, ListSessionsResponse, McpServerConfigWire, ModelOption, PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, PermissionDecisionSource, PermissionMode, PermissionRequest, ProfileConfigSnapshot, ProfileDefaults, ProfileEngine, ProfileInfo, ProfileSessionDefaults, ProviderConfig, QuestionBehavior, QueueServerFrame, QueueStats, QueueStatsResponse, RateLimitInfo, ResolvePermissionRequest, ResolvePermissionResponse, SaveProfileResponse, SdkSessionSummary, ServerFrame, SessionCapability, SessionCommand, SessionEvent, SessionEventBody, SessionFileInfo, SessionInfo, SessionNotification, SessionNotificationType, SessionStatus, SessionWebhookConfig, SlashCommandInfo, SubmitExecutionResultRequest, SubmitExecutionResultResponse, TextBlock, ThinkingBlock, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput, ToolExecutionStatus, ToolResultBlock, ToolUseBlock, UnknownBlock, UpdateProfileRequest, UserQuestion, UserQuestionOption, WebhookConfig, supportsPermissionMode };
+//# sourceMappingURL=index.d.mts.map

package/build/index.mjs

@@ -0,0 +1,35 @@
+//#region src/index.ts
+/**
+* @workerdeck/protocol — the wire protocol between a workerdeck server and its clients.
+*
+* One session = one ordered stream of {@link SessionEvent}s (each stamped with a monotonically
+* increasing `seq`) plus a small command set ({@link SessionCommand}). Clients attach over
+* WebSocket, optionally replaying from a known `seq`, and drive the session with commands.
+*
+* This package is dependency-free and browser-safe. Anthropic API message content is modeled
+* structurally (see {@link ApiMessage}) so clients don't need the Agent SDK to render transcripts.
+*/
+/** Bumped on any breaking change to events, commands, or REST shapes. */
+const PROTOCOL_VERSION = 4;
+/**
+* Permission modes the model-agnostic provider engine understands. The rest of
+* {@link PermissionMode}'s vocabulary is Claude Code's: `acceptEdits`, `plan` and
+* `auto` name CLI-side behaviours a provider session has no equivalent of.
+*/
+const PROVIDER_PERMISSION_MODES = [
+	"default",
+	"bypassPermissions",
+	"dontAsk"
+];
+/**
+* Whether a profile's engine can run a permission mode. The single source of
+* truth for the restriction: create forms filter what they offer with it, the
+* gateway rejects with it. An absent `engine` means 'claude' (every mode).
+*/
+function supportsPermissionMode(engine, mode) {
+	return engine === "provider" ? PROVIDER_PERMISSION_MODES.includes(mode) : true;
+}
+//#endregion
+export { PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, supportsPermissionMode };
+
+//# sourceMappingURL=index.mjs.map

package/build/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @workerdeck/protocol — the wire protocol between a workerdeck server and its clients.\n *\n * One session = one ordered stream of {@link SessionEvent}s (each stamped with a monotonically\n * increasing `seq`) plus a small command set ({@link SessionCommand}). Clients attach over\n * WebSocket, optionally replaying from a known `seq`, and drive the session with commands.\n *\n * This package is dependency-free and browser-safe. Anthropic API message content is modeled\n * structurally (see {@link ApiMessage}) so clients don't need the Agent SDK to render transcripts.\n */\n\n/** Bumped on any breaking change to events, commands, or REST shapes. */\nexport const PROTOCOL_VERSION = 4\n\n// ---------------------------------------------------------------------------\n// Session lifecycle\n// ---------------------------------------------------------------------------\n\n/**\n * - `starting` — runner spawned, waiting for the SDK init handshake\n * - `running` — a turn is in progress\n * - `awaiting_approval` — blocked on at least one pending permission request\n * - `idle` — between turns; accepting user messages\n * - `parked` — waiting on a deferred tool execution. The live runner has been torn\n *   down and the session's state persisted; delivering the execution's result\n *   (`POST {basePath}/executions/:executionId/result`) rehydrates it under the same\n *   id and the run continues. Not terminal.\n * - `failed` — the underlying query errored; terminal\n * - `closed` — closed by a client or the host; terminal\n */\nexport type SessionStatus =\n  | 'starting'\n  | 'running'\n  | 'awaiting_approval'\n  | 'idle'\n  | 'parked'\n  | 'failed'\n  | 'closed'\n\nexport type PermissionMode =\n  | 'default'\n  | 'acceptEdits'\n  | 'bypassPermissions'\n  | 'plan'\n  | 'dontAsk'\n  | 'auto'\n\n// ---------------------------------------------------------------------------\n// API message content (structural mirror of Anthropic message shapes)\n// ---------------------------------------------------------------------------\n\nexport type TextBlock = { type: 'text'; text: string }\nexport type ThinkingBlock = { type: 'thinking'; thinking: string }\nexport type ToolUseBlock = { type: 'tool_use'; id: string; name: string; input: unknown }\nexport type ToolResultBlock = {\n  type: 'tool_result'\n  tool_use_id: string\n  content?: string | Array<{ type: string; text?: string; [key: string]: unknown }>\n  is_error?: boolean\n}\n/** Forward-compatible fallback for block types this protocol version doesn't model. */\nexport type UnknownBlock = { type: string; [key: string]: unknown }\n\nexport type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock\n\nexport type ApiMessage = {\n  role: 'user' | 'assistant'\n  content: string | ContentBlock[]\n  model?: string\n  stop_reason?: string | null\n  /** Per-API-call token usage when the message carries it (assistant messages do).\n   * Enables mid-run token accounting; result-message usage stays authoritative. */\n  usage?: {\n    input_tokens?: number\n    output_tokens?: number\n    cache_creation_input_tokens?: number\n    cache_read_input_tokens?: number\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Permission requests\n// ---------------------------------------------------------------------------\n\n/** A tool call promoted into a pending approval by the runner's canUseTool hook. */\nexport type PermissionRequest = {\n  /** Server-assigned id; used by the `permission_decision` command. */\n  id: string\n  toolName: string\n  input: Record<string, unknown>\n  toolUseId: string\n  /** Full prompt sentence from the SDK, e.g. \"Claude wants to read foo.txt\". */\n  title?: string\n  /** Short noun phrase for the tool action, e.g. \"Read file\". */\n  displayName?: string\n  /** Human-readable subtitle, e.g. \"Claude will have read access to ~/x\". */\n  description?: string\n  /** Why this permission request was triggered. */\n  decisionReason?: string\n  /** If raised from within a subagent, that subagent's id. */\n  agentId?: string\n  /** Epoch ms after which the server resolves it via its timeout policy. */\n  expiresAt?: number\n}\n\nexport type PermissionDecisionSource = 'client' | 'timeout' | 'policy'\n\n// ---------------------------------------------------------------------------\n// User questions (the AskUserQuestion tool)\n// ---------------------------------------------------------------------------\n\n/** One choice of an AskUserQuestion question (SDK tool-input mirror). */\nexport type UserQuestionOption = {\n  label: string\n  description?: string\n  /** Optional preview content (markdown unless the session configures html)\n   * rendered when the option is focused. */\n  preview?: string\n}\n\n/** One question from the AskUserQuestion tool's input. By the tool's convention the\n * first option is the model's recommended choice. */\nexport type UserQuestion = {\n  question: string\n  /** Short chip/tag label (max ~12 chars), e.g. \"Auth method\". */\n  header: string\n  options: UserQuestionOption[]\n  multiSelect?: boolean\n}\n\n/** How a session treats the AskUserQuestion tool:\n * - 'ask' (default) — a pending permission like any other: interactive UIs render the\n *   question form; job webhooks carry the full request so a remote controller can\n *   answer over REST (POST /sessions/:id/permissions/:requestId).\n * - 'auto' — resolved immediately with each question's first (recommended) option.\n * - 'deny' — the tool is refused with guidance to decide autonomously (unattended runs).\n * Answers ride a permission allow as `updatedInput.answers`: question text → chosen\n * option label(s), multi-select labels comma-joined — the shape the CLI's own UI uses. */\nexport type QuestionBehavior = 'ask' | 'auto' | 'deny'\n\n// ---------------------------------------------------------------------------\n// Session capabilities (models / slash commands the CLI reports)\n// ---------------------------------------------------------------------------\n\n/** A model the session can switch to (SDK ModelInfo mirror; fields it may grow stay unknown). */\nexport type ModelOption = {\n  /** Model id for createSession.model / set_model. */\n  value: string\n  displayName: string\n  description?: string\n}\n\n/** A slash command the CLI accepts as user-message text (SDK SlashCommand mirror). */\nexport type SlashCommandInfo = {\n  /** Command name without the leading slash. */\n  name: string\n  description?: string\n  /** Hint for arguments, e.g. \"<file>\". */\n  argumentHint?: string\n  /** Alternate names resolving to this command. */\n  aliases?: string[]\n}\n\n// ---------------------------------------------------------------------------\n// Usage telemetry (context window + subscription rate limits)\n// ---------------------------------------------------------------------------\n\n/** One category row from the CLI's context-usage breakdown (system prompt, tools, ...). */\nexport type ContextUsageCategory = {\n  name: string\n  tokens: number\n  /** Color the CLI assigns the category. Often a CLI theme token name ('inactive',\n   * 'promptBorder', ...), not a CSS color — validate before styling with it. */\n  color: string\n}\n\n/** Context-window usage snapshot (SDK getContextUsage mirror), polled after each turn. */\nexport type ContextUsage = {\n  categories: ContextUsageCategory[]\n  totalTokens: number\n  maxTokens: number\n  /** Used share of the window, 0–100. */\n  percentage: number\n  /** Model the window sizing applies to. */\n  model?: string\n}\n\n/**\n * One rate-limit window snapshot (SDK SDKRateLimitInfo mirror). Emitted only for\n * claude.ai subscription sessions — API-key sessions may never produce one, so\n * clients must render nothing (not 0%) until data arrives.\n */\nexport type RateLimitInfo = {\n  /** 'allowed' | 'allowed_warning' | 'rejected' — kept as string, the SDK union may grow. */\n  status: string\n  /** Which window: 'five_hour' (session), 'seven_day' (weekly), 'seven_day_opus',\n   * 'seven_day_sonnet', 'overage', ... — kept as string, the SDK union may grow. */\n  rateLimitType?: string\n  /** Used share of the window, 0–100. The CLI omits it on some updates — treat\n   * absent as unknown, not 0. */\n  utilization?: number\n  /** Epoch **seconds** when the window resets (render countdowns client-side). */\n  resetsAt?: number\n  isUsingOverage?: boolean\n}\n\n// ---------------------------------------------------------------------------\n// Tool execution (bridged, deferred, and remote)\n// ---------------------------------------------------------------------------\n\n/**\n * Lifecycle of one tool execution, correlated by `executionId` end to end.\n *\n * - `pending` — dispatched, result not in yet (bridged to a client, or queued).\n * - `deferred` — parked beyond this turn/process; may outlive the session's\n *   liveness and be applied on rehydration.\n * - `settled` / `failed` — terminal. Results are applied idempotently by id, so\n *   a duplicate delivery is a no-op rather than a second application.\n */\nexport type ToolExecutionStatus = 'pending' | 'deferred' | 'settled' | 'failed'\n\n/** Where a tool execution ran (or is running). Advisory: for display and routing. */\nexport type ToolExecutionBackend = 'server' | 'browser' | 'managed' | 'remote'\n\n/** Result payload of a tool execution, by value — never a live host reference. */\nexport type ToolExecutionOutput =\n  | { type: 'text'; value: string }\n  | { type: 'json'; value: unknown }\n\n// ---------------------------------------------------------------------------\n// Session events (server -> client)\n// ---------------------------------------------------------------------------\n\nexport type SessionEventBody =\n  /** SDK init handshake: what this session actually is. */\n  | {\n      type: 'system_init'\n      sdkSessionId: string\n      model: string\n      cwd: string\n      /** Where the session's Anthropic auth came from: 'oauth' means a claude.ai\n       * subscription login; other values ('user' | 'project' | 'org' | 'temporary')\n       * are API-key provenance. Kept as string — the SDK union may grow. */\n      apiKeySource: string\n      tools: string[]\n      skills: string[]\n      slashCommands: string[]\n      permissionMode: PermissionMode\n      claudeCodeVersion: string\n      mcpServers: Array<{ name: string; status: string }>\n    }\n  | { type: 'status_changed'; status: SessionStatus; detail?: string }\n  /** Models and slash commands available to this session; fetched from the CLI after\n   * init. Late attachers get it via replay like any other event. */\n  | { type: 'capabilities'; models: ModelOption[]; commands: SlashCommandInfo[] }\n  /** The session's model changed via `set_model`. `model` undefined = back to default. */\n  | { type: 'model_changed'; model?: string }\n  /** The session's permission mode changed via `set_permission_mode`. */\n  | { type: 'permission_mode_changed'; mode: PermissionMode }\n  /** Context-window usage snapshot; the runner polls it after each turn. */\n  | { type: 'context_usage'; usage: ContextUsage }\n  /** Subscription rate-limit update for one window (see {@link RateLimitInfo}). */\n  | { type: 'rate_limit'; info: RateLimitInfo }\n  | {\n      type: 'assistant_message'\n      message: ApiMessage\n      /** Set when the message was produced inside a subagent (Task tool). */\n      parentToolUseId: string | null\n      /** True when backfilled from a resumed session's history. */\n      replay?: boolean\n      uuid: string\n    }\n  | {\n      type: 'user_message'\n      message: ApiMessage\n      parentToolUseId: string | null\n      /** True when replayed from a resumed session's history. */\n      replay?: boolean\n      /** True for tool results and other synthetic user-role messages. */\n      synthetic?: boolean\n      uuid?: string\n    }\n  /** Raw Anthropic streaming event (message_start/content_block_delta/...); emitted only\n   * when the session was created with `includePartialMessages`. */\n  | {\n      type: 'stream_delta'\n      event: { type: string; [key: string]: unknown }\n      parentToolUseId: string | null\n      uuid: string\n    }\n  | {\n      type: 'turn_result'\n      subtype:\n        | 'success'\n        | 'error_during_execution'\n        | 'error_max_turns'\n        | 'error_max_budget_usd'\n        | 'error_max_structured_output_retries'\n      isError: boolean\n      durationMs: number\n      numTurns: number\n      totalCostUsd: number\n      /** Final text of the turn (success only). */\n      result?: string\n      errors?: string[]\n      usage?: unknown\n    }\n  | { type: 'permission_requested'; request: PermissionRequest }\n  | {\n      type: 'permission_resolved'\n      requestId: string\n      behavior: 'allow' | 'deny'\n      resolvedBy: PermissionDecisionSource\n      /** Denial message, when denied. */\n      message?: string\n    }\n  /** A tool execution was dispatched to a backend. For bridged executions this\n   * precedes the `tool_call_request` frame; for deferred ones it is the record\n   * that survives a teardown. */\n  | {\n      type: 'execution_dispatched'\n      executionId: string\n      toolName: string\n      backend: ToolExecutionBackend\n      /** True when the execution may outlive this turn or process. */\n      deferred?: boolean\n      /** Epoch ms after which the server applies its timeout policy. */\n      expiresAt?: number\n    }\n  /** A dispatched execution produced a result. Applied idempotently by `executionId`. */\n  | {\n      type: 'execution_result'\n      executionId: string\n      output: ToolExecutionOutput\n      /** Guest/agent-visible logs, if the backend captured any. */\n      logs?: string[]\n      durationMs?: number\n    }\n  /** A dispatched execution failed, timed out, or was orphaned. The failure is fed\n   * back into the loop as tool output so the agent can adapt — it is not a session error. */\n  | {\n      type: 'execution_failed'\n      executionId: string\n      /** Machine-readable cause: 'timeout' | 'oom' | 'exception' | 'orphaned' | backend-specific. */\n      reason: string\n      error: string\n      logs?: string[]\n      durationMs?: number\n    }\n  /** The agent handed over a file from its session scratch filesystem (the\n   * `deliver_file` tool). Download it via `GET {basePath}/sessions/:id/files/<path>`\n   * for as long as the session lives (the VFS is in-memory). */\n  | { type: 'file_delivered'; path: string; bytes: number; description?: string }\n  /** Any SDKMessage this protocol version doesn't model first-class (task progress,\n   * compaction boundaries, auth status, ...). Payload is the raw SDK message. */\n  | { type: 'sdk_event'; payload: { type: string; [key: string]: unknown } }\n  | { type: 'session_error'; message: string }\n  | { type: 'session_closed'; reason: 'client' | 'server' | 'error' }\n\nexport type SessionEvent = SessionEventBody & {\n  /** Monotonic per-session sequence number, starting at 1. */\n  seq: number\n  /** Epoch ms when the server emitted the event. */\n  ts: number\n}\n\n// ---------------------------------------------------------------------------\n// Commands (client -> server)\n// ---------------------------------------------------------------------------\n\nexport type SessionCommand =\n  | { type: 'user_message'; text: string }\n  | {\n      type: 'permission_decision'\n      requestId: string\n      behavior: 'allow' | 'deny'\n      /** allow only: modified tool input to run instead of the original. */\n      updatedInput?: Record<string, unknown>\n      /** deny only: reason surfaced to the model. */\n      message?: string\n      /** deny only: also interrupt the running turn. */\n      interrupt?: boolean\n    }\n  | { type: 'interrupt' }\n  | { type: 'set_permission_mode'; mode: PermissionMode }\n  /** Switch the model for subsequent responses; omit `model` for the default. */\n  | { type: 'set_model'; model?: string }\n  /**\n   * Result of a tool execution the server bridged to this client (see\n   * {@link ToolCallRequestFrame}). Unknown or already-settled `executionId`s are\n   * ignored — delivery is idempotent, and a late result after a timeout must not\n   * re-open a settled call.\n   *\n   * Browser-returned results are UNTRUSTED input: acceptable for the user's own\n   * data, never a source for server-authoritative state.\n   */\n  | {\n      type: 'tool_call_result'\n      executionId: string\n      output: ToolExecutionOutput\n      logs?: string[]\n    }\n  /** The client could not execute a bridged call (unsupported tool, guest error,\n   * tab closing). Fed back to the agent as tool output. */\n  | {\n      type: 'tool_call_error'\n      executionId: string\n      reason: string\n      error: string\n      logs?: string[]\n    }\n  | { type: 'close' }\n\n// ---------------------------------------------------------------------------\n// WebSocket frames\n// ---------------------------------------------------------------------------\n\n/** First frame the server sends after a successful attach. */\nexport type AttachedFrame = {\n  type: 'attached'\n  protocolVersion: number\n  session: SessionInfo\n  /** Events with seq > the client's `afterSeq` follow as `event` frames. */\n  replayingFrom: number\n}\n\n/**\n * Ask the attached client to execute a tool call in its own sandbox (browser\n * bridge). The client answers with `tool_call_result` or `tool_call_error`\n * carrying the same `executionId`.\n *\n * Only sandbox-benefiting tools are ever bridged. Authenticated/authoritative\n * tools (MCP, secret-bearing APIs) execute server-side and never appear here.\n */\nexport type ToolCallRequestFrame = {\n  type: 'tool_call_request'\n  executionId: string\n  toolName: string\n  input: unknown\n  /** Files to seed the client's scratch VFS with, path → contents. */\n  vfsSeed?: Record<string, string>\n  limits?: { timeoutMs?: number; memoryLimitBytes?: number }\n  /** Epoch ms after which the server gives up and fails the execution. */\n  expiresAt?: number\n}\n\nexport type ServerFrame =\n  | AttachedFrame\n  | { type: 'event'; event: SessionEvent }\n  | ToolCallRequestFrame\n  /** A bridged execution no longer needs an answer (turn interrupted, timed out,\n   * or the session closed) — the client should abandon it. */\n  | { type: 'tool_call_canceled'; executionId: string; reason: string }\n  | { type: 'protocol_error'; message: string }\n\nexport type ClientFrame = SessionCommand\n\n// ---------------------------------------------------------------------------\n// Profiles (named Claude Code config directories)\n// ---------------------------------------------------------------------------\n\n/** Per-profile fallbacks filled into session/job requests that leave the field\n * unset. Defaults, not enforced caps — an explicit request value always wins. */\nexport type ProfileDefaults = {\n  model?: string\n  permissionMode?: PermissionMode\n}\n\n/**\n * A named Claude Code config directory sessions can run under: the session's CLI\n * process gets it as CLAUDE_CONFIG_DIR, so the profile carries that directory's\n * settings, memory, skills, and whatever credentials the SDK/CLI resolves from it.\n * Profiles are declared in server options at startup (or a 'default' one is\n * auto-created from the operator's own config dir) — the API only reads them.\n */\n/**\n * Which engine a profile runs on.\n * - `claude` (default) — Claude Code via the Agent SDK, configured by a config dir.\n * - `provider` — a model-agnostic provider (OpenAI-compatible, Anthropic, Moonshot),\n *   configured by provider id and credentials from the operator's environment.\n */\nexport type ProfileEngine = 'claude' | 'provider'\n\n/**\n * Permission modes the model-agnostic provider engine understands. The rest of\n * {@link PermissionMode}'s vocabulary is Claude Code's: `acceptEdits`, `plan` and\n * `auto` name CLI-side behaviours a provider session has no equivalent of.\n */\nexport const PROVIDER_PERMISSION_MODES: readonly PermissionMode[] = [\n  'default',\n  'bypassPermissions',\n  'dontAsk',\n]\n\n/**\n * Whether a profile's engine can run a permission mode. The single source of\n * truth for the restriction: create forms filter what they offer with it, the\n * gateway rejects with it. An absent `engine` means 'claude' (every mode).\n */\nexport function supportsPermissionMode(\n  engine: ProfileEngine | undefined,\n  mode: PermissionMode,\n): boolean {\n  return engine === 'provider' ? PROVIDER_PERMISSION_MODES.includes(mode) : true\n}\n\n/**\n * A model provider a `provider` profile can run on. Credentials are ALWAYS\n * resolved from the operator's environment — never carried on the wire, never\n * stored here. `apiKeyEnv` names the variable to read, it does not hold a key.\n */\nexport type ProviderConfig = {\n  /** Provider adapter to use, e.g. 'anthropic' | 'openai' | 'moonshotai' |\n   * 'openai-compatible'. Kept as a string: the set is host-extensible. */\n  id: string\n  /** Default model id, e.g. 'kimi-k3'. Overridable per session. */\n  model?: string\n  /** Model ids this profile offers, for the dashboard's picker. Operator-declared\n   * rather than discovered: provider engines have no equivalent of the CLI's\n   * `supportedModels()`, and only the operator knows which ids their endpoint and\n   * key actually serve. Unset → the picker offers {@link ProviderConfig.model} alone. */\n  models?: string[]\n  /** Base URL for OpenAI-compatible providers. */\n  baseUrl?: string\n  /** Environment variable the operator put the key in. Never the key itself. */\n  apiKeyEnv?: string\n}\n\n/**\n * A grantable capability of the model-agnostic engine, named after the tool it\n * yields. The always-present tools (`fs_*`, `eval_script`) are not listed: they\n * are the engine's scratch filesystem and sandbox, not a grant.\n */\nexport type SessionCapability = 'web_search' | 'download' | 'web_fetch' | 'deliver_file'\n\n/**\n * What sessions under a `provider` profile get, declared by the operator. Meaning-\n * less for `claude` profiles, whose equivalents live in the config directory.\n *\n * MCP servers are named, never configured, here: a server's transport config can\n * carry credentials in its headers, and this type is served by `GET /profiles`.\n * The names refer to servers the host connected in `createEngineRunner`, which is\n * where the configs (and the credentials) stay.\n */\nexport type ProfileSessionDefaults = {\n  /** Capabilities granted to sessions under this profile. Absent = no\n   * declaration, so a session gets whatever backends the host wired. A session\n   * request may narrow this set, never widen it. */\n  capabilities?: SessionCapability[]\n  /** MCP servers, by name, whose tools sessions under this profile may use.\n   * Absent = no declaration (every server the host connected). */\n  mcpServers?: string[]\n  /** Prepended to the session's system prompt. */\n  instructions?: string\n}\n\nexport type ProfileInfo = {\n  /** Unique name, used as {@link CreateSessionRequest.profile}. */\n  name: string\n  /** Engine this profile runs on. Defaults to 'claude' when absent, so profiles\n   * written before provider support keep working unchanged. */\n  engine?: ProfileEngine\n  /** Absolute path set as CLAUDE_CONFIG_DIR for the session's CLI process.\n   * Required for 'claude' profiles; meaningless for 'provider' ones. */\n  configDir?: string\n  /** Provider wiring for 'provider' profiles. */\n  provider?: ProviderConfig\n  description?: string\n  defaults?: ProfileDefaults\n  /** Provider-engine session grants (capabilities, MCP servers, instructions). */\n  session?: ProfileSessionDefaults\n  /** Response-only, computed by the server: this profile came from the profile\n   * store and can be edited or deleted through the API. Profiles declared in\n   * server options are absent/false — they are code. Ignored on the way in. */\n  managed?: boolean\n}\n\n/**\n * Curated, read-only snapshot of what a profile's config directory contains —\n * the parts relevant to running worker sessions. Values that could carry secrets\n * (env var values) never leave the server; only names are listed.\n */\nexport type ProfileConfigSnapshot = {\n  /** From the config dir's settings.json; absent when missing or unparseable. */\n  settings?: {\n    /** Configured default model. */\n    model?: string\n    /** permissions.defaultMode — the CLI's default permission mode. */\n    defaultPermissionMode?: string\n    /** Rule counts from permissions.allow / ask / deny. */\n    permissionRules?: { allow: number; ask: number; deny: number }\n    /** Env var NAMES declared in settings.json env (values never included). */\n    envKeys?: string[]\n    /** Hook event names with at least one hook configured. */\n    hooks?: string[]\n  }\n  /** CLAUDE.md (user memory) present in the config dir. */\n  hasUserMemory: boolean\n  /** Skill names (skills/<name>/). */\n  skills: string[]\n  /** Agent names (agents/<name>.md). */\n  agents: string[]\n  /** Custom slash-command names (commands/<name>.md). */\n  commands: string[]\n}\n\n// ---------------------------------------------------------------------------\n// REST shapes\n// ---------------------------------------------------------------------------\n\nexport type McpServerConfigWire =\n  | { type?: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }\n  | { type: 'http'; url: string; headers?: Record<string, string> }\n  | { type: 'sse'; url: string; headers?: Record<string, string> }\n\nexport type CreateSessionRequest = {\n  /** Directory the session is rooted at. Required: `cwd` is per-query in the SDK\n   * and the server re-pins it on every call. */\n  cwd: string\n  /** Profile (named Claude Code config dir) to run under. Required when the server\n   * declares more than one profile; implicit when exactly one exists. */\n  profile?: string\n  /** Optional initial prompt (may be a skill invocation like \"/verify-content 123\"). */\n  prompt?: string\n  permissionMode?: PermissionMode\n  /** Pre-authorize 'bypassPermissions' (the CLI's --dangerously-skip-permissions\n   * capability) so the mode can be switched on mid-session. Without it the CLI\n   * rejects `set_permission_mode: 'bypassPermissions'` on a running session.\n   * Implied when `permissionMode` is already 'bypassPermissions'. */\n  allowDangerouslySkipPermissions?: boolean\n  allowedTools?: string[]\n  disallowedTools?: string[]\n  mcpServers?: Record<string, McpServerConfigWire>\n  /** Which filesystem settings the session loads. Include 'project' to pick up the\n   * target repo's skills and CLAUDE.md (\"close-to-real\" fidelity). */\n  settingSources?: Array<'user' | 'project' | 'local'>\n  model?: string\n  maxTurns?: number\n  maxBudgetUsd?: number\n  /** Resume an existing SDK session by id. */\n  resume?: string\n  /** With `resume`: fork to a new session id instead of continuing. */\n  forkSession?: boolean\n  /** Emit `stream_delta` events for token-by-token rendering. Default true. */\n  includePartialMessages?: boolean\n  /** Per-session override of the server's permission-request timeout (ms). */\n  approvalTimeoutMs?: number\n  /** AskUserQuestion handling (see {@link QuestionBehavior}). Default 'ask'. */\n  questionBehavior?: QuestionBehavior\n  /** Provider engine only: run with fewer capabilities than the profile grants\n   * (see {@link ProfileSessionDefaults.capabilities}). Narrowing only — naming a\n   * capability the profile does not grant is a 400, not a silent upgrade. */\n  capabilities?: SessionCapability[]\n  /** Free-form metadata echoed back on SessionInfo (host app bookkeeping). */\n  meta?: Record<string, unknown>\n}\n\nexport type SessionInfo = {\n  /** Server-assigned id (stable across SDK session forks/resumes). */\n  id: string\n  /** Underlying Agent SDK session id, once known; use for `resume`. */\n  sdkSessionId?: string\n  status: SessionStatus\n  cwd: string\n  /** Profile the session runs under (resolved name, present even when implicit). */\n  profile?: string\n  /** Engine actually running this session, reported by the runner itself. Lets a\n   * session surface gate CLI-only affordances (permission modes, context usage,\n   * rate limits) without looking the profile back up. Absent = 'claude'. */\n  engine?: ProfileEngine\n  model?: string\n  permissionMode?: PermissionMode\n  /** See the `system_init` event; 'oauth' = claude.ai subscription credentials. */\n  apiKeySource?: string\n  createdAt: number\n  /** Highest event seq emitted so far; attach with `afterSeq` to catch up. */\n  lastSeq: number\n  pendingPermissionCount: number\n  meta?: Record<string, unknown>\n  /** Display title: `meta.title` if the host set one, else derived (e.g. first prompt). */\n  title?: string\n  /** Cumulative cost across all turns so far (sum of turn_result totals). */\n  totalCostUsd?: number\n  /** Cumulative turn count across the session. */\n  numTurns?: number\n  /** Epoch ms of the most recent emitted event. */\n  lastActivityAt?: number\n}\n\n/**\n * A session in the Agent SDK's on-disk store (independent of this server's registry).\n * Listed so hosts can offer \"resume\" across server restarts: feed `sessionId` to\n * CreateSessionRequest.resume. Mirrors the SDK's SDKSessionInfo, kept browser-safe.\n */\nexport type SdkSessionSummary = {\n  sessionId: string\n  /** Custom title, auto summary, or first prompt — whichever the SDK has. */\n  summary: string\n  /** Epoch ms of last modification. */\n  lastModified: number\n  createdAt?: number\n  customTitle?: string\n  firstPrompt?: string\n  gitBranch?: string\n  cwd?: string\n}\n\n/** One deliverable in the session's scratch filesystem (see the `file_delivered` event). */\nexport type SessionFileInfo = { path: string; bytes: number }\n/** `GET {basePath}/sessions/:id/files` — every file currently in the session's VFS.\n * `GET {basePath}/sessions/:id/files/<path>` downloads one (attachment disposition).\n * 404 when the session's engine exposes no VFS (Claude-engine sessions). */\nexport type ListSessionFilesResponse = { files: SessionFileInfo[] }\nexport type ListSessionsResponse = { sessions: SessionInfo[] }\nexport type CreateSessionResponse = { session: SessionInfo }\nexport type GetSessionResponse = { session: SessionInfo }\n\n/** Body of `POST {basePath}/sessions/:id/permissions/:requestId` — the REST counterpart\n * of the WS `permission_decision` command, for remote controllers without a socket\n * (e.g. answering a job's AskUserQuestion from a webhook consumer). 404 = the request\n * is unknown, already resolved, or expired. */\nexport type ResolvePermissionRequest =\n  | { behavior: 'allow'; updatedInput?: Record<string, unknown> }\n  | { behavior: 'deny'; message?: string; interrupt?: boolean }\nexport type ResolvePermissionResponse = { resolved: true }\n\n/**\n * Body of `POST {basePath}/executions/:executionId/result` — the way a deferred\n * executor (a remote worker, a batch job, a human) delivers the outcome of an\n * execution the session parked on. The session is rehydrated if its runner was\n * torn down, and the result is folded back into the agent loop; a `failed` result\n * is ordinary tool output the agent adapts to, not a session error.\n *\n * Applied **idempotently by `executionId`**: a duplicate or late delivery (one\n * racing the execution watchdog) answers 200 with `applied: false` rather than\n * erroring or applying twice. 404 means no session is parked on that id.\n */\nexport type SubmitExecutionResultRequest =\n  | { status: 'ok'; output: ToolExecutionOutput; logs?: string[] }\n  | { status: 'failed'; reason: string; error: string; logs?: string[] }\nexport type SubmitExecutionResultResponse = {\n  /** False when the id was already settled — the delivery was a no-op. */\n  applied: boolean\n  /** Session the execution belonged to. */\n  sessionId: string\n}\n\nexport type ListSdkSessionsResponse = { sdkSessions: SdkSessionSummary[] }\n/** `GET {basePath}/profiles` — filtered to the profiles the caller may use. */\nexport type ListProfilesResponse = {\n  profiles: ProfileInfo[]\n  /** Whether this caller may create profiles here — true only when the server has\n   * a profile store AND the principal carries `canManageProfiles`. Lets a UI hide\n   * controls that would always be refused. */\n  canManage?: boolean\n}\n\n/**\n * `POST {basePath}/profiles` — create a managed profile. Available only when the\n * server was given a profile store, and only to a principal with\n * `canManageProfiles`. Profiles declared in server options are code, not data:\n * they cannot be created, edited, or deleted through these routes.\n */\nexport type CreateProfileRequest = ProfileInfo\n\n/** `PATCH {basePath}/profiles/:name` — merge into a managed profile. The name is\n * the route, not the body; pass `null` to clear an optional field. */\nexport type UpdateProfileRequest = Omit<Partial<ProfileInfo>, 'name'>\n\nexport type SaveProfileResponse = { profile: ProfileInfo }\n/** `GET {basePath}/profiles/:name` — the profile plus a fresh config snapshot. */\nexport type GetProfileResponse = { profile: ProfileInfo; config: ProfileConfigSnapshot }\nexport type ErrorResponse = { error: string }\n\n// ---------------------------------------------------------------------------\n// Session notifications (the out-of-band \"something wants you\" channel)\n// ---------------------------------------------------------------------------\n\n/**\n * The moments in an *interactive* session a person needs to hear about when they\n * are not watching it — the whole point being that a phone cannot hold a\n * WebSocket open in the background, so the server has to reach out.\n *\n * Deliberately four: this is a human-attention channel, not an event mirror. The\n * event log stays on the session WS (attach with `afterSeq` to catch up); if you\n * want every assistant message, subscribe there instead.\n */\nexport type SessionNotificationType =\n  /** The agent is blocked on an approval — the one that matters most. */\n  | 'permission_requested'\n  /** A turn finished; the session is idle and waiting for the human. */\n  | 'turn_completed'\n  /** The session failed (`session_error`). */\n  | 'session_error'\n  /** The session ended (`session_closed`), whoever ended it. */\n  | 'session_closed'\n\n/** One delivery on the session-notification channel (JSON body of a webhook POST). */\nexport type SessionNotification = {\n  type: SessionNotificationType\n  sessionId: string\n  /** Snapshot at notification time — status, title, cwd, cost, `lastSeq`. */\n  session: SessionInfo\n  /** Seq of the event behind this notification; attach with `afterSeq: seq - 1` to\n   * land on it. */\n  seq: number\n  ts: number\n  /** One line fit for a notification body: the permission title, the turn's final\n   * text, the error message. */\n  preview?: string\n  /** `permission_requested` only: the full request, so a consumer can answer it via\n   * `POST {basePath}/sessions/:id/permissions/:requestId` — which is what makes an\n   * Approve/Deny action on a lock-screen notification possible. */\n  request?: PermissionRequest\n  /** `turn_completed` only. */\n  result?: { isError: boolean; durationMs: number; numTurns: number; totalCostUsd: number }\n  /** `session_closed` only. */\n  reason?: 'client' | 'server' | 'error'\n}\n\n/** Where session notifications are POSTed (JSON body = {@link SessionNotification}).\n * Server-wide, not per session: the point is to hear about sessions you did not\n * create yourself and are not attached to. */\nexport type SessionWebhookConfig = {\n  url: string\n  /** Extra headers sent with every delivery (auth tokens etc.). */\n  headers?: Record<string, string>\n  /** Types to deliver. Default: all of them. */\n  events?: SessionNotificationType[]\n}\n\n// ---------------------------------------------------------------------------\n// Job queue (one-shot scheduled runs over the session runner)\n// ---------------------------------------------------------------------------\n\n/**\n * - `queued` — accepted, waiting for a concurrency slot (or the daily token budget)\n * - `running` — a session is executing the prompt\n * - `parked` — waiting on an external event (a deferred tool execution). Not\n *   terminal and not consuming a concurrency slot; resumes to `running` when the\n *   result arrives, or fails via the execution watchdog if it never does.\n * - `succeeded` / `failed` — terminal; `result` (and `error` on failure) are set\n * - `canceled` — terminal; canceled by a client before or during the run\n */\nexport type JobStatus = 'queued' | 'running' | 'parked' | 'succeeded' | 'failed' | 'canceled'\n\n/** Where job progress/completion deliveries are POSTed (JSON body = {@link JobEvent}). */\nexport type WebhookConfig = {\n  url: string\n  /** Extra headers sent with every delivery (auth tokens etc.). */\n  headers?: Record<string, string>\n  /** Delivery granularity: 'messages' also POSTs job_progress per assistant message /\n   * permission request; 'completion' only job_started + job_completed. Default 'messages'. */\n  progress?: 'messages' | 'completion'\n}\n\n/**\n * Schedule a one-shot run: the session executes `prompt` unattended and the job\n * completes with that run's result. `session.prompt` is the task and is required;\n * `resume`/`forkSession` are not supported for queued jobs.\n */\nexport type CreateJobRequest = {\n  session: CreateSessionRequest & { prompt: string }\n  webhook?: WebhookConfig\n  /** Per-job token cap; the effective cap is min(this, the server's sessionTokenLimit). */\n  maxTokens?: number\n  /** Per-job wall-clock cap; the effective cap is min(this, the server's maxJobDurationMs). */\n  maxDurationMs?: number\n  /** Total run attempts: failed (not canceled) runs re-queue until this many attempts\n   * have been made. Default 1 (no retries). */\n  attempts?: number\n  /** Delay before the first retry, doubled for each subsequent one. Default 5000. */\n  retryDelayMs?: number\n  /** Host bookkeeping echoed back on JobInfo. */\n  meta?: Record<string, unknown>\n}\n\n/** Cumulative resource usage of a job's run. `tokens` counts input + output +\n * cache-creation + cache-read tokens across all turns. */\nexport type JobUsage = {\n  tokens: number\n  totalCostUsd: number\n  numTurns: number\n}\n\n/** Terminal outcome of the job's run (mirrors the final turn_result). */\nexport type JobResult = {\n  subtype: string\n  isError: boolean\n  /** Final text of the run (success only). */\n  result?: string\n  errors?: string[]\n  durationMs: number\n}\n\nexport type JobInfo = {\n  id: string\n  status: JobStatus\n  cwd: string\n  /** Profile the run executes under (resolved name, present even when implicit). */\n  profile?: string\n  prompt: string\n  /** Server session id once started — attach via the sessions WS to watch the run live. */\n  sessionId?: string\n  sdkSessionId?: string\n  createdAt: number\n  startedAt?: number\n  finishedAt?: number\n  /** 1-based run attempt this info reflects. */\n  attempt?: number\n  /** Total attempts configured on the request (see CreateJobRequest.attempts). */\n  maxAttempts?: number\n  /** For a job re-queued by retry backoff: earliest time the next attempt may start. */\n  nextRunAt?: number\n  /** Set while `status` is 'parked': when the run parked, and the execution it is\n   * waiting on — the id to POST a result to. Cleared when it resumes. */\n  parkedAt?: number\n  parkedExecutionId?: string\n  /** Cumulative across attempts. */\n  usage: JobUsage\n  result?: JobResult\n  /** Failure or cancellation reason (for a queued retry: the previous attempt's error). */\n  error?: string\n  meta?: Record<string, unknown>\n}\n\n/** Latest mid-run activity, carried on job_progress deliveries. */\nexport type JobProgress = {\n  kind: 'assistant_text' | 'tool_use' | 'permission_requested' | 'permission_resolved'\n  /** Short human-readable preview (message excerpt, tool name, permission title). */\n  preview?: string\n  /** 'permission_requested' only: the full request (including AskUserQuestion input) so\n   * webhook consumers can answer via POST /sessions/:sessionId/permissions/:requestId. */\n  request?: PermissionRequest\n}\n\n/** Webhook delivery payload (also the queue's local event shape). `job_submitted` goes\n * to local observers and the queue WS only — the submitter already has the POST\n * response, so webhooks start at `job_started`. `job_retrying` marks a failed run that\n * was re-queued (`job.nextRunAt` says when); `job_completed` is always terminal. */\nexport type JobEvent =\n  | { type: 'job_submitted'; job: JobInfo; ts: number }\n  | { type: 'job_started'; job: JobInfo; ts: number }\n  | { type: 'job_progress'; job: JobInfo; progress: JobProgress; ts: number }\n  /** The run parked on a deferred execution; `executionId` says what it waits on —\n   * the id to POST a result to. The *work itself* (tool name, input, VFS seed) went\n   * to the executor's own dispatch hook, not over this channel: a webhook consumer\n   * learns that a run is waiting, the worker learns what to do. */\n  | { type: 'job_parked'; job: JobInfo; executionId: string; ts: number }\n  /** A parked run resumed because its execution result arrived. */\n  | { type: 'job_resumed'; job: JobInfo; executionId: string; ts: number }\n  | { type: 'job_retrying'; job: JobInfo; ts: number }\n  | { type: 'job_completed'; job: JobInfo; ts: number }\n\nexport type QueueStats = {\n  maxConcurrency: number\n  running: number\n  queued: number\n  /** Jobs waiting on a deferred execution. They hold no concurrency slot and\n   * their wall-clock budget is not ticking. */\n  parked: number\n  sessionTokenLimit?: number\n  dailyTokenLimit?: number\n  /** Tokens consumed by queue jobs in the current UTC day. */\n  dailyTokensUsed: number\n  /** True when the daily budget is exhausted and queued jobs are being held. */\n  paused: boolean\n}\n\n/** Frames sent on the queue WS (`{basePath}/queue/ws`). The stream is one-way\n * (server→client): every job's lifecycle as it happens, plus refreshed stats after\n * lifecycle changes. Clients send nothing; job mutations stay on REST. */\nexport type QueueServerFrame =\n  | { type: 'queue_attached'; protocolVersion: number; stats: QueueStats }\n  | { type: 'job_event'; event: JobEvent }\n  | { type: 'queue_stats'; stats: QueueStats }\n\nexport type CreateJobResponse = { job: JobInfo }\nexport type GetJobResponse = { job: JobInfo }\nexport type ListJobsResponse = { jobs: JobInfo[] }\nexport type QueueStatsResponse = { stats: QueueStats }\n"],"mappings":";;;;;;;;;;;;AAYA,MAAa,mBAAmB;;;;;;AA4dhC,MAAa,4BAAuD;CAClE;CACA;CACA;CACD;;;;;;AAOD,SAAgB,uBACd,QACA,MACS;AACT,QAAO,WAAW,aAAa,0BAA0B,SAAS,KAAK,GAAG"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@workerdeck/protocol",
+  "version": "0.6.0",
+  "type": "module",
+  "description": "The WorkerDeck wire protocol: typed session events, commands, and REST shapes shared by server and clients. Dependency-free, browser-safe. This protocol is the product boundary — versioned from day one.",
+  "license": "MIT",
+  "main": "./build/index.mjs",
+  "types": "./build/index.d.mts",
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": {
+      "@workerdeck/source": "./src/index.ts",
+      "types": "./build/index.d.mts",
+      "default": "./build/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.21.10"
+  },
+  "author": "Tobias Strebitzer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/workerdeck/workerdeck.git",
+    "directory": "packages/protocol"
+  },
+  "homepage": "https://workerdeck.github.io/workerdeck/",
+  "bugs": "https://github.com/workerdeck/workerdeck/issues",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "agent",
+    "protocol",
+    "websocket",
+    "types"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "tsdown",
+    "typecheck": "tsgo -p tsconfig.json"
+  }
+}