sidekick-shared 0.29.0 → 0.29.1

package/dist/esm/providers/codex.js

@@ -270,6 +270,12 @@ class CodexReader {
     lineBuffer = '';
     _wasTruncated = false;
     decoder = new StringDecoder('utf8');
+    /**
+     * Position from `seekTo()` whose prefix still has to be parsed for model,
+     * turn, and cumulative-token context; `restoreResumeState()` supplies that
+     * context instead and clears it.
+     */
+    pendingSeek = null;
     constructor(rolloutPath, onContextWindowLimit, onRateLimits, onTokenUsage) {
         this.rolloutPath = rolloutPath;
         this.onContextWindowLimit = onContextWindowLimit;
@@ -279,9 +285,11 @@ class CodexReader {
     }
     /** Get the parser's session metadata. */
     getSessionMeta() {
+        this.settleSeek();
         return this.parser.getSessionMeta();
     }
     readNew(endPosition) {
+        this.settleSeek();
         this._wasTruncated = false;
         const events = [];
         try {
@@ -335,47 +343,51 @@ class CodexReader {
                     // Skip malformed JSON lines
                 }
             }
-            // Propagate model_context_window from token_count events to the provider.
-            // The model comes along so the value can be persisted per model — the
-            // window Codex reports is tier-specific, not the published maximum.
-            const mcw = this.parser.getModelContextWindow();
-            if (mcw && this.onContextWindowLimit) {
-                this.onContextWindowLimit(mcw, this.parser.getCurrentModel() ?? undefined);
-            }
-            // Propagate rate_limits from token_count events to the provider
-            const rateLimits = this.parser.getLastRateLimits();
-            if (rateLimits && this.onRateLimits) {
-                this.onRateLimits(rateLimits);
-            }
-            // Propagate last token usage snapshot to the provider
-            const lastUsage = this.parser.getLastTokenUsage();
-            if (lastUsage && this.onTokenUsage) {
-                const normalized = normalizeProviderUsage({
-                    semantics: 'openai',
-                    provider: 'openai',
-                    source: 'codex-reader-snapshot',
-                    model: this.parser.getCurrentModel() || undefined,
-                    inputTokens: lastUsage.input_tokens,
-                    outputTokens: lastUsage.output_tokens,
-                    cacheReadTokens: lastUsage.cached_input_tokens,
-                    reasoningTokens: lastUsage.reasoning_output_tokens,
-                });
-                this.onTokenUsage({
-                    inputTokens: normalized.uncachedInputTokens,
-                    outputTokens: normalized.outputTokens,
-                    cacheWriteTokens: normalized.cacheWriteTokens,
-                    cacheReadTokens: normalized.cacheReadTokens,
-                    reasoningTokens: normalized.reasoningTokens,
-                    model: this.parser.getCurrentModel() || 'unknown',
-                    timestamp: new Date(),
-                });
-            }
+            this.propagateParserState();
         }
         catch {
             // Skip read errors
         }
         return events;
     }
+    /** Hands the parser's context window, rate limits, and last usage to the provider. */
+    propagateParserState() {
+        // Propagate model_context_window from token_count events to the provider.
+        // The model comes along so the value can be persisted per model — the
+        // window Codex reports is tier-specific, not the published maximum.
+        const mcw = this.parser.getModelContextWindow();
+        if (mcw && this.onContextWindowLimit) {
+            this.onContextWindowLimit(mcw, this.parser.getCurrentModel() ?? undefined);
+        }
+        // Propagate rate_limits from token_count events to the provider
+        const rateLimits = this.parser.getLastRateLimits();
+        if (rateLimits && this.onRateLimits) {
+            this.onRateLimits(rateLimits);
+        }
+        // Propagate last token usage snapshot to the provider
+        const lastUsage = this.parser.getLastTokenUsage();
+        if (lastUsage && this.onTokenUsage) {
+            const normalized = normalizeProviderUsage({
+                semantics: 'openai',
+                provider: 'openai',
+                source: 'codex-reader-snapshot',
+                model: this.parser.getCurrentModel() || undefined,
+                inputTokens: lastUsage.input_tokens,
+                outputTokens: lastUsage.output_tokens,
+                cacheReadTokens: lastUsage.cached_input_tokens,
+                reasoningTokens: lastUsage.reasoning_output_tokens,
+            });
+            this.onTokenUsage({
+                inputTokens: normalized.uncachedInputTokens,
+                outputTokens: normalized.outputTokens,
+                cacheWriteTokens: normalized.cacheWriteTokens,
+                cacheReadTokens: normalized.cacheReadTokens,
+                reasoningTokens: normalized.reasoningTokens,
+                model: this.parser.getCurrentModel() || 'unknown',
+                timestamp: new Date(),
+            });
+        }
+    }
     readAll() {
         this.reset();
         return this.readNew();
@@ -387,11 +399,13 @@ class CodexReader {
         this.parser.reset();
         this.decoder = new StringDecoder('utf8');
         this._wasTruncated = false;
+        this.pendingSeek = null;
     }
     exists() {
         return fs.existsSync(this.rolloutPath);
     }
     flush() {
+        this.settleSeek();
         this.lineBuffer += this.decoder.end();
         // Process any remaining data in the line buffer
         if (this.lineBuffer.trim()) {
@@ -409,15 +423,45 @@ class CodexReader {
         return this.committedPosition;
     }
     seekTo(position) {
-        // Rebuild model, turn, and cumulative-token context before resuming.
-        // The prefix is parsed only; its events are already in the consumer snapshot.
         this.reset();
+        this.filePosition = position;
+        this.committedPosition = position;
+        // The prefix's context is rebuilt on the next read, unless
+        // restoreResumeState() supplies it first.
         if (position > 0)
-            this.readNew(position);
+            this.pendingSeek = position;
     }
     wasTruncated() {
         return this._wasTruncated;
     }
+    /** The parser's continuation state (see `CodexRolloutParser.exportResumeState`). */
+    getResumeState() {
+        this.settleSeek();
+        return this.parser.exportResumeState();
+    }
+    /**
+     * Restores parser state from `getResumeState()`; after `seekTo()` this
+     * replaces re-parsing the rollout up to that position.
+     */
+    restoreResumeState(state) {
+        if (!this.parser.importResumeState(state))
+            return false;
+        this.pendingSeek = null;
+        this.propagateParserState();
+        return true;
+    }
+    /**
+     * Rebuilds model, turn, and cumulative-token context for a pending
+     * `seekTo()` position. The prefix is parsed only; its events are already
+     * in the consumer snapshot.
+     */
+    settleSeek() {
+        const position = this.pendingSeek;
+        if (position === null)
+            return;
+        this.reset();
+        this.readNew(position);
+    }
 }
 // ---------------------------------------------------------------------------
 // CodexProvider — full SessionProviderBase implementation

package/dist/esm/schemas/sessionEvent.js

@@ -8,6 +8,7 @@
  */
 import { z } from 'zod';
 import { normalizedUsageSchema } from './usageNormalization';
+import { taskNotificationPromptFromAttachment } from '../subagentSpawn';
 // ── MessageUsage ──
 export const messageUsageSchema = z.object({
     input_tokens: z.number(),
@@ -52,7 +53,9 @@ const eventBaseShape = {
     promptSource: z.string().optional(),
     cwd: z.string().optional(),
     gitBranch: z.string().optional(),
-    permissionMode: permissionModeSchema.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.
+    permissionMode: permissionModeSchema.optional().catch(undefined),
     rateLimits: z
         .object({
         primary: z
@@ -169,22 +172,21 @@ export const sessionEventSchema = z.union([
 // ── Progress unwrapping ──
 /** Recursion bound for nested progress envelopes; real data nests 1 level. */
 const MAX_PROGRESS_DEPTH = 8;
-/**
- * Extracts canonical SessionEvents from a raw JSONL value.
- *
- * Claude Code wraps subagent/SDK events as
- * `{ type: 'progress', data: { message: <SessionEvent> } }`, which
- * `sessionEventSchema` alone rejects. This helper tries a direct parse,
- * then unwraps progress envelopes (recursively, in case of nesting).
- * Returns zero events for unrecognized input — never throws.
- */
-export function extractSessionEvents(raw, depth = 0) {
-    return extractSessionEventsWithProvenance(raw, depth, {});
+export function extractSessionEvents(raw, depthOrOptions = 0) {
+    if (typeof depthOrOptions === 'number') {
+        return extractSessionEventsWithProvenance(raw, depthOrOptions, {}, {});
+    }
+    return extractSessionEventsWithProvenance(raw, 0, {}, depthOrOptions ?? {});
 }
-function extractSessionEventsWithProvenance(raw, depth, inherited) {
+function extractSessionEventsWithProvenance(raw, depth, inherited, options) {
     const direct = sessionEventSchema.safeParse(raw);
     if (direct.success)
         return [{ ...inherited, ...direct.data }];
+    if (options.includeTaskNotifications) {
+        const notification = taskNotificationAttachmentEvent(raw);
+        if (notification)
+            return [{ ...inherited, ...notification }];
+    }
     if (depth >= MAX_PROGRESS_DEPTH)
         return [];
     if (typeof raw === 'object' && raw !== null && raw.type === 'progress') {
@@ -193,12 +195,31 @@ function extractSessionEventsWithProvenance(raw, depth, inherited) {
         if (typeof data === 'object' && data !== null) {
             const message = data.message;
             if (typeof message === 'object' && message !== null) {
-                return extractSessionEventsWithProvenance(message, depth + 1, provenance);
+                return extractSessionEventsWithProvenance(message, depth + 1, provenance, options);
             }
         }
     }
     return [];
 }
+/** The `system` event for a task-notification attachment line, or `null`. */
+function taskNotificationAttachmentEvent(raw) {
+    const prompt = taskNotificationPromptFromAttachment(raw);
+    if (prompt === null)
+        return null;
+    const line = raw;
+    const candidate = {
+        type: 'system',
+        timestamp: line.timestamp,
+        origin: { kind: 'task-notification' },
+        message: { role: 'user', sourceLabel: 'task notification', content: prompt },
+    };
+    for (const key of ['entrypoint', 'isSidechain', 'cwd', 'gitBranch']) {
+        if (line[key] !== undefined)
+            candidate[key] = line[key];
+    }
+    const parsed = systemSessionEventSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : null;
+}
 function progressProvenance(raw) {
     const value = raw;
     const provenance = {};

package/dist/esm/subagentSpawn.js

@@ -0,0 +1,163 @@
+/**
+ * Recognizes Claude Code subagent spawns and background-task notifications.
+ *
+ * Claude Code's subagent tool is `Agent`; `Task` is its earlier name (and the
+ * name OpenCode's `task` tool is normalized to). A background agent's spawning
+ * tool call gets its result right away ("Async agent launched successfully.")
+ * and its completion arrives later as a `<task-notification>` block, delivered
+ * either as a user line or as a mid-turn `queued_command` attachment.
+ *
+ * Pure: no filesystem access, so it is safe for browser bundles.
+ *
+ * @module subagentSpawn
+ */
+/** Tool names that spawn a subagent: `Agent` (current) and `Task` (earlier name). */
+export const SUBAGENT_SPAWN_TOOL_NAMES = Object.freeze(['Agent', 'Task']);
+const SPAWN_TOOLS = new Set(SUBAGENT_SPAWN_TOOL_NAMES);
+/** Whether a tool name spawns a subagent (`Agent` or `Task`). */
+export function isSubagentSpawnTool(name) {
+    return typeof name === 'string' && SPAWN_TOOLS.has(name);
+}
+const ASYNC_LAUNCH_PREFIX = /^\s*Async agent launched successfully\b/;
+const AGENT_ID_LINE = /(?:^|\n)[ \t]*agentId:[ \t]*([A-Za-z0-9][\w.@-]*)/;
+/**
+ * Plain text of tool-result or message content: a string as-is, or the text
+ * blocks of a content array joined by newlines.
+ */
+export function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const typed = block;
+        if (typed.type === 'text' && typeof typed.text === 'string')
+            parts.push(typed.text);
+    }
+    return parts.join('\n');
+}
+/**
+ * Recognizes the immediate result of a background spawn
+ * (`Async agent launched successfully.` … `agentId: <id> …`). Accepts the
+ * result text or the raw tool-result content. Returns `null` for anything
+ * else, including a finished foreground agent's result.
+ */
+export function parseAsyncAgentLaunch(result) {
+    const text = contentText(result);
+    if (!ASYNC_LAUNCH_PREFIX.test(text))
+        return null;
+    const match = AGENT_ID_LINE.exec(text);
+    return match ? { agentId: match[1] } : {};
+}
+const NOTIFICATION_OPEN = '<task-notification>';
+const NOTIFICATION_CLOSE = '</task-notification>';
+const NOTIFICATION_PREFIX = /^\s*<task-notification>/;
+const TAG_PATTERNS = {
+    taskId: /<task-id>\s*([\s\S]*?)\s*<\/task-id>/,
+    toolUseId: /<tool-use-id>\s*([\s\S]*?)\s*<\/tool-use-id>/,
+    status: /<status>\s*([\s\S]*?)\s*<\/status>/,
+    summary: /<summary>\s*([\s\S]*?)\s*<\/summary>/,
+    note: /<note>\s*([\s\S]*?)\s*<\/note>/,
+};
+const INTERIM_TEXT = /waiting on its own background work|background work of its own still running/i;
+function tagValue(body, pattern) {
+    const value = pattern.exec(body)?.[1]?.trim();
+    return value ? value : undefined;
+}
+/**
+ * Parses the first `<task-notification>` block in `text`. Whitespace and
+ * newlines between tags, missing fields, and unknown extra fields are
+ * tolerated; the block needs a `<task-id>`. Fields are read before the
+ * agent's own `<result>` output, which may quote anything.
+ */
+export function parseTaskNotification(text) {
+    if (typeof text !== 'string')
+        return null;
+    const start = text.indexOf(NOTIFICATION_OPEN);
+    if (start < 0)
+        return null;
+    let body = text.slice(start + NOTIFICATION_OPEN.length);
+    const resultAt = body.indexOf('<result>');
+    let header = resultAt >= 0 ? body.slice(0, resultAt) : body;
+    if (resultAt < 0) {
+        const end = body.indexOf(NOTIFICATION_CLOSE);
+        if (end >= 0)
+            header = body = body.slice(0, end);
+    }
+    if (!TAG_PATTERNS.taskId.test(header))
+        header = body;
+    const taskId = tagValue(header, TAG_PATTERNS.taskId);
+    if (!taskId)
+        return null;
+    const toolUseId = tagValue(header, TAG_PATTERNS.toolUseId);
+    const status = tagValue(header, TAG_PATTERNS.status);
+    const summary = tagValue(header, TAG_PATTERNS.summary);
+    const note = tagValue(header, TAG_PATTERNS.note);
+    return {
+        taskId,
+        ...(toolUseId ? { toolUseId } : {}),
+        ...(status ? { status } : {}),
+        ...(summary ? { summary } : {}),
+        interim: INTERIM_TEXT.test(summary ?? '') || INTERIM_TEXT.test(note ?? ''),
+    };
+}
+/**
+ * The `<task-notification>` prompt of a raw Claude Code attachment line
+ * (`{ type: 'attachment', attachment: { type: 'queued_command', commandMode:
+ * 'task-notification', prompt } }`), which is how a notification that lands
+ * mid-turn is recorded. `null` for any other value.
+ */
+export function taskNotificationPromptFromAttachment(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const line = raw;
+    if (line.type !== 'attachment' || !line.attachment || typeof line.attachment !== 'object') {
+        return null;
+    }
+    const attachment = line.attachment;
+    return attachment.type === 'queued_command' &&
+        attachment.commandMode === 'task-notification' &&
+        typeof attachment.prompt === 'string'
+        ? attachment.prompt
+        : null;
+}
+/**
+ * The synthetic `system` event `extractSessionEvents(raw, {
+ * includeTaskNotifications: true })` makes from a mid-turn task-notification
+ * attachment. It is bookkeeping, not a message or a prompt.
+ */
+export function isTaskNotificationSystemEvent(event) {
+    return event.type === 'system' && event.origin?.kind === 'task-notification';
+}
+/**
+ * The task notification an event carries: a user line with
+ * `origin.kind === 'task-notification'` or whose text starts with
+ * `<task-notification>`, or the opt-in synthetic system event. `null` otherwise.
+ */
+export function taskNotificationFromEvent(event) {
+    if (event.type !== 'user' && event.type !== 'system')
+        return null;
+    const flagged = event.origin?.kind === 'task-notification';
+    if (event.type === 'system' && !flagged)
+        return null;
+    const text = contentText(event.message?.content);
+    if (!flagged && !NOTIFICATION_PREFIX.test(text))
+        return null;
+    return parseTaskNotification(text);
+}
+/** Maps a notification `<status>` to an outcome; unknown or missing statuses read as `completed`. */
+export function taskNotificationOutcome(status) {
+    switch (status?.toLowerCase()) {
+        case 'failed':
+            return 'failed';
+        case 'killed':
+            return 'killed';
+        case 'stopped':
+            return 'stopped';
+        default:
+            return 'completed';
+    }
+}

package/dist/esm/transcript.js

@@ -1,4 +1,5 @@
 import { calculateNormalizedUsageCost, extractNormalizedUsage, } from './usageNormalization';
+import { isTaskNotificationSystemEvent } from './subagentSpawn';
 const EMPTY_TOTALS = {
     uncachedInputTokens: 0,
     cacheReadTokens: 0,
@@ -25,6 +26,9 @@ export function projectSessionTranscript(events, options = {}) {
     let cwd;
     let gitBranch;
     events.forEach((event, eventIndex) => {
+        // A reader's synthetic notice that a background task finished, not a message.
+        if (isTaskNotificationSystemEvent(event))
+            return;
         if (nonEmpty(event.cwd))
             cwd = event.cwd;
         if (nonEmpty(event.gitBranch))

package/dist/esm/turns/assistantTurn.js

@@ -1,10 +1,10 @@
 import { formatToolSummary, truncate } from '../formatters/toolSummary';
+import { isSubagentSpawnTool } from '../subagentSpawn';
 const DEFAULT_NARRATION_CHARS = 4000;
 const DEFAULT_REASONING_CHARS = 8000;
 const DEFAULT_PROCESS_STEPS = 60;
 const DEFAULT_REASONING_BLOCKS = 24;
 const DEFAULT_TOOL_INPUT_CHARS = 200;
-const SUBAGENT_TOOL_NAMES = new Set(['Task']);
 const LABEL_MAX = 80;
 const TITLE_RE = /^\s*\*\*([^*\n]+)\*\*[ \t]*(?:\n+([\s\S]*))?$/;
 const TITLE_MAX = 100;
@@ -22,8 +22,9 @@ export function reasoningSummary(text) {
     }
     return { title: null, body: trimmed };
 }
+/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
 export function isAssistantTurnSubagentTool(toolName) {
-    return toolName != null && SUBAGENT_TOOL_NAMES.has(toolName);
+    return isSubagentSpawnTool(toolName);
 }
 export function segmentAssistantTurn(events, options = {}) {
     const maxNarrationChars = options.maxNarrationChars ?? DEFAULT_NARRATION_CHARS;

package/dist/esm/usage/claudeUsageDedupe.js

@@ -59,6 +59,25 @@ export function normalizeClaudeUsage(event) {
         },
     };
 }
+const BUCKET_KEYS = ['input', 'cacheRead', 'cacheWrite', 'output', 'reasoning'];
+/** Entries {@link ClaudeUsageDeduper.exportState} keeps by default. */
+const DEFAULT_EXPORT_LIMIT = 256;
+function isCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function bucketsFrom(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const buckets = {};
+    for (const key of BUCKET_KEYS) {
+        const count = record[key];
+        if (!isCount(count))
+            return null;
+        buckets[key] = count;
+    }
+    return buckets;
+}
 function bucketsOf(usage) {
     return {
         input: usage.uncachedInputTokens,
@@ -163,6 +182,55 @@ export class ClaudeUsageDeduper {
     reset() {
         this.seen.clear();
     }
+    /**
+     * The most recent `limit` message ids and the tokens counted for each,
+     * oldest first. Split lines of one response are adjacent, so a reader
+     * resumed at the position this was taken at needs only the last few.
+     */
+    exportState(limit = DEFAULT_EXPORT_LIMIT) {
+        const count = limit >= 0 ? Math.min(this.seen.size, Math.floor(limit)) : 0;
+        const entries = [];
+        if (count > 0) {
+            let skip = this.seen.size - count;
+            for (const [id, buckets] of this.seen) {
+                if (skip > 0) {
+                    skip -= 1;
+                    continue;
+                }
+                entries.push([id, { ...buckets }]);
+            }
+        }
+        return { version: 1, entries };
+    }
+    /**
+     * Replaces this deduper's state with one from {@link exportState}. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state
+     * (wrong shape, empty ids, or counts that are not finite non-negative
+     * numbers). Entries beyond this deduper's capacity drop oldest first.
+     */
+    importState(state) {
+        if (!state || typeof state !== 'object')
+            return false;
+        const { version, entries } = state;
+        if (version !== 1 || !Array.isArray(entries))
+            return false;
+        const parsed = [];
+        for (const entry of entries) {
+            if (!Array.isArray(entry) || entry.length !== 2)
+                return false;
+            const [id, value] = entry;
+            if (typeof id !== 'string' || id.length === 0)
+                return false;
+            const buckets = bucketsFrom(value);
+            if (!buckets)
+                return false;
+            parsed.push([id, buckets]);
+        }
+        this.seen.clear();
+        for (const [id, buckets] of parsed)
+            this.remember(id, buckets);
+        return true;
+    }
     remember(id, buckets) {
         this.seen.delete(id);
         this.seen.set(id, buckets);

package/dist/esm/watchers/eventBridge.js

@@ -8,6 +8,7 @@
  * FollowEvent is a lossy summary for timeline display and CLI output.
  */
 import { formatToolSummary } from '../formatters/toolSummary';
+import { isTaskNotificationSystemEvent, taskNotificationFromEvent } from '../subagentSpawn';
 /**
  * Converts a single SessionEvent to one or more FollowEvents.
  *
@@ -148,6 +149,20 @@ export function toFollowEvents(event, providerId) {
             break;
         }
         case 'system': {
+            // A background task's notice (opt-in reader event): its summary, not the raw block.
+            const notification = isTaskNotificationSystemEvent(event)
+                ? taskNotificationFromEvent(event)
+                : null;
+            if (notification) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: notification.summary ?? `Background task ${notification.status ?? 'finished'}`,
+                    raw: event,
+                });
+                break;
+            }
             const text = extractTextContent(event.message?.content);
             const label = event.message?.sourceLabel || event.message?.role || 'system';
             const summary = text ||

package/dist/esm/watchers/factory.js

@@ -41,13 +41,15 @@ export function resolveSessionPath(provider, workspacePath, sessionId) {
 export function createWatcher(options) {
     const { provider, workspacePath, sessionId, callbacks } = options;
     const sessionPath = resolveSessionPath(provider, workspacePath, sessionId);
-    const watcher = createWatcherForProvider(provider, sessionPath, callbacks);
+    const watcher = createWatcherForProvider(provider, sessionPath, callbacks, {
+        includeTaskNotifications: options.includeTaskNotifications === true,
+    });
     return { watcher, sessionPath };
 }
-function createWatcherForProvider(provider, sessionPath, callbacks) {
+function createWatcherForProvider(provider, sessionPath, callbacks, jsonlOptions) {
     switch (provider.id) {
         case 'claude-code':
-            return new JsonlSessionWatcher(provider.id, sessionPath, callbacks);
+            return new JsonlSessionWatcher(provider.id, sessionPath, callbacks, jsonlOptions);
         case 'codex':
             return new ProviderReaderSessionWatcher(provider, sessionPath, callbacks);
         case 'opencode': {