@workerdeck/react 0.7.0 → 0.10.0

package/README.md

@@ -77,11 +77,41 @@ stream doesn't carry yet; events stay authoritative once they arrive.
 - `pendingApprovals` — permission requests awaiting an approve/deny decision.
 - `status` / `statusDetail`, `model`, `cwd`, `sdkSessionId`, `permissionMode`.
 - `models` and `commands` — what the session can switch to / accepts (from `capabilities`).
+- `capabilities` — **the engine's capability record**, always present: the runner-reported copy
+  from the attach snapshot, else the protocol's static default for the engine. Render affordances
+  from this rather than switching on the engine name; an absent capability means the control is
+  *hidden*, never one that silently does nothing.
+- `session` — the whole attach snapshot, for the facts no event carries (profile, `apiKeySource`,
+  `canBypassPermissions`, `createdAt`).
 - `contextUsage`, `rateLimits` (keyed by window; absent for API-key sessions — render nothing,
-  not 0%), `totalCostUsd` (session-cumulative), and `lastSeq` for replay dedupe.
+  not 0%) with `rateLimitsUpdatedAt`, `totalCostUsd` (session-cumulative), and `lastSeq` for
+  replay dedupe.
 
 The reducer is pure and immutable: same events in, same state out — which is also how it is
-unit-tested. Keep rendering logic out of it.
+unit-tested. Keep rendering logic out of it. `rateLimitWindows(state)` and `scanPromptTokens(text)`
+are the other pure helpers here, for the same reason: ordered usage windows and `@file` /
+`/command` token recognition are string-and-shape work every client needs and every client should
+agree on.
+
+## Composing a message
+
+Two more hooks cover what a composer needs beyond text, both capability-aware:
+
+```tsx
+const { state, send } = useClaudeSession(client, sessionId)
+// Staging + upload, filtered by `capabilities.attachments`: a kind the engine
+// forswears is refused locally instead of 415'ing at the gateway.
+const attachments = useAttachments(client, sessionId, {
+  capabilities: state.capabilities,
+  engine: state.engine,
+})
+// `@file` search rooted at the session's cwd. `available` is false when the
+// gateway serves no host files — don't advertise what isn't there.
+const files = useHostFileSearch(client, state.cwd)
+
+attachments.add(pickedFiles) // uploads start immediately
+send(text, attachments.readyIds) // the message names ids; bytes never enter the event log
+```
 
 ## Running tool calls in the tab
 

package/build/index.d.mts

@@ -1,5 +1,5 @@
+import { ContextUsage, EngineCapabilities, HostDirEntry, HostFileMatch, MessageAttachment, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, RateLimitInfo, SessionEvent, SessionInfo, SessionStatus, SkillInfo, SlashCommandInfo, ToolExecutionBackend } from "@workerdeck/protocol";
 import { SessionHandle, WorkerDeckClient } from "@workerdeck/client";
-import { ContextUsage, ModelOption, PermissionMode, PermissionRequest, ProfileEngine, RateLimitInfo, SessionEvent, SessionInfo, SessionStatus, SlashCommandInfo, ToolExecutionBackend } from "@workerdeck/protocol";
 import { RunScriptResult, SandboxEngine, SandboxVfs } from "@workerdeck/sandbox";
 
 //#region src/transcript.d.ts
