@workerdeck/protocol 0.15.0 → 0.17.0

package/build/index.d.mts

@@ -20,8 +20,32 @@ type SessionState = 'attention' | 'working' | 'idle' | 'ended';
 declare const STATE_ORDER: readonly SessionState[];
 declare const STATE_LABELS: Record<SessionState, string>;
 declare function sessionState(info: SessionInfo): SessionState;
+/**
+ * The sub-agents a list row draws as live.
+ *
+ * `sessionState` deliberately does **not** grow a `subagents` bucket — a fifth
+ * state would split `working` in two for every client that filters by it,
+ * including the ones that have not shipped this yet. Instead `working` *counts*
+ * them: a synchronous `Task` keeps the turn in flight so the status already
+ * says `working`, and a **background** agent — which outlives its turn on
+ * purpose — is the carve-out the extra arm in `sessionState` exists for.
+ * That is what makes "sub-agents are an annotation on a working row" true
+ * rather than assumed: the row is in the working bucket whichever kind is
+ * running, and this list only says more about it.
+ */
+declare function runningSubagents(info: SessionInfo): SubagentInfo[];
+/**
+ * A sub-agent's identity on one line: `Explore · find the auth check`.
+ *
+ * The same two fields `taskLabel` builds its transcript row from, minus the
+ * `Task(…)` wrapper — a list row is already inside a session, so naming the tool
+ * spends the width that the description needs. Falls back to the bare agent type,
+ * then to a generic word: a row with no label at all reads as a rendering bug,
+ * and an engine is free to send neither field.
+ */
+declare function subagentLabel(sub: SubagentInfo): string;
 /** The facets a session can be grouped or sorted by. */
