@workerdeck/react 0.15.0 → 0.17.0

package/build/index.mjs

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
-import { ENGINE_CAPABILITIES, PROTOCOL_VERSION } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, mergeUsage, orderUsageWindows } from "@workerdeck/protocol";
 import { WorkerDeckError } from "@workerdeck/client";
-//#region src/transcript.ts
+//#region src/lib/transcript.ts
 const initialTranscriptState = {
 	status: "starting",
 	capabilities: ENGINE_CAPABILITIES.claude,
@@ -10,13 +10,48 @@ const initialTranscriptState = {
 	totalCostUsd: 0,
 	lastSeq: 0
 };
+/**
+* The in-flight streamed text and thought — a singleton **per agent**, not per
+* session.
+*
+* It was one id for the whole stream, which was right while one thread streamed
+* at a time. It is not: with subagent text forwarded, a `Task` and the thread
+* that spawned it stream *concurrently*, and three parallel Tasks stream three
+* ways at once. Under one id every one of those deltas accumulates into the same
+* item — a row welding several agents' half-sentences together — and the first
+* `assistant_message` to land wipes all of them, including the ones still being
+* written.
+*
+* So the id carries the agent: `streaming` for the main thread (unchanged, so
+* nothing that keys off it moves) and `streaming:<parentToolUseId>` inside a
+* subagent.
+*/
 const STREAMING_ID = "streaming";
 const STREAMING_THINKING_ID = "streaming-thinking";
+const streamingTextId = (parentToolUseId) => parentToolUseId == null ? STREAMING_ID : `${STREAMING_ID}:${parentToolUseId}`;
+const streamingThinkingId = (parentToolUseId) => parentToolUseId == null ? STREAMING_THINKING_ID : `${STREAMING_THINKING_ID}:${parentToolUseId}`;
+/** Is this item an in-flight stream — anyone's? The turn's end finalizes every
+* one of them, since a subagent's last text is as unrecoverable as the main
+* thread's when a turn is interrupted. */
+const isStreamingItem = (item) => item.kind === "assistant_text" && item.id.startsWith(STREAMING_ID) || item.kind === "thinking" && item.id.startsWith(STREAMING_THINKING_ID);
 function blockText(content) {
 	if (content === void 0) return "";
 	if (typeof content === "string") return content;
 	return content.map((part) => typeof part.text === "string" ? part.text : "").filter(Boolean).join("\n");
 }
+/** The `image_ref` addresses in a result's content, or undefined when it holds
+* none — which is the common case, and is why this returns undefined rather than
+* an empty array: an absent field keeps the item byte-identical. */
+function imageRefsOf(content, seq) {
+	if (!Array.isArray(content)) return void 0;
+	const refs = content.flatMap((part) => part.type === "image_ref" ? [{
+		partIndex: Number(part.part_index),
+		mediaType: String(part.media_type ?? "application/octet-stream"),
+		bytes: Number(part.bytes ?? 0),
+		sourceSeq: seq
+	}] : []);
+	return refs.length > 0 ? refs : void 0;
+}
 function contentToBlocks(content) {
 	return typeof content === "string" ? [{
 		type: "text",
@@ -34,6 +69,27 @@ function outputText(output) {
 }
 /** CLI-side command output arrives as user text wrapped in local-command tags. */
 const LOCAL_COMMAND_OUTPUT = /^<local-command-(stdout|stderr)>([\s\S]*?)<\/local-command-\1>$/;
+/**
+* A slash command the person ran, as the CLI writes it into the transcript:
+* `<command-message>…</command-message><command-name>/wrapup</command-name>
+* <command-args>…</command-args>`, in whichever order.
+*
+* Rendered as the command line rather than hidden. It *is* a person's turn — it
+* is the reason everything after it happened — but the raw wrapper is markup
+* nobody typed, and it showed up verbatim in every resumed transcript. Not
+* suppressed in the runner for that same reason: hiding it would erase the
+* turn's cause and, since `transcriptActivity` counts a non-synthetic user
+* message as one row, silently disagree with the unread count.
+*/
+const COMMAND_NAME = /<command-name>([\s\S]*?)<\/command-name>/;
+const COMMAND_ARGS = /<command-args>([\s\S]*?)<\/command-args>/;
+/** The typed command line, or undefined when this is ordinary prose. */
+function slashCommandText(text) {
+	const name = COMMAND_NAME.exec(text)?.[1]?.trim();
+	if (!name) return void 0;
+	const args = COMMAND_ARGS.exec(text)?.[1]?.trim();
+	return args ? `${name} ${args}` : name;
+}
 function upsert(items, item) {
 	const index = items.findIndex((existing) => existing.id === item.id && existing.kind === item.kind);
 	if (index === -1) return [...items, item];
@@ -65,19 +121,50 @@ function seedFromSessionInfo(state, info) {
 * 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.
 */
 function rateLimitWindows(state) {
-	const all = Object.entries(state.rateLimits ?? {}).filter(([, info]) => info.utilization !== void 0).map(([key, info]) => ({
-		key,
-		info
-	}));
-	const named = ["five_hour", "seven_day"].flatMap((key) => all.filter((w) => w.key === key));
-	const perModel = all.filter((w) => w.key.startsWith("seven_day_")).sort((a, b) => a.key.localeCompare(b.key));
-	return [...named, ...perModel];
+	return orderUsageWindows(mergeUsage({
+		rateLimits: state.rateLimits,
+		updatedAt: state.rateLimitsUpdatedAt
+	}, void 0));
+}
+/**
+* Put a fetched tool result back where its head was — the other half of
+* `truncateResults`.
+*
+* Into **transcript state**, not row-local state, and the three reasons are the
+* design: the copy button then copies the whole thing rather than the head, the
+* transcript cache retains it across a session switch, and no later event can
+* re-truncate it. The markers are cleared, so a hydrated result is
+* indistinguishable from one that was never cut and every renderer needs a
+* branch for exactly one state, not two.
+*
+* Keyed on `toolUseId`, which is the id the row already holds; `seq` is what the
+* *fetch* needed, not what the fold needs. Unknown id returns `state` unchanged
+* — a press answered after the session was cleared must not resurrect a row.
+*/
+function hydrateToolResult(state, toolUseId, text) {
+	let changed = false;
+	const items = state.items.map((item) => {
+		if (item.kind !== "tool_call" || item.id !== toolUseId || !item.result?.truncated) return item;
+		changed = true;
+		return {
+			...item,
+			result: {
+				text,
+				isError: item.result.isError,
+				...item.result.images && { images: item.result.images }
+			}
+		};
+	});
+	return changed ? {
+		...state,
+		items
+	} : state;
 }
 function applyEvent(state, event) {
 	if (event.seq <= state.lastSeq) return state;
@@ -147,6 +234,12 @@ function applyEvent(state, event) {
 			...base,
 			subscriptionType: event.subscriptionType
 		};
+		case "conversation_reset": return {
+			...base,
+			items: [],
+			contextUsage: void 0,
+			sdkSessionId: event.sdkSessionId ?? base.sdkSessionId
+		};
 		case "user_message": {
 			let items = base.items;
 			for (const block of contentToBlocks(event.message.content)) if (block.type === "tool_result") {
@@ -157,8 +250,15 @@ function applyEvent(state, event) {
 					status: isError ? "failed" : "settled",
 					result: {
 						text: blockText(toolResult.content),
-						isError
-					}
+						isError,
+						...toolResult.truncated && {
+							truncated: true,
+							totalChars: toolResult.total_chars,
+							sourceSeq: event.seq
+						},
+						...imageRefsOf(toolResult.content, event.seq) && { images: imageRefsOf(toolResult.content, event.seq) }
+					},
+					...event.patch && { patch: event.patch }
 				} : item);
 			} else if (block.type === "text" && !event.synthetic) {
 				const text = block.text;
@@ -172,8 +272,9 @@ function applyEvent(state, event) {
 				else items = upsert(items, {
 					kind: "user",
 					id: event.uuid ?? `user-${event.seq}`,
-					text,
-					attachments: event.attachments
+					text: slashCommandText(text) ?? text,
+					attachments: event.attachments,
+					...event.parentToolUseId != null && { parentToolUseId: event.parentToolUseId }
 				});
 			}
 			return {
@@ -182,8 +283,10 @@ function applyEvent(state, event) {
 			};
 		}
 		case "assistant_message": {
-			let streamedThinking = base.items.find((item) => item.kind === "thinking" && item.id === STREAMING_THINKING_ID)?.text ?? "";
-			let items = base.items.filter((item) => !(item.kind === "assistant_text" && item.id === STREAMING_ID) && !(item.kind === "thinking" && item.id === STREAMING_THINKING_ID));
+			const streamingText = streamingTextId(event.parentToolUseId);
+			const streamingThought = streamingThinkingId(event.parentToolUseId);
+			let streamedThinking = base.items.find((item) => item.kind === "thinking" && item.id === streamingThought)?.text ?? "";
+			let items = base.items.filter((item) => !(item.kind === "assistant_text" && item.id === streamingText) && !(item.kind === "thinking" && item.id === streamingThought));
 			contentToBlocks(event.message.content).forEach((block, index) => {
 				const id = `${event.uuid}-${index}`;
 				if (block.type === "text") items = upsert(items, {
@@ -224,10 +327,11 @@ function applyEvent(state, event) {
 			const delta = event.event;
 			if (delta.type !== "content_block_delta") return base;
 			if (delta.delta?.type === "text_delta") {
+				const id = streamingTextId(event.parentToolUseId);
 				const item = {
 					kind: "assistant_text",
-					id: STREAMING_ID,
-					text: (base.items.find((item) => item.kind === "assistant_text" && item.id === STREAMING_ID)?.text ?? "") + (delta.delta.text ?? ""),
+					id,
+					text: (base.items.find((item) => item.kind === "assistant_text" && item.id === id)?.text ?? "") + (delta.delta.text ?? ""),
 					streaming: true,
 					parentToolUseId: event.parentToolUseId
 				};
@@ -237,10 +341,13 @@ function applyEvent(state, event) {
 				};
 			}
 			if (delta.delta?.type === "thinking_delta") {
+				const id = streamingThinkingId(event.parentToolUseId);
+				const text = (base.items.find((item) => item.kind === "thinking" && item.id === id)?.text ?? "") + (delta.delta.thinking ?? "");
+				if (text.trim() === "") return base;
 				const item = {
 					kind: "thinking",
-					id: STREAMING_THINKING_ID,
-					text: (base.items.find((item) => item.kind === "thinking" && item.id === STREAMING_THINKING_ID)?.text ?? "") + (delta.delta.thinking ?? ""),
+					id,
+					text,
 					parentToolUseId: event.parentToolUseId
 				};
 				return {
@@ -253,7 +360,18 @@ function applyEvent(state, event) {
 		case "turn_result": return {
 			...base,
 			totalCostUsd: event.totalCostUsd,
-			items: [...base.items, {
+			items: [...base.items.map((item) => {
+				if (!isStreamingItem(item)) return item;
+				const agent = "parentToolUseId" in item && item.parentToolUseId ? `-${item.parentToolUseId}` : "";
+				return item.kind === "assistant_text" ? {
+					...item,
+					id: `text-${event.seq}${agent}`,
+					streaming: false
+				} : {
+					...item,
+					id: `thinking-${event.seq}${agent}`
+				};
+			}), {
 				kind: "turn_result",
 				id: `turn-${event.seq}`,
 				subtype: event.subtype,
@@ -338,38 +456,266 @@ function applyEvent(state, event) {
 	}
 }
 //#endregion
-//#region src/use-session.ts
+//#region src/lib/transcript-cache.ts
+/**
+* Module-scope cache of detached transcript states, so switching back to a
+* recently viewed session paints its transcript in the mount frame and
+* re-attaches with `afterSeq: lastSeq` — the wire replays only what happened
+* while the panel was away, instead of the whole event log.
+*
+* Module-scope for the same reason `useSessions` and the watermarks are: the
+* consumers that need it (the VS Code panel, the dashboard's session route)
+* remount `SessionPanel` per session, so any per-hook copy would die with the
+* unmount that is the entire point of surviving.
+*
+* Entries are the same `TranscriptState` objects the reducer held — retention,
+* not duplication — and the bound is what keeps retention from becoming a
+* leak. Eviction is least-recently-STORED: every detach stores, so store
+* recency is viewing recency, and reads don't need to reorder.
+*
+* Keys come from {@link transcriptCacheKey} and carry the client's
+* `identityKey` (gateway + auth headers), never the session id alone: a
+* session id is unique only within one gateway, and an entry must never be
+* readable through a client speaking as a different principal.
+*/
+/**
+* How many detached transcripts stay warm.
+*
+* Five covers the working set the feature exists for — an operator alternating
+* between the handful of sessions that are simultaneously working or awaiting
+* them — while keeping the pathological case (five `perf`-fixture-sized
+* transcripts of ~4k items each) in the tens of megabytes, no more than a few
+* times what the one mounted panel already holds. Too small degrades to
+* today's behaviour (a replay on switch-back); too large is memory held
+* forever in a webview — the asymmetry favours small.
+*/
+const MAX_ENTRIES = 5;
+const entries = /* @__PURE__ */ new Map();
+/** Cache key for one session as seen through one (gateway, principal). The
+* NUL separator is unambiguous: the identity key is `JSON.stringify` output,
+* which escapes control characters, so no two (identity, session) pairs can
+* spell the same key. */
+function transcriptCacheKey(client, sessionId) {
+	return `${client.identityKey}\u0000${sessionId}`;
+}
+function readTranscriptCache(key) {
+	return entries.get(key);
+}
+function writeTranscriptCache(key, state) {
+	entries.delete(key);
+	entries.set(key, state);
+	if (entries.size > MAX_ENTRIES) {
+		const oldest = entries.keys().next().value;
+		if (oldest !== void 0) entries.delete(oldest);
+	}
+}
+function deleteTranscriptCache(key) {
+	entries.delete(key);
+}
+/**
+* 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.
+*/
+function clearTranscriptCache() {
+	entries.clear();
+}
+//#endregion
+//#region src/lib/attach-plan.ts
+/**
+* The attach effect's decisions, pure.
+*
+* `useClaudeSession` is never rendered in tests — this package deliberately
+* carries no jsdom and no testing-library — so the logic that used to live
+* inline in the attach effect (which state an attach holds, whether the
+* reducer must be re-seeded, which `afterSeq` to request, whether the parting
+* state may go back into the cache) is decided here, where plain vitest
+* reaches it, and the effect keeps only glue: read its refs into inputs,
+* apply the returned instructions, subscribe. The refs themselves stay in the
+* hook — a decision function that owned React state would be the untestable
+* thing again — so everything stateful arrives as a value and leaves as an
+* instruction.
+*/
+/**
+* Which (resync, client identity, session) a reducer state was seeded for.
+* One format, shared by the hook's mount initializer and {@link planAttach},
+* so the two sites cannot drift: a token that dropped `resyncSeq` would leave
+* the stale-log retry looking already-seeded, and the fresh replay would
+* compose into the condemned state the resync just discarded.
+*/
+function attachSeedToken(resyncSeq, key) {
+	return `${resyncSeq}:${key}`;
+}
+/**
+* Decide what one run of the attach effect does before it opens the socket.
+*/
+function planAttach(input) {
+	const seedToken = attachSeedToken(input.resyncSeq, input.key);
+	const warm = input.cacheEnabled && !input.skipCache ? input.warm : void 0;
+	const seed = input.seededFor !== seedToken;
+	const held = seed ? warm ?? initialTranscriptState : input.current;
+	return {
+		held,
+		seed,
+		seedToken,
+		...held.lastSeq > 0 ? { afterSeq: held.lastSeq } : {}
+	};
+}
+/**
+* Whether the effect's cleanup may keep the parting transcript warm for a
+* switch-back. Refused when caching is off; after a stale-log detection —
+* writing the condemned state back would re-poison the very retry that just
+* discarded it; and when there is nothing real to keep — `lastSeq === 0` also
+* protects an existing entry from being clobbered by a mount that never
+* finished attaching, and a state with no `session` never saw its attached
+* frame at all.
+*/
+function shouldWriteParting(input) {
+	return input.cacheEnabled && !input.skipCache && input.parting.lastSeq > 0 && input.parting.session !== void 0;
+}
+//#endregion
+//#region src/hooks/use-session.ts
 /** Session events drive the reducer; the attach snapshot seeds fields (permission
 * mode, model) that a promptless session's event stream doesn't carry yet. */
 function reduce(state, action) {
+	if (action.type === "transcript_seed") return action.state;
+	if (action.type === "transcript_hydrate_result") return hydrateToolResult(state, action.toolUseId, action.text);
 	return action.type === "attached" ? seedFromSessionInfo(state, action.session) : applyEvent(state, action);
 }
 /** Failed attempts in a row before "reconnecting…" stops being the honest word.
 * Three is ~3.5s of backoff — past a blip. Matches the iOS client. */
 const OFFLINE_AFTER_ATTEMPTS = 3;
+/**
+* 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.
+*/
+function initialReplayTarget(frame) {
+	return frame.replayingFrom === 0 && frame.session.lastSeq > 0 ? frame.session.lastSeq : void 0;
+}
+/**
+* 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.
+*/
+function staleAttach(frame, held) {
+	if (frame.replayingFrom === 0 || held.lastSeq === 0) return false;
+	if (frame.session.lastSeq < held.lastSeq) return true;
+	return held.session !== void 0 && frame.session.createdAt !== held.session.createdAt;
+}
+/**
+* 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.
+*/
+const REPLAY_HOLD_MAX_MS = 1500;
 /** Attach to a session and maintain live transcript state. Detaches on unmount. */
 function useClaudeSession(client, sessionId, options) {
-	const [state, dispatch] = useReducer(reduce, initialTranscriptState);
+	const [state, dispatch] = useReducer(reduce, void 0, () => (options?.cacheTranscript !== false && sessionId !== void 0 ? readTranscriptCache(transcriptCacheKey(client, sessionId)) : void 0) ?? initialTranscriptState);
 	const [connection, setConnection] = useState("reconnecting");
 	const [protocolMismatch, setProtocolMismatch] = useState();
+	/** Where the current attach's replay ends, while one is being held for. */
+	const [replayTarget, setReplayTarget] = useState();
+	/** Bumped to force a fresh attach from seq 0 after a stale-log detection. */
+	const [resyncSeq, setResyncSeq] = useState(0);
 	const [handleState, setHandleState] = useState();
 	const handleRef = useRef(null);
-	const onProtocolErrorRef = useRef(options?.onProtocolError);
-	onProtocolErrorRef.current = options?.onProtocolError;
+	const optionsRef = useRef(options);
+	optionsRef.current = options;
+	const stateRef = useRef(state);
+	stateRef.current = state;
+	const seededForRef = useRef(attachSeedToken(0, sessionId === void 0 ? "" : transcriptCacheKey(client, sessionId)));
+	const skipCacheRef = useRef(false);
 	useEffect(() => {
 		if (!sessionId) return;
-		const handle = client.attach(sessionId);
+		const cache = optionsRef.current?.cacheTranscript !== false;
+		const key = transcriptCacheKey(client, sessionId);
+		const plan = planAttach({
+			resyncSeq,
+			key,
+			seededFor: seededForRef.current,
+			current: stateRef.current,
+			cacheEnabled: cache,
+			skipCache: skipCacheRef.current,
+			warm: readTranscriptCache(key)
+		});
+		skipCacheRef.current = false;
+		if (plan.seed) {
+			dispatch({
+				type: "transcript_seed",
+				state: plan.held
+			});
+			seededForRef.current = plan.seedToken;
+		}
+		const handle = client.attach(sessionId, {
+			truncateResults: true,
+			imageRefs: true,
+			...plan.afterSeq === void 0 ? {} : { afterSeq: plan.afterSeq }
+		});
 		handleRef.current = handle;
 		setHandleState(handle);
 		const offEvent = handle.on("event", (event) => dispatch(event));
 		const offAttached = handle.on("attached", (frame) => {
+			if (staleAttach(frame, stateRef.current)) {
+				offEvent();
+				deleteTranscriptCache(key);
+				skipCacheRef.current = true;
+				setResyncSeq((n) => n + 1);
+				return;
+			}
 			dispatch(frame);
+			setReplayTarget(initialReplayTarget(frame));
 			setProtocolMismatch(frame.protocolVersion === PROTOCOL_VERSION ? void 0 : frame.protocolVersion);
 		});
 		const offConn = handle.on("connectionChange", (open) => setConnection(open ? "live" : "reconnecting"));
 		const offRetry = handle.on("reconnectAttempt", (attempts) => setConnection(attempts >= OFFLINE_AFTER_ATTEMPTS ? "offline" : "reconnecting"));
 		const offProtocolError = handle.on("protocolError", (message) => {
-			onProtocolErrorRef.current?.(message);
+			optionsRef.current?.onProtocolError?.(message);
 		});
 		return () => {
 			offEvent();
@@ -382,15 +728,53 @@ function useClaudeSession(client, sessionId, options) {
 			setHandleState(void 0);
 			setConnection("reconnecting");
 			setProtocolMismatch(void 0);
+			setReplayTarget(void 0);
+			const parting = stateRef.current;
+			if (shouldWriteParting({
+				cacheEnabled: cache,
+				skipCache: skipCacheRef.current,
+				parting
+			})) writeTranscriptCache(key, parting);
 		};
-	}, [client, sessionId]);
+	}, [
+		client,
+		sessionId,
+		resyncSeq
+	]);
+	useEffect(() => {
+		if (replayTarget === void 0) return;
+		const timer = setTimeout(() => setReplayTarget(void 0), REPLAY_HOLD_MAX_MS);
+		return () => clearTimeout(timer);
+	}, [replayTarget]);
+	useEffect(() => {
+		if (replayTarget !== void 0 && state.lastSeq >= replayTarget) setReplayTarget(void 0);
+	}, [replayTarget, state.lastSeq]);
 	const models = useProfileModelFallback(client, sessionId, state);
 	const connected = connection === "live";
+	const replaying = replayTarget !== void 0 && state.lastSeq < replayTarget;
 	const reconnectNow = useCallback(() => handleRef.current?.reconnectNow(), []);
+	const loadFullResult = useCallback(async (toolUseId) => {
+		if (!sessionId) return false;
+		const item = stateRef.current.items.find((candidate) => candidate.kind === "tool_call" && candidate.id === toolUseId);
+		const result = item?.kind === "tool_call" ? item.result : void 0;
+		if (!result?.truncated || result.sourceSeq === void 0) return false;
+		try {
+			const full = await client.toolResult(sessionId, result.sourceSeq, toolUseId);
+			dispatch({
+				type: "transcript_hydrate_result",
+				toolUseId,
+				text: typeof full.content === "string" ? full.content : (full.content ?? []).map((part) => typeof part.text === "string" ? part.text : "").filter(Boolean).join("\n")
+			});
+			return true;
+		} catch {
+			return false;
+		}
+	}, [client, sessionId]);
 	return useMemo(() => ({
 		state,
 		connected,
 		connection,
+		replaying,
 		protocolMismatch,
 		models,
 		effectiveModel: state.model ?? state.defaultModel,
@@ -402,15 +786,18 @@ function useClaudeSession(client, sessionId, options) {
 		setPermissionMode: (mode) => handleRef.current?.setPermissionMode(mode),
 		setModel: (model) => handleRef.current?.setModel(model),
 		closeSession: () => handleRef.current?.closeSession(),
-		reconnectNow
+		reconnectNow,
+		loadFullResult
 	}), [
 		state,
 		connected,
 		connection,
+		replaying,
 		protocolMismatch,
 		models,
 		handleState,
-		reconnectNow
+		reconnectNow,
+		loadFullResult
 	]);
 }
 /**
@@ -445,7 +832,7 @@ function useProfileModelFallback(client, sessionId, state) {
 	return hasReported ? reported : catalog;
 }
 //#endregion
-//#region src/use-attachments.ts
+//#region src/hooks/use-attachments.ts
 /**
 * How a media type reaches a model, in the capability record's vocabulary.
 * `undefined` means this build can't classify it — the upload still goes,
@@ -681,7 +1068,7 @@ async function prepare(file) {
 	}
 }
 //#endregion
-//#region src/prompt-tokens.ts
+//#region src/lib/prompt-tokens.ts
 /** Characters a command name may contain after the slash. Deliberately excludes
 * `/`, so an absolute path pasted into a message (`/Users/me/…`) is not mistaken
 * for a command; `:` is in because namespaced skills (`dev:wrapup`) are spelled
@@ -731,7 +1118,7 @@ function scanPromptTokens(text) {
 	return tokens;
 }
 //#endregion
-//#region src/host-tree.ts
+//#region src/lib/host-tree.ts
 /**
 * Flatten the loaded directories into the rows the tree shows.
 *
@@ -796,7 +1183,7 @@ function ancestorsWithin(root, path) {
 	return out;
 }
 //#endregion
-//#region src/use-host-files.ts
+//#region src/hooks/use-host-files.ts
 /**
 * Fuzzy file search rooted at a session's working directory — what an `@file`
 * picker needs.
@@ -978,7 +1365,133 @@ function useHostFileTree(client, cwd) {
 	};
 }
 //#endregion
-//#region src/use-session-info.ts
+//#region src/hooks/use-project-icons.ts
+/**
+* Project icon bytes for a list of sessions, as object URLs keyed by the icon's
+* own content hash.
+*
+* **Keyed by hash, and cached for the life of the page.** That is what the
+* wire's `ProjectIcon.image.hash` is for: every session in one project serves
+* identical bytes, so twelve rows of one repo cost one request, and two
+* *different* projects that happen to declare the same file cost one between
+* them. A hash names its bytes, so an entry can never go stale — editing the
+* icon changes the hash, which arrives on the next poll as a key this cache has
+* not seen. The old entry is dead weight rather than a wrong answer, and the
+* population is bounded by how many distinct icons an operator has open.
+*
+* The cache is **module scope on purpose**, like `useSessions`' store: the
+* sidebar and any other surface rendering rows mount this at once, and a
+* per-hook cache would be N copies each fetching the same bytes.
+*
+* A failure is cached as a failure. The route's 404 is the uniform "no icon"
+* (no project, a glyph, or one the gateway refused), so retrying it every poll
+* would be a request per session per poll for a picture that is never coming.
+*
+* Object URLs are never revoked, which is the same decision stated twice: they
+* are the cache. Revoking one would break every row still pointing at it, and
+* the whole point of hashing is that nothing here is ever superseded.
+*
+* The VS Code extension has the same three-set structure in `project-icons.ts`
+* and cannot share this one — its webview has no external `connect-src` at all,
+* so its bytes arrive as data URLs pushed from the extension host. One design,
+* two implementations, for a reason that is in the transport rather than here.
+*/
+const byHash = /* @__PURE__ */ new Map();
+const inFlight = /* @__PURE__ */ new Set();
+const failed = /* @__PURE__ */ new Set();
+function useProjectIcons(rows, clientFor) {
+	const [resolved, setResolved] = useState(() => Object.fromEntries(byHash));
+	useEffect(() => {
+		let alive = true;
+		for (const row of rows) {
+			const icon = row.info.project?.icon;
+			if (icon?.type !== "image") continue;
+			const { hash } = icon;
+			if (byHash.has(hash) || inFlight.has(hash) || failed.has(hash)) continue;
+			const client = clientFor(row.hostId);
+			if (!client) continue;
+			inFlight.add(hash);
+			client.projectIcon(row.info.id).then((blob) => {
+				byHash.set(hash, URL.createObjectURL(blob));
+				if (alive) setResolved(Object.fromEntries(byHash));
+			}).catch(() => {
+				failed.add(hash);
+			}).finally(() => inFlight.delete(hash));
+		}
+		return () => {
+			alive = false;
+		};
+	}, [rows, clientFor]);
+	return resolved;
+}
+//#endregion
+//#region src/hooks/use-profile-usage.ts
+/**
+* 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.
+*/
+function useProfileUsage(client, profile, options = {}) {
+	const { intervalMs = 6e4, enabled = true } = options;
+	const [usage, setUsage] = useState();
+	const [unsupported, setUnsupported] = useState(false);
+	const [nonce, setNonce] = useState(0);
+	const refresh = useCallback(() => setNonce((n) => n + 1), []);
+	useEffect(() => setUsage(void 0), [client, profile]);
+	const alive = useRef(true);
+	useEffect(() => {
+		alive.current = true;
+		return () => {
+			alive.current = false;
+		};
+	}, []);
+	useEffect(() => {
+		if (!profile || !enabled || unsupported) return;
+		let cancelled = false;
+		const load = () => {
+			if (globalThis.document?.hidden) return;
+			client.listProfiles().then((res) => {
+				if (cancelled || !alive.current) return;
+				setUsage(res.profiles.find((p) => p.name === profile)?.usage);
+			}).catch((e) => {
+				if (cancelled || !alive.current) return;
+				if (e instanceof WorkerDeckError && e.status === 404) setUnsupported(true);
+			});
+		};
+		load();
+		const timer = setInterval(load, intervalMs);
+		return () => {
+			cancelled = true;
+			clearInterval(timer);
+		};
+	}, [
+		client,
+		profile,
+		enabled,
+		unsupported,
+		intervalMs,
+		nonce
+	]);
+	return {
+		usage,
+		refresh
+	};
+}
+//#endregion
+//#region src/hooks/use-session-info.ts
 /**
 * The registry's record of one session, over REST.
 *
@@ -1026,7 +1539,7 @@ function useSessionInfo(client, sessionId) {
 	};
 }
 //#endregion
-//#region src/open-files.ts
+//#region src/lib/open-files.ts
 /** Whether a tab has edits that are not on disk. Derived, so typing something
 * and undoing it back leaves the tab clean — which is what an editor should do
 * and what a boolean flag set on first keystroke would get wrong. */
@@ -1174,7 +1687,7 @@ function baseName(path) {
 	return trimmed.slice(trimmed.lastIndexOf("/") + 1) || trimmed || path;
 }
 //#endregion
-//#region src/use-open-files.ts
+//#region src/hooks/use-open-files.ts
 /**
 * The open-file tabs of a workspace: which files are open, which one is focused,
 * the bytes behind each, and the edits on top of them.
@@ -1352,7 +1865,7 @@ function useOpenFiles(client) {
 	};
 }
 //#endregion
-//#region src/tool-host.ts
+//#region src/lib/tool-host.ts
 /**
 * Answers server-bridged tool calls by executing them in this browser tab.
 * Framework-free — {@link useToolCallHost} is a thin React wrapper.
@@ -1480,7 +1993,7 @@ async function defaultLoadEngine() {
 	return sandbox.loadEngine(variant);
 }
 //#endregion
-//#region src/use-tool-host.ts
+//#region src/hooks/use-tool-host.ts
 /**
 * React wrapper around {@link createToolCallHost}: subscribes while mounted and
 * exposes recent executions for rendering. All the logic lives in the
@@ -1522,7 +2035,7 @@ function useToolCallHost(handle, options = {}) {
 	return { executions };
 }
 //#endregion
-//#region src/recap.ts
+//#region src/lib/recap.ts
 /**
 * Summarize the items from `fromIndex` onward — the boundary being the number
 * of items that existed when the session was last looked at.
@@ -1601,6 +2114,6 @@ function plural(count, one, many = `${one}s`) {
 	return `${count} ${count === 1 ? one : many}`;
 }
 //#endregion
-export { ancestorsWithin, applyEvent, attachmentKind, createToolCallHost, currentText, flattenHostTree, initialOpenFilesState, initialTranscriptState, isDirty, openFilesReducer, rateLimitWindows, recapLine, scanPromptTokens, seedFromSessionInfo, summarizeSince, useAttachments, useClaudeSession, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useSessionInfo, useToolCallHost };
+export { REPLAY_HOLD_MAX_MS, ancestorsWithin, applyEvent, attachmentKind, clearTranscriptCache, createToolCallHost, currentText, flattenHostTree, hydrateToolResult, initialOpenFilesState, initialReplayTarget, initialTranscriptState, isDirty, openFilesReducer, rateLimitWindows, recapLine, scanPromptTokens, seedFromSessionInfo, staleAttach, summarizeSince, useAttachments, useClaudeSession, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useProfileUsage, useProjectIcons, useSessionInfo, useToolCallHost };
 
 //# sourceMappingURL=index.mjs.map