sidekick-shared 0.29.1 → 0.30.0

package/dist/schemas/sessionEvent.d.ts

@@ -60,9 +60,11 @@ export declare const sessionMessageSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const permissionModeSchema: z.ZodEnum<{
     default: "default";
+    auto: "auto";
     acceptEdits: "acceptEdits";
     bypassPermissions: "bypassPermissions";
     plan: "plan";
+    dontAsk: "dontAsk";
 }>;
 export declare const userSessionEventSchema: z.ZodObject<{
     timestamp: z.ZodString;
@@ -78,9 +80,11 @@ export declare const userSessionEventSchema: z.ZodObject<{
     gitBranch: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
+        auto: "auto";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
+        dontAsk: "dontAsk";
     }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
@@ -167,9 +171,11 @@ export declare const assistantSessionEventSchema: z.ZodObject<{
     gitBranch: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
+        auto: "auto";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
+        dontAsk: "dontAsk";
     }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
@@ -244,6 +250,7 @@ export declare const assistantSessionEventSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const summarySessionEventSchema: z.ZodType<SummarySessionEvent>;
 export declare const systemSessionEventSchema: z.ZodObject<{
+    subtype: z.ZodCatch<z.ZodOptional<z.ZodString>>;
     timestamp: z.ZodString;
     entrypoint: z.ZodOptional<z.ZodString>;
     isMeta: z.ZodOptional<z.ZodBoolean>;
@@ -257,9 +264,11 @@ export declare const systemSessionEventSchema: z.ZodObject<{
     gitBranch: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
+        auto: "auto";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
+        dontAsk: "dontAsk";
     }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
@@ -350,9 +359,11 @@ export declare const toolUseSessionEventSchema: z.ZodObject<{
     gitBranch: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
+        auto: "auto";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
+        dontAsk: "dontAsk";
     }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
@@ -444,9 +455,11 @@ export declare const toolResultSessionEventSchema: z.ZodObject<{
     gitBranch: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
         default: "default";
+        auto: "auto";
         acceptEdits: "acceptEdits";
         bypassPermissions: "bypassPermissions";
         plan: "plan";
+        dontAsk: "dontAsk";
     }>>>;
     rateLimits: z.ZodOptional<z.ZodObject<{
         primary: z.ZodOptional<z.ZodObject<{
@@ -528,8 +541,19 @@ export interface ExtractSessionEventsOptions {
      * commandMode: 'task-notification', prompt } }`) into one `system` event
      * with `origin: { kind: 'task-notification' }`, `message: { role: 'user',
      * sourceLabel: 'task notification', content: <prompt> }`, and the line's
-     * timestamp. They report background agents finishing. Default `false`:
-     * attachment lines yield no events.
+     * timestamp. They report background agents finishing (or, as plain text,
+     * the user stopping them: see `parseAgentsStoppedNotice`).
+     *
+     * Also turns a background agent's `task_status` attachment with a final
+     * status (`{ type: 'attachment', attachment: { type: 'task_status',
+     * taskType: 'local_agent', taskId, status: 'completed', … } }`) into a
+     * `system` event with `origin: { kind: 'task-status' }` and `message: {
+     * role: 'system', sourceLabel: 'task status', content: [{ type:
+     * 'task_status', taskId, taskType, status, description }] }` (read it with
+     * `taskStatusFromEvent`). Default `false`: attachment lines yield no events.
+     *
+     * System lines (`agents_killed` among them) parse either way and keep
+     * their `subtype`.
      */
     includeTaskNotifications?: boolean;
 }

package/dist/schemas/sessionEvent.js

@@ -45,6 +45,8 @@ exports.permissionModeSchema = zod_1.z.enum([
     'acceptEdits',
     'bypassPermissions',
     'plan',
+    'auto',
+    'dontAsk',
 ]);
 // ── SessionEvent ──
 const eventBaseShape = {
@@ -57,8 +59,8 @@ const eventBaseShape = {
     promptSource: zod_1.z.string().optional(),
     cwd: zod_1.z.string().optional(),
     gitBranch: zod_1.z.string().optional(),
-    // A mode this release doesn't know (Claude Code added `auto`) is dropped
-    // rather than rejecting the whole line with its prompt or tool results.
+    // A mode this release doesn't know is dropped rather than rejecting the
+    // whole line with its prompt or tool results.
     permissionMode: exports.permissionModeSchema.optional().catch(undefined),
     rateLimits: zod_1.z
         .object({
@@ -148,6 +150,9 @@ exports.systemSessionEventSchema = zod_1.z.object({
     type: zod_1.z.literal('system'),
     message: exports.sessionMessageSchema.optional(),
     ...eventBaseShape,
+    // Claude Code's system-line subtype (`agents_killed`, `turn_duration`, …);
+    // a malformed one is dropped rather than rejecting the line.
+    subtype: zod_1.z.string().optional().catch(undefined),
 });
 exports.toolUseSessionEventSchema = zod_1.z.object({
     type: zod_1.z.literal('tool_use'),
@@ -187,7 +192,7 @@ function extractSessionEventsWithProvenance(raw, depth, inherited, options) {
     if (direct.success)
         return [{ ...inherited, ...direct.data }];
     if (options.includeTaskNotifications) {
-        const notification = taskNotificationAttachmentEvent(raw);
+        const notification = taskNotificationAttachmentEvent(raw) ?? taskStatusAttachmentEvent(raw);
         if (notification)
             return [{ ...inherited, ...notification }];
     }
@@ -224,6 +229,29 @@ function taskNotificationAttachmentEvent(raw) {
     const parsed = exports.systemSessionEventSchema.safeParse(candidate);
     return parsed.success ? parsed.data : null;
 }
+/** The `system` event for a background agent's final `task_status` attachment, or `null`. */
+function taskStatusAttachmentEvent(raw) {
+    const status = (0, subagentSpawn_1.taskStatusFromAttachment)(raw);
+    if (!status || !(0, subagentSpawn_1.isFinalTaskStatus)(status.status))
+        return null;
+    const line = raw;
+    const candidate = {
+        type: 'system',
+        timestamp: line.timestamp,
+        origin: { kind: subagentSpawn_1.TASK_STATUS_ORIGIN_KIND },
+        message: {
+            role: 'system',
+            sourceLabel: 'task status',
+            content: [{ type: subagentSpawn_1.TASK_STATUS_BLOCK_TYPE, ...status }],
+        },
+    };
+    for (const key of ['entrypoint', 'isSidechain', 'cwd', 'gitBranch']) {
+        if (line[key] !== undefined)
+            candidate[key] = line[key];
+    }
+    const parsed = exports.systemSessionEventSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : null;
+}
 function progressProvenance(raw) {
     const value = raw;
     const provenance = {};

package/dist/sessionMonitor.d.ts

@@ -25,6 +25,12 @@ export declare class SessionMonitor {
     constructor(provider: SessionProviderBase, options?: SessionMonitorOptions);
     attach(sessionPath: string, replay?: boolean): AggregatedMetrics;
     attachLatest(workspacePath: string, replay?: boolean): AggregatedMetrics | null;
+    /**
+     * Reads and aggregates what the session gained since the last call. When
+     * the reader had to start over (the file was truncated, rewritten, or
+     * replaced) the aggregator is reset first and the returned events are the
+     * session from the beginning.
+     */
     poll(): SessionEvent[];
     process(event: SessionEvent): void;
     onEvent(listener: (event: SessionEvent) => void): () => void;

package/dist/sessionMonitor.js

@@ -67,12 +67,18 @@ class SessionMonitor {
         const sessionPath = this.provider.findActiveSession(workspacePath);
         return sessionPath ? this.attach(sessionPath, replay) : null;
     }
+    /**
+     * Reads and aggregates what the session gained since the last call. When
+     * the reader had to start over (the file was truncated, rewritten, or
+     * replaced) the aggregator is reset first and the returned events are the
+     * session from the beginning.
+     */
     poll() {
         if (!this.reader)
             return [];
+        const events = this.reader.readNew();
         if (this.reader.wasTruncated())
             this.aggregator.reset();
-        const events = this.reader.readNew();
         this.consume(events);
         return events;
     }

package/dist/sessionPreviews.js

@@ -57,6 +57,7 @@ exports.readSessionPreviewAsync = readSessionPreviewAsync;
 exports.listSessionPreviews = listSessionPreviews;
 exports.listSessionPreviewsAsync = listSessionPreviewsAsync;
 const fs = __importStar(require("fs"));
+const compressedRollouts_1 = require("./providers/compressedRollouts");
 function emptyPrefixScan() {
     return { firstTimestamp: null, workspacePath: null };
 }
@@ -454,6 +455,12 @@ function scanPrefix(sessionPath, maxPrefixBytes) {
     const result = { firstTimestamp: null, workspacePath: null };
     let content;
     let sawWholeFile;
+    if ((0, compressedRollouts_1.isCompressedRolloutPath)(sessionPath)) {
+        // A compressed Codex rollout: scan its decompressed prefix.
+        const head = (0, compressedRollouts_1.readRolloutHead)(sessionPath, Math.max(1, maxPrefixBytes) + 1);
+        parsePrefixInto(result, head.subarray(0, Math.max(1, maxPrefixBytes)).toString('utf8'), head.length <= maxPrefixBytes);
+        return result;
+    }
     try {
         const descriptor = fs.openSync(sessionPath, 'r');
         try {
@@ -509,6 +516,8 @@ function scanPrefix(sessionPath, maxPrefixBytes) {
 }
 async function scanPrefixAsync(sessionPath, maxPrefixBytes) {
     const result = { firstTimestamp: null, workspacePath: null };
+    if ((0, compressedRollouts_1.isCompressedRolloutPath)(sessionPath))
+        return scanPrefix(sessionPath, maxPrefixBytes);
     let handle = null;
     try {
         handle = await fs.promises.open(sessionPath, 'r');

package/dist/sessionPromptHistory.d.ts

@@ -62,6 +62,11 @@ export interface CollectSessionPromptHistoryOptions {
     include?: SessionPromptHistoryInclude;
     bounds?: SessionPromptHistoryBounds;
     signal?: AbortSignal;
+    /**
+     * Codex: also read compressed rollouts (`….jsonl.zst`), as for
+     * `collectPromptHistory()`. Default false.
+     */
+    includeCompressedRollouts?: boolean;
 }
 export interface PromptHistorySessionPrompt extends Omit<PromptHistoryEntry, 'provider' | 'sessionId' | 'sessionKey'> {
     /** With `include.replies`: the agent's last text for this prompt's turn. */

package/dist/sessionPromptHistory.js

@@ -14,42 +14,9 @@
  * `sessionIds` continues. Scope fails closed as in `collectPromptHistory()`,
  * and replies or signals that belong to an out-of-scope prompt are dropped.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectSessionPromptHistory = collectSessionPromptHistory;
-const fs = __importStar(require("fs"));
+const compressedRollouts_1 = require("./providers/compressedRollouts");
 const promptHistory_1 = require("./promptHistory");
 const sessionPromptSignals_1 = require("./sessionPromptSignals");
 const DEFAULT_SESSION_BOUNDS = {
@@ -224,7 +191,9 @@ function definedBounds(bounds) {
 async function selectCandidates(options, listingRoots) {
     const sinceMs = options.since ? options.since.getTime() : null;
     const providers = options.providers ?? ['claude-code', 'codex'];
-    let candidates = await (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs);
+    let candidates = await (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs, {
+        includeCompressedRollouts: options.includeCompressedRollouts,
+    });
     if (options.sessionIds || options.sessionRefs) {
         const ids = new Set(options.sessionIds ?? []);
         const keys = new Set();
@@ -242,7 +211,7 @@ async function selectCandidates(options, listingRoots) {
     const selected = [];
     for (const candidate of candidates) {
         try {
-            selected.push({ candidate, stat: await fs.promises.stat(candidate.filePath) });
+            selected.push({ candidate, stat: await (0, compressedRollouts_1.statRolloutContent)(candidate.filePath) });
         }
         catch {
             // Gone since it was listed.

package/dist/subagentActivity.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Subagent lifecycle records as `system` session events.
+ *
+ * Codex records its multi-agent lifecycle in the parent's rollout:
+ * `item_completed` → `SubAgentActivity` items link a `spawn_agent` call to the
+ * child thread it started (`started`), mark each finished child turn
+ * (`completed`, Codex 0.150+), and note `followup_task` / `send_message`
+ * calls (`interacted`) and `interrupt_agent` calls (`interrupted`); a child's
+ * report arrives as an `agent_message` whose text starts
+ * `Message Type: FINAL_ANSWER`. With
+ * `CodexRolloutParserOptions.includeSubagentActivity`, the parser turns each
+ * into one `system` event with `origin: { kind: 'subagent-activity' }` whose
+ * `message.content` is a single `{ type: 'subagent_activity', ... }` block.
+ *
+ * Those events are bookkeeping, not messages: transcripts, context
+ * attribution, and message counts skip them, as they do task notifications.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module subagentActivity
+ */
+import type { SessionEvent } from './types/sessionEvent';
+/** `origin.kind` of a subagent-activity `system` event. */
+export declare const SUBAGENT_ACTIVITY_ORIGIN_KIND = "subagent-activity";
+/** `type` of the content block that carries the activity. */
+export declare const SUBAGENT_ACTIVITY_BLOCK_TYPE = "subagent_activity";
+/**
+ * - `started`: a spawn call started the child thread (`callId` = the spawn
+ *   call's id, `agentThreadId` = the child's rollout id).
+ * - `completed`: one child turn finished (`turnId` = that child turn).
+ * - `interacted`: the parent sent the child work or a message (`callId` =
+ *   the `followup_task` or `send_message` call; `tool` says which, when the
+ *   call was seen). After `followup_task` the child runs again.
+ * - `interrupted`: the parent interrupted the child (`interrupt_agent`).
+ * - `final-answer`: the child's final report reached the parent
+ *   (`agentPath` = its author, `text` = the report).
+ */
+export type SubagentActivityKind = 'started' | 'completed' | 'interacted' | 'interrupted' | 'final-answer';
+export interface SubagentActivity {
+    kind: SubagentActivityKind;
+    /**
+     * The parent's tool call the record refers to: the spawn call for
+     * `started`, the `followup_task` / `send_message` call for `interacted`,
+     * the `interrupt_agent` call for `interrupted`.
+     */
+    callId?: string;
+    /**
+     * Raw name of the `callId` tool call (`spawn_agent`, `followup_task`,
+     * `send_message`, `interrupt_agent`) when the parser saw that call.
+     */
+    tool?: string;
+    /** `completed`: the child turn that finished. */
+    turnId?: string;
+    /** The child's thread id, which is its rollout's session id. */
+    agentThreadId?: string;
+    /** The child's agent path, e.g. `/root/review_builder` (`final-answer`: the author). */
+    agentPath?: string;
+    /** `final-answer`: the agent path the report went to, e.g. `/root`. */
+    recipient?: string;
+    /** `started`: the child's model and reasoning effort, when recorded. */
+    model?: string;
+    reasoningEffort?: string;
+    /** The thread and turn that recorded the activity (the parent's). */
+    parentThreadId?: string;
+    parentTurnId?: string;
+    /** `final-answer`: the report text (empty in metadata-only parsing). */
+    text?: string;
+}
+/** Whether an event is a subagent-activity `system` event (see the module docs). */
+export declare function isSubagentActivitySystemEvent(event: SessionEvent): boolean;
+/**
+ * The activity a subagent-activity `system` event carries, copied with only
+ * its known string fields; `null` for any other event or a malformed block.
+ */
+export declare function subagentActivityFromEvent(event: SessionEvent): SubagentActivity | null;
+/** A one-line, content-free description, e.g. `Subagent /root/review started`. */
+export declare function describeSubagentActivity(activity: SubagentActivity): string;
+/** Fields of a Codex inter-agent message text (`Message Type: … Payload:\n…`). */
+export interface CodexAgentMessageText {
+    /** `MESSAGE`, `NEW_TASK`, `FINAL_ANSWER`, … */
+    messageType: string;
+    taskName?: string;
+    sender?: string;
+    /** Everything after the `Payload:` line. */
+    payload: string;
+}
+/**
+ * Parses a Codex inter-agent message text. Returns `null` unless it starts
+ * with a `Message Type:` line.
+ */
+export declare function parseCodexAgentMessageText(text: unknown): CodexAgentMessageText | null;

package/dist/subagentActivity.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Subagent lifecycle records as `system` session events.
+ *
+ * Codex records its multi-agent lifecycle in the parent's rollout:
+ * `item_completed` → `SubAgentActivity` items link a `spawn_agent` call to the
+ * child thread it started (`started`), mark each finished child turn
+ * (`completed`, Codex 0.150+), and note `followup_task` / `send_message`
+ * calls (`interacted`) and `interrupt_agent` calls (`interrupted`); a child's
+ * report arrives as an `agent_message` whose text starts
+ * `Message Type: FINAL_ANSWER`. With
+ * `CodexRolloutParserOptions.includeSubagentActivity`, the parser turns each
+ * into one `system` event with `origin: { kind: 'subagent-activity' }` whose
+ * `message.content` is a single `{ type: 'subagent_activity', ... }` block.
+ *
+ * Those events are bookkeeping, not messages: transcripts, context
+ * attribution, and message counts skip them, as they do task notifications.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module subagentActivity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBAGENT_ACTIVITY_BLOCK_TYPE = exports.SUBAGENT_ACTIVITY_ORIGIN_KIND = void 0;
+exports.isSubagentActivitySystemEvent = isSubagentActivitySystemEvent;
+exports.subagentActivityFromEvent = subagentActivityFromEvent;
+exports.describeSubagentActivity = describeSubagentActivity;
+exports.parseCodexAgentMessageText = parseCodexAgentMessageText;
+/** `origin.kind` of a subagent-activity `system` event. */
+exports.SUBAGENT_ACTIVITY_ORIGIN_KIND = 'subagent-activity';
+/** `type` of the content block that carries the activity. */
+exports.SUBAGENT_ACTIVITY_BLOCK_TYPE = 'subagent_activity';
+const KINDS = new Set([
+    'started',
+    'completed',
+    'interacted',
+    'interrupted',
+    'final-answer',
+]);
+const STRING_FIELDS = [
+    'callId',
+    'tool',
+    'turnId',
+    'agentThreadId',
+    'agentPath',
+    'recipient',
+    'model',
+    'reasoningEffort',
+    'parentThreadId',
+    'parentTurnId',
+    'text',
+];
+/** Whether an event is a subagent-activity `system` event (see the module docs). */
+function isSubagentActivitySystemEvent(event) {
+    return event.type === 'system' && event.origin?.kind === exports.SUBAGENT_ACTIVITY_ORIGIN_KIND;
+}
+/**
+ * The activity a subagent-activity `system` event carries, copied with only
+ * its known string fields; `null` for any other event or a malformed block.
+ */
+function subagentActivityFromEvent(event) {
+    if (!isSubagentActivitySystemEvent(event))
+        return null;
+    const content = event.message?.content;
+    if (!Array.isArray(content))
+        return null;
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const raw = block;
+        if (raw.type !== exports.SUBAGENT_ACTIVITY_BLOCK_TYPE)
+            continue;
+        if (typeof raw.kind !== 'string' || !KINDS.has(raw.kind))
+            return null;
+        const activity = { kind: raw.kind };
+        for (const field of STRING_FIELDS) {
+            const value = raw[field];
+            if (typeof value === 'string' && value.length > 0)
+                activity[field] = value;
+        }
+        return activity;
+    }
+    return null;
+}
+/** A one-line, content-free description, e.g. `Subagent /root/review started`. */
+function describeSubagentActivity(activity) {
+    const who = activity.agentPath ?? activity.agentThreadId ?? 'subagent';
+    const name = `Subagent ${who}`;
+    switch (activity.kind) {
+        case 'started':
+            return `${name} started`;
+        case 'completed':
+            return `${name} finished a turn`;
+        case 'interacted':
+            return activity.tool === 'send_message'
+                ? `Message sent to subagent ${who}`
+                : `${name} given a follow-up task`;
+        case 'interrupted':
+            return `${name} interrupted`;
+        case 'final-answer':
+            return `${name} reported its final answer`;
+    }
+}
+const MESSAGE_HEADER = /^Message Type:[ \t]*([A-Z_]+)[ \t]*(?:\r?\n|$)/;
+/**
+ * Parses a Codex inter-agent message text. Returns `null` unless it starts
+ * with a `Message Type:` line.
+ */
+function parseCodexAgentMessageText(text) {
+    if (typeof text !== 'string')
+        return null;
+    const header = MESSAGE_HEADER.exec(text);
+    if (!header)
+        return null;
+    const rest = text.slice(header[0].length);
+    const payloadAt = /(?:^|\n)Payload:[ \t]*(?:\r?\n|$)/.exec(rest);
+    const head = payloadAt ? rest.slice(0, payloadAt.index) : rest;
+    const payload = payloadAt ? rest.slice(payloadAt.index + payloadAt[0].length) : '';
+    const field = (name) => {
+        const match = new RegExp(`(?:^|\\n)${name}:[ \\t]*([^\\n]*)`).exec(head);
+        const value = match?.[1]?.trim();
+        return value ? value : undefined;
+    };
+    const taskName = field('Task name');
+    const sender = field('Sender');
+    return {
+        messageType: header[1],
+        ...(taskName ? { taskName } : {}),
+        ...(sender ? { sender } : {}),
+        payload,
+    };
+}

package/dist/subagentDisplayState.d.ts

@@ -0,0 +1,81 @@
+/**
+ * How to show a subagent: its lifecycle's outcome once something settled
+ * it, otherwise `running`, unless its transcript or its parent says it has
+ * stopped in all but name.
+ *
+ * Some background agents never get a final notification (they stopped after
+ * an interim "may resume" notice, the user stopped them from the UI, or a
+ * restart killed them). Their lifecycles stay `running`. This rule reads
+ * them as:
+ *
+ * - `finished-unreported`: the transcript ended cleanly (last assistant turn
+ *   `end_turn` / `stop_sequence`, no tool call unanswered) and has been quiet
+ *   for {@link SUBAGENT_UNREPORTED_QUIET_MS}.
+ * - `ended`: neither the parent session nor the transcript has been active for
+ *   {@link SUBAGENT_PARENT_IDLE_ENDED_MS}.
+ *
+ * Neither is stored: the state is recomputed from the latest data on every
+ * call, so an agent that resumes (its transcript grows, or a later
+ * notification reopens its lifecycle) reads as `running` again. Silence alone
+ * is never enough for `finished-unreported`: live agents can be quiet for
+ * hours.
+ *
+ * Pure: no filesystem access. Browser-safe.
+ *
+ * @module subagentDisplayState
+ */
+import type { SubagentLifecycle } from './aggregation/types';
+/** Quiet time after a clean end before a running agent reads as finished without a report (2 min). */
+export declare const SUBAGENT_UNREPORTED_QUIET_MS: number;
+/** Parent and transcript idle time after which a running agent reads as ended (6 h). */
+export declare const SUBAGENT_PARENT_IDLE_ENDED_MS: number;
+/** How a subagent is shown. The last four are lifecycle outcomes. */
+export type SubagentDisplayStateName = 'running' | 'finished-unreported' | 'ended' | 'completed' | 'failed' | 'stopped' | 'killed';
+/** Why a subagent reads as it does. */
+export type SubagentDisplayReason = 
+/** Its lifecycle is settled; the state is the outcome. */
+'settled'
+/** Claude Code's meta flags (`finished`, `stoppedByUser`) on a running lifecycle. */
+ | 'meta'
+/** The transcript ended cleanly and has been quiet. */
+ | 'clean-end'
+/** The parent session (and the transcript) has been idle. */
+ | 'parent-idle';
+export interface SubagentDisplayState {
+    state: SubagentDisplayStateName;
+    /** Absent for a plain `running`. */
+    reason?: SubagentDisplayReason;
+}
+/** The lifecycle fields the rule reads. */
+export type SubagentDisplayLifecycle = Pick<SubagentLifecycle, 'status' | 'outcome'>;
+/**
+ * Transcript facts the rule reads; a `SubagentTrace`, or a `SubagentStats`
+ * mapped with `lastActivityAt: stats.endTime`.
+ */
+export interface SubagentDisplayTrace {
+    /** The transcript ended cleanly (see `SubagentTrace.endedCleanly`). */
+    endedCleanly?: boolean;
+    /** Time of the transcript's last record. */
+    lastActivityAt?: Date | string | number;
+    /** Claude Code meta `finished`. */
+    finished?: boolean;
+    /** Claude Code meta `stoppedByUser`. */
+    stoppedByUser?: boolean;
+}
+export interface SubagentDisplayOptions {
+    /** The current time (epoch ms or a Date). */
+    now: number | Date;
+    /** Time of the parent session's last event, when known. */
+    parentLastActivity?: Date | string | number | null;
+}
+/**
+ * Resolves how to show a subagent (see the module docs). Settled lifecycles
+ * map to their outcome (`completed` when none is recorded). A running one is
+ * `stopped` / `completed` when its meta flags say so, `finished-unreported`
+ * after a clean end and {@link SUBAGENT_UNREPORTED_QUIET_MS} of quiet,
+ * `ended` when the parent and transcript have both been idle for longer than
+ * {@link SUBAGENT_PARENT_IDLE_ENDED_MS}, and `running` otherwise.
+ */
+export declare function resolveSubagentDisplayState(lifecycle: SubagentDisplayLifecycle, trace: SubagentDisplayTrace | null | undefined, options: SubagentDisplayOptions): SubagentDisplayState;
+/** A short label: `running`, `finished (no report)`, `ended`, `completed`, `failed`, `stopped`, `killed`. */
+export declare function subagentDisplayLabel(state: SubagentDisplayStateName): string;