@workerdeck/react 0.22.0 → 1.0.0

package/build/index.d.mts

@@ -3,26 +3,17 @@ import { SessionHandle, WorkerDeckClient } from "@workerdeck/client";
 import { RunScriptResult, SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
 
 //#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.
- */
+type ToolResultImageRef = {
+  partIndex: number;
+  mediaType: string;
+  bytes: number;
+  sourceSeq: number;
+};
 type TranscriptItem = {
   kind: 'user';
   id: string;
   text: string;
   attachments?: MessageAttachment[];
-  /**
-   * The `Task` call this prompt was addressed to, when it is a subagent's
-   * brief rather than something a person typed.
-   *
-   * Optional where the other kinds carry it as `string | null`, and the
-   * asymmetry is the point: on those it is a fact about every instance, so
-   * forgetting to stamp it should not typecheck. Here the overwhelming case
-   * is a human prompt, which has no parent at all — `undefined` says that,
-   * where `null` on 24 construction sites would only say "somebody
-   * remembered".
-   */
   parentToolUseId?: string;
 } | {
   kind: 'assistant_text';
@@ -41,82 +32,19 @@ type TranscriptItem = {
   name: string;
   input: unknown;
   parentToolUseId: string | null;
-  /**
-   * When the model called it — the event's own `ts`, so it is replay-stable
-   * rather than a receive time (the mistake `rateLimitsUpdatedAt` makes on
-   * iOS). Optional because it is stamped at creation only: an item
-   * reconstructed by an older path has none, and absent must read as "no
-   * elapsed" rather than as the epoch.
-   *
-   * Added for the sub-agent takeover's header, which is the one surface that
-   * has to say how long an agent has been going: `SubagentInfo.startedAt`
-   * cannot answer it, being frozen at attach for anything spawned later.
-   * Immutable after creation, which is what makes it safe for iOS's
-   * `Equatable` row-plan cache key to mirror later.
-   */
   ts?: number;
-  /**
-   * - `running` — the model called it; execution has not been reported
-   * - `pending` — dispatched to an executor (bridged to this client, queued)
-   * - `deferred` — parked beyond this turn; may outlive the session's liveness
-   * - `settled` / `failed` — terminal
-   *
-   * Derive UI from this, not from `result` being present: a pending or
-   * deferred call has no result yet and is not the same as a running one.
-   */
   status: 'running' | 'pending' | 'deferred' | 'settled' | 'failed';
-  /**
-   * `truncated`/`totalChars`/`sourceSeq` are set **only** when the replay
-   * delivered a head (protocol's {@link ToolResultBlock.truncated}), so
-   * every other result stays byte-identical to what it was before this
-   * feature existed. That matters beyond tidiness: on iOS `ToolCallItem` is
-   * `Equatable` and is half the row-plan cache key.
-   *
-   * `sourceSeq` is what makes the press possible at all — the item is what a
-   * renderer holds, and it must be able to name the event to fetch. It goes
-   * away again on hydration, along with the other two, so a hydrated result
-   * is indistinguishable from one that was never cut.
-   */
   result?: {
     text: string;
     isError: boolean;
     truncated?: boolean;
     totalChars?: number;
     sourceSeq?: number;
-    /**
-     * The pictures this result carried, as addresses rather than bytes —
-     * set **only** when the replay delivered `image_ref` parts, so every
-     * other result stays byte-identical (the `Equatable` argument above,
-     * again).
-     *
-     * Each entry carries its **own** `sourceSeq`, which is not redundant
-     * with the one beside it: that one is cleared by text hydration, and a
-     * reader who pressed "show everything" must still be able to load the
-     * screenshot afterwards.
-     *
-     * Raw base64 `image` parts are still dropped on arrival, as they always
-     * were. Folding them in would pin megabytes inside `TranscriptState`,
-     * which the transcript LRU then retains across session switches.
-     */
-    images?: ReadonlyArray<{
-      partIndex: number;
-      mediaType: string;
-      bytes: number;
-      sourceSeq: number;
-    }>;
+    images?: ReadonlyArray<ToolResultImageRef>;
   };
-  /**
-   * 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). */
+  patch?: FilePatch;
+  executionId?: string;
+  backend?: ToolExecutionBackend;
   logs?: string[];
 } | {
   kind: 'turn_result';
@@ -131,18 +59,13 @@ type TranscriptItem = {
   id: string;
   level: 'info' | 'error';
   text: string;
-}
-/** The agent handed over a session file (`file_delivered`). Render a download
- * card; the file is served by GET /sessions/:id/files/<path> while the
- * session lives. */
-| {
+} | {
   kind: 'file_delivered';
   id: string;
   path: string;
   bytes: number;
   description?: string;
 };
-/** A `file_produced` announcement, as the transcript keeps it. */
 type ProducedFileRef = {
   fileId: string;
   mediaType?: string;
@@ -154,62 +77,18 @@ type TranscriptState = {
   model?: string;
   cwd?: string;
   sdkSessionId?: string;
-  /** Engine running the session, from the attach snapshot. Gates CLI-only
-   * affordances; absent (an older server) reads as 'claude'. */
   engine?: ProfileEngine;
-  /**
-   * What this session's engine does and does not do: the runner-reported record
-   * from the attach snapshot when present, else {@link ENGINE_CAPABILITIES} for
-   * the engine. Always defined, so a surface can render every affordance from it
-   * rather than switching on the engine name — an absent capability means the
-   * affordance is *hidden*, never a control that silently does nothing.
-   */
   capabilities: EngineCapabilities;
-  /**
-   * The most recent attach snapshot, whole. The session-level facts no event
-   * carries — profile, apiKeySource, canBypassPermissions, createdAt, numTurns —
-   * live only here. Unlike the fields above it is replaced on every attach: it is
-   * the server's answer, not something the event stream refines.
-   */
-  session?: SessionInfo; /** Models the session can switch to (from the `capabilities` event). */
-  models?: ModelOption[]; /** Slash commands the CLI accepts (from the `capabilities` event). */
+  session?: SessionInfo;
+  models?: ModelOption[];
   commands?: SlashCommandInfo[];
-  /**
-   * Skills the engine can reach (from the `skills` event), replaced whole each
-   * time. Absent until the engine has enumerated them — which for codex is on
-   * its first turn, since listing needs a live child. So gate the affordance on
-   * *this being defined*, not on `capabilities.skillsList` alone: the flag says
-   * the engine can answer, this says it has.
-   *
-   * Not commands, and must not be offered as such — see the protocol's
-   * `SkillInfo`.
-   */
   skills?: SkillInfo[];
-  /**
-   * Files the engine wrote on the host, keyed by the absolute path it reported
-   * (from `file_produced`). A tool card holding a `savedPath` looks itself up
-   * here to turn that path into a fetchable id — `client.producedFileUrl` — so
-   * the picture renders without the operator having declared a host-file root.
-   */
   producedFiles?: Record<string, ProducedFileRef>;
-  /** What this session's default model resolves to (from `capabilities`). Known
-   * before the first turn, which `model` is not — a promptless session has no
-   * `system_init` until it is spoken to. */
-  defaultModel?: string; /** Seeded from `system_init`, updated on `permission_mode_changed`. */
-  permissionMode?: PermissionMode; /** Latest context-window snapshot; absent until the first turn completes. */
+  defaultModel?: string;
+  permissionMode?: PermissionMode;
   contextUsage?: ContextUsage;
-  /** Latest rate-limit snapshot per window ('five_hour', 'seven_day', ...).
-   * Absent for API-key sessions — render nothing, not 0%. */
   rateLimits?: Record<string, RateLimitInfo>;
-  /**
-   * When the newest window reading was *taken* (the event's `ts`), not when this
-   * client received it — so a reading replayed on attach is dated honestly
-   * rather than as "just now". Updates come one per turn at best, which makes a
-   * stale reading normal and worth saying out loud.
-   */
   rateLimitsUpdatedAt?: number;
-  /** claude.ai plan the rate-limit windows belong to ('pro', 'max', ...), from
-   * `plan_info`. Absent for API-key sessions, like the windows themselves. */
   subscriptionType?: string;
   items: TranscriptItem[];
   pendingApprovals: PermissionRequest[];
@@ -217,556 +96,191 @@ type TranscriptState = {
   lastSeq: number;
 };
 declare const initialTranscriptState: TranscriptState;
-/**
- * Seed transcript state from the attach snapshot (the `attached` frame's SessionInfo).
- * A promptless session emits no `system_init` until its first message, so fields like
- * `permissionMode` and `model` would otherwise stay empty — fill only what events
- * haven't set yet; the event stream stays authoritative.
- */
 declare function seedFromSessionInfo(state: TranscriptState, info: SessionInfo): TranscriptState;
-/**
- * The session's rate-limit windows in reading order: the session window, the
- * weekly window, then whichever per-model weekly windows it reports.
- *
- * 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): UsageWindowRow[];
-/**
- * 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.
- */
 declare function hydrateToolResult(state: TranscriptState, toolUseId: string, text: string): TranscriptState;
 declare function applyEvent(state: TranscriptState, event: SessionEvent): TranscriptState;
 //#endregion
 //#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
- * holds is *stale*, so a surface that merges them must say so rather than keep
- * claiming "idle".
- *
- * The handle retries forever, so `offline` is a judgement about how long it has
- * 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;
-  /** True while the socket is open. {@link UseClaudeSessionResult.connection}
-   * 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;
-  /**
-   * What a model picker should offer. Two sources, and which is authoritative
-   * depends on the engine: the `capabilities` event is the CLI asked what it
-   * supports, so for claude it wins; codex never sends one — its models are a
-   * catalog shipped with the release and served on the profile — so without the
-   * fallback its picker would be permanently empty and the session unswitchable.
-   */
   models: ModelOption[];
-  /** The model this session answers as: the one it reported, or, before it has
-   * reported anything, the default it will use. */
   effectiveModel?: string;
-  /** The live attach handle, for wiring companions that must ride the SAME
-   * socket — e.g. useToolCallHost: the bridge asks the first attached client,
-   * so a host on a second handle would never see the requests. Undefined until
-   * attached and after unmount. */
-  handle: SessionHandle | undefined; /** Attachment ids come from `client.uploadAttachment`, in send order. */
+  handle: SessionHandle | undefined;
   send: (text: string, attachmentIds?: string[]) => void;
   approve: (requestId: string, updatedInput?: Record<string, unknown>) => void;
-  /** `message` is fed back to the agent, which can then try something else;
-   * `interrupt` also stops the turn ("deny & stop"). */
   deny: (requestId: string, message?: string, interrupt?: boolean) => void;
   interrupt: () => void;
-  /**
-   * Reset the conversation in place: same session, empty transcript. Gate the
-   * affordance on `session.capabilities?.clearContext` — an engine or a gateway
-   * that cannot do it answers with an error, which is the wrong way for a user
-   * to find out.
-   */
   clearContext: () => void;
   setPermissionMode: (mode: PermissionMode) => void;
   setModel: (model?: string) => void;
-  closeSession: () => void; /** Skip the reconnect backoff — what a tab returning to the foreground does. */
+  closeSession: () => void;
   reconnectNow: () => void;
-  /**
-   * Fetch the whole of a tool result the replay delivered as a head, and put it
-   * back on its row (`result.truncated` clears with it).
-   *
-   * Resolves `false` when there was nothing to do — an untruncated row, an
-   * unknown id, or a gateway that refused (a stale `sourceSeq` after a dormant
-   * rebuild 404s by design; re-attaching is what fixes that, not a retry). It
-   * never throws, because the caller is a press on a row and an exception there
-   * has nowhere sensible to go.
-   */
   loadFullResult: (toolUseId: string) => Promise<boolean>;
 };
-/** 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/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/lib/profile-usage-cache.d.ts
+declare function clearProfileUsageCache(): void;
+//#endregion
+//#region src/lib/draft-store.d.ts
+declare function clearDrafts(): void;
+//#endregion
 //#region src/hooks/use-attachments.d.ts
-/**
- * Files staged for the next message.
- *
- * The upload happens as soon as something is picked, not at send time — the
- * message names attachment *ids*, so the bytes must already be the server's
- * before a turn can reference them, and the wait is spent while the user is
- * still typing rather than after they hit send. It also keeps base64 out of the
- * event log entirely, which is the protocol's rule.
- */
 type StagedAttachment = {
-  /** Local identity, stable across a retry — the React key while uploading. */key: string;
+  key: string;
   name: string;
   mediaType: string;
-  bytes: number; /** Object URL for an image thumbnail, revoked when the item goes away. */
+  bytes: number;
   previewUrl?: string;
-  status: 'uploading' | 'ready' | 'failed'; /** The server's id once uploaded — what `send` names. */
-  id?: string; /** Why the upload failed, verbatim from the gateway (413, 415, …). */
+  status: 'uploading' | 'ready' | 'failed';
+  id?: string;
   error?: string;
 };
-/** The kind vocabulary of {@link EngineCapabilities.attachments}. */
 type AttachmentKind = 'image' | 'pdf' | 'text';
-/**
- * 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,
- * because the gateway's vocabulary is the authoritative one.
- */
 declare function attachmentKind(mediaType: string): AttachmentKind | undefined;
 type UseAttachmentsOptions = {
-  /** The session's capability record — its `attachments` list decides which
-   * kinds are offered and which are refused locally. */
   capabilities: EngineCapabilities;
-  /** Named in a local refusal, so "the codex engine does not take pdf
-   * attachments" says which engine meant it. */
   engine?: ProfileEngine;
 };
 type UseAttachmentsResult = {
-  items: StagedAttachment[]; /** Uploaded ids in staging order — what {@link UseClaudeSessionResult.send} names. */
-  readyIds: string[]; /** An id that hasn't landed can't be named, so send waits. */
-  uploading: boolean; /** A refused file must be dealt with before the message goes. */
-  hasFailure: boolean; /** Accept attribute for a file input, narrowed to what the engine takes. */
+  items: StagedAttachment[];
+  readyIds: string[];
+  uploading: boolean;
+  hasFailure: boolean;
   accept: string;
-  /** True when the engine takes no attachments at all — hide the affordance
-   * entirely rather than offer one with no meaning. */
   disabled: boolean;
   add: (files: Iterable<File>) => void;
   retry: (key: string) => void;
   remove: (key: string) => void;
-  clear: () => void; /** A local refusal (wrong kind), surfaced once rather than silently dropped. */
+  clear: () => void;
   error?: string;
   dismissError: () => void;
 };
-/**
- * Stage, upload and track files for the next message of a session.
- *
- * Refusals happen as early as they can be known: a kind the capability record
- * forswears never reaches the network (the gateway would 415 it), and everything
- * else is the gateway's call — its vocabulary is authoritative, so an unknown
- * media type is uploaded rather than guessed at.
- */
 declare function useAttachments(client: WorkerDeckClient, sessionId: string | undefined, {
   capabilities,
   engine
 }: UseAttachmentsOptions): UseAttachmentsResult;
 //#endregion
 //#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.
- *
- * The mirror of the iOS client's `PromptTokens.scan`, and deliberately the same
- * rules: a message should read the same after sending as it did in the composer,
- * on either client. It lives here, beside the transcript reducer, for the same
- * reason its Swift twin lives in the kit rather than the app — every interesting
- * case is an edge (an `@` mid-word, an email address, a slash that is really an
- * absolute path), so it is the part that gets unit-tested.
- *
- * Only the finished-text half is here; the composer's completion is the
- * prompt-area's own trigger machinery.
- */
 type PromptToken = {
-  kind: 'file' | 'command'; /** Offsets into the scanned string, prefix included. */
+  kind: 'file' | 'command';
   start: number;
   end: number;
   text: string;
 };
-/**
- * Every token in a sent message.
- *
- * Stricter than what a composer completes: a bare `@` is a token being typed, but
- * in a sent message it is just an at sign.
- */
 declare function scanPromptTokens(text: string): PromptToken[];
 //#endregion
 //#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.
- *
- * A directory that has never been asked for is simply absent from the map — which
- * is not the same as an empty directory, and the difference is what tells the
- * renderer to show a spinner rather than "nothing here".
- */
 type HostDirState = {
-  entries: HostDirEntry[]; /** The directory held more entries than the server will return. */
+  entries: HostDirEntry[];
   truncated?: boolean;
 };
-/** One rendered row of the tree — a flat list is what a scroll container wants,
- * and indentation is a number, not a nesting of DOM. */
 type HostTreeRow = {
-  entry: HostDirEntry; /** 0 for the root's own children. */
-  depth: number; /** Directories only: whether this row's children are showing. */
-  expanded?: boolean; /** Set on an expanded directory whose listing hasn't arrived yet. */
-  loading?: boolean; /** Set on an expanded directory the server truncated. */
+  entry: HostDirEntry;
+  depth: number;
+  expanded?: boolean;
+  loading?: boolean;
   truncated?: boolean;
 };
-/**
- * Flatten the loaded directories into the rows the tree shows.
- *
- * Pure, so the interesting part of a file tree — which nodes are visible at what
- * depth once a few directories are expanded and one of them is still loading —
- * is testable without a DOM or a gateway.
- *
- * Only *expanded* directories contribute children, and only if their listing has
- * arrived. An expanded-but-unlisted directory yields its own row with
- * `loading: true` and no children: expansion is a request the user already made,
- * so the row must say the answer is coming rather than look like an empty folder.
- */
 declare function flattenHostTree(root: string, dirs: ReadonlyMap<string, HostDirState>, expanded: ReadonlySet<string>): HostTreeRow[];
-/**
- * Every ancestor of `path` below `root`, outermost first — the directories that
- * must be expanded for `path` to be on screen.
- *
- * Returns `[]` when `path` is not under `root` rather than guessing: revealing a
- * file the tree cannot contain is a no-op, not an error worth raising, and the
- * caller has no better answer either.
- *
- * The prefix test is on a **path boundary** (`root` + `/`), so `/src/app` is not
- * treated as living under `/src/a`.
- */
 declare function ancestorsWithin(root: string, path: string): string[];
 //#endregion
 //#region src/hooks/use-host-files.d.ts
 type UseHostFileSearchResult = {
-  /**
-   * Whether `@file` completion is on offer at all: the session's cwd is known
-   * and this gateway hasn't already 404'd the search. Read it before advertising
-   * the affordance — a server without host files configured has none.
-   */
   available: boolean;
-  /**
-   * Run one search. Safe to call per keystroke — the route is built for it
-   * (bounded walk, build directories skipped) — and it answers `[]` rather than
-   * throwing, because a failed lookup is not worth an error banner over an
-   * affordance the user can ignore.
-   */
   search: (query: string, options?: {
     limit?: number;
     signal?: AbortSignal;
   }) => Promise<HostFileMatch[]>;
 };
-/**
- * Fuzzy file search rooted at a session's working directory — what an `@file`
- * picker needs.
- *
- * Deliberately session-scoped: the server's `hostFiles.roots` are the security
- * boundary, but what someone wants while talking to an agent is *this* project's
- * tree, so this never offers the roots list.
- *
- * A gateway that answers 404 once has answered for the session: host files are
- * either configured or they aren't, and the answer will not change while the cwd
- * holds. Asking again on every character would be a request per keystroke for a
- * feature that does not exist here.
- */
 declare function useHostFileSearch(client: WorkerDeckClient, cwd: string | undefined): UseHostFileSearchResult;
 type UseHostFileRootsResult = {
-  /** Whether this gateway serves host files at all. */available: boolean;
-  /**
-   * Whether `PUT /fs/write` is enabled here.
-   *
-   * Read it before offering an editor. Writing is a **separate** server opt-in
-   * from reading and defaults off, so a gateway that happily lists and reads a
-   * tree may still refuse every save — and finding that out at save time, with
-   * edits already made, is the worst moment for it.
-   */
+  available: boolean;
   canWrite: boolean;
 };
-/**
- * Whether host files are served here, and whether they may be written.
- *
- * One request per client, cached for the life of the hook: the roots and the
- * write flag are gateway configuration, not session state, and they do not
- * change while the tab is open.
- */
 declare function useHostFileRoots(client: WorkerDeckClient): UseHostFileRootsResult;
 type UseHostFileTreeResult = {
-  /**
-   * Whether a tree can be shown at all: the cwd is known and this gateway serves
-   * host files. Read it before rendering the rail — a gateway with no
-   * `hostFiles` configured has no tree, and that is a layout decision, not an
-   * error to display.
-   */
-  available: boolean; /** The directory the tree is rooted at — the session's cwd. */
-  root: string | undefined; /** The visible tree, flattened. Empty until the root listing arrives. */
-  rows: HostTreeRow[]; /** True while the root listing is outstanding and there is nothing to show. */
-  loading: boolean; /** A listing that failed, verbatim from the gateway. */
-  error: string | undefined; /** Expand or collapse a directory. Expanding lists it once and remembers. */
-  toggle: (path: string) => void; /** Expand every directory between the root and this path, so it is on screen. */
-  reveal: (path: string) => void; /** Re-list one directory (default: the root), keeping what is expanded. */
+  available: boolean;
+  root: string | undefined;
+  rows: HostTreeRow[];
+  loading: boolean;
+  error: string | undefined;
+  toggle: (path: string) => void;
+  reveal: (path: string) => void;
   refresh: (path?: string) => void;
 };
-/**
- * An expandable file tree rooted at a session's working directory.
- *
- * Rooted at the cwd rather than at `/fs/roots` for the same reason
- * {@link useHostFileSearch} is: the roots are the *security* boundary the server
- * enforces on every request, but what someone wants while watching an agent work
- * is this project's tree. The roots may well be broader; showing them would
- * offer navigation to directories the session has nothing to do with.
- *
- * Listings are cached per directory and kept across a collapse, so reopening a
- * folder is instant and does not re-ask. That staleness is deliberate and
- * bounded: `refresh` exists, and knowing when to call it is the *next* problem
- * (the agent is editing this same tree), not something a tree can guess.
- *
- * Like the search hook, a 404 is answered once for the session: host files are
- * either configured here or they are not.
- */
 declare function useHostFileTree(client: WorkerDeckClient, cwd: string | undefined): UseHostFileTreeResult;
 //#endregion
 //#region src/hooks/use-project-icons.d.ts
 type ClientForHost = (hostId: string) => WorkerDeckClient | undefined;
 declare function useProjectIcons(rows: readonly SessionRow[], clientFor: ClientForHost): Record<string, string>;
 //#endregion
+//#region src/hooks/use-draft.d.ts
+type UseDraftResult = {
+  /** What was left unsent last time, read once so it can seed the composer on mount. */initialText: string;
+  save: (text: string) => void;
+  clear: () => void;
+};
+/**
+ * Remember unsent composer text for a session. Purely local: it never reaches the gateway and never syncs between
+ * clients, because a half-written prompt is not something anyone asked to publish.
+ */
+declare function useDraft(client: WorkerDeckClient, sessionId: string | undefined): UseDraftResult;
+//#endregion
 //#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. */
+  intervalMs?: number;
   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. */
+  usage: ProfileUsage | undefined;
   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. */
+  info: SessionInfo | undefined;
+  loading: boolean;
   error: string | undefined;
 };
-/**
- * The registry's record of one session, over REST.
- *
- * Separate from {@link useClaudeSession} on purpose: that hook attaches a
- * WebSocket and streams a transcript, which is far more than a caller needs to
- * know a session's `cwd` or title — and a second attach would be a second
- * client on the bridge, which is the one thing the bridge's "asks the first
- * attached client" rule cannot tolerate.
- *
- * Fetched once per session id. The record is registry state, not a live feed;
- * anything that changes during a run arrives on the session's event stream.
- */
 declare function useSessionInfo(client: WorkerDeckClient, sessionId: string | undefined): UseSessionInfoResult;
 //#endregion
 //#region src/lib/open-files.d.ts
-/**
- * One open file, in whatever state its read got to.
- *
- * A tab exists from the moment it is opened, before any bytes arrive — the tab
- * strip is the record of what the user asked for, not of what the gateway has
- * answered, and a tab that only appeared once the read landed would make a slow
- * read look like a dead click.
- */
 type OpenFile = {
-  /** Absolute host path — the tab's identity. Opening the same path twice
-   * focuses the existing tab rather than making a second one. */
-  path: string; /** Last segment, for the tab label. */
+  path: string;
   name: string;
-  status: 'loading' | 'ready' | 'binary' | 'error'; /** The text **as last seen on disk** — never the user's edits. */
+  status: 'loading' | 'ready' | 'binary' | 'error';
   content?: string;
-  /**
-   * The user's unsaved text. Absent when nothing has been typed since the last
-   * read or save.
-   *
-   * Kept separate from `content` rather than overwriting it, because a
-   * conditional write needs to know both: what is being sent, and what the
-   * `hash` describes. Collapsing them would make "did this change?" unanswerable
-   * after the first keystroke.
-   */
   draft?: string;
   bytes?: number;
-  /**
-   * sha256 of the bytes `content` was read from — the `expectedHash` for the
-   * next write.
-   *
-   * This is the whole safety mechanism: `/fs/write` is conditional *always*, so
-   * a tab that lost its hash could not save at all without re-reading, and
-   * re-reading to save is precisely the race the conditional write exists to
-   * prevent.
-   */
   hash?: string;
-  modifiedAt?: number; /** Why the read failed, verbatim from the gateway. */
-  error?: string; /** A write is in flight. */
-  saving?: boolean; /** Why the last write failed, verbatim from the gateway. */
+  modifiedAt?: number;
+  error?: string;
+  saving?: boolean;
   saveError?: string;
-  /**
-   * The file changed on disk since this tab read it — the gateway answered 409.
-   *
-   * Held as a distinct flag rather than folded into `saveError` because it is
-   * the one failure with a *choice* attached (reload, overwrite, keep editing)
-   * rather than a message to read.
-   */
   conflict?: boolean;
 };
-/** 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. */
 declare function isDirty(file: OpenFile): boolean;
-/** What a tab would write: its edits if it has any, else what it read. */
 declare function currentText(file: OpenFile): string;
 type OpenFilesState = {
-  /** Tab order, left to right. */files: OpenFile[]; /** Absolute path of the focused tab, or undefined when nothing is open. */
+  files: OpenFile[];
   activePath?: string;
 };
 type OpenFilesAction = {
@@ -780,7 +294,7 @@ type OpenFilesAction = {
 } | {
   type: 'activate';
   path: string;
-} /** A read landed. Ignored if the tab was closed while it was in flight. */ | {
+} | {
   type: 'loaded';
   path: string;
   content: string;
@@ -792,20 +306,17 @@ type OpenFilesAction = {
   type: 'failed';
   path: string;
   error: string;
-} /** The user typed. */ | {
+} | {
   type: 'edit';
   path: string;
   content: string;
-} /** Throw away unsaved edits and go back to what was read. */ | {
+} | {
   type: 'revert';
   path: string;
 } | {
   type: 'saveStart';
   path: string;
-}
-/** A write succeeded. `content` is **what was written**, not what the tab
- * holds now — the user may have kept typing while it was in flight. */
-| {
+} | {
   type: 'saved';
   path: string;
   content: string;
@@ -817,72 +328,31 @@ type OpenFilesAction = {
   path: string;
   error: string;
   conflict?: boolean;
-} /** Dismiss the conflict banner and carry on editing. */ | {
+} | {
   type: 'dismissConflict';
   path: string;
 };
 declare const initialOpenFilesState: OpenFilesState;
-/**
- * The tab strip and the editor's whole behaviour, as a pure function.
- *
- * The rules worth stating, because they are the ones a naive implementation
- * gets wrong:
- *
- * - **Opening an open path never re-reads it.** It focuses the tab. Re-reading
- *   would silently discard that tab's unsaved edits on a double click.
- * - **Closing the focused tab focuses its right-hand neighbour**, falling back
- *   to the left when it was last. Focusing "the first tab" instead is what makes
- *   closing several tabs in a row jump the user around.
- * - **A successful save is applied against the text that was sent**, not against
- *   the tab's current text. Typing during a save is normal; treating the write's
- *   completion as "the tab is now clean" would silently drop those keystrokes.
- * - **Nothing here discards edits implicitly.** `revert` and `loaded` are the
- *   only two things that clear a draft, and both are the direct result of
- *   someone asking for it. The conditional write exists so a browser edit cannot
- *   clobber the agent mid-run; this holds the same line in the other direction.
- *
- * Late results are addressed by path and dropped if that tab is gone, so a slow
- * read of a closed file cannot resurrect it.
- */
 declare function openFilesReducer(state: OpenFilesState, action: OpenFilesAction): OpenFilesState;
 //#endregion
 //#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. */
+  active: OpenFile | undefined;
+  hasUnsaved: boolean;
   open: (path: string) => void;
   close: (path: string) => void;
   closeAll: () => void;
-  activate: (path: string) => void; /** Record a keystroke. Pure state; nothing is written until `save`. */
-  edit: (path: string, content: string) => void; /** Write the tab's edits, conditional on the hash it read. No-op if clean. */
-  save: (path: string) => Promise<void>; /** Throw the tab's edits away and go back to what was read. */
+  activate: (path: string) => void;
+  edit: (path: string, content: string) => void;
+  save: (path: string) => Promise<void>;
   revert: (path: string) => void;
-  /** Re-read from disk. **Discards unsaved edits** — only call on an explicit
-   * choice, never to "refresh". */
   reload: (path: string) => void;
-  /** Resolve a conflict by taking this tab's version: re-read for the current
-   * hash, then write the draft against it. */
-  overwrite: (path: string) => Promise<void>; /** Dismiss the conflict banner without resolving it. */
+  overwrite: (path: string) => Promise<void>;
   dismissConflict: (path: string) => void;
 };
-/**
- * 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.
- *
- * Reads are fired from an effect keyed on "which tabs are still loading" rather
- * than from `open` itself, so the reducer stays pure and a tab that was opened,
- * closed and reopened does not carry a stale in-flight request with it.
- *
- * Deliberately **not** given the session's cwd: a tab is an absolute host path,
- * and where it came from — the tree, a search hit, a path in the transcript — is
- * the caller's business. Containment is the server's job on every `/fs/read` and
- * `/fs/write`, not something re-derived here from a directory this hook would
- * have to trust.
- */
 declare function useOpenFiles(client: WorkerDeckClient): UseOpenFilesResult;
 //#endregion
 //#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;
   toolName: string;
@@ -898,107 +368,56 @@ type ToolHostRunner = (request: {
   memoryLimitBytes: number;
   signal: AbortSignal;
 }) => Promise<RunScriptResult>;
+type ClientToolResult = {
+  value: unknown;
+} | {
+  error: string;
+  reason?: string;
+};
+type ClientToolHandler = (input: unknown, context: {
+  executionId: string;
+  signal: AbortSignal;
+}) => ClientToolResult | Promise<ClientToolResult>;
 type ToolCallHostOptions = {
-  /** Tools this client will execute. Anything else is refused, so a server can
-   * never talk this tab into running something it didn't opt into.
-   * Default: `['eval_script']`. */
-  tools?: string[]; /** Guest wall-clock limit, unless the request asks for less. Default 5000. */
-  timeoutMs?: number; /** Guest allocator cap, unless the request asks for less. Default 64 MiB. */
+  tools?: string[];
+  clientTools?: Record<string, ClientToolHandler>;
+  timeoutMs?: number;
   memoryLimitBytes?: number;
-  /**
-   * Load the WASM guest engine. Called at most once, on the first bridged call
-   * — nothing is downloaded or parsed until a session actually bridges one.
-   * Defaults to `@workerdeck/sandbox` with the single-file browser build.
-   */
   loadEngine?: () => Promise<SandboxEngine>;
-  /**
-   * Run the script. Defaults to executing on this thread, which is fine for the
-   * short, time-boxed evaluations this is built for. Supply your own (a Web
-   * Worker running the same engine) to keep long evaluations off the UI thread
-   * — the guest deadline preempts the interpreter, but only between bytecode
-   * ops on whichever thread it runs on.
-   */
-  execute?: ToolHostRunner; /** Host-gated fetch for the guest. Omitted = the guest has no network at all. */
-  fetchText?: (url: string) => Promise<string>; /** Observe executions (rendering, logging). */
+  execute?: ToolHostRunner;
+  fetchText?: (url: string) => Promise<string>;
   onExecution?: (execution: ToolHostExecution) => void;
 };
-/**
- * Answers server-bridged tool calls by executing them in this browser tab.
- * Framework-free — {@link useToolCallHost} is a thin React wrapper.
- *
- * The point is data locality: documents fetched or held client-side can be
- * evaluated here and never touch the server. The engine loads lazily, so a page
- * that never bridges a call never pays for the WASM guest.
- */
 declare function createToolCallHost(handle: SessionHandle, options?: ToolCallHostOptions): {
   dispose: () => void;
 };
 //#endregion
 //#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. */
+  enabled?: boolean;
   historyLimit?: number;
 };
-/**
- * React wrapper around {@link createToolCallHost}: subscribes while mounted and
- * exposes recent executions for rendering. All the logic lives in the
- * framework-free host — this only manages the subscription's lifetime.
- */
 declare function useToolCallHost(handle: SessionHandle | undefined, options?: UseToolCallHostOptions): {
   executions: ToolHostExecution[];
 };
 //#endregion
 //#region src/lib/recap.d.ts
-/**
- * "What happened while you were away", counted rather than written.
- *
- * Deterministic on purpose. A prose recap would mean spending a turn — tokens,
- * context and latency — on a summary nobody asked the model for, and it would
- * be wrong in the one case that matters most (a session that failed while
- * unattended, where the model is exactly who you shouldn't ask). Everything
- * here is already in the transcript; this only counts it.
- *
- * Framework-free and pure, like the reducer it reads from: both clients render
- * the same recap from the same numbers.
- */
 type RecapSummary = {
-  /** Completed turns — `turn_result` rows, the engine's own unit of work. */turns: number; /** Messages the model wrote. Streaming ones count: they are on screen. */
-  replies: number; /** Tool calls started, and the distinct names, most-used first. */
+  turns: number;
+  replies: number;
   tools: number;
-  toolNames: string[]; /** Files the agent handed over (`file_delivered`). */
+  toolNames: string[];
   files: number;
-  /** Failed turns and failed tool calls, together — what you'd want to know
-   * first on coming back. */
   errors: number;
-  /** Approvals still waiting. Not a count of what happened, but the reason to
-   * look now rather than later. */
-  pending: number; /** Any of the above non-zero. A recap of nothing is noise. */
+  pending: number;
   any: boolean;
 };
-/** The `TranscriptState` fields a recap reads — structural, so a caller can
- * pass the whole state or just these. */
 type RecapInput = {
   items: readonly TranscriptItem[];
   pendingApprovals?: readonly unknown[];
 };
-/**
- * Summarize the items from `fromIndex` onward — the boundary being the number
- * of items that existed when the session was last looked at.
- *
- * An out-of-range boundary is clamped rather than rejected: a transcript can
- * *shrink* (a `/clear`, a fresh attach after a compaction), and the honest
- * reading of "you last saw 40 items, there are now 12" is "everything here is
- * new", not a negative count.
- */
 declare function summarizeSince(state: RecapInput, fromIndex: number): RecapSummary;
-/**
- * The recap as one line of text, in the order a person reads it: what got done,
- * what it used, what went wrong, what is waiting.
- *
- * Returns `undefined` when there is nothing to say, so a caller can render the
- * row or not on the value alone.
- */
 declare function recapLine(summary: RecapSummary): string | undefined;
 //#endregion
-export { type AttachmentKind, type ClientForHost, 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, hydrateToolResult, initialOpenFilesState, initialReplayTarget, initialTranscriptState, isDirty, openFilesReducer, rateLimitWindows, recapLine, scanPromptTokens, seedFromSessionInfo, staleAttach, summarizeSince, useAttachments, useClaudeSession, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useProfileUsage, useProjectIcons, useSessionInfo, useToolCallHost };
+export { type AttachmentKind, type ClientForHost, type ClientToolHandler, type ClientToolResult, 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 ToolResultImageRef, type TranscriptItem, type TranscriptState, type UseAttachmentsOptions, type UseAttachmentsResult, type UseClaudeSessionOptions, type UseClaudeSessionResult, type UseDraftResult, type UseHostFileRootsResult, type UseHostFileSearchResult, type UseHostFileTreeResult, type UseOpenFilesResult, type UseProfileUsageOptions, type UseProfileUsageResult, type UseSessionInfoResult, type UseToolCallHostOptions, ancestorsWithin, applyEvent, attachmentKind, clearDrafts, clearProfileUsageCache, clearTranscriptCache, createToolCallHost, currentText, flattenHostTree, hydrateToolResult, initialOpenFilesState, initialReplayTarget, initialTranscriptState, isDirty, openFilesReducer, rateLimitWindows, recapLine, scanPromptTokens, seedFromSessionInfo, staleAttach, summarizeSince, useAttachments, useClaudeSession, useDraft, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useProfileUsage, useProjectIcons, useSessionInfo, useToolCallHost };
 //# sourceMappingURL=index.d.mts.map