@workerdeck/protocol 0.16.0 → 0.18.0

package/build/index.mjs

@@ -13,15 +13,67 @@ const STATE_LABELS = {
 };
 function sessionState(info) {
 	if (info.pendingPermissionCount > 0 || info.status === "awaiting_approval") return "attention";
-	if (info.status === "running" || info.status === "starting") return "working";
 	if (info.status === "failed" || info.status === "closed") return "ended";
+	if (info.status === "running" || info.status === "starting") return "working";
+	if (runningSubagents(info).length > 0) return "working";
 	return "idle";
 }
+/**
+* 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.
+*/
+function runningSubagents(info) {
+	return (info.subagents ?? []).filter((sub) => sub.status === "running");
+}
+/**
+* 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.
+*/
+function isAgentRecord(sub) {
+	return (sub.agentType?.trim() ?? "") !== "";
+}
+function subagentLabel(sub) {
+	const agent = sub.agentType?.trim();
+	const description = sub.description?.trim();
+	if (agent && description) return `${agent} · ${description}`;
+	return agent || description || "Sub-agent";
+}
 const DEFAULT_VIEW_CONFIG = {
 	search: "",
 	gateways: [],
 	adapters: [],
 	states: [],
+	projects: [],
 	scoped: true,
 	groupBy: "state",
 	sortBy: "recent"
@@ -31,10 +83,90 @@ const DEFAULT_VIEW_CONFIG = {
 function adaptersOf(rows) {
 	return [...new Set(rows.map((r) => r.adapter))].sort();
 }
+/**
+* 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.
+*/
+function projectsOf(rows) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const row of rows) byKey.set(projectKey(row), projectLabel(row));
+	return [...byKey].map(([key, label]) => ({
+		key,
+		label
+	})).sort((a, b) => a.label.toLowerCase().localeCompare(b.label.toLowerCase()));
+}
 function sessionLabel(info) {
 	return info.title ?? info.id.slice(0, 8);
 }
 /**
+* 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}.
+*/
+function projectKey(row) {
+	return `${row.hostId}:${normalizePath(row.info.project?.root ?? row.info.cwd)}`;
+}
+/**
+* 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.
+*/
+function projectLabel(row) {
+	const name = row.info.project?.name;
+	if (name) return name;
+	const dir = normalizePath(row.info.cwd);
+	return dir.slice(dir.lastIndexOf("/") + 1) || "No project";
+}
+/**
+* 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.
+*/
+function projectSubpath(row) {
+	const root = row.info.project?.root;
+	if (root === void 0 || !row.info.cwd) return void 0;
+	const base = normalizePath(root);
+	const dir = normalizePath(row.info.cwd);
+	if (dir === base) return void 0;
+	if (!dir.startsWith(`${base}/`)) return void 0;
+	return dir.slice(base.length + 1) || void 0;
+}
+/**
 * This session is a job run — the queue created it, and `JobInfo.sessionId`
 * points at it.
 *
@@ -49,7 +181,7 @@ function isJobRun(info) {
 }
 function matchesSearch(row, needle) {
 	if (!needle) return true;
-	return sessionLabel(row.info).toLowerCase().includes(needle) || row.info.cwd.toLowerCase().includes(needle) || row.hostName.toLowerCase().includes(needle) || row.adapter.toLowerCase().includes(needle) || row.info.id.startsWith(needle);
+	return sessionLabel(row.info).toLowerCase().includes(needle) || row.info.cwd.toLowerCase().includes(needle) || (row.info.project?.name.toLowerCase().includes(needle) ?? false) || row.hostName.toLowerCase().includes(needle) || row.adapter.toLowerCase().includes(needle) || row.info.id.startsWith(needle);
 }
 /** Trailing separators dropped and separators unified, so containment is a
 * plain prefix test on both a posix and a Windows gateway. */
