@workerdeck/react 0.15.0 → 0.16.0

package/README.md

@@ -152,6 +152,16 @@ input by construction: fine for the user's own data, never a source of server-au
 - **The recap is counted, never written.** `summarizeSince` returns numbers because generating
   prose would spend a turn on a summary nobody asked for, and would be worst exactly where it
   matters most: a session that failed while unattended.
+- **Detached transcripts stay warm by default.** `useClaudeSession` keeps a bounded, module-scope
+  cache of the last few transcripts it held, so switching back to a session paints in the mount
+  frame and re-attaches with `afterSeq`, replaying only what it missed. Entries are keyed by the
+  client's `identityKey` — gateway base URL plus auth headers — never the session id alone (a
+  session id is unique only within one gateway), and a cached `afterSeq` pointed at a log the
+  server no longer has (a dormant rebuild, a restart) is detected off the attach frame
+  (`staleAttach`) and discarded with a full resync, because that attach would otherwise deliver
+  nothing and the stale rows would stand forever. Opt out with `cacheTranscript: false` if your
+  principal varies on one base URL by means the client cannot see, and call
+  `clearTranscriptCache()` on an in-place logout.
 
 ## License
 

package/build/index.d.mts

@@ -1,8 +1,8 @@
-import { ContextUsage, EngineCapabilities, HostDirEntry, HostFileMatch, MessageAttachment, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, RateLimitInfo, SessionEvent, SessionInfo, SessionStatus, SkillInfo, SlashCommandInfo, ToolExecutionBackend } from "@workerdeck/protocol";
+import { AttachedFrame, ContextUsage, EngineCapabilities, FilePatch, HostDirEntry, HostFileMatch, MessageAttachment, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, ProfileUsage, RateLimitInfo, SessionEvent, SessionInfo, SessionStatus, SkillInfo, SlashCommandInfo, ToolExecutionBackend, UsageWindowRow } from "@workerdeck/protocol";
 import { SessionHandle, WorkerDeckClient } from "@workerdeck/client";
 import { RunScriptResult, SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
 
-//#region src/transcript.d.ts
+//#region src/lib/transcript.d.ts
 /**
  * Pure transcript state machine over the wire-protocol event stream. Framework-free
  * so it can be unit-tested and reused outside React.
@@ -42,7 +42,17 @@ type TranscriptItem = {
   result?: {
     text: string;
     isError: boolean;
-  }; /** Correlation id when this call is executed outside the model loop. */
+  };
+  /**
+   * What this call changed on disk, when it was a file edit — the engine's
+   * own hunks and line numbers (see protocol's {@link FilePatch}).
+   *
+   * Only ever set from the wire. A client cannot derive it: it has never
+   * seen the file, so a diff it computed from the tool's *input* would have
+   * no line numbers, and one parsed out of the result prose would be welded
+   * to an engine's text formatting.
+   */
+  patch?: FilePatch; /** Correlation id when this call is executed outside the model loop. */
   executionId?: string; /** Which backend is executing it, when known. */
   backend?: ToolExecutionBackend; /** Logs captured by the executor (guest console output). */
   logs?: string[];
@@ -156,18 +166,15 @@ declare function seedFromSessionInfo(state: TranscriptState, info: SessionInfo):
  * The session's rate-limit windows in reading order: the session window, the
  * weekly window, then whichever per-model weekly windows it reports.
  *
- * Discovered rather than hardcoded — the SDK's set of windows is an open union
- * and has grown before — but ordered, so the first two always mean the same
- * thing. A window with no `utilization` is *unknown*, not zero, and is dropped
- * entirely rather than drawn as an empty bar that reads as "plenty left".
+ * The ordering and the drop-the-unknown rule are protocol's `orderUsageWindows`
+ * — the dashboard renders the same windows straight off `ProfileInfo.usage`,
+ * with no transcript anywhere near it, and two orderings would be one account
+ * described two ways. This stays as the transcript-shaped door to it.
  */
-declare function rateLimitWindows(state: TranscriptState): Array<{
-  key: string;
-  info: RateLimitInfo;
-}>;
+declare function rateLimitWindows(state: TranscriptState): UsageWindowRow[];
 declare function applyEvent(state: TranscriptState, event: SessionEvent): TranscriptState;
 //#endregion
-//#region src/use-session.d.ts
+//#region src/hooks/use-session.d.ts
 /**
  * How the client is doing at reaching the gateway — deliberately not the session's
  * status. The two are orthogonal, and while the socket is down the status a client
@@ -178,11 +185,88 @@ declare function applyEvent(state: TranscriptState, event: SessionEvent): Transc
  * been failing rather than a state the transport reports.
  */
 type ConnectionState = 'live' | 'reconnecting' | 'offline';
+/**
+ * The seq the initial attach replay ends on, or undefined when there is nothing
+ * to hold for.
+ *
+ * This is an exact signal, not a heuristic: the `attached` frame is sent before
+ * any replayed `event` frame and carries the runner's seq at attach time
+ * (`session.lastSeq`), so the moment the frame arrives the client knows
+ * precisely which seq the replay ends on. Every runner keeps its full event log
+ * and always delivers the highest-seq event on a fresh replay (the
+ * `conversation_reset` skip is strictly-below-the-reset, and the reset's seq is
+ * itself ≤ lastSeq), so `TranscriptState.lastSeq >= target` means the replay
+ * has landed. No quiet window or other arrival heuristic belongs here.
+ *
+ * Only a FRESH attach yields a target (`replayingFrom === 0`): a reconnect
+ * replays into a transcript the reader is already looking at, and blanking it
+ * mid-turn would be a worse bug than the flicker the hold exists to fix. A
+ * brand-new session (`lastSeq === 0`) has nothing to replay and never holds.
+ */
+declare function initialReplayTarget(frame: AttachedFrame): number | undefined;
+/**
+ * Whether an attach frame describes a DIFFERENT event log than the transcript
+ * `held` was built from — in which case attaching with `afterSeq: held.lastSeq`
+ * has already gone wrong: every event in the new log has seq ≤ afterSeq, so
+ * nothing will ever arrive and the stale rows would stand forever, with no
+ * error. The only recovery is to forget the state and re-attach from seq 0.
+ *
+ * A log resets on routine paths, not corner cases: a dormant session
+ * (claude/codex surviving a gateway restart) is rebuilt with a brand-new
+ * runner whose log starts at 0 and refills from the engine's own store. Two
+ * checks, each of which the other misses:
+ *
+ * - `session.lastSeq < held.lastSeq` — the server's log is shorter than what
+ *   we hold. Within one log seq only grows, so this is proof of a reset. It
+ *   catches a rebuilt runner that has not yet re-run far — but not one whose
+ *   backfill already advanced past us.
+ * - `session.createdAt !== held.session.createdAt` — a different runner
+ *   incarnation. The claude and codex runners stamp `Date.now()` at
+ *   construction, so a dormant rebuild always changes it; the provider runner
+ *   restores `createdAt` from its snapshot precisely when it also restores
+ *   the event log and seq counter (ai-sdk-runner's `#restore`), so equality
+ *   truthfully means "same log" for every engine.
+ *
+ * A full replay (`replayingFrom === 0`) is never stale — it carries the whole
+ * log, so the caller heals by resetting state and applying it — and holding
+ * nothing (`held.lastSeq === 0`) has nothing to be stale about. That first
+ * clause is also what makes the recovery loop-proof: the re-attach from 0 can
+ * never re-trigger this predicate.
+ *
+ * Not cache-specific: a live handle reconnecting after a gateway restart
+ * re-attaches with its own advanced `afterSeq` against the rebuilt log and
+ * hits the identical silence, so the hook applies this to every attach frame.
+ */
+declare function staleAttach(frame: AttachedFrame, held: TranscriptState): boolean;
+/**
+ * Backstop for the replay hold: if the target seq has not landed after this
+ * long, reveal what has arrived. On a healthy attach the target is always
+ * reached (see {@link initialReplayTarget}); the backstop exists because a
+ * blank panel forever would be a much worse failure than a visible stream, so
+ * the hold is bounded no matter what a future filter or a lossy path does. It
+ * runs from the attach — a per-event re-arm would be a quiet-window heuristic
+ * in a new costume.
+ */
+declare const REPLAY_HOLD_MAX_MS = 1500;
 type UseClaudeSessionOptions = {
   /** Called when the server rejects a command with a protocol_error frame — e.g. a
    * permission-mode switch the CLI refuses. Without a handler these are dropped
    * silently and the UI looks like "nothing happened". */
   onProtocolError?: (message: string) => void;
+  /**
+   * Keep this session's transcript warm after unmount (default true): the next
+   * mount of the same (client identity, session) paints the cached rows in its
+   * first frame and attaches with `afterSeq`, replaying only what it missed.
+   * Bounded module-scope LRU, keyed by the client's `identityKey` (gateway +
+   * auth headers) so nothing crosses gateways or credentials; if the attach
+   * frame shows a different event log (see {@link staleAttach}), the entry is
+   * discarded and the hook re-attaches from seq 0.
+   *
+   * Set `false` for an embedder whose principal varies on one base URL by
+   * means the client cannot see (a custom `fetchImpl` switching users, say) —
+   * or call `clearTranscriptCache()` on logout. Read at attach time.
+   */
+  cacheTranscript?: boolean;
 };
 type UseClaudeSessionResult = {
   state: TranscriptState;
@@ -190,6 +274,16 @@ type UseClaudeSessionResult = {
    * carries the same fact with the "has it been failing a while" distinction. */
   connected: boolean;
   connection: ConnectionState;
+  /**
+   * True while the initial attach replay is still landing: the `attached` frame
+   * said events up to `session.lastSeq` follow, and they have not all been
+   * applied yet. A surface can hold its paint on this — keep the rows mounted
+   * and measuring, show nothing — and reveal a settled transcript in one frame,
+   * instead of streaming hundreds of replayed rows past the reader. Always
+   * false on a reconnect (only a fresh attach holds; see
+   * {@link initialReplayTarget}) and bounded by {@link REPLAY_HOLD_MAX_MS}.
+   */
+  replaying: boolean;
   /** The server's `PROTOCOL_VERSION` when it disagrees with the one this build
    * mirrors — undefined when they match. Some events may not render. */
   protocolMismatch?: number;
@@ -223,7 +317,15 @@ type UseClaudeSessionResult = {
 /** Attach to a session and maintain live transcript state. Detaches on unmount. */
 declare function useClaudeSession(client: WorkerDeckClient, sessionId: string | undefined, options?: UseClaudeSessionOptions): UseClaudeSessionResult;
 //#endregion
-//#region src/use-attachments.d.ts
+//#region src/lib/transcript-cache.d.ts
+/**
+ * Drop every cached transcript. For an embedder changing principals in place
+ * (a logout that keeps the page alive) — entries are unreachable through the
+ * new principal's client either way, but scrubbing them is free and final.
+ */
+declare function clearTranscriptCache(): void;
+//#endregion
+//#region src/hooks/use-attachments.d.ts
 /**
  * Files staged for the next message.
  *
@@ -288,7 +390,7 @@ declare function useAttachments(client: WorkerDeckClient, sessionId: string | un
   engine
 }: UseAttachmentsOptions): UseAttachmentsResult;
 //#endregion
-//#region src/prompt-tokens.d.ts
+//#region src/lib/prompt-tokens.d.ts
 /**
  * The two prompt tokens the CLI understands — `@file` and `/command` — found in
  * text that has already been sent.
@@ -317,7 +419,7 @@ type PromptToken = {
  */
 declare function scanPromptTokens(text: string): PromptToken[];
 //#endregion
-//#region src/host-tree.d.ts
+//#region src/lib/host-tree.d.ts
 /**
  * One directory as the tree knows it: what `/fs/list` answered, plus whether the
  * server held entries back.
@@ -365,7 +467,7 @@ declare function flattenHostTree(root: string, dirs: ReadonlyMap<string, HostDir
  */
 declare function ancestorsWithin(root: string, path: string): string[];
 //#endregion
-//#region src/use-host-files.d.ts
+//#region src/hooks/use-host-files.d.ts
 type UseHostFileSearchResult = {
   /**
    * Whether `@file` completion is on offer at all: the session's cwd is known
@@ -453,7 +555,41 @@ type UseHostFileTreeResult = {
  */
 declare function useHostFileTree(client: WorkerDeckClient, cwd: string | undefined): UseHostFileTreeResult;
 //#endregion
-//#region src/use-session-info.d.ts
+//#region src/hooks/use-profile-usage.d.ts
+type UseProfileUsageOptions = {
+  /** How often to re-ask while enabled. Default 60s. */intervalMs?: number;
+  /** Set false to hold the poll — a panel that is off screen has nothing to
+   * refresh. Default true. */
+  enabled?: boolean;
+};
+type UseProfileUsageResult = {
+  /** The gateway's plan-usage state for this profile, or undefined when there
+   * is none to have: no profile, an older gateway, or nothing reported yet.
+   * Absent is **unknown, never 0%** — see `ProfileUsageWindow`. */
+  usage: ProfileUsage | undefined; /** Ask again now. */
+  refresh: () => void;
+};
+/**
+ * The gateway's per-profile plan usage, over REST.
+ *
+ * The session's own event stream carries a `rate_limit` reading only when the
+ * engine volunteers one — for claude that is at a turn's edges and nowhere else,
+ * so a session idle since yesterday replays yesterday's number, and a session
+ * opened today knows nothing of what a sibling on the same account spent an hour
+ * ago. `GET /profiles` answers the account-wide question, which is why this is a
+ * poll and not a subscription: nothing pushes it.
+ *
+ * Polling and not attaching, deliberately — a second WebSocket per surface is
+ * exactly what the bridge's "asks the first attached client" rule forbids, and
+ * this is one small GET a minute.
+ *
+ * Self-disabling on a 404, like {@link useHostFileSearch}: a gateway without the
+ * route will never grow one mid-session, so stop asking rather than log a miss
+ * every minute.
+ */
+declare function useProfileUsage(client: WorkerDeckClient, profile: string | undefined, options?: UseProfileUsageOptions): UseProfileUsageResult;
+//#endregion
+//#region src/hooks/use-session-info.d.ts
 type UseSessionInfoResult = {
   info: SessionInfo | undefined; /** True until the first answer — distinguishes "still asking" from "no such session". */
   loading: boolean; /** Set when the gateway refused; `info` stays undefined. */
@@ -473,7 +609,7 @@ type UseSessionInfoResult = {
  */
 declare function useSessionInfo(client: WorkerDeckClient, sessionId: string | undefined): UseSessionInfoResult;
 //#endregion
-//#region src/open-files.d.ts
+//#region src/lib/open-files.d.ts
 /**
  * One open file, in whatever state its read got to.
  *
@@ -610,7 +746,7 @@ declare const initialOpenFilesState: OpenFilesState;
  */
 declare function openFilesReducer(state: OpenFilesState, action: OpenFilesAction): OpenFilesState;
 //#endregion
-//#region src/use-open-files.d.ts
+//#region src/hooks/use-open-files.d.ts
 type UseOpenFilesResult = OpenFilesState & {
   /** The focused file, resolved — what the editor renders. */active: OpenFile | undefined; /** Any tab with unsaved edits — what a close or unload guard asks. */
   hasUnsaved: boolean; /** Open a path, or focus it if it is already open. */
@@ -645,7 +781,7 @@ type UseOpenFilesResult = OpenFilesState & {
  */
 declare function useOpenFiles(client: WorkerDeckClient): UseOpenFilesResult;
 //#endregion
-//#region src/tool-host.d.ts
+//#region src/lib/tool-host.d.ts
 /** What the host was asked to do and how it went (for UI/telemetry). */
 type ToolHostExecution = {
   executionId: string;
@@ -698,7 +834,7 @@ declare function createToolCallHost(handle: SessionHandle, options?: ToolCallHos
   dispose: () => void;
 };
 //#endregion
-//#region src/use-tool-host.d.ts
+//#region src/hooks/use-tool-host.d.ts
 type UseToolCallHostOptions = ToolCallHostOptions & {
   /** Turn the host off without unmounting. Default true. */enabled?: boolean; /** How many recent executions to keep for rendering. Default 50. */
   historyLimit?: number;
@@ -712,7 +848,7 @@ declare function useToolCallHost(handle: SessionHandle | undefined, options?: Us
   executions: ToolHostExecution[];
 };
 //#endregion
-//#region src/recap.d.ts
+//#region src/lib/recap.d.ts
 /**
  * "What happened while you were away", counted rather than written.
  *
@@ -764,5 +900,5 @@ declare function summarizeSince(state: RecapInput, fromIndex: number): RecapSumm
  */
 declare function recapLine(summary: RecapSummary): string | undefined;
 //#endregion
-export { type AttachmentKind, type ConnectionState, type HostDirState, type HostTreeRow, type OpenFile, type OpenFilesAction, type OpenFilesState, type ProducedFileRef, type PromptToken, type RecapInput, type RecapSummary, type StagedAttachment, type ToolCallHostOptions, type ToolHostExecution, type ToolHostRunner, type TranscriptItem, type TranscriptState, type UseAttachmentsOptions, type UseAttachmentsResult, type UseClaudeSessionOptions, type UseClaudeSessionResult, type UseHostFileRootsResult, type UseHostFileSearchResult, type UseHostFileTreeResult, type UseOpenFilesResult, type UseSessionInfoResult, type UseToolCallHostOptions, ancestorsWithin, applyEvent, attachmentKind, createToolCallHost, currentText, flattenHostTree, initialOpenFilesState, initialTranscriptState, isDirty, openFilesReducer, rateLimitWindows, recapLine, scanPromptTokens, seedFromSessionInfo, summarizeSince, useAttachments, useClaudeSession, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useSessionInfo, useToolCallHost };
+export { type AttachmentKind, type ConnectionState, type HostDirState, type HostTreeRow, type OpenFile, type OpenFilesAction, type OpenFilesState, type ProducedFileRef, type PromptToken, REPLAY_HOLD_MAX_MS, type RecapInput, type RecapSummary, type StagedAttachment, type ToolCallHostOptions, type ToolHostExecution, type ToolHostRunner, type TranscriptItem, type TranscriptState, type UseAttachmentsOptions, type UseAttachmentsResult, type UseClaudeSessionOptions, type UseClaudeSessionResult, type UseHostFileRootsResult, type UseHostFileSearchResult, type UseHostFileTreeResult, type UseOpenFilesResult, type UseProfileUsageOptions, type UseProfileUsageResult, type UseSessionInfoResult, type UseToolCallHostOptions, ancestorsWithin, applyEvent, attachmentKind, clearTranscriptCache, createToolCallHost, currentText, flattenHostTree, initialOpenFilesState, initialReplayTarget, initialTranscriptState, isDirty, openFilesReducer, rateLimitWindows, recapLine, scanPromptTokens, seedFromSessionInfo, staleAttach, summarizeSince, useAttachments, useClaudeSession, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useProfileUsage, useSessionInfo, useToolCallHost };
 //# sourceMappingURL=index.d.mts.map