@@ -11,6 +11,7 @@ type TranscriptItem = {
   kind: 'user';
   id: string;
   text: string;
+  attachments?: MessageAttachment[];
 } | {
   kind: 'assistant_text';
   id: string;
@@ -69,6 +70,12 @@ type TranscriptItem = {
   bytes: number;
   description?: string;
 };
+/** A `file_produced` announcement, as the transcript keeps it. */
+type ProducedFileRef = {
+  fileId: string;
+  mediaType?: string;
+  bytes?: number;
+};
 type TranscriptState = {
   status: SessionStatus;
   statusDetail?: string;
@@ -77,14 +84,61 @@ type TranscriptState = {
   sdkSessionId?: string;
   /** Engine running the session, from the attach snapshot. Gates CLI-only
    * affordances; absent (an older server) reads as 'claude'. */
-  engine?: ProfileEngine; /** Models the session can switch to (from the `capabilities` event). */
+  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). */
-  commands?: SlashCommandInfo[]; /** Seeded from `system_init`, updated on `permission_mode_changed`. */
+  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. */
   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[];
   totalCostUsd: number;
@@ -98,9 +152,32 @@ declare const initialTranscriptState: TranscriptState;
  * 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.
+ *
+ * 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".
+ */
+declare function rateLimitWindows(state: TranscriptState): Array<{
+  key: string;
+  info: RateLimitInfo;
+}>;
 declare function applyEvent(state: TranscriptState, event: SessionEvent): TranscriptState;
 //#endregion
 //#region src/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';
 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
@@ -109,23 +186,465 @@ type UseClaudeSessionOptions = {
 };
 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;
+  /** 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;
-  send: (text: string) => void;
+  handle: SessionHandle | undefined; /** Attachment ids come from `client.uploadAttachment`, in send order. */
+  send: (text: string, attachmentIds?: string[]) => void;
   approve: (requestId: string, updatedInput?: Record<string, unknown>) => void;
-  deny: (requestId: string, message?: string) => 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;
   setPermissionMode: (mode: PermissionMode) => void;
   setModel: (model?: string) => void;
-  closeSession: () => void;
+  closeSession: () => void; /** Skip the reconnect backoff — what a tab returning to the foreground does. */
+  reconnectNow: () => void;
 };
 /** 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
+/**
+ * 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;
+  name: string;
+  mediaType: string;
+  bytes: number; /** Object URL for an image thumbnail, revoked when the item goes away. */
+  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, …). */
+  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. */
+  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. */
+  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/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. */
+  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/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. */
+  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. */
+  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/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.
+   */
+  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. */
+  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/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. */
+  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/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. */
+  name: string;
+  status: 'loading' | 'ready' | 'binary' | 'error'; /** The text **as last seen on disk** — never the user's edits. */
+  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. */
+  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. */
+  activePath?: string;
+};
+type OpenFilesAction = {
+  type: 'open';
+  path: string;
+} | {
+  type: 'close';
+  path: string;
+} | {
+  type: 'closeAll';
+} | {
+  type: 'activate';
+  path: string;
+} /** A read landed. Ignored if the tab was closed while it was in flight. */ | {
+  type: 'loaded';
+  path: string;
+  content: string;
+  encoding: 'utf8' | 'base64';
+  bytes: number;
+  hash: string;
+  modifiedAt: number;
+} | {
+  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;
+  bytes: number;
+  hash: string;
+  modifiedAt: number;
+} | {
+  type: 'saveFailed';
+  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/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. */
+  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. */
+  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. */
+  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/tool-host.d.ts
 /** What the host was asked to do and how it went (for UI/telemetry). */
 type ToolHostExecution = {
@@ -193,5 +712,5 @@ declare function useToolCallHost(handle: SessionHandle | undefined, options?: Us
   executions: ToolHostExecution[];
 };
 //#endregion
-export { type ToolCallHostOptions, type ToolHostExecution, type ToolHostRunner, type TranscriptItem, type TranscriptState, type UseClaudeSessionResult, type UseToolCallHostOptions, applyEvent, createToolCallHost, initialTranscriptState, seedFromSessionInfo, useClaudeSession, useToolCallHost };
+export { type AttachmentKind, type ConnectionState, type HostDirState, type HostTreeRow, type OpenFile, type OpenFilesAction, type OpenFilesState, type ProducedFileRef, type PromptToken, 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, scanPromptTokens, seedFromSessionInfo, useAttachments, useClaudeSession, useHostFileRoots, useHostFileSearch, useHostFileTree, useOpenFiles, useSessionInfo, useToolCallHost };
 //# sourceMappingURL=index.d.mts.map