@@ -78,13 +210,13 @@ function scopeActive(config, scope) {
 function filterRows(rows, config, scope) {
 	const needle = config.search.trim().toLowerCase();
 	const scoping = scopeActive(config, scope) ? scope : void 0;
-	return rows.filter((row) => (config.gateways.length === 0 || config.gateways.includes(row.hostId)) && (config.adapters.length === 0 || config.adapters.includes(row.adapter)) && (config.states.length === 0 || config.states.includes(row.state)) && (!scoping || inScope(row, scoping)) && matchesSearch(row, needle));
+	return rows.filter((row) => (config.gateways.length === 0 || config.gateways.includes(row.hostId)) && (config.adapters.length === 0 || config.adapters.includes(row.adapter)) && (config.states.length === 0 || config.states.includes(row.state)) && (!config.projects?.length || config.projects.includes(projectKey(row))) && (!scoping || inScope(row, scoping)) && matchesSearch(row, needle));
 }
 function facetKey(row, facet) {
-	return facet === "gateway" ? row.hostId : facet === "adapter" ? row.adapter : row.state;
+	return facet === "gateway" ? row.hostId : facet === "adapter" ? row.adapter : facet === "project" ? projectKey(row) : row.state;
 }
 function facetLabel(row, facet) {
-	return facet === "gateway" ? row.hostName : facet === "adapter" ? row.adapter : STATE_LABELS[row.state];
+	return facet === "gateway" ? row.hostName : facet === "adapter" ? row.adapter : facet === "project" ? projectLabel(row) : STATE_LABELS[row.state];
 }
 /** Comparable rank for a facet: states run worst-first (attention before ended),
 * the rest alphabetically by their visible label. */
@@ -129,7 +261,7 @@ function subsetSummary(config, scope, shown, total) {
 	if (shown >= total) return void 0;
 	const causes = [];
 	if (scope && scopeActive(config, scope)) causes.push(scope.label);
-	const facets = (config.gateways.length ? 1 : 0) + (config.adapters.length ? 1 : 0) + (config.states.length ? 1 : 0);
+	const facets = (config.gateways.length ? 1 : 0) + (config.adapters.length ? 1 : 0) + (config.states.length ? 1 : 0) + (config.projects?.length ? 1 : 0);
 	if (facets > 0) causes.push(`${facets} filter${facets === 1 ? "" : "s"}`);
 	if (config.search.trim()) causes.push("search");
 	return {
@@ -147,7 +279,7 @@ function subsetSummary(config, scope, shown, total) {
 * someone made.
 */
 function hasFacetFilter(config) {
-	return config.search.trim().length > 0 || config.gateways.length > 0 || config.adapters.length > 0 || config.states.length > 0;
+	return config.search.trim().length > 0 || config.gateways.length > 0 || config.adapters.length > 0 || config.states.length > 0 || (config.projects?.length ?? 0) > 0;
 }
 /** "Show me everything": every filter off, including scope. The group/sort
 * choices are a layout preference and survive. */
@@ -318,6 +450,55 @@ function unseenCount(mark, info) {
 /** Bumped on any breaking change to events, commands, or REST shapes. */
 const PROTOCOL_VERSION = 7;
 /**
+* 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.
+*/
+const TOOL_RESULT_HEAD_CHARS = 8e3;
+/** How many bytes a base64 payload decodes to, without decoding it. */
+function base64Bytes(data) {
+	const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+	return Math.max(0, Math.floor(data.length * 3 / 4) - padding);
+}
+/**
+* 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.
+*/
+function imagePartRef(part, index) {
+	if (part.type !== "image") return void 0;
+	const source = part.source;
+	if (!source || source.type !== "base64" || typeof source.data !== "string") return void 0;
+	return {
+		type: "image_ref",
+		media_type: typeof source.media_type === "string" ? source.media_type : "application/octet-stream",
+		bytes: base64Bytes(source.data),
+		part_index: index
+	};
+}
+/**
 * The static capability record of each engine — the browser-safe default for
 * `ProfileInfo.capabilities` / `SessionInfo.capabilities`, and the single place
 * the values are written down. Core's adapters *reference* this record and a
@@ -442,6 +623,33 @@ function supportsPermissionMode(engine, mode) {
 	return ENGINE_CAPABILITIES[engine ?? "claude"].permissionModes.includes(mode);
 }
 /**
+* 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.
+*/
+const SUBAGENT_HISTORY = 8;
+/**
+* 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.
+*/
+function contextReading(body) {
+	if (body.type !== "context_usage") return void 0;
+	const { totalTokens, maxTokens, percentage } = body.usage;
+	return {
+		totalTokens,
+		maxTokens,
+		percentage
+	};
+}
+/**
 * How many transcript rows an event materializes — the unit behind
 * {@link SessionInfo.activityCount}.
 *
@@ -457,6 +665,7 @@ function supportsPermissionMode(engine, mode) {
 * reducer's row rule changes, change this with it.
 */
 function transcriptActivity(body) {
+	if ("parentToolUseId" in body && body.parentToolUseId != null) return 0;
 	switch (body.type) {
 		case "assistant_message": {
 			const content = body.message.content;
@@ -563,10 +772,105 @@ function replayCoalesceKey(body) {
 		case "context_usage": return "context_usage";
 		case "rate_limit": return body.info.rateLimitType ? `rate_limit:${body.info.rateLimitType}` : void 0;
 		case "status_changed": return "status_changed";
+		case "sdk_event": return body.payload.type === "system" && body.payload.subtype === "status" ? "sdk_event:system:status" : void 0;
 		default: return;
 	}
 }
+/**
+* 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`).
+*/
+function replayRetains(body) {
+	if (body.type !== "stream_delta") return true;
+	const delta = body.event;
+	if (delta.type !== "content_block_delta") return false;
+	return delta.delta?.type === "text_delta" || delta.delta?.type === "thinking_delta";
+}
+/**
+* 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.
+*/
+function snapshotRetains(body) {
+	return body.type !== "stream_delta";
+}
 //#endregion
-export { DEFAULT_VIEW_CONFIG, ENGINE_CAPABILITIES, PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, STATE_LABELS, STATE_ORDER, Watermarks, adaptersOf, clearFilters, filterRows, groupRows, hasFacetFilter, inScope, isJobRun, mergeUsage, orderUsageWindows, replayCoalesceKey, scopeActive, sessionLabel, sessionState, subsetSummary, supportsPermissionMode, transcriptActivity, transcriptContent, unseenCount, usageInfos, watermarkKey };
+export { DEFAULT_VIEW_CONFIG, ENGINE_CAPABILITIES, PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, STATE_LABELS, STATE_ORDER, SUBAGENT_HISTORY, TOOL_RESULT_HEAD_CHARS, Watermarks, 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.mjs.map