-type Facet = 'gateway' | 'adapter' | 'state';
+type Facet = 'gateway' | 'adapter' | 'state' | 'project';
 type GroupBy = 'none' | Facet;
 type SortBy = 'recent' | 'name' | Facet;
 type ViewConfig = {
@@ -29,6 +53,16 @@ type ViewConfig = {
   gateways: string[];
   adapters: string[];
   states: SessionState[];
+  /**
+   * Empty = no filter. Keys are {@link projectKey} output — never names, which
+   * are neither unique (two repos both called "api") nor stable (editing
+   * `.workerdeck.json` renames every session at once and must not empty a
+   * saved filter). Optional, unlike its three siblings, because stored view
+   * configs predate it: a config restored from `localStorage`/`globalState`
+   * without the key must keep filtering, so absent and empty mean the same
+   * thing.
+   */
+  projects?: string[];
   /** Show only sessions inside the host's own folders. Inert where there is no
    * such notion (no folder open, a dashboard with no workspace), which is why it
    * can default on. */
@@ -74,7 +108,51 @@ type SessionGroup = {
 /** The adapters actually present, for the filter chips — derived rather than
  * enumerated, so a new engine needs no change here. */
 declare function adaptersOf(rows: readonly SessionRow[]): string[];
+/**
+ * The projects actually present, as `{ key, label }` for a filter control —
+ * derived like {@link adaptersOf}, and paired because the two halves differ:
+ * the *key* is what {@link ViewConfig.projects} holds (gateway-qualified root,
+ * so a rename regroups nothing) and the *label* is what a person picks by.
+ *
+ * Sorted by label, deduped by key. Two projects with the same name on two
+ * gateways therefore stay two entries wearing one word — which is honest: they
+ * really are two different directories, and the alternative is a filter that
+ * silently selects both.
+ */
+declare function projectsOf(rows: readonly SessionRow[]): {
+  key: string;
+  label: string;
+}[];
 declare function sessionLabel(info: SessionInfo): string;
+/**
+ * The project facet's grouping key: gateway id + the project root, falling
+ * back to the session's cwd when no project is declared.
+ *
+ * The root and not the name, because a name is not a key (two repos can both
+ * be called "api", and a rename must regroup nothing); qualified by gateway,
+ * because a remote gateway's identical-looking path is another machine's
+ * directory — the same rule `ScopeRoot` states. The cwd fallback is what makes
+ * grouping by project useful before anyone has written a `.workerdeck.json`:
+ * undeclared sessions group by their folder, declared ones by their root, and
+ * a session in `packages/ui` joins its repo's group the moment the file
+ * exists. Sessions with no cwd at all (a filesystem-less engine) share one
+ * per-gateway bucket — see {@link projectLabel}.
+ */
+declare function projectKey(row: SessionRow): string;
+/**
+ * What a project group (or a row's project slot) is called: the declared name,
+ * else the cwd's basename — the exact string clients rendered before this
+ * feature existed, so an undeclared project looks like today. 'No project' is
+ * only ever the no-cwd case (a sandboxed provider session), where there is no
+ * folder to name.
+ *
+ * Takes only the `info` it reads, so a surface holding a bare `SessionInfo` —
+ * a row component, an iOS cell — can call it without inventing the rest of a
+ * `SessionRow`. That matters more than it looks: this string is what a client
+ * renders *in place of* the cwd basename it used to draw, and two spellings of
+ * it would put the list and its group headers on different names.
+ */
+declare function projectLabel(row: Pick<SessionRow, 'info'>): string;
 /**
  * This session is a job run — the queue created it, and `JobInfo.sessionId`
  * points at it.
@@ -136,6 +214,72 @@ declare function hasFacetFilter(config: ViewConfig): boolean;
  * choices are a layout preference and survive. */
 declare function clearFilters(config: ViewConfig): ViewConfig;
 //#endregion
+//#region src/usage.d.ts
+/**
+ * What one session was last told about the plan's windows: the transcript's own
+ * rate-limit state, and the event clock of the newest reading in it.
+ *
+ * Deliberately structural rather than `TranscriptState` — protocol may not
+ * import a client — and it is exactly the two fields the reducer keeps.
+ */
+type SessionUsage = {
+  /** Keyed by `rateLimitType`, as the reducer stores it. */rateLimits?: Record<string, RateLimitInfo>;
+  /** Epoch ms of the newest `rate_limit` event this session saw — one clock for
+   * the whole map, which is all the reducer records. */
+  updatedAt?: number;
+};
+/**
+ * The usage a client should render: the gateway's per-profile state where it has
+ * the window, this session's own reading where it does not.
+ *
+ * Why the profile wins outright rather than by comparing timestamps: the
+ * gateway's `ProfileUsageTracker` is fed from **every** session on the profile —
+ * including this one, from seq 0 — and keeps the newest reading per window by
+ * the event's own `ts`. So for any window it holds, it holds a reading at least
+ * as new as the one in this transcript, and a timestamp comparison could only
+ * ever go wrong: the reducer keeps a *single* `updatedAt` for the whole map, so
+ * a `five_hour` reading from this morning is dated with the afternoon's
+ * `seven_day` event and would beat a genuinely fresher profile entry.
+ *
+ * The session half is not a fallback for correctness but for *coverage*: the
+ * profile map is in-memory, so a restarted gateway serves nothing until a
+ * session reports again, and a session with no profile has no account state at
+ * all. In both cases the transcript's reading is the only one there is, and it
+ * is dated honestly (see {@link SessionUsage.updatedAt}) rather than as now.
+ *
+ * Absent stays absent throughout: a window nobody has reported is **unknown,
+ * never 0%**, and this returns an empty map rather than inventing entries.
+ */
+declare function mergeUsage(session: SessionUsage, profile: ProfileUsage | undefined): ProfileUsage;
+/** One window as a surface draws it: the reading, its own date, and whether the
+ * gateway is the one that zeroed it. */
+type UsageWindowRow = {
+  key: string;
+  info: RateLimitInfo; /** Epoch ms of the reading. Absent only for a hand-built state with no clock. */
+  updatedAt?: number;
+  inferredReset?: boolean;
+};
+/**
+ * The windows in reading order: the session window, the weekly one, then the
+ * per-model weeklies alphabetically.
+ *
+ * Discovered rather than hardcoded — the engine's set of windows is an open
+ * union and has grown before — but ordered, so the first two always mean the
+ * same thing wherever they are drawn. A window with no `utilization` is
+ * **unknown, not zero**, and is dropped entirely rather than rendered as an
+ * empty bar that reads as "plenty left".
+ *
+ * Here rather than in a client because two surfaces now render the same windows
+ * from different sources — the session panel from its merged state, the
+ * dashboard's profile page straight off `ProfileInfo.usage` — and a list that
+ * ordered or filtered differently would be the same account described two ways.
+ */
+declare function orderUsageWindows(usage: ProfileUsage | undefined): UsageWindowRow[];
+/** The flat `rateLimitType → reading` map every existing renderer takes, out of
+ * the dated form. Undefined in, undefined out — so a surface can keep telling
+ * "no reading" apart from "an empty one". */
+declare function usageInfos(usage: ProfileUsage | undefined): Record<string, RateLimitInfo> | undefined;
+//#endregion
 //#region src/watermarks.d.ts
 /**
  * "What had you seen, and when" — per session, across reloads.
@@ -263,12 +407,171 @@ type ToolResultBlock = {
     [key: string]: unknown;
   }>;
   is_error?: boolean;
+  /**
+   * This block carries only the **head** of the result: the replay truncated it
+   * (see {@link TOOL_RESULT_HEAD_CHARS}), and the whole thing is one fetch away
+   * at `GET /sessions/:id/events/:seq/result?toolUseId=`.
+   *
+   * On the **block**, never the event, and that is the same argument
+   * `user_message.patch` has to make in reverse: the patch sits on the event and
+   * its doc must therefore caveat "only when the message carries exactly one
+   * `tool_result` block — with two, nothing says which one it belongs to". A
+   * message answering three calls truncates whichever of them is large, so
+   * paying that caveat a second time would make the marker unusable exactly
+   * when it matters. {@link FilePatch.truncated} is the shipped precedent.
+   *
+   * Only ever set on a **replay** a client asked for (`truncateResults`), so a
+   * client that has never heard of this field cannot receive one — which is why
+   * this is additive at protocol 7 rather than a bump. Absent means the block is
+   * whole.
+   */
+  truncated?: boolean;
+  /** How many characters the untruncated result had. Set iff `truncated`.
+   *
+   * A client cannot compute it — it holds the head — and the number is not
+   * cosmetic: a collapsed row spells "… +N chars", and `height.ts` sizes the row
+   * by wrapping **that exact string**, so a count derived from the head would be
+   * both a lie and a different pixel height. */
+  total_chars?: number;
 };
+/**
+ * How much of a tool result a truncating replay keeps.
+ *
+ * Chosen against the two clients' *own* budgets, and the relationship is the
+ * whole point: the terminal theme shows ~400 characters collapsed and ~2,000
+ * open, so at 8,000 the collapsed and open states are **byte-identical to an
+ * untruncated attach** and only the uncapped "show everything" press ever
+ * fetches. That collapses the entire feature to one press, and it is asserted
+ * in a test rather than trusted — lowered below the open budget, this would
+ * silently clip the open state with no marker, which is the one failure this
+ * design must not have.
+ *
+ * Measured justification: on one 1,270-row session three `tool_result` frames
+ * were 641 / 463 / 396 KB, 68% of a 3.1 MB attach. The cut is *structural* —
+ * proportional to the thing that is actually large, wherever in the log it sits
+ * — which a row window is not.
+ */
+declare const TOOL_RESULT_HEAD_CHARS = 8000;
+/**
+ * A base64 image part, delivered as an address instead of its bytes.
+ *
+ * The **seventh** rule of the family, and the first written *after* its
+ * measurement rather than before it. Across 214 local sessions, 91% of all
+ * tool-result payload is base64 image data — 489 MB against 44 MB of text — and
+ * **no client renders a byte of it**: `blockText` in the reducer and
+ * `joinedText` on iOS both fold a `tool_result` to its text parts, and both
+ * clients draw a tool's picture from a host *path* (`savedPath` → `/produced`,
+ * `/fs/read`), never from block content. So it is `replayRetains`' argument at
+ * nine times the size of the case that rule was written for: bytes whose entire
+ * effect on the reader is `return base`.
+ *
+ * A **new part type rather than a hollowed-out `image`**, and that is the one
+ * judgement here worth stating. `headOf`'s shape-preservation rule — "a
+ * truncation is a shorter result, never a different kind of one" — cuts the
+ * other way for pixels: a head *is* a valid shorter text, but an image with no
+ * bytes is not a smaller image, and spelling it `{ type: 'image', source }` with
+ * no `data` invites precisely the failure shape-preservation exists to prevent,
+ * a renderer that trusts `source.data` drawing `data:;base64,undefined`. An
+ * unfamiliar type instead falls through every fold that already exists, exactly
+ * as the CLI's own `tool_reference` part does: no `text`, so it contributes
+ * nothing, and an unaware consumer renders what it renders today, which is
+ * nothing. That is this family's safe failure.
+ *
+ * Only ever produced for a socket that asked (`imageRefs`), so a client that has
+ * never heard of this type cannot receive one — which is why this is additive at
+ * protocol 7, the same argument {@link ToolResultBlock.truncated} makes. Unlike
+ * truncation it applies to **live events as well as replays**: the client's one
+ * render path is ref-then-fetch, so bytes on a live event would either be
+ * discarded (335 KB median, once per attached watcher) or need a second
+ * decode-from-event path pinning megabytes inside the transcript cache — the
+ * disease relocated rather than cured.
+ */
+type ImageRefPart = {
+  type: 'image_ref';
+  /** The stored part's own media type (`image/png`, `image/jpeg` and
+   * `image/webp` are the three observed), or `application/octet-stream` when it
+   * had none. Never the membership test — that is `image` plus a base64 source. */
+  media_type: string;
+  /** Decoded size, which a client cannot compute from an address it has not
+   * fetched yet. Not cosmetic: the placeholder spells it, and in the terminal
+   * theme a rendered string *is* a row height. */
+  bytes: number;
+  /**
+   * Index of this part in the **stored** block's content array, and the address
+   * a fetch is made with.
+   *
+   * A stamped field rather than the position it arrives at, because that
+   * position is not stable: `headOf` builds a truncated head by keeping text
+   * parts up to budget and dropping every other part, so a block that is both
+   * over the text budget and image-bearing has its parts renumbered the moment
+   * the two rules compose. Stamped, the address survives any later reshaping —
+   * and the route verifies it against the stored block rather than trusting it.
+   */
+  part_index: number;
+};
+/**
+ * Project one `tool_result` content part onto its {@link ImageRefPart}, or
+ * `undefined` when the part is not a base64 image and must be delivered as it
+ * stands.
+ *
+ * The rule's **one spelling**, shared by the transform that replaces parts
+ * (core), the route that serves them back (server) and the property test that
+ * proves the fold is otherwise unchanged (react) — the same reason every other
+ * member of this family lives here rather than in whichever package applies it.
+ *
+ * Deliberately narrow. The corpus holds exactly two non-text part kinds: this
+ * one, and the CLI's `tool_reference`, of which every instance across 214
+ * sessions totals 122 KB. A "drop non-text parts" rule would sweep those in for
+ * no measurable gain, and narrowness is this family's standing habit.
+ */
+declare function imagePartRef(part: {
+  type?: string;
+  [key: string]: unknown;
+}, index: number): ImageRefPart | undefined;
 /** Forward-compatible fallback for block types this protocol version doesn't model. */
 type UnknownBlock = {
   type: string;
   [key: string]: unknown;
 };
+/**
+ * One hunk of a file edit, in unified-diff terms.
+ *
+ * The numbers are the engine's own, not the client's: `newStart` is where this
+ * hunk begins in the file *after* the edit, which is what a reader needs to jump
+ * to the change. A client cannot compute them — it has never seen the file — so
+ * a diff rendered without this is a diff with no line numbers.
+ */
+type PatchHunk = {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  /** Body lines, each prefixed ' ' (context), '-' (removed) or '+' (added), as
+   * unified diff spells them. The prefix is part of the string. */
+  lines: string[];
+};
+/**
+ * What a file-editing tool changed — the renderable half of an engine's edit
+ * output, and deliberately only that half.
+ *
+ * Both engines can say far more: the Claude SDK's `FileEditOutput` carries
+ * `originalFile`, the **entire** contents of the file before the edit. That must
+ * not travel here. This log is replayed to every attaching client and captured
+ * into parking snapshots, so a whole file on every edit is paid for again on
+ * every attach, forever — the same reason attachment bytes are references (see
+ * {@link MessageAttachment}) rather than inline base64.
+ *
+ * So the runner projects the engine's output down to the hunks, which is exactly
+ * what a diff renders and nothing more.
+ */
+type FilePatch = {
+  /** Absolute path the engine reported, when it named one. */path?: string; /** `create` when the file did not exist before this edit. */
+  kind?: 'create' | 'update';
+  hunks: PatchHunk[];
+  /** Hunks were dropped to keep the event small. A renderer must say so rather
+   * than present a partial diff as the whole change. */
+  truncated?: boolean;
+};
 type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock;
 /**
  * A file the user attached to a message — a photo, a screenshot, a document.
@@ -567,6 +870,28 @@ type SessionEventBody = /** SDK init handshake: what this session actually is. *
 | {
   type: 'plan_info';
   subscriptionType: string;
+}
+/**
+ * The engine started a **fresh conversation inside the same session** — the
+ * CLI's `/clear`, a plan-mode exit, and whatever fresh-conversation flows the
+ * SDK grows. The session id, registry row, workspace and scope are all
+ * unchanged; only the conversation is new. Clients empty the transcript and
+ * keep every session-scoped fact (models, commands, skills, produced files,
+ * rate limits, cwd, permission mode).
+ *
+ * The server's replay honours it too: an attach after a reset does not
+ * resurrect the cleared rows, because the runner skips *transcript content*
+ * below the latest reset (see {@link transcriptContent}) while still
+ * replaying every state-bearing event. `SessionInfo.activityCount` stays
+ * monotonic across a reset on purpose — it is an unread cursor, not an item
+ * count, and winding it back would kill every stored watermark above it.
+ */
+| {
+  type: 'conversation_reset';
+  /** The engine session id the fresh conversation runs under (the SDK's
+   * `new_conversation_id`), when the engine reported one. The follow-up
+   * `system_init` remains authoritative. */
+  sdkSessionId?: string;
 } | {
   type: 'assistant_message';
   message: ApiMessage; /** Set when the message was produced inside a subagent (Task tool). */
@@ -583,6 +908,16 @@ type SessionEventBody = /** SDK init handshake: what this session actually is. *
    * `message.content` carries the typed text only — the attachment bytes went
    * to the model, not into this log. */
   attachments?: MessageAttachment[];
+  /**
+   * What a file-editing tool changed, when this message carries that tool's
+   * result (see {@link FilePatch}). Set by the runner from the engine's own
+   * structured output — never derived by a client from the result text.
+   *
+   * Only when the message carries exactly one `tool_result` block, which is
+   * what both engines send: with two, there is nothing that says which one
+   * the patch belongs to, and guessing would attach a diff to the wrong call.
+   */
+  patch?: FilePatch;
   uuid?: string;
 }
 /** Raw Anthropic streaming event (message_start/content_block_delta/...); emitted only
@@ -924,6 +1259,37 @@ type ProfileSessionDefaults = {
   mcpServers?: string[]; /** Prepended to the session's system prompt. */
   instructions?: string;
 };
+/**
+ * One rate-limit window of a profile's plan, as the *gateway* last saw it — the
+ * newest {@link RateLimitInfo} any session on the profile reported, across every
+ * session, live or since closed. The profile is the account boundary (one config
+ * dir / codex home / provider key = one plan), so this is the single usage state
+ * per account, where a session's own transcript only knows what *it* was last
+ * told.
+ *
+ * Two rules a client must keep:
+ * - An absent window (or an absent {@link ProfileInfo.usage} entirely) is
+ *   **unknown, not 0%** — render nothing, exactly as for session-level readings.
+ *   The map is in-memory and starts empty on a cold server.
+ * - `inferredReset` marks a reading the server zeroed at serve time because the
+ *   reading's own `resetsAt` passed with nothing newer: the pre-reset number is
+ *   then provably wrong, and 0 is the truthful *floor* (the account may have
+ *   been used outside this gateway since). Distinguishable on the wire from an
+ *   engine-reported 0, which carries no flag.
+ */
+type ProfileUsageWindow = {
+  /** The reading, exactly as the session event carried it — except after an
+   * elapsed reset, when `utilization` is 0 and `resetsAt` is dropped (the old
+   * one names the *previous* window; a countdown from it would be nonsense). */
+  info: RateLimitInfo;
+  /** Epoch ms of the event that carried the reading — honest for "Updated …"
+   * lines even when the served utilization is inferred. */
+  updatedAt: number; /** Present (true) only on the served-as-0 inference described above. */
+  inferredReset?: boolean;
+};
+/** Per-window plan usage, keyed by `rateLimitType` ('five_hour', 'seven_day',
+ * ...) — the same keying as a transcript's rate-limit state. */
+type ProfileUsage = Record<string, ProfileUsageWindow>;
 type ProfileInfo = {
   /** Unique name, used as {@link CreateSessionRequest.profile}. */name: string;
   /** Engine this profile runs on. Defaults to 'claude' when absent, so profiles
@@ -961,6 +1327,11 @@ type ProfileInfo = {
   /** Response-only: one operator-actionable line, present only when
    * `available === false`. */
   unavailableReason?: string;
+  /** Response-only: the plan's rate-limit windows as last reported by any
+   * session on this profile (see {@link ProfileUsageWindow}). Absent = unknown
+   * — no session has reported yet (API-key sessions never do), or the server
+   * restarted. **Display-only**, like `available`: never a gate. */
+  usage?: ProfileUsage;
   /** Response-only, computed by the server: this profile came from the profile
    * store and can be edited or deleted through the API. Profiles declared in
    * server options are absent/false — they are code. Ignored on the way in. */
@@ -1128,6 +1499,178 @@ type CreateSessionRequest = {
    */
   scope?: Record<string, string>;
 };
+/**
+ * One sub-agent (a `Task` call and the sidechain it spawned), as a *list* surface
+ * sees it — without attaching.
+ *
+ * Sub-agent work is otherwise attach-only: it exists on the wire as
+ * `parentToolUseId` on three event bodies, and is reconstructed into rows by the
+ * react reducer and grouped per-Task by `terminalBlocks`. A sessions list never
+ * attaches (one live attach per session, owned by the panel), so it reads
+ * `SessionInfo` over REST and would otherwise have no way to know a session has
+ * six agents running inside one turn.
+ *
+ * This is a **runner-owned rollup computed at read time**, exactly like
+ * {@link SessionInfo.pendingPermissionCount}: it is not an event, it is not
+ * persisted separately, and it therefore rides the REST list, the WS attach
+ * snapshot and parking snapshots for free. Only the claude engine produces it —
+ * codex and provider emit `parentToolUseId: null` on every event, so an empty
+ * list there is the truth rather than a gap.
+ *
+ * It is deliberately **not** the input to `taskSummary`. That string is spelled
+ * from the absorbed transcript items and must stay that way, so a transcript
+ * replayed tomorrow spells the same line from the same items it holds today.
+ */
+type SubagentInfo = {
+  /** The `tool_use` id of the `Task` call that spawned it — the same id its
+   * nested events carry as `parentToolUseId`, and therefore the handle a client
+   * uses to jump to that Task's row. */
+  toolUseId: string; /** The Task input's `subagent_type` (e.g. "Explore"), when it named one. */
+  agentType?: string;
+  /** The Task input's short `description`, clipped by the runner. Together with
+   * `agentType` this is what makes two parallel sub-agents tell apart in a list;
+   * a row reading only `Task` answers nothing. */
+  description?: string;
+  /**
+   * `running` until the Task's own `tool_result` arrives, then `done`/`failed`
+   * from that result's `is_error`. A turn that ends without that result — an
+   * interrupt, a session error, a turn or budget cap — settles what is still
+   * running as `failed`: the report never came, which is the one thing `done`
+   * could have claimed, and a `running` badge on an idle session would be a
+   * lie a list re-renders at every poll.
+   *
+   * Deliberately **narrower than `taskFailed`** in `@workerdeck/ui`'s
+   * `tool-run.ts`, which reddens a Task row when *any child call* failed. That is
+   * right for a transcript row the reader can expand — the failure is one press
+   * away and hiding it would be worse. It is wrong for a list: a grep that
+   * matched nothing inside an otherwise successful Explore agent would put
+   * `failed` beside the session's name with nothing to open. So this reports the
+   * sub-agent's own outcome. If you are here to "fix" the inconsistency, this is
+   * the reason it exists.
+   */
+  status: 'running' | 'done' | 'failed'; /** Epoch ms the `Task` call was emitted. */
+  startedAt: number;
+  /** Tool calls the sub-agent has made so far — its progress reading while
+   * running, counted from nested `tool_use` blocks. */
+  toolCount: number;
+};
+/**
+ * How many *settled* sub-agents {@link SessionInfo.subagents} keeps behind the
+ * running ones. Small on purpose: the point of the tail is that a list row does
+ * not go blank the instant a run finishes, not that it is a history.
+ */
+declare const SUBAGENT_HISTORY = 8;
+/**
+ * A project's icon, as declared by its `.workerdeck.json` — either a named
+ * glyph or a reference to an image the gateway serves.
+ *
+ * A discriminated union rather than one stringly field, because the two arms
+ * have opposite render paths: a glyph is looked up in the client's own icon
+ * set with no I/O, an image is a fetch. Collapsing them would put "is this a
+ * name or an address" back on every renderer, which is the inference this
+ * family keeps refusing (`ImageRefPart` is a new part type, never a
+ * hollowed-out `image`, for the same reason).
+ *
+ * `glyph.name` is a lucide icon name, validated by the gateway for *shape*
+ * only (lowercase kebab-case): the gateway has no lucide catalog and must not
+ * grow one — icon sets version independently of this protocol. A client whose
+ * set lacks the name renders its no-project fallback rather than erroring;
+ * an unknown name is a stale row, never withheld state.
+ *
+ * `image` carries an **address, never bytes** — the attachment-bytes rule.
+ * `SessionInfo` rides every row of `GET /sessions`, which clients poll at 1.2s
+ * while anything is working, so an inlined base64 icon would be paid for on
+ * every poll of every session forever (the same argument that keeps
+ * `originalFile` off {@link FilePatch} and message bytes off events). The
+ * bytes come from `GET {basePath}/sessions/:id/project/icon` — session-scoped
+ * on purpose, so the fetch rides the same `canSee` gate as every other
+ * `/sessions/:id/*` route and a scoped principal's miss is the uniform 404. A
+ * project-keyed route would need the project root in the URL, and a route
+ * addressed by host paths is an existence oracle for the gateway's
+ * filesystem. `hash` (sha256 hex of the bytes) is the cross-session cache
+ * key: two sessions in one project serve identical bytes, so a client caches
+ * by hash rather than by URL and fetches once per project, not once per
+ * session. The route answers with `ETag: "<hash>"` and honors
+ * `If-None-Match`.
+ */
+type ProjectIcon = {
+  type: 'glyph';
+  name: string;
+} | {
+  type: 'image';
+  mediaType: 'image/png' | 'image/svg+xml';
+  hash: string;
+};
+/**
+ * Project identity for a session — what a `.workerdeck.json` in the session's
+ * ancestry declares, resolved by the **gateway** and shipped on
+ * {@link SessionInfo.project}.
+ *
+ * The gateway reads the file, not each client: the iOS app and a browser
+ * pointed at a remote gateway have no access to that filesystem, so a
+ * per-client reader would make the feature exist on exactly one client.
+ * Discovery is an ancestor walk from the session's `cwd` upward — nearest
+ * `.workerdeck.json` wins, so a session started in `packages/ui` still says
+ * "WorkerDeck" — over the *realpath'd* cwd, which is what makes `root`
+ * canonical below.
+ *
+ * The file's schema, stated here because this type is its wire projection
+ * (clients never read the file; the gateway is its only parser):
+ *
+ * ```json
+ * { "name": "WorkerDeck", "icon": "layers" }
+ * { "name": "WorkerDeck", "icon": "./docs/assets/icon.png" }
+ * ```
+ *
+ * Both keys optional, unknown keys ignored (forward compatibility). An empty
+ * `{}` still marks its directory as the project root — grouping is the point,
+ * and the name falls back to the root's basename. `icon` is one string with a
+ * total classification rule: a value ending in `.png`/`.svg`
+ * (case-insensitive) is a repo-relative image path — relative only, since the
+ * file is checked into a repo that clones onto other machines, where an
+ * absolute path is wrong by construction — and anything else must be a
+ * lucide-shaped glyph name (`^[a-z0-9]+(-[a-z0-9]+)*$`) or it is ignored. The
+ * two shapes cannot collide (a glyph name contains no dot), so the rule is a
+ * classification, not a guess. Every degradation degrades *fieldwise and
+ * silently*: a malformed or oversized file is skipped and the walk continues
+ * to an ancestor (a broken nested file must not shadow the repo root's valid
+ * one), a junk name falls back to the basename, a junk or escaping icon is
+ * dropped — a session must never fail, or even warn, because of a display
+ * declaration.
+ *
+ * `root` — the canonical (realpath'd) absolute directory holding the file, on
+ * the **gateway's** filesystem — is the grouping key: two sessions are in the
+ * same project iff same root *on the same gateway* (a remote gateway's
+ * identical-looking path is another machine's directory — the `ScopeRoot`
+ * argument). A *name* is not a key: two repos can both be called "api".
+ * Canonicalizing at discovery is what makes two differently-spelled cwds of
+ * one project agree on it.
+ *
+ * Resolved at **serve time** from a TTL cache, never persisted — the same
+ * placement argument as the profile tracker's 0%-after-reset inference: it is
+ * a function of the gateway's current filesystem, and a copy captured into a
+ * parking record would replay a stale name forever. Editing the file shows up
+ * on every session in the project within the TTL, with no migration and no
+ * event.
+ *
+ * Additive at protocol **7**: an optional field on `SessionInfo`, where
+ * absent means exactly what today's wire means (no project declared — render
+ * the folder basename), an old client ignores it, and a new client against an
+ * old gateway sees absent. The icon route is likewise unreachable by
+ * accident: a client only fetches it when this gateway told it an image
+ * exists.
+ */
+type ProjectInfo = {
+  /** Display name — the file's `name`, else the root's basename. Never empty. */name: string;
+  /** Canonical absolute path of the directory holding `.workerdeck.json`, on
+   * the gateway's filesystem. The grouping key (per gateway); an opaque string
+   * to clients beyond equality and display. */
+  root: string;
+  /** Absent = the file declared none (or declared one the gateway refused —
+   * malformed, escaping, oversized — which a client cannot and must not
+   * distinguish). */
+  icon?: ProjectIcon;
+};
 type SessionInfo = {
   /** Server-assigned id (stable across SDK session forks/resumes). */id: string; /** Underlying Agent SDK session id, once known; use for `resume`. */
   sdkSessionId?: string;
@@ -1158,6 +1701,22 @@ type SessionInfo = {
   createdAt: number; /** Highest event seq emitted so far; attach with `afterSeq` to catch up. */
   lastSeq: number;
   pendingPermissionCount: number;
+  /**
+   * Sub-agents this session has running, plus a short tail of settled ones — see
+   * {@link SubagentInfo}. Absent on an engine that has no sidechains and on an
+   * older server; **absent and empty mean the same thing to a client**, so render
+   * nothing rather than "0 sub-agents".
+   *
+   * Bounded on purpose. This rides every row of `GET /sessions`, which a busy
+   * client polls at 1.2s, and it is captured into parking snapshots — the same
+   * attachment-bytes rule that keeps whole files off {@link FilePatch}. Every
+   * *running* sub-agent is always present (they are the live reading and there
+   * are never many at once); settled ones are kept newest-first to
+   * {@link SUBAGENT_HISTORY} and then dropped, so a day-long session with two
+   * hundred Tasks does not grow an unbounded field. A client must therefore not
+   * treat this as the session's full Task history — the transcript is that.
+   */
+  subagents?: SubagentInfo[];
   meta?: Record<string, unknown>; /** Display title: `meta.title` if the host set one, else derived (e.g. first prompt). */
   title?: string; /** Cumulative cost across all turns so far (sum of turn_result totals). */
   totalCostUsd?: number; /** Cumulative turn count across the session. */
@@ -1172,6 +1731,13 @@ type SessionInfo = {
    * `lastSeq` cannot either — it counts every event, and with token streaming on
    * that is hundreds per reply. Absent on an older server; a client should fall
    * back to `numTurns` rather than showing nothing.
+   *
+   * Monotonic for the session's whole life, **including across a
+   * `conversation_reset`**: after a `/clear` this deliberately exceeds the
+   * number of rows a fresh attach renders. It is an unread *cursor* diffed
+   * against stored monotonic watermarks (see `watermarks.ts`) — resetting it to
+   * the new row count would leave every stored mark above it, and that
+   * session's badge dead until the count caught back up.
    */
   activityCount?: number; /** Epoch ms of the most recent emitted event. */
   lastActivityAt?: number;
@@ -1179,6 +1745,15 @@ type SessionInfo = {
    * {@link CreateSessionRequest.scope}. Echoed by the runner, re-stamped by the
    * gateway, and never editable. */
   scope?: Record<string, string>;
+  /**
+   * Project identity discovered from the session's `cwd` — see
+   * {@link ProjectInfo}. Stamped by the **gateway at serve time** (runners
+   * never set it; a runner-echoed value would be persisted into parking
+   * records and replay a stale name forever). Absent = no `.workerdeck.json`
+   * in the cwd's ancestry, and also = an older gateway: both mean "render the
+   * folder basename", which is exactly today's behaviour.
+   */
+  project?: ProjectInfo;
 };
 /**
  * How many transcript rows an event materializes — the unit behind
@@ -1196,6 +1771,167 @@ type SessionInfo = {
  * reducer's row rule changes, change this with it.
  */
 declare function transcriptActivity(body: SessionEventBody): number;
+/**
+ * Whether an event is **transcript content** — whether the reducer
+ * (`@workerdeck/react`'s `transcript.ts`, and its Swift mirror) mutates
+ * `items` when it applies it. The rule behind `conversation_reset`'s replay
+ * semantics: the runner keeps its whole event log, but `subscribe()` skips
+ * content below the latest reset so an attaching client does not resurrect a
+ * cleared conversation — while every *state-bearing* event (`system_init`,
+ * `capabilities`, `skills`, `status_changed`, usage and rate-limit readings,
+ * `file_produced`, permission bookkeeping) still replays, because a fresh
+ * attacher with no model list and no cwd is broken, not cleared.
+ *
+ * Deliberately **broader than `transcriptActivity() > 0`**: stream deltas,
+ * tool results (synthetic user messages) and execution lifecycle events count
+ * zero rows but still mutate items — replaying them across a reset would leave
+ * orphaned deltas and results with no parent message.
+ *
+ * `conversation_reset` itself is content under this rule, and that is load-
+ * bearing twice: a *superseded* reset (below a newer one) is skipped with the
+ * conversation it cleared, while the latest reset always replays (the skip is
+ * strictly-below), which is what clears a reconnecting client that still holds
+ * pre-reset rows.
+ *
+ * Lives here beside {@link transcriptActivity} for the same reason: the
+ * reducer owns the rule and the runners filter with it, and the two sides may
+ * not import each other. If the reducer's items-mutating set changes, change
+ * this with it. Unknown/future event types are NOT content — the safe failure
+ * is replaying a stale row, never withholding state.
+ */
+declare function transcriptContent(body: SessionEventBody): boolean;
+/**
+ * The dedupe key for an event that is **last-write-wins** on replay, or
+ * `undefined` for one that must always be delivered.
+ *
+ * The problem: the runner polls context usage and the plan's rate limits after
+ * every turn, so a fifty-turn session's log holds fifty context readings and
+ * fifty per rate-limit window. Replaying all of them is not merely wasteful —
+ * it is *visible*. A client applies each in turn, so opening a session shows
+ * the usage meters counting up from the session's first reading to its last
+ * over the length of the replay, announcing history as if it were news.
+ *
+ * The fix is a backwards scan over the buffered log keeping the first
+ * occurrence of each key, which is `staleReplaySeqs` in `@workerdeck/core`.
+ * The key is per *window* for rate limits, not per event type: the reducer
+ * stores them keyed by window ("so five_hour and seven_day updates don't
+ * clobber each other"), so a single key would keep only the most recently
+ * polled window and silently drop the others.
+ *
+ * **This is a claim about the reducer**, which is why it lives here rather
+ * than in core: only the server coalesces, but only `@workerdeck/react` can
+ * prove the rule correct, and neither package may import the other. The
+ * property that must hold is that coalescing is *unobservable* — folding the
+ * full log and the coalesced log through `applyEvent` yields identical state.
+ * `packages/react/test/replay-coalesce.test.ts` asserts exactly that, over
+ * every event kind. Extend the rule only with a case that test still passes.
+ *
+ * Three kinds are deliberately **excluded** despite looking eligible:
+ *
+ * - `capabilities` — `defaultModel: event.defaultModel ?? base.defaultModel`
+ *   is a fallback *merge*, so a later event without one would erase an earlier
+ *   event's. (It is also emitted once per session, so there is nothing to win.)
+ * - `model_changed` — `undefined` means "reset to the server default" and the
+ *   reducer *keeps* the last known model, so the last event alone is not the
+ *   same as the fold.
+ * - `system_init` — pure replace for the reducer, but the server's
+ *   `watchAuthSource` reads the **first** one to decide an auth policy, and
+ *   parking treats each as a resume point.
+ *
+ * Coalescing never drops the highest-seq event, and that is load-bearing
+ * rather than incidental: the globally-last event is by definition the last of
+ * its own key, so it always survives. `useClaudeSession`'s replay hold waits
+ * for `state.lastSeq` to reach the attach's `session.lastSeq`, and would hang
+ * on a blank panel forever if a coalescer could swallow the final event.
+ */
+declare function replayCoalesceKey(body: SessionEventBody): string | undefined;
+/**
+ * Does a **replay** have to deliver this event, or may it be dropped outright?
+ *
+ * The fifth of the family, and the closest relative of {@link snapshotRetains} —
+ * the same claim ("no client can tell") pointed at the wire instead of at a
+ * store. The difference from {@link replayCoalesceKey} is that this is not
+ * last-write-wins: there is nothing to keep. These are events the reducer reads
+ * and *discards*, so a replay that sends them is spending the reader's network
+ * on frames whose whole effect is `return base`.
+ *
+ * Today that is exactly one thing, and it is the second-largest item in a real
+ * attach: the `stream_delta`s the reducer does not model. Measured over one
+ * 1,270-row session, the delta run was 774 KB, and **~85% of it was frames the
+ * reducer throws away** — `input_json_delta` (a tool call's arguments, streamed
+ * character by character, 383 KB), `signature_delta` (encrypted-thinking
+ * signatures, 153 KB) and the `message_start`/`content_block_start`/`_stop`
+ * scaffolding (244 KB). The reducer models two delta kinds, `text_delta` and
+ * `thinking_delta`; everything else falls through its switch untouched.
+ *
+ * What is deliberately **not** dropped, though the arithmetic would allow it:
+ *
+ * - `thinking_delta` — the Claude SDK delivers thinking blocks whose `thinking`
+ *   is `''`, and the reducer backfills them from the accumulated streamed text
+ *   (`streamedThinking`). Dropping these erases every thought from a replayed
+ *   transcript. This is the same carve-out `snapshotRetains` documents, and it
+ *   is the reason that rule is provider-engine-only.
+ * - `text_delta` — superseded by the `assistant_message` that follows it, which
+ *   filters the streaming id and rebuilds from the full content blocks. It could
+ *   go, but only with a lookahead proving the message arrived, and at 24 KB in
+ *   the measured session it is not worth a rule that has to be right about
+ *   supersession. A merge is likewise not worth it: a *drop* needs no synthesized
+ *   event and therefore no invented seq.
+ *
+ * A live event is never affected — this is about the buffered replay alone — and
+ * the caller must never drop the log's highest-seq event whatever this says, for
+ * the reason {@link replayCoalesceKey} gives: the replay hold waits for
+ * `state.lastSeq` to reach the attach's `session.lastSeq` and would hang on a
+ * blank panel forever.
+ *
+ * The property is the family's usual one and is a test rather than an argument:
+ * folding the full log and the retained log through `applyEvent` yields
+ * identical state (`packages/react/test/replay-retain.test.ts`).
+ */
+declare function replayRetains(body: SessionEventBody): boolean;
+/**
+ * Does a `RunnerSnapshot` keep this event in its persisted log?
+ *
+ * The fourth of the same family, and the same shape of claim as
+ * {@link replayCoalesceKey}: which events a *store* may drop without any client
+ * being able to tell. It exists because a snapshot embeds the whole event log,
+ * and a log is mostly stream deltas — a four-character token rides a ~180-byte
+ * JSON envelope, so the delta run is tens of times the size of the text it
+ * spells, sitting on disk *beside* the `assistant_message` that respells it in
+ * full. That was affordable while a snapshot was written once, at a park. It is
+ * not affordable written after every turn, which is what restart-survival needs.
+ *
+ * So: everything is retained except `stream_delta`. The reason that is safe is
+ * not that deltas are unimportant but that they are **superseded by
+ * construction**. The reducer upserts them under one constant id and the
+ * following `assistant_message` filters exactly that id out and rebuilds from
+ * the full content blocks — and a snapshot may only be taken at a rest point,
+ * where the stream loop has exited and flushed. Both exits flush, including the
+ * error path: an interrupted turn pushes its half-finished buffers into a
+ * durable `assistant_message` before it emits the failed `turn_result`. There is
+ * no rest state in which a delta is the only record of anything.
+ *
+ * **Provider engine only**, and this is the carve-out that must not be lost:
+ * against a *Claude* log the rule would be wrong. The Claude SDK delivers
+ * thinking blocks whose text is `''`, with the human-readable summary existing
+ * only in the delta stream, and the reducer carries the streamed text over to
+ * fill them (`transcript.ts`, the `streamedThinking` backfill). Dropping deltas
+ * there would silently erase every thought from a restored transcript. Today
+ * that is unreachable rather than merely avoided — only the provider engine
+ * implements `park()`/`snapshot()` at all, and `#restore` refuses a snapshot
+ * from another engine — but an engine that gains one inherits this obligation.
+ *
+ * Two properties hold it up, both of which are tests rather than arguments:
+ * folding the full log and the retained log through `applyEvent` yields
+ * identical state (`packages/react/test/snapshot-retain.test.ts`, the same
+ * property `replay-coalesce.test.ts` asserts), and the retained log's last event
+ * still carries the snapshot's own `seq`. The second matters more than it looks:
+ * `transcriptActivity(stream_delta)` is 0, so the count `#restore` recomputes
+ * from the log is bit-identical — a client's unread cursor cannot move — and the
+ * replay hold waits for `state.lastSeq` to reach the attach's `lastSeq`, which a
+ * rule that could drop the final event would hang forever.
+ */
+declare function snapshotRetains(body: SessionEventBody): boolean;
 /**
  * A session in an engine's on-disk store (independent of this server's registry):
  * the Agent SDK's session files, or a codex profile's CODEX_HOME threads. Listed
@@ -1631,5 +2367,5 @@ type QueueStatsResponse = {
   stats: QueueStats;
 };
 //#endregion
-export { ApiMessage, AttachedFrame, ClientFrame, ContentBlock, ContextUsage, ContextUsageCategory, CreateJobRequest, CreateJobResponse, CreateProfileRequest, CreateSessionRequest, CreateSessionResponse, DEFAULT_VIEW_CONFIG, ENGINE_CAPABILITIES, EngineCapabilities, ErrorResponse, Facet, FindHostFilesResponse, GetJobResponse, GetProfileResponse, GetSessionResponse, GroupBy, HostDirEntry, HostFileMatch, HostFileRoot, JobEvent, JobInfo, JobProgress, JobResult, JobStatus, JobUsage, ListHostDirResponse, ListHostRootsResponse, ListJobsResponse, ListProfilesResponse, ListSdkSessionsResponse, ListSessionFilesResponse, ListSessionsResponse, McpServerActionRequest, McpServerConfigWire, McpServerStatusInfo, McpServerToolInfo, McpServersResponse, MessageAttachment, ModelOption, PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, PermissionDecisionSource, PermissionMode, PermissionRequest, ProfileConfigSnapshot, ProfileDefaults, ProfileEngine, ProfileInfo, ProfileSessionDefaults, ProviderConfig, QuestionBehavior, QueueServerFrame, QueueStats, QueueStatsResponse, RateLimitInfo, ReadHostFileResponse, ResolvePermissionRequest, ResolvePermissionResponse, STATE_LABELS, STATE_ORDER, SaveProfileResponse, ScopeRoot, SdkSessionSummary, ServerFrame, SessionCapability, SessionCommand, SessionEvent, SessionEventBody, SessionFileInfo, SessionGroup, SessionInfo, SessionNotification, SessionNotificationType, SessionRow, SessionState, SessionStatus, SessionWebhookConfig, SkillInfo, SlashCommandInfo, SortBy, SubmitExecutionResultRequest, SubmitExecutionResultResponse, SubsetSummary, TextBlock, ThinkingBlock, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput, ToolExecutionStatus, ToolResultBlock, ToolUseBlock, UnknownBlock, UpdateProfileRequest, UpdateSessionRequest, UpdateSessionResponse, UploadAttachmentResponse, UserQuestion, UserQuestionOption, ViewConfig, Watermark, WatermarkStore, Watermarks, WebhookConfig, WorkspaceScope, WriteHostFileRequest, WriteHostFileResponse, adaptersOf, clearFilters, filterRows, groupRows, hasFacetFilter, inScope, isJobRun, scopeActive, sessionLabel, sessionState, subsetSummary, supportsPermissionMode, transcriptActivity, unseenCount, watermarkKey };
+export { ApiMessage, AttachedFrame, ClientFrame, ContentBlock, ContextUsage, ContextUsageCategory, CreateJobRequest, CreateJobResponse, CreateProfileRequest, CreateSessionRequest, CreateSessionResponse, DEFAULT_VIEW_CONFIG, ENGINE_CAPABILITIES, EngineCapabilities, ErrorResponse, Facet, FilePatch, FindHostFilesResponse, GetJobResponse, GetProfileResponse, GetSessionResponse, GroupBy, HostDirEntry, HostFileMatch, HostFileRoot, ImageRefPart, JobEvent, JobInfo, JobProgress, JobResult, JobStatus, JobUsage, ListHostDirResponse, ListHostRootsResponse, ListJobsResponse, ListProfilesResponse, ListSdkSessionsResponse, ListSessionFilesResponse, ListSessionsResponse, McpServerActionRequest, McpServerConfigWire, McpServerStatusInfo, McpServerToolInfo, McpServersResponse, MessageAttachment, ModelOption, PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, PatchHunk, PermissionDecisionSource, PermissionMode, PermissionRequest, ProfileConfigSnapshot, ProfileDefaults, ProfileEngine, ProfileInfo, ProfileSessionDefaults, ProfileUsage, ProfileUsageWindow, ProjectIcon, ProjectInfo, ProviderConfig, QuestionBehavior, QueueServerFrame, QueueStats, QueueStatsResponse, RateLimitInfo, ReadHostFileResponse, ResolvePermissionRequest, ResolvePermissionResponse, STATE_LABELS, STATE_ORDER, SUBAGENT_HISTORY, SaveProfileResponse, ScopeRoot, SdkSessionSummary, ServerFrame, SessionCapability, SessionCommand, SessionEvent, SessionEventBody, SessionFileInfo, SessionGroup, SessionInfo, SessionNotification, SessionNotificationType, SessionRow, SessionState, SessionStatus, SessionUsage, SessionWebhookConfig, SkillInfo, SlashCommandInfo, SortBy, SubagentInfo, SubmitExecutionResultRequest, SubmitExecutionResultResponse, SubsetSummary, TOOL_RESULT_HEAD_CHARS, TextBlock, ThinkingBlock, ToolCallRequestFrame, ToolExecutionBackend, ToolExecutionOutput, ToolExecutionStatus, ToolResultBlock, ToolUseBlock, UnknownBlock, UpdateProfileRequest, UpdateSessionRequest, UpdateSessionResponse, UploadAttachmentResponse, UsageWindowRow, UserQuestion, UserQuestionOption, ViewConfig, Watermark, WatermarkStore, Watermarks, WebhookConfig, WorkspaceScope, WriteHostFileRequest, WriteHostFileResponse, adaptersOf, clearFilters, filterRows, groupRows, hasFacetFilter, imagePartRef, inScope, isJobRun, mergeUsage, orderUsageWindows, projectKey, projectLabel, projectsOf, replayCoalesceKey, replayRetains, runningSubagents, scopeActive, sessionLabel, sessionState, snapshotRetains, subagentLabel, subsetSummary, supportsPermissionMode, transcriptActivity, transcriptContent, unseenCount, usageInfos, watermarkKey };
 //# sourceMappingURL=index.d.mts.map