@workerdeck/core 0.16.0 → 0.17.0

package/README.md

@@ -165,10 +165,32 @@ selectExecutor: () => new DeferredExecutor({
 for you — a `SessionStore` plus `POST /executions/:id/result` — but the mechanism is here, and works
 with no server at all.
 
+`snapshot()` is the same value **without** the teardown: the runner stays live, attached and warm.
+That separation is what makes a provider session survive a process restart, since it has no
+engine-side store to resume from the way claude and codex do — the host writes the snapshot through
+after each turn and rebuilds from the last one. The gate differs from `park()`'s in one direction
+only: it refuses a turn in flight and pending *in-process* executions (whose results die with the
+process), and allows the idle case `park()` exists to refuse.
+
 ## Rules you cannot infer from the types
 
 Things the compiler will not tell you, each of which has cost someone real time:
 
+- **Truncation happens on the replay path, never at emit.** `subscribe(..., { truncateResults })`
+  hands out a copy; `#events` keeps the whole result, because the live path, the parking snapshot
+  and `Runner.eventAt` (which serves `GET /sessions/:id/events/:seq/result`) all read it. Refuse
+  the temptation to truncate into a snapshot: it would break the fetch for exactly the sessions
+  most likely to be read late.
+
+- **Image refs happen there too — and on the live path as well.** `subscribe(..., { imageRefs })`
+  replaces a `tool_result`'s base64 `image` parts with `image_ref` addresses, and unlike truncation
+  it applies to live events as well as the replay, because a client's one render path is
+  ref-then-fetch. The same "never at emit" rule holds for the same reason: `#events` keeps every
+  byte, which is what the fetch route serves back. `SubscriberSet` (`src/lib/subscribers.ts`) is
+  where that per-subscriber decision lives — a subscriber is a listener *plus what it asked for*,
+  so the three runners no longer each own a copy of the answer. Consumers that subscribe with no
+  options — parking, notifications, the queue — see everything, as they do for every rule here.
+
 - **A declared MCP server that never connected is refused, not degraded.** If a profile's
   `session.mcpServers` names a server and it isn't there, `createEngineSession` throws. The old
   behaviour — start anyway, minus those tools — produced a session that reported perfectly healthy

package/build/index.d.mts

@@ -184,10 +184,45 @@ interface Runner {
    * default must stay off: it is only sound for a consumer whose handling of
    * those events is last-write-wins, and `parking.ts` — which subscribes from
    * seq 0 — branches on `status_changed` instead. Live events are never
-   * affected; this touches the buffered replay alone. */
+   * affected; this touches the buffered replay alone.
+   *
+   * `truncateResults` delivers an oversized `tool_result` block as its head plus
+   * the markers that say so (protocol's {@link TOOL_RESULT_HEAD_CHARS}), leaving
+   * the whole thing one fetch away. Measured, that is 68% of a long session's
+   * attach in three frames. Opt-in for the same reason and with one extra
+   * condition: **the opt-in must be issued by the unit that renders**, because
+   * `client` and `react` are separate packages an embedder can skew, and a
+   * client that asked for heads without knowing how to fetch the rest would show
+   * one as though it were the whole result. Live events are untouched — a result
+   * arriving while you watch is already on screen — and so is the stored log,
+   * which parking snapshots and the fetch route both read.
+   *
+   * `imageRefs` replaces a `tool_result`'s base64 image parts with `image_ref`
+   * addresses (protocol's {@link ImageRefPart}), their bytes one REST fetch
+   * away. Opt-in under the same rule — issued by the unit that renders — but
+   * unlike the other two it applies to **live events as well as the replay**,
+   * because the client's one render path is ref-then-fetch and bytes on a live
+   * event would only be discarded or pinned. Measured, this is 91% of all
+   * tool-result payload and 0% of what any client draws. The stored log keeps
+   * every byte, which is what the fetch route serves back. */
   subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
     coalesceReplay?: boolean;
+    truncateResults?: boolean;
+    imageRefs?: boolean;
   }): () => void;
+  /** One buffered event by seq, or undefined — the read side of the log the
+   * replay already walks.
+   *
+   * Optional, like every member added after `Runner` became public API: an
+   * out-of-tree runner that declines it declines only the on-demand tool result
+   * with it (the route 404s), which is exactly the degradation a runner with no
+   * `truncateResults` support wants anyway.
+   *
+   * Deliberately **not** a "give me the whole log" accessor. The one caller
+   * needs a single event by a seq a client is holding, and a method that handed
+   * out the array would invite a second copy of the bytes this feature exists
+   * to stop shipping. */
+  eventAt?(seq: number): SessionEvent | undefined;
   /** Queue a user message for the session (starts the next turn when idle).
    * `attachments` carry their bytes to the engine and their reference to the
    * event log (see {@link AttachmentInput}). */
@@ -226,12 +261,39 @@ interface Runner {
    * doesn't: the CLI owns its own process state).
    */
   park?(): RunnerSnapshot | undefined;
+  /**
+   * The same snapshot, taken **without ending anything** — the runner stays live,
+   * attached and warm.
+   *
+   * Park and snapshot are two operations that happen to produce the same value,
+   * and separating them is what makes restart-survival possible for an engine
+   * that has no on-disk session of its own. A park is for a session with nothing
+   * to do for possibly days; this is for one whose user is mid-conversation and
+   * whose process might be redeployed out from under it. The host writes it
+   * through after each turn — never on a shutdown hook, because a `kill -9` runs
+   * no hook and that is precisely the case worth surviving — and rebuilds from
+   * the last write through the ordinary `restore` path.
+   *
+   * Returns undefined when a snapshot would capture a half-happened turn: one in
+   * flight, or pending in-process executions whose results die with the process.
+   * Optional for the same reason `park()` is — claude and codex run behind a
+   * binary that owns its process state, and have engine-side resume instead.
+   */
+  snapshot?(): RunnerSnapshot | undefined;
   /** Emit a session_error and terminate. For host-enforced policy (e.g. requireApiKey). */
   fail(message: string): void;
   /** Terminate the session and any underlying engine process. */
   close(reason?: 'client' | 'server' | 'error'): void;
 }
 //#endregion
+//#region src/lib/subscribers.d.ts
+/** What a subscriber asked for. Absent fields mean the untransformed stream. */
+type SubscribeOptions = {
+  coalesceReplay?: boolean;
+  truncateResults?: boolean;
+  imageRefs?: boolean;
+};
+//#endregion
 //#region src/engines/claude/runner.d.ts
 type QueryFn = (params: {
   prompt: AsyncIterable<SDKUserMessage>;
@@ -302,6 +364,10 @@ declare class SessionRunner implements Runner {
   fail(message: string): void;
   /** Terminate the session and the underlying CLI subprocess. */
   close(reason?: 'client' | 'server' | 'error'): void;
+  /** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
+   * "show everything" on one row, so a per-runner seq index would be a map
+   * maintained on every emit to save a walk nobody makes twice a minute. */
+  eventAt(seq: number): SessionEvent | undefined;
   /**
    * Replay buffered events with seq > afterSeq, then deliver live events.
    * Returns an unsubscribe function.
@@ -315,11 +381,64 @@ declare class SessionRunner implements Runner {
    * reconnecting client still holding pre-reset rows; superseded resets are
    * content below the newer one and are skipped with what they cleared.
    */
-  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
-    coalesceReplay?: boolean;
-  }): () => void;
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: SubscribeOptions): () => void;
 }
 //#endregion
+//#region src/lib/replay.d.ts
+/**
+ * The one replay body, and what a socket receives from it.
+ *
+ * Every runner had a byte-identical copy of this loop — three spellings of four
+ * rules, one of which ("never drop the highest-seq event, whatever the rule
+ * says") is load-bearing and was three copies of a comment. Not a base class:
+ * the runners share nothing else, and a base class would have to own `#emit`,
+ * the most engine-specific method each of them has.
+ *
+ * The rules, in the order they are applied:
+ *
+ * 1. `afterSeq` — the caller already holds everything at or below it.
+ * 2. `resetSeq` — transcript *content* strictly below the latest
+ *    `conversation_reset` is skipped, so a re-attach cannot resurrect a cleared
+ *    conversation while state events still replay. Claude's alone; the other
+ *    engines pass 0.
+ * 3. `coalesceReplay` — last-write-wins state readings superseded later in the
+ *    same replay (`staleReplaySeqs`), plus everything `replayRetains` says the
+ *    reducer reads and discards. Opt-in, and only sound for a consumer whose
+ *    handling of those events is last-write-wins.
+ * 4. `imageRefs` — a base64 image part is delivered as an `image_ref` address
+ *    (protocol's {@link imagePartRef}), its bytes one REST fetch away. Applied
+ *    **before** rule 5, because it stamps indices from the stored part array
+ *    which rule 5 then reshapes. Unlike rule 5 this also applies to the live
+ *    path (see `SubscriberSet`), which is the one place these two rules differ.
+ * 5. `truncateResults` — a huge `tool_result` block is delivered as its head
+ *    plus the markers that say so. **Never mutates the stored event**: the live
+ *    path, the parking snapshot and the fetch route all need the whole thing,
+ *    so this builds a copy and the log stays the log.
+ *
+ * The highest-seq event is delivered whatever rules 2 and 3 say — a client's
+ * replay hold waits for `state.lastSeq` to reach the attach's and would
+ * otherwise hang forever — but it is still *truncated* when rule 4 applies. A
+ * session that ends on a `find /` puts its 641 KB frame exactly there.
+ */
+declare function replaySlice(events: readonly SessionEvent[], options: {
+  afterSeq: number;
+  resetSeq?: number;
+  coalesceReplay?: boolean;
+  truncateResults?: boolean;
+  imageRefs?: boolean;
+}): SessionEvent[];
+/**
+ * A copy of `event` whose oversized `tool_result` blocks carry their head and
+ * say so — or `event` itself, unchanged and un-copied, when nothing is over the
+ * budget. That identity matters: an attach is mostly small events, and a fresh
+ * object for every one of them would cost more than the feature saves.
+ *
+ * Blocks are measured and cut **individually**. A message answering three calls
+ * where one is a `find /` keeps the two small results whole, which is what makes
+ * the per-block marker (rather than a per-event one) honest.
+ */
+declare function truncateResultBlocks(event: SessionEvent): SessionEvent;
+//#endregion
 //#region src/engines/provider/runner.d.ts
 /** `cwd` is optional for this engine: the loop has no host-filesystem coupling
  * (tools get scoped VFS handles instead). Defaults to process.cwd() for display. */
@@ -457,6 +576,34 @@ declare class AiSdkRunner implements Runner {
    * or an already-closed/parked runner.
    */
   park(): RunnerSnapshot | undefined;
+  /**
+   * The same snapshot, taken without ending anything.
+   *
+   * `park()` and this are two operations that happen to produce the same value,
+   * and the difference is the whole point: `park()` *ends* the live runner
+   * (inert, listeners dropped, `onClose` called), which is right for deferred
+   * execution — the session has nothing to do for possibly days — and wrong for
+   * restart-survival, where the session is active and someone is mid-
+   * conversation. This one changes nothing at all: no status emit, no listener
+   * clear, no disposer. The host writes the value through to durable storage
+   * after each turn and keeps the runner live and warm, so a restart rebuilds
+   * from the last write through the existing `restore` path and the next message
+   * costs no wake.
+   *
+   * The gate is `park()`'s minus the requirement that there be something parked:
+   *
+   * - `#abort` set is refused for the reason it always was — a `generate()` in
+   *   flight has produced messages that are not in the history yet, so the
+   *   snapshot would be of a turn that half-happened.
+   * - Pending calls that are **not** all deferred are refused, which is
+   *   `park()`'s rule wearing a different hat. An in-process execution's result
+   *   is coming back to *this* runner and dies with the process; a restore would
+   *   wait on it forever, and `state.dispatched` is what would stop the rebuilt
+   *   runner from simply calling it again.
+   * - Idle with nothing pending — the case `park()` exists to refuse — is
+   *   exactly the case this exists to allow.
+   */
+  snapshot(): RunnerSnapshot | undefined;
   sendMessage(text: string, attachments?: readonly AttachmentInput[]): void;
   /**
    * Deliver the result of an external (execute-less) tool call. Appends the
@@ -485,9 +632,11 @@ declare class AiSdkRunner implements Runner {
   setModel(model?: string): Promise<void>;
   fail(message: string): void;
   close(reason?: 'client' | 'server' | 'error'): void;
-  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
-    coalesceReplay?: boolean;
-  }): () => void;
+  /** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
+   * "show everything" on one row, so a per-runner seq index would be a map
+   * maintained on every emit to save a walk nobody makes twice a minute. */
+  eventAt(seq: number): SessionEvent | undefined;
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: SubscribeOptions): () => void;
   /**
    * Deliver the result of an execution this runner dispatched. Used by the host
    * when a backend settled out-of-band (a browser bridge answering later, a
@@ -1528,9 +1677,11 @@ declare class CodexRunner implements Runner {
   setModel(model?: string): Promise<void>;
   fail(message: string): void;
   close(reason?: 'client' | 'server' | 'error'): void;
-  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
-    coalesceReplay?: boolean;
-  }): () => void;
+  /** See `Runner.eventAt`. A linear scan: the one caller is a reader pressing
+   * "show everything" on one row, so a per-runner seq index would be a map
+   * maintained on every emit to save a walk nobody makes twice a minute. */
+  eventAt(seq: number): SessionEvent | undefined;
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: SubscribeOptions): () => void;
   /**
    * The session's MCP servers, live from the binary.
    *
@@ -1625,5 +1776,5 @@ declare class JsonRpcStdioConnection {
  */
 declare const providerAdapter: EngineAdapter;
 //#endregion
-export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type AppServerConnectFn, type AppServerConnectOptions, type AppServerConnection, type AppServerHistoryTurn, type AppServerItem, type AppServerThreadListResponse, type AppServerThreadSummary, type AppServerTokenUsage, type AppServerTurn, type AppServerUserInput, type AttachmentInput, type AttachmentKind, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, CLAUDE_CATALOG, CODEX_CATALOG, type ClaudeAuthProbe, type ClaudeAuthStatus, CodexRunner, type CodexRunnerConfig, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineAdapter, type EngineAvailability, type EngineRunnerRequest, type EngineSessionOptions, type HistoryFn, type HostFetch, type HostToolDefinition, InputQueue, JsonRpcError, JsonRpcStdioConnection, type LanguageModel, type McpConnection, type ModelCatalog, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, SUPPORTED_ATTACHMENT_TYPES, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type Tool, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolSet, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, withHostTools, withMcpTools };
+export { AiSdkRunner, type AiSdkRunnerConfig, type AiSdkSessionState, type AppServerConnectFn, type AppServerConnectOptions, type AppServerConnection, type AppServerHistoryTurn, type AppServerItem, type AppServerThreadListResponse, type AppServerThreadSummary, type AppServerTokenUsage, type AppServerTurn, type AppServerUserInput, type AttachmentInput, type AttachmentKind, type BridgeAnswer, BrowserBridgeExecutor, type BrowserBridgeExecutorOptions, CLAUDE_CATALOG, CODEX_CATALOG, type ClaudeAuthProbe, type ClaudeAuthStatus, CodexRunner, type CodexRunnerConfig, type DeferredDispatch, DeferredExecutor, type DeferredExecutorOptions, type EngineAdapter, type EngineAvailability, type EngineRunnerRequest, type EngineSessionOptions, type HistoryFn, type HostFetch, type HostToolDefinition, InputQueue, JsonRpcError, JsonRpcStdioConnection, type LanguageModel, type McpConnection, type ModelCatalog, type ParkedExecution, type PendingEntry, type PendingKind, type PendingOutcome, PendingRequestRegistry, type PendingToolCall, type PermissionDecision, type QueryFn, QuickJsExecutor, type QuickJsExecutorOptions, type RegisterOptions, type Runner, type RunnerSnapshot, SUPPORTED_ATTACHMENT_TYPES, type SessionEventListener, SessionRunner, type SessionRunnerConfig, type SettledBy, type Tool, type ToolCallOutput, type ToolContext, type ToolContextOptions, type ToolDefinition, type ToolExecutionCall, type ToolExecutionDispatch, type ToolExecutionResult, type ToolExecutor, type ToolSet, type ToolTrust, type WebFetchDigest, type WebFetchFn, type WebFetchOptions, type WebFetchResult, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, replaySlice, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, truncateResultBlocks, withHostTools, withMcpTools };
 //# sourceMappingURL=index.d.mts.map