sidekick-shared 0.28.3 → 0.29.1

package/dist/usage/usageReports.js

@@ -13,6 +13,8 @@ exports.bucketUsage = bucketUsage;
 exports.summarizeUsageRows = summarizeUsageRows;
 const costProvenance_1 = require("../aggregation/costProvenance");
 const formatting_1 = require("../formatting");
+const modelInfo_1 = require("../modelInfo");
+const claudeUsageDedupe_1 = require("./claudeUsageDedupe");
 function dayParts(ms, utc) {
     const date = new Date(ms);
     return utc
@@ -75,7 +77,8 @@ function addTokens(target, source) {
 }
 /**
  * Group usage events into rows. Rows are sorted by key (sessions by first
- * event), then provider, project, and model, so tables read oldest first.
+ * event), then provider, project, and model, so tables read oldest first;
+ * rows grouped by `session` within one of those follow their first event.
  */
 function bucketUsage(events, options) {
     const groupBy = new Set(options.groupBy ?? ['provider']);
@@ -83,13 +86,21 @@ function bucketUsage(events, options) {
     const byProvider = isSession || groupBy.has('provider');
     const byProject = isSession || groupBy.has('project');
     const byModel = groupBy.has('model');
+    const bySession = isSession || groupBy.has('session');
+    const keyModel = options.modelKey === 'canonical'
+        ? (model) => (model === claudeUsageDedupe_1.SYNTHETIC_MODEL ? model : (0, modelInfo_1.canonicalModelId)(model) || model)
+        : (model) => model;
     const buckets = new Map();
     for (const event of events) {
+        if (options.excludeSynthetic && event.model === claudeUsageDedupe_1.SYNTHETIC_MODEL)
+            continue;
         const key = usageBucketKey(event, options);
         const provider = byProvider ? event.provider : null;
         const project = byProject ? event.project : null;
-        const model = byModel ? event.model : null;
-        const id = [key, provider ?? '', project ?? '', model ?? ''].join('|');
+        const eventModel = keyModel(event.model);
+        const model = byModel ? eventModel : null;
+        const sessionId = bySession ? event.sessionId : null;
+        const id = JSON.stringify([key, provider, project, model, sessionId]);
         let acc = buckets.get(id);
         if (!acc) {
             acc = {
@@ -99,15 +110,17 @@ function bucketUsage(events, options) {
                     provider,
                     project,
                     model,
-                    sessionId: isSession ? event.sessionId : null,
+                    sessionId,
                     models: [],
                     calls: 0,
                     sessions: 0,
                     tokens: emptyTokens(),
                     totalTokens: 0,
                     costUsd: 0,
+                    pricedCostUsd: null,
                     costProvenance: 'none',
                     unpricedCalls: 0,
+                    reasoningTokens: 0,
                     firstTimestamp: event.timestamp,
                     lastTimestamp: event.timestamp,
                 },
@@ -122,12 +135,14 @@ function bucketUsage(events, options) {
         row.calls += 1;
         addTokens(row.tokens, event.tokens);
         row.totalTokens += event.tokens.totalTokens;
+        row.reasoningTokens = (row.reasoningTokens ?? 0) + reasoningOf(event.tokens.reasoningTokens);
         row.firstTimestamp = Math.min(row.firstTimestamp, event.timestamp);
         row.lastTimestamp = Math.max(row.lastTimestamp, event.timestamp);
         acc.sessionIds.add(event.sessionId);
-        acc.modelTokens.set(event.model, (acc.modelTokens.get(event.model) ?? 0) + event.tokens.totalTokens);
+        acc.modelTokens.set(eventModel, (acc.modelTokens.get(eventModel) ?? 0) + event.tokens.totalTokens);
         if (event.costUsd !== null) {
             row.costUsd += event.costUsd;
+            row.pricedCostUsd = (row.pricedCostUsd ?? 0) + event.costUsd;
             if (event.costProvenance === 'provider-reported')
                 acc.reportedCalls += 1;
             else
@@ -153,7 +168,14 @@ function bucketUsage(events, options) {
     return rows.sort((a, b) => (isSession ? a.firstTimestamp - b.firstTimestamp : a.key.localeCompare(b.key)) ||
         (a.provider ?? '').localeCompare(b.provider ?? '') ||
         (a.project ?? '').localeCompare(b.project ?? '') ||
-        (a.model ?? '').localeCompare(b.model ?? ''));
+        (a.model ?? '').localeCompare(b.model ?? '') ||
+        (bySession && !isSession
+            ? a.firstTimestamp - b.firstTimestamp ||
+                (a.sessionId ?? '').localeCompare(b.sessionId ?? '')
+            : 0));
+}
+function reasoningOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
 }
 /**
  * Sum rows that do not overlap (for example every row of one `bucketUsage`
@@ -167,8 +189,10 @@ function summarizeUsageRows(rows, events) {
         tokens: emptyTokens(),
         totalTokens: 0,
         costUsd: 0,
+        pricedCostUsd: null,
         costProvenance: 'none',
         unpricedCalls: 0,
+        reasoningTokens: 0,
     };
     let reportedCalls = 0;
     let estimatedCalls = 0;
@@ -178,6 +202,15 @@ function summarizeUsageRows(rows, events) {
         addTokens(totals.tokens, row.tokens);
         totals.totalTokens += row.totalTokens;
         totals.costUsd += row.costUsd;
+        // Rows from before `pricedCostUsd` existed: any priced call means a priced cost.
+        const rowPriced = row.pricedCostUsd !== undefined
+            ? row.pricedCostUsd
+            : row.calls > row.unpricedCalls
+                ? row.costUsd
+                : null;
+        if (rowPriced !== null)
+            totals.pricedCostUsd = (totals.pricedCostUsd ?? 0) + rowPriced;
+        totals.reasoningTokens = (totals.reasoningTokens ?? 0) + reasoningOf(row.reasoningTokens);
         totals.unpricedCalls += row.unpricedCalls;
         const priced = row.calls - row.unpricedCalls;
         if (row.costProvenance === 'reported')

package/dist/watchers/eventBridge.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toFollowEvents = toFollowEvents;
 const toolSummary_1 = require("../formatters/toolSummary");
+const subagentSpawn_1 = require("../subagentSpawn");
 /**
  * Converts a single SessionEvent to one or more FollowEvents.
  *
@@ -151,6 +152,20 @@ function toFollowEvents(event, providerId) {
             break;
         }
         case 'system': {
+            // A background task's notice (opt-in reader event): its summary, not the raw block.
+            const notification = (0, subagentSpawn_1.isTaskNotificationSystemEvent)(event)
+                ? (0, subagentSpawn_1.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/watchers/factory.d.ts

@@ -8,6 +8,12 @@ export interface CreateWatcherOptions {
     workspacePath: string;
     sessionId?: string;
     callbacks: SessionWatcherCallbacks;
+    /**
+     * Claude Code only: also emit a `system` event for each mid-turn
+     * task-notification attachment, so an `EventAggregator` fed by this watcher
+     * can finish background subagents. Default `false`.
+     */
+    includeTaskNotifications?: boolean;
 }
 /**
  * Resolve the session a command should act on: an exact or unique-prefix

package/dist/watchers/factory.js

@@ -78,13 +78,15 @@ function resolveSessionPath(provider, workspacePath, sessionId) {
 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 jsonlWatcher_1.JsonlSessionWatcher(provider.id, sessionPath, callbacks);
+            return new jsonlWatcher_1.JsonlSessionWatcher(provider.id, sessionPath, callbacks, jsonlOptions);
         case 'codex':
             return new providerReaderWatcher_1.ProviderReaderSessionWatcher(provider, sessionPath, callbacks);
         case 'opencode': {

package/dist/watchers/jsonlTail.d.ts

@@ -7,6 +7,8 @@ import type { ZodType } from 'zod';
 export declare const DEFAULT_JSONL_TAIL_READ_BYTES: number;
 /** Default longest line parsed; longer lines are skipped and reported. */
 export declare const DEFAULT_JSONL_TAIL_MAX_LINE_BYTES: number;
+/** The `version` written into, and accepted from, {@link JsonlTailCheckpoint}. */
+export declare const JSONL_TAIL_CHECKPOINT_VERSION = 1;
 export interface JsonlTailBatch {
     bytesRead: number;
     eventsRead: number;
@@ -20,12 +22,69 @@ export interface JsonlTailLine {
     length: number;
 }
 export type JsonlTailResetReason = 'truncated' | 'rewritten' | 'replaced';
-/** The tail started over from the beginning of the file. */
+/**
+ * What the tail does when the file it follows shrank, was rewritten, or was
+ * replaced: `'restart'` replays it from offset 0; `'end'` continues from its
+ * current end, skipping what it already holds.
+ */
+export type JsonlTailRewritePolicy = 'restart' | 'end';
+/** The tail started over from the beginning, or (with `onRewrite: 'end'`) the end, of the file. */
 export interface JsonlTailReset {
     /** `truncated`: the file shrank; `rewritten`: its first bytes or the resume point changed; `replaced`: another file now has the path. */
     reason: JsonlTailResetReason;
     /** The committed offset before the reset. */
     previousOffset: number;
+    /**
+     * Where reading continues. Present only with `onRewrite: 'end'`; with the
+     * default `'restart'` policy reading always continues from 0.
+     */
+    offset?: number;
+}
+/** An event parsed by {@link JsonlTail.read}, with its line's position. */
+export interface JsonlTailEntry<T> {
+    event: T;
+    line: JsonlTailLine;
+}
+/** What one {@link JsonlTail.read} call read. */
+export interface JsonlTailReadResult<T> extends JsonlTailBatch {
+    /** Events from the lines that became complete, in file order: the same ones `onEvent` received. */
+    events: JsonlTailEntry<T>[];
+    /** Present when the tail reset before reading; `onReset` received the same object. */
+    reset?: JsonlTailReset;
+}
+/**
+ * A JSON-serializable resume point from {@link JsonlTail.checkpoint} or
+ * {@link captureJsonlCheckpoint}. It identifies the file by device and inode
+ * plus a digest of its first bytes, so a new tail (in this or a later
+ * process) or {@link verifyJsonlCheckpoint} can confirm the file is still the
+ * same, append-only one before anything continues from `offset`.
+ */
+export interface JsonlTailCheckpoint {
+    version: typeof JSONL_TAIL_CHECKPOINT_VERSION;
+    /** Resume-safe byte offset: 0, or just after a newline. */
+    offset: number;
+    /** Device and inode of the file the offset refers to; `null` before the first read. */
+    identity: {
+        dev: number;
+        ino: number;
+    } | null;
+    /**
+     * Length (at most 4096) and truncated SHA-256 hex of the file's first
+     * bytes when last read; `null` before the first read.
+     */
+    prefixDigest: {
+        bytes: number;
+        hash: string;
+    } | null;
+}
+/**
+ * Reported to `onError` (and nothing is read) when `noFollow` is set and the
+ * tailed path is a symbolic link.
+ */
+export declare class JsonlTailSymlinkError extends Error {
+    readonly path: string;
+    readonly code = "JSONL_TAIL_SYMLINK";
+    constructor(path: string);
 }
 export interface JsonlTailOptions<T> {
     path: string;
@@ -37,20 +96,81 @@ export interface JsonlTailOptions<T> {
     onEvent: (event: T, line: JsonlTailLine) => void;
     onBatchComplete?: (batch: JsonlTailBatch) => void;
     onError?: (error: Error, line?: string) => void;
-    /** Called after the tail resets to offset 0; events from the start follow. */
+    /** Called after the tail resets (see `onRewrite`); events from the new position follow. */
     onReset?: (reset: JsonlTailReset) => void;
     /** Bytes read per chunk (default 1 MiB); one poll reads chunk by chunk to the end. */
     maxReadBytes?: number;
     /** Longest line parsed (default 16 MiB); a longer line is skipped and reported to `onError`. */
     maxLineBytes?: number;
+    /**
+     * Where to continue after the file is truncated, rewritten, or replaced,
+     * and after `resumeFrom()` rejects a checkpoint. `'restart'` (default)
+     * replays from offset 0. `'end'` continues from the file's current end, or
+     * from the start of an unfinished final line as `startAtEnd` does. `onReset`
+     * fires either way.
+     */
+    onRewrite?: JsonlTailRewritePolicy;
+    /**
+     * Refuse to follow a symbolic link at `path`: the file is opened with
+     * `O_NOFOLLOW` where the platform defines it (a no-op where it does not,
+     * such as Windows). A symlinked path is reported to `onError` as a
+     * {@link JsonlTailSymlinkError} and not read or watched. Only the final
+     * path component is checked; symlinked parent directories still resolve.
+     */
+    noFollow?: boolean;
 }
-export interface JsonlTail {
+export interface JsonlTail<T = unknown> {
     readonly isActive: boolean;
     start(): void;
     stop(): void;
     dispose(): void;
+    /**
+     * Reads every newly complete line now, synchronously, through the
+     * callbacks. While `read()` calls are queued or running, the call is
+     * deferred until the last of them settles.
+     */
     readNow(): void;
+    /**
+     * Reads like `readNow()`, with asynchronous I/O, and resolves with what it
+     * read; the callbacks fire as they do for `readNow()`. Never rejects for
+     * I/O or parse problems (those go to `onError`). Concurrent calls run one
+     * after another.
+     */
+    read(): Promise<JsonlTailReadResult<T>>;
     getOffset(): number;
     seekTo(offset: number): void;
+    /** A JSON-serializable resume point at the committed offset; does no I/O. */
+    checkpoint(): JsonlTailCheckpoint;
+    /**
+     * Validates `checkpoint` (shape, file identity, prefix digest, and that its
+     * offset still follows a newline) against the file now at the path. On
+     * success reading continues from its offset and this returns true.
+     * Otherwise the `onRewrite` policy picks the position (0, or the file's
+     * current end) and this returns false; `onReset` is not called. Either way
+     * the position overrides `startAtEnd` on a later `start()`.
+     */
+    resumeFrom(checkpoint: unknown): boolean;
 }
-export declare function createJsonlTail<T>(options: JsonlTailOptions<T>): JsonlTail;
+export declare function createJsonlTail<T>(options: JsonlTailOptions<T>): JsonlTail<T>;
+/**
+ * Records a {@link JsonlTailCheckpoint} for byte `offset` of `filePath`
+ * without a tail, for readers that keep their own offset (a snapshot that
+ * stores a reader position, for example). The checkpoint carries the file's
+ * current device and inode and a digest of its first bytes, so
+ * {@link verifyJsonlCheckpoint} (or {@link JsonlTail.resumeFrom}) can later
+ * tell whether `offset` still refers to the same, append-only content.
+ *
+ * Returns `null` when the file is missing or unreadable, or when `offset` is
+ * not a resume-safe position in it: negative, past the end, or not 0 and not
+ * just after a newline. Follows symbolic links.
+ */
+export declare function captureJsonlCheckpoint(filePath: string, offset: number): JsonlTailCheckpoint | null;
+/**
+ * Whether `checkpoint` (any value, typically parsed from JSON) is a valid
+ * {@link JsonlTailCheckpoint} that still describes `filePath`: same device
+ * and inode, the recorded first bytes unchanged, and its offset within the
+ * file and just after a newline (or 0). This is the check
+ * {@link JsonlTail.resumeFrom} applies. `false` on any error, including a
+ * missing file. Follows symbolic links.
+ */
+export declare function verifyJsonlCheckpoint(filePath: string, checkpoint: unknown): boolean;