@workerdeck/protocol 0.16.0 → 0.18.0

package/build/index.d.mts

@@ -20,8 +20,49 @@ 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.
+ */
+/**
+ * Does this record name an **agent**, as opposed to a task the model merely
+ * described?
+ *
+ * The tracker opens a record for every spawner call and for any nested event
+ * whose parent it has not seen, so the list holds two different things wearing
+ * one shape. One carries a `subagent_type` — a delegated agent with an identity
+ * (`Explore`), whose own work is worth a surface of its own. The other carries
+ * only a description, and there is no agent there to open: a row that offered a
+ * screen and then showed a frame with nothing in it would be worse than a row
+ * that offered nothing.
+ *
+ * Here rather than in a client because it decides two things a list must not
+ * disagree about across surfaces — what is pressable, and what wears the
+ * sub-agent colour.
+ */
+declare function isAgentRecord(sub: SubagentInfo): boolean;
+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 +70,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 +125,68 @@ 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;
+/**
+ * Where inside its project a session actually sits — the cwd with the project
+ * root taken off the front, or `undefined` when it sits at the root, has no
+ * declared project, or has no cwd at all.
+ *
+ * The companion to {@link projectLabel}, and it exists for one situation: a list
+ * **grouped by project**. There the header has already said the project's name,
+ * so repeating it on every row spends the row's most valuable line on the one
+ * fact the reader already has. What the header cannot say is which *part* of the
+ * project a session is working in, and two sessions in the same repo are told
+ * apart by exactly that.
+ *
+ * Undefined is the honest answer for a session at the project root, and callers
+ * must render nothing rather than a `.` or a repeated name — the slot simply
+ * goes away, which is the point.
+ */
+declare function projectSubpath(row: Pick<SessionRow, 'info'>): string | undefined;
 /**
  * This session is a job run — the queue created it, and `JobInfo.sessionId`
  * points at it.
@@ -329,7 +441,127 @@ 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;
@@ -537,6 +769,27 @@ type ContextUsage = {
   percentage: number; /** Model the window sizing applies to. */
   model?: string;
 };
+/**
+ * The context-window reading that rides the **sessions list**, as opposed to the
+ * full {@link ContextUsage} that rides the event stream.
+ *
+ * Three numbers, and the omission is the design: `categories` is a breakdown for
+ * a dialog that has a live session behind it, and this field is on every row of
+ * `GET /sessions`, which a busy client polls at 1.2s. Same attachment-bytes
+ * discipline as {@link SessionInfo.subagents}. `percentage` alone would size a
+ * ring, but the token pair is what lets a row *say* `142k / 200k` on hover or
+ * long-press without a second round trip, and it is two numbers.
+ *
+ * **Absent is a real state and is not zero.** A parked session, one that has
+ * never run a turn, or an engine that reports no window has no reading — render
+ * nothing, never an empty ring, which claims "context is empty" rather than "no
+ * answer". Also absent on an older server.
+ */
+type ContextReading = {
+  totalTokens: number;
+  maxTokens: number; /** Used share of the window, 0–100. */
+  percentage: number;
+};
 /**
  * One rate-limit window snapshot (SDK SDKRateLimitInfo mirror). Emitted only for
  * claude.ai subscription sessions — API-key sessions may never produce one, so
@@ -1301,6 +1554,187 @@ 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.
+ *
+ * **The claude and codex engines both produce it; the provider engine's absence
+ * is the truth.** The AI SDK has no multi-agent primitive and no tool that runs
+ * a nested agent loop, so `parentToolUseId: null` on every provider event is
+ * honest. Codex's spawn signal is the `subAgentActivity` item, whose own `id` is
+ * the model's `spawn_agent` call id — a genuine tool-use id — so `toolUseId`
+ * keeps its documented meaning there: the codex runner authors the anchor
+ * `tool_use` itself and keys every event of the agent's *thread* to it
+ * (`engines/codex/subagents.ts`). The earlier version of this comment asserted
+ * codex had no sidechains; that was true of the exec era and has not been true
+ * for a while.
+ *
+ * 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;
@@ -1331,6 +1765,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. */
@@ -1355,11 +1805,50 @@ type SessionInfo = {
    */
   activityCount?: number; /** Epoch ms of the most recent emitted event. */
   lastActivityAt?: number;
+  /**
+   * The session's latest context-window reading — see {@link ContextReading}.
+   *
+   * The same number the session screen draws, served on the list so a row can
+   * show where a session is bloating **without attaching to it**. That is the
+   * whole reason it is here: context fill is the one session metric you want
+   * across *all* sessions at once, and until now it existed only as an event on
+   * an attached socket.
+   *
+   * Retained by the runner from the last `context_usage` it emitted, so it is
+   * exactly what the transcript last showed — never recomputed on the serve
+   * path, which would be a second answer to a question that already has one.
+   * Absent until the first reading (a promptless session has none), and cleared
+   * by a `conversation_reset` for the same reason the transcript state clears
+   * it: the old window is not this conversation's.
+   */
+  contextUsage?: ContextReading;
   /** Opaque scope tags this session was created with — see
    * {@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;
 };
+/**
+ * The list-sized context reading an event carries, or `undefined` for the events
+ * that carry none — the rule behind {@link SessionInfo.contextUsage}.
+ *
+ * Here rather than in each runner for the same reason {@link transcriptActivity}
+ * is: it is one rule both sides have to agree on, and three copies of "which
+ * events move the reading" is three chances to disagree. Runners fold it in
+ * their emit path; **clearing on `conversation_reset` is the caller's half** —
+ * this function answers "what does this event say the reading is", and a reset
+ * says nothing about the window, it retires the conversation the window
+ * described.
+ */
+declare function contextReading(body: SessionEventBody): ContextReading | undefined;
 /**
  * How many transcript rows an event materializes — the unit behind
  * {@link SessionInfo.activityCount}.
@@ -1450,6 +1939,93 @@ declare function transcriptContent(body: SessionEventBody): boolean;
  * 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
@@ -1885,5 +2461,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, FilePatch, 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, PatchHunk, PermissionDecisionSource, PermissionMode, PermissionRequest, ProfileConfigSnapshot, ProfileDefaults, ProfileEngine, ProfileInfo, ProfileSessionDefaults, ProfileUsage, ProfileUsageWindow, 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, SessionUsage, SessionWebhookConfig, SkillInfo, SlashCommandInfo, SortBy, SubmitExecutionResultRequest, SubmitExecutionResultResponse, SubsetSummary, 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, inScope, isJobRun, mergeUsage, orderUsageWindows, replayCoalesceKey, scopeActive, sessionLabel, sessionState, subsetSummary, supportsPermissionMode, transcriptActivity, transcriptContent, unseenCount, usageInfos, watermarkKey };
+export { ApiMessage, AttachedFrame, ClientFrame, ContentBlock, ContextReading, 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, contextReading, filterRows, groupRows, hasFacetFilter, imagePartRef, inScope, isAgentRecord, isJobRun, mergeUsage, orderUsageWindows, projectKey, projectLabel, projectSubpath, projectsOf, replayCoalesceKey, replayRetains, runningSubagents, scopeActive, sessionLabel, sessionState, snapshotRetains, subagentLabel, subsetSummary, supportsPermissionMode, transcriptActivity, transcriptContent, unseenCount, usageInfos, watermarkKey };
 //# sourceMappingURL=index.d.mts.map