sidekick-shared 0.29.1 → 0.30.0

package/dist/types/sessionEvent.d.ts

@@ -85,7 +85,7 @@ export interface SessionEventBase {
     /** Provider-reported git branch for this event/session. */
     gitBranch?: string;
     /** Permission mode active when this event occurred */
-    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+    permissionMode?: PermissionMode;
     /** Subscription rate limits, when provided by the session source. */
     rateLimits?: {
         primary?: {
@@ -166,6 +166,11 @@ export interface SystemSessionEvent extends SessionEventBase {
     type: 'system';
     /** Bookkeeping-only system rows legitimately have no message. */
     message?: SessionMessage;
+    /**
+     * The provider's system-line subtype, when it wrote one (Claude Code:
+     * `turn_duration`, `compact_boundary`, `agents_killed`, …).
+     */
+    subtype?: string;
 }
 export interface ToolUseSessionEvent extends SessionEventBase {
     type: 'tool_use';
@@ -187,9 +192,11 @@ export interface ToolResultSessionEvent extends SessionEventBase {
 /** Canonical provider-neutral event contract. */
 export type SessionEvent = UserSessionEvent | AssistantSessionEvent | SummarySessionEvent | SystemSessionEvent | ToolUseSessionEvent | ToolResultSessionEvent;
 /**
- * Permission mode values from Claude Code JSONL.
+ * Permission mode values from Claude Code JSONL. `auto` approves or denies
+ * permission prompts with a model classifier; `dontAsk` denies anything not
+ * pre-approved. Unknown future modes are dropped by the schema, not rejected.
  */
-export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'auto' | 'dontAsk';
 /**
  * A permission mode change event in the session timeline.
  */
@@ -423,6 +430,34 @@ export interface SubagentStats {
     endTime?: Date;
     /** Duration in milliseconds */
     durationMs?: number;
+    /**
+     * Codex: the subagent's rollout file — the `.jsonl`, or the `.jsonl.zst`
+     * when only the compressed one exists (with `includeCompressedRollouts`).
+     */
+    filePath?: string;
+    /**
+     * Codex: the parent's spawn call (`spawn_agent` call id) that started this
+     * subagent — the tool-use id of that call in the parent's events.
+     */
+    spawnToolUseId?: string;
+    /** Codex: the display nickname Codex gave the subagent (e.g. `Banach`). */
+    agentNickname?: string;
+    /** Codex: the subagent's agent path (e.g. `/root/review_builder`). */
+    agentPath?: string;
+    /**
+     * Codex: the thread that spawned this subagent — the session's id for its
+     * own children, another subagent's `agentId` below that.
+     */
+    parentAgentId?: string;
+    /** Codex: spawn depth — 1 for the session's own children, 2 for theirs, … */
+    depth?: number;
+    /**
+     * The subagent's transcript ended cleanly: Claude Code, its last assistant
+     * turn stopped with `end_turn` / `stop_sequence` and left no tool call
+     * unanswered; Codex, its last own turn ended with `task_complete`. A later
+     * prompt (a resumed agent) clears it. Absent when unknown.
+     */
+    endedCleanly?: boolean;
 }
 /**
  * Pending user request awaiting assistant response.

package/dist/usage/usageEvents.d.ts

@@ -15,7 +15,10 @@
  * tagged with the subagent, and their sizes and mtimes join the fingerprint.
  * (Codex spawned subagents and forks are top-level rollouts, already listed
  * as sessions of their own; their events are tagged with the parent read
- * from the rollout's first line.)
+ * from the rollout's first line; the parent history a forked child embeds
+ * is not counted (it carries no token usage). Compressed rollouts
+ * (`….jsonl.zst`) are read when a Codex provider was created with
+ * `includeCompressedRollouts`.)
  *
  * Each event also carries the ordinal of the human prompt it answered, from
  * the same scanner as `collectPromptHistory()`, so usage joins prompt history

package/dist/usage/usageEvents.js

@@ -16,7 +16,10 @@
  * tagged with the subagent, and their sizes and mtimes join the fingerprint.
  * (Codex spawned subagents and forks are top-level rollouts, already listed
  * as sessions of their own; their events are tagged with the parent read
- * from the rollout's first line.)
+ * from the rollout's first line; the parent history a forked child embeds
+ * is not counted (it carries no token usage). Compressed rollouts
+ * (`….jsonl.zst`) are read when a Codex provider was created with
+ * `includeCompressedRollouts`.)
  *
  * Each event also carries the ordinal of the human prompt it answered, from
  * the same scanner as `collectPromptHistory()`, so usage joins prompt history

package/dist/watchers/eventBridge.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toFollowEvents = toFollowEvents;
 const toolSummary_1 = require("../formatters/toolSummary");
 const subagentSpawn_1 = require("../subagentSpawn");
+const subagentActivity_1 = require("../subagentActivity");
 /**
  * Converts a single SessionEvent to one or more FollowEvents.
  *
@@ -166,6 +167,35 @@ function toFollowEvents(event, providerId) {
                 });
                 break;
             }
+            // The user stopping background agents, or a background agent's final status.
+            const stopped = (0, subagentSpawn_1.agentsStoppedNoticeFromEvent)(event);
+            const taskStatus = stopped ? null : (0, subagentSpawn_1.taskStatusFromEvent)(event);
+            if (stopped || taskStatus || (0, subagentSpawn_1.isAgentsKilledSystemEvent)(event)) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: stopped
+                        ? (0, subagentSpawn_1.describeAgentsStopped)(stopped)
+                        : taskStatus
+                            ? (0, subagentSpawn_1.describeTaskStatus)(taskStatus)
+                            : (0, subagentSpawn_1.describeAgentsStopped)(null),
+                    raw: event,
+                });
+                break;
+            }
+            // A subagent lifecycle record (opt-in Codex parser event): a content-free summary.
+            const activity = (0, subagentActivity_1.subagentActivityFromEvent)(event);
+            if (activity) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: (0, subagentActivity_1.describeSubagentActivity)(activity),
+                    raw: event,
+                });
+                break;
+            }
             const text = extractTextContent(event.message?.content);
             const label = event.message?.sourceLabel || event.message?.role || 'system';
             const summary = text ||

package/dist/watchers/jsonlTail.js

@@ -43,6 +43,7 @@ exports.captureJsonlCheckpoint = captureJsonlCheckpoint;
 exports.verifyJsonlCheckpoint = verifyJsonlCheckpoint;
 const fs = __importStar(require("fs"));
 const fileHead_1 = require("../fileHead");
+const fileContinuity_1 = require("../fileContinuity");
 const jsonl_1 = require("../parsers/jsonl");
 const DEFAULT_DEBOUNCE_MS = 100;
 const DEFAULT_CATCHUP_INTERVAL_MS = 30_000;
@@ -168,10 +169,8 @@ class JsonlTailReader {
     /** Inside a line over `maxLineBytes`: drop bytes until its newline. */
     skippingLine = false;
     currentLine = { offset: 0, length: 0 };
-    /** Identity and prefix of the file the offsets refer to, once read. */
-    identity = null;
-    head = null;
-    lastMtimeMs = -1;
+    /** Identity, mtime, and prefix of the file the offsets refer to, once read. */
+    continuity = new fileContinuity_1.FileContinuity();
     maxReadBytes;
     maxLineBytes;
     rewritePolicy;
@@ -379,21 +378,10 @@ class JsonlTailReader {
     }
     /** Whether the continuity check needs bytes from the file. */
     probeNeeded(stat) {
-        return (this.identity === null ||
-            stat.dev !== this.identity.dev ||
-            stat.ino !== this.identity.ino ||
-            stat.size < this.readOffset ||
-            stat.mtimeMs !== this.lastMtimeMs ||
-            this.head === null ||
-            this.head.bytes < Math.min(fileHead_1.HEAD_BYTES, stat.size));
+        return this.continuity.needsProbe(stat, this.readOffset);
     }
     probeSync(fd, stat) {
-        return {
-            prefix: readPrefix(fd, stat),
-            before: this.committedOffset > 0 && this.committedOffset <= stat.size
-                ? readAt(fd, this.committedOffset - 1, 1)
-                : null,
-        };
+        return (0, fileContinuity_1.probeFileContinuity)(fd, stat, this.committedOffset);
     }
     async probeAsync(handle, stat) {
         const committedOffset = this.committedOffset;
@@ -410,31 +398,16 @@ class JsonlTailReader {
      * newline. `null` when it can continue.
      */
     resetReason(stat, probe) {
-        if (this.identity && (stat.dev !== this.identity.dev || stat.ino !== this.identity.ino)) {
-            return 'replaced';
-        }
-        if (stat.size < this.readOffset)
-            return 'truncated';
-        if (this.identity && stat.mtimeMs !== this.lastMtimeMs && probe) {
-            if (this.head && !(0, fileHead_1.headMatches)(this.head, probe.prefix))
-                return 'rewritten';
-            if (probe.before && probe.before[0] !== 0x0a)
-                return 'rewritten';
-        }
-        return null;
+        return this.continuity.reasonFor(stat, this.readOffset, probe);
     }
     /** Records the identity and prefix of the file the offsets now refer to. */
     adoptFile(stat, probe) {
-        this.identity = { dev: stat.dev, ino: stat.ino };
-        this.lastMtimeMs = stat.mtimeMs;
-        if (probe && (!this.head || this.head.bytes < Math.min(fileHead_1.HEAD_BYTES, stat.size))) {
-            this.head = (0, fileHead_1.fileHeadOf)(probe.prefix);
-        }
+        this.continuity.record(stat, probe);
     }
     reset(reason, offset) {
         const previousOffset = this.committedOffset;
         this.position(offset);
-        this.head = null;
+        this.continuity.discardHead();
         if (reason === 'replaced' && this.active) {
             // fs.watch follows the old inode; watch the file now at the path.
             this.fsWatcher?.close();
@@ -509,7 +482,7 @@ class JsonlTailReader {
         this.position(Math.max(0, offset));
     }
     checkpoint() {
-        return checkpointOf(this.committedOffset, this.identity, this.head);
+        return checkpointOf(this.committedOffset, this.continuity.knownIdentity, this.continuity.knownHead);
     }
     resumeFrom(checkpoint) {
         this.generation += 1;
@@ -527,16 +500,12 @@ class JsonlTailReader {
                     ? lastCompleteLineOffset(fd, stat.size)
                     : 0;
             this.position(offset);
-            this.identity = { dev: stat.dev, ino: stat.ino };
-            this.lastMtimeMs = stat.mtimeMs;
-            this.head = (0, fileHead_1.fileHeadOf)(prefix);
+            this.continuity.adoptPrefix(stat, prefix);
             return matches;
         }
         catch (error) {
             this.position(0);
-            this.identity = null;
-            this.head = null;
-            this.lastMtimeMs = -1;
+            this.continuity.forget();
             this.options.onError?.(toError(error));
             return false;
         }

package/dist/watchers/jsonlWatcher.d.ts

@@ -8,7 +8,11 @@ import type { SessionWatcher, SessionWatcherCallbacks } from './types';
 export interface JsonlSessionWatcherOptions {
     /**
      * Emit a `system` event (summary from the notification, `raw` the line) for
-     * each Claude Code mid-turn task-notification attachment. Default `false`.
+     * each Claude Code mid-turn task-notification attachment, and for the other
+     * lines that settle background agents: the plain-text "background agents
+     * were stopped by the user" notice, a background agent's final
+     * `task_status` attachment, and an `agents_killed` system line. Default
+     * `false`.
      */
     includeTaskNotifications?: boolean;
 }

package/dist/watchers/jsonlWatcher.js

@@ -139,15 +139,25 @@ function normalizeClaudeCodeEvent(raw, deduper, includeTaskNotifications) {
         }
         else if (includeTaskNotifications) {
             // A task notification that landed mid-turn is only an attachment line.
-            const notification = (0, subagentSpawn_1.parseTaskNotification)((0, subagentSpawn_1.taskNotificationPromptFromAttachment)(raw));
+            const prompt = (0, subagentSpawn_1.taskNotificationPromptFromAttachment)(raw);
+            const notification = (0, subagentSpawn_1.parseTaskNotification)(prompt);
+            const stopped = notification ? null : (0, subagentSpawn_1.parseAgentsStoppedNotice)(prompt);
+            const taskStatus = (0, subagentSpawn_1.taskStatusFromAttachment)(raw);
+            let summary = null;
             if (notification) {
-                events.push({
-                    providerId: 'claude-code',
-                    type: 'system',
-                    timestamp: ts,
-                    summary: notification.summary ?? `Background task ${notification.status ?? 'finished'}`,
-                    raw,
-                });
+                summary = notification.summary ?? `Background task ${notification.status ?? 'finished'}`;
+            }
+            else if (stopped) {
+                summary = (0, subagentSpawn_1.describeAgentsStopped)(stopped);
+            }
+            else if (taskStatus && (0, subagentSpawn_1.isFinalTaskStatus)(taskStatus.status)) {
+                summary = (0, subagentSpawn_1.describeTaskStatus)(taskStatus);
+            }
+            else if ((0, subagentSpawn_1.isAgentsKilledSystemEvent)(raw)) {
+                summary = (0, subagentSpawn_1.describeAgentsStopped)(null);
+            }
+            if (summary !== null) {
+                events.push({ providerId: 'claude-code', type: 'system', timestamp: ts, summary, raw });
             }
         }
     }

package/dist/watchers/providerReaderWatcher.js

@@ -148,11 +148,12 @@ class ProviderReaderSessionWatcher {
         if (!this._isActive)
             return;
         try {
-            if (this.reader.wasTruncated()) {
-                this.reader.reset();
-                this.callbacks.onReset?.();
-            }
             const events = this.reader.readNew();
+            // The reader started over (truncated, rewritten, or replaced file):
+            // these events are the session from the beginning, so consumers must
+            // drop what they built before receiving them.
+            if (this.reader.wasTruncated())
+                this.callbacks.onReset?.();
             for (const event of events) {
                 for (const followEvent of (0, eventBridge_1.toFollowEvents)(event, this.provider.id)) {
                     this.callbacks.onEvent(followEvent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "keywords": [
     "claude-code",