@workerdeck/core 0.15.0 → 0.16.0

package/build/index.d.mts

@@ -1,10 +1,10 @@
-import { McpServerStatus, Options, Query, SDKMessage, SDKUserMessage, SessionMessage } from "@anthropic-ai/claude-agent-sdk";
+import { McpServerStatus, Options, Query, SDKMessage, SDKSessionInfo, SDKUserMessage, SessionMessage } from "@anthropic-ai/claude-agent-sdk";
 import { ApiMessage, CreateSessionRequest, EngineCapabilities, McpServerConfigWire, McpServerStatusInfo, MessageAttachment, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, ProfileInfo, SdkSessionSummary, SessionEvent, SessionEventBody, SessionInfo, SessionStatus, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput } from "@workerdeck/protocol";
 import { LanguageModel, LanguageModel as LanguageModel$1, ModelMessage, Tool, Tool as Tool$1, ToolSet, ToolSet as ToolSet$1 } from "ai";
 import { SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
 import { Readable, Writable } from "node:stream";
 
-//#region src/attachments.d.ts
+//#region src/lib/attachments.d.ts
 /**
  * An attachment plus its bytes — what the host hands a runner at send time.
  *
@@ -44,7 +44,7 @@ declare function attachmentContentBlocks(attachments: readonly AttachmentInput[]
 /** Strip the bytes: the log-safe half of an attachment. */
 declare function attachmentRef(attachment: AttachmentInput): MessageAttachment;
 //#endregion
-//#region src/tool-executor.d.ts
+//#region src/executors/tool-executor.d.ts
 /**
  * Result of one tool execution, whenever it arrives. `failed` is a normal
  * outcome the agent loop adapts to — not an exception.
@@ -175,8 +175,19 @@ interface Runner {
   /** Begin the session. Idempotent; returns the run promise (resolves when the run ends). */
   start(): Promise<void>;
   info(): SessionInfo;
-  /** Replay buffered events with seq > afterSeq, then deliver live events. Returns unsubscribe. */
-  subscribe(listener: SessionEventListener, afterSeq?: number): () => void;
+  /** Replay buffered events with seq > afterSeq, then deliver live events. Returns unsubscribe.
+   *
+   * `coalesceReplay` drops state readings superseded later in the same replay —
+   * the fifty stale context/rate-limit polls a long session accumulates, which
+   * a client otherwise applies one by one and *renders*, counting its usage
+   * meters up through the session's history on every attach. Opt-in, and the
+   * 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. */
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
+    coalesceReplay?: boolean;
+  }): () => void;
   /** 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}). */
@@ -221,7 +232,7 @@ interface Runner {
   close(reason?: 'client' | 'server' | 'error'): void;
 }
 //#endregion
-//#region src/runner.d.ts
+//#region src/engines/claude/runner.d.ts
 type QueryFn = (params: {
   prompt: AsyncIterable<SDKUserMessage>;
   options?: Options;
@@ -229,6 +240,9 @@ type QueryFn = (params: {
 type HistoryFn = (sdkSessionId: string, options: {
   dir?: string;
 }) => Promise<SessionMessage[]>;
+type SessionInfoFn = (sdkSessionId: string, options: {
+  dir?: string;
+}) => Promise<SDKSessionInfo | undefined>;
 type SessionRunnerConfig = CreateSessionRequest & {
   /** Injectable query implementation (tests, instrumentation). Defaults to the SDK's query(). */queryFn?: QueryFn; /** Environment for the spawned Claude Code process. Defaults to process.env. */
   env?: Record<string, string | undefined>;
@@ -239,6 +253,10 @@ type SessionRunnerConfig = CreateSessionRequest & {
    * starts, so late-attaching clients get a full transcript. Default true. */
   backfillHistory?: boolean; /** Injectable history reader (tests). Defaults to the SDK's getSessionMessages. */
   historyFn?: HistoryFn;
+  /** Injectable session-metadata reader (tests). Defaults to the SDK's
+   * getSessionInfo — the only place the CLI's own session title is readable
+   * from, since no message on the stream carries it. */
+  sessionInfoFn?: SessionInfoFn;
 };
 /**
  * One live Agent SDK session: owns the query() call, the streaming input queue, the
@@ -287,11 +305,22 @@ declare class SessionRunner implements Runner {
   /**
    * Replay buffered events with seq > afterSeq, then deliver live events.
    * Returns an unsubscribe function.
+   *
+   * Replay honours the reset watermark: transcript content below the latest
+   * `conversation_reset` is skipped (the reducer would clear it again anyway,
+   * and a pre-reset client that never learned the reducer's case would render
+   * a conversation the engine has discarded), while state-bearing events —
+   * which are emitted once and never again — always replay. The reset event
+   * itself replays (the skip is strictly-below), which is what clears a
+   * 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): () => void;
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
+    coalesceReplay?: boolean;
+  }): () => void;
 }
 //#endregion
-//#region src/ai-sdk-runner.d.ts
+//#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. */
 type AiSdkRunnerConfig = Omit<CreateSessionRequest, 'cwd'> & {
@@ -456,7 +485,9 @@ 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): () => void;
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
+    coalesceReplay?: boolean;
+  }): () => 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
@@ -477,7 +508,7 @@ declare class AiSdkRunner implements Runner {
   setTitle(title: string | undefined): void;
 }
 //#endregion
-//#region src/claude-auth.d.ts
+//#region src/engines/claude/auth.d.ts
 /**
  * Credential presence for one Claude Code environment, as the CLI itself reports
  * it. 'unknown' means the check could not run at all (no binary, a CLI too old
@@ -515,7 +546,7 @@ declare function checkClaudeAuth(env: Record<string, string | undefined>, option
   timeoutMs?: number;
 }): Promise<ClaudeAuthStatus>;
 //#endregion
-//#region src/quickjs-executor.d.ts
+//#region src/executors/quickjs-executor.d.ts
 /** Resolve a URL to text for the guest. Runs host-side with host authority —
  * this is where a credential may be attached, never inside the sandbox. */
 type HostFetch = (url: string, signal: AbortSignal) => Promise<string>;
@@ -548,7 +579,7 @@ declare class QuickJsExecutor implements ToolExecutor {
  * (not the bare parent). Only http(s) — no file:, data:, or other schemes. */
 declare function isHostAllowed(url: string, allowedHosts: string[]): boolean;
 //#endregion
-//#region src/pending-registry.d.ts
+//#region src/lib/pending-registry.d.ts
 /**
  * One registry for every request that leaves the runner and must come back:
  * permission approvals, browser-bridged tool calls, and deferred executions.
@@ -610,7 +641,7 @@ declare class PendingRequestRegistry {
   cancelAll(reason: string, error: string, kind?: PendingKind): number;
 }
 //#endregion
-//#region src/browser-bridge-executor.d.ts
+//#region src/executors/browser-bridge-executor.d.ts
 /** Answer a bridged call, as delivered by the client over the wire. */
 type BridgeAnswer = {
   output: ToolExecutionOutput;
@@ -664,7 +695,7 @@ declare class BrowserBridgeExecutor implements ToolExecutor {
 /** Map a registry outcome onto the executor's result contract. */
 declare function toExecutionResult(outcome: PendingOutcome<BridgeAnswer>): ToolExecutionResult;
 //#endregion
-//#region src/deferred-executor.d.ts
+//#region src/executors/deferred-executor.d.ts
 /** A dispatched execution, as handed to the backend that will run it. */
 type DeferredDispatch = {
   /** Correlation id. The result is delivered under it — `POST
@@ -714,7 +745,7 @@ declare class DeferredExecutor implements ToolExecutor {
   dispatch(call: ToolExecutionCall): Promise<ToolExecutionDispatch>;
 }
 //#endregion
-//#region src/web-fetch.d.ts
+//#region src/engines/provider/web-fetch.d.ts
 /**
  * `web_fetch` backend, close to Claude Code's original WebFetch: fetch a URL,
  * convert HTML to markdown, and (optionally) digest it with a model against the
@@ -760,7 +791,7 @@ declare function isPrivateAddress(address: string): boolean;
  */
 declare function htmlToMarkdown(html: string): string;
 //#endregion
-//#region src/tools.d.ts
+//#region src/engines/provider/tools.d.ts
 /**
  * How much authority a tool carries, which decides where it may run.
  *
@@ -863,7 +894,7 @@ declare function withHostTools(context: ToolContext, hostTools: Record<string, H
 
 kind?: string): ToolContext;
 //#endregion
-//#region src/engine.d.ts
+//#region src/engines/provider/session.d.ts
 type EngineSessionOptions = {
   /** Resolved session config (profile defaults already applied). */config: AiSdkRunnerConfig; /** The profile that selected this engine, when there was one. */
   profile?: ProfileInfo;
@@ -1014,7 +1045,7 @@ declare function connectMcpTools(servers: Record<string, McpServerConfigWire>, o
   required?: boolean;
 }): Promise<McpConnection>;
 //#endregion
-//#region src/input-queue.d.ts
+//#region src/lib/input-queue.d.ts
 /**
  * Push-based single-consumer AsyncIterable bridging imperative sendMessage() calls
  * into the streaming `prompt` the Agent SDK consumes.
@@ -1026,7 +1057,7 @@ declare class InputQueue implements AsyncIterable<SDKUserMessage> {
   [Symbol.asyncIterator](): AsyncIterator<SDKUserMessage>;
 }
 //#endregion
-//#region src/normalize.d.ts
+//#region src/lib/normalize.d.ts
 declare function toApiMessage(message: unknown): ApiMessage;
 /**
  * The CLI's MCP status, as `McpServerStatusInfo`.
@@ -1497,7 +1528,9 @@ 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): () => void;
+  subscribe(listener: SessionEventListener, afterSeq?: number, options?: {
+    coalesceReplay?: boolean;
+  }): () => void;
   /**
    * The session's MCP servers, live from the binary.
    *