sidekick-shared 0.29.0 → 0.29.1

package/dist/subagentSpawn.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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
+ */
+import type { SubagentOutcome } from './aggregation/types';
+import type { SessionEvent } from './types/sessionEvent';
+/** Tool names that spawn a subagent: `Agent` (current) and `Task` (earlier name). */
+export declare const SUBAGENT_SPAWN_TOOL_NAMES: readonly string[];
+/** Whether a tool name spawns a subagent (`Agent` or `Task`). */
+export declare function isSubagentSpawnTool(name: string | null | undefined): boolean;
+/** A spawning tool result that launched the agent in the background. */
+export interface AsyncAgentLaunch {
+    /** The agent id Claude Code reported (`agentId: <id>`), when present. */
+    agentId?: string;
+}
+/**
+ * Plain text of tool-result or message content: a string as-is, or the text
+ * blocks of a content array joined by newlines.
+ */
+export declare function contentText(content: unknown): string;
+/**
+ * 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 declare function parseAsyncAgentLaunch(result: unknown): AsyncAgentLaunch | null;
+/** Fields of a `<task-notification>` block. */
+export interface TaskNotification {
+    /** `<task-id>`: the background agent's id (or a background shell task's id). */
+    taskId: string;
+    /** `<tool-use-id>`: the tool call that started the background work. */
+    toolUseId?: string;
+    /** `<status>` as written, e.g. `completed`, `failed`, `killed`, `stopped`. */
+    status?: string;
+    /** `<summary>`, e.g. `Agent "Explore auth" finished`. */
+    summary?: string;
+    /**
+     * The agent stopped while background work of its own is still running; it
+     * may resume, and the same task id notifies again.
+     */
+    interim: boolean;
+}
+/**
+ * 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 declare function parseTaskNotification(text: unknown): TaskNotification | null;
+/**
+ * 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 declare function taskNotificationPromptFromAttachment(raw: unknown): string | 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 declare function isTaskNotificationSystemEvent(event: SessionEvent): boolean;
+/**
+ * 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 declare function taskNotificationFromEvent(event: SessionEvent): TaskNotification | null;
+/** Maps a notification `<status>` to an outcome; unknown or missing statuses read as `completed`. */
+export declare function taskNotificationOutcome(status: string | undefined): SubagentOutcome;

package/dist/subagentSpawn.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBAGENT_SPAWN_TOOL_NAMES = void 0;
+exports.isSubagentSpawnTool = isSubagentSpawnTool;
+exports.contentText = contentText;
+exports.parseAsyncAgentLaunch = parseAsyncAgentLaunch;
+exports.parseTaskNotification = parseTaskNotification;
+exports.taskNotificationPromptFromAttachment = taskNotificationPromptFromAttachment;
+exports.isTaskNotificationSystemEvent = isTaskNotificationSystemEvent;
+exports.taskNotificationFromEvent = taskNotificationFromEvent;
+exports.taskNotificationOutcome = taskNotificationOutcome;
+/** Tool names that spawn a subagent: `Agent` (current) and `Task` (earlier name). */
+exports.SUBAGENT_SPAWN_TOOL_NAMES = Object.freeze(['Agent', 'Task']);
+const SPAWN_TOOLS = new Set(exports.SUBAGENT_SPAWN_TOOL_NAMES);
+/** Whether a tool name spawns a subagent (`Agent` or `Task`). */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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`. */
+function taskNotificationOutcome(status) {
+    switch (status?.toLowerCase()) {
+        case 'failed':
+            return 'failed';
+        case 'killed':
+            return 'killed';
+        case 'stopped':
+            return 'stopped';
+        default:
+            return 'completed';
+    }
+}

package/dist/transcript.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectSessionTranscript = projectSessionTranscript;
 const usageNormalization_1 = require("./usageNormalization");
+const subagentSpawn_1 = require("./subagentSpawn");
 const EMPTY_TOTALS = {
     uncachedInputTokens: 0,
     cacheReadTokens: 0,
@@ -28,6 +29,9 @@ 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 ((0, subagentSpawn_1.isTaskNotificationSystemEvent)(event))
+            return;
         if (nonEmpty(event.cwd))
             cwd = event.cwd;
         if (nonEmpty(event.gitBranch))

package/dist/turns/assistantTurn.d.ts

@@ -70,6 +70,7 @@ export interface ReasoningSummary {
     body: string;
 }
 export declare function reasoningSummary(text: string): ReasoningSummary;
+/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
 export declare function isAssistantTurnSubagentTool(toolName: string | undefined): boolean;
 export declare function segmentAssistantTurn(events: readonly AssistantTurnEvent[], options?: SegmentAssistantTurnOptions): AssistantTurnProjection;
 export declare function assistantTurnEventsFromSessionEvents(events: readonly SessionEvent[]): AssistantTurnEvent[];

package/dist/turns/assistantTurn.js

@@ -6,12 +6,12 @@ exports.segmentAssistantTurn = segmentAssistantTurn;
 exports.assistantTurnEventsFromSessionEvents = assistantTurnEventsFromSessionEvents;
 exports.extractTurnSubagents = extractTurnSubagents;
 const toolSummary_1 = require("../formatters/toolSummary");
+const subagentSpawn_1 = require("../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;
@@ -29,8 +29,9 @@ function reasoningSummary(text) {
     }
     return { title: null, body: trimmed };
 }
+/** Whether a tool call spawns a subagent (`Agent`, or its earlier name `Task`). */
 function isAssistantTurnSubagentTool(toolName) {
-    return toolName != null && SUBAGENT_TOOL_NAMES.has(toolName);
+    return (0, subagentSpawn_1.isSubagentSpawnTool)(toolName);
 }
 function segmentAssistantTurn(events, options = {}) {
     const maxNarrationChars = options.maxNarrationChars ?? DEFAULT_NARRATION_CHARS;

package/dist/usage/claudeUsageDedupe.d.ts

@@ -22,6 +22,24 @@ import type { SessionEvent } from '../types/sessionEvent';
 export declare const SYNTHETIC_MODEL = "<synthetic>";
 /** Attach Anthropic-semantics normalized usage and Claude Code provenance to an event. */
 export declare function normalizeClaudeUsage(event: SessionEvent): SessionEvent;
+/** Tokens a {@link ClaudeUsageDeduper} has already counted for one message id. */
+export interface ClaudeUsageDedupeBuckets {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+/**
+ * JSON-serializable state of a {@link ClaudeUsageDeduper}, from
+ * `exportState()`, for `importState()` in a reader resumed at the same
+ * position (for example from a persisted session snapshot).
+ */
+export interface ClaudeUsageDedupeState {
+    version: 1;
+    /** `[message id, counted tokens]` pairs, oldest first. */
+    entries: Array<[string, ClaudeUsageDedupeBuckets]>;
+}
 /**
  * Per-reader dedupe state. Split lines of one response are adjacent, so a
  * bounded map (oldest keys evicted first) is enough.
@@ -40,6 +58,19 @@ export declare class ClaudeUsageDeduper {
     /** Whether a message id has already been counted by this deduper. */
     has(id: string): boolean;
     reset(): void;
+    /**
+     * 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?: number): ClaudeUsageDedupeState;
+    /**
+     * 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: unknown): boolean;
     private remember;
 }
 /**

package/dist/usage/claudeUsageDedupe.js

@@ -64,6 +64,25 @@ 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,
@@ -168,6 +187,55 @@ 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/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

@@ -53,10 +53,11 @@ export interface JsonlTailReadResult<T> extends JsonlTailBatch {
     reset?: JsonlTailReset;
 }
 /**
- * A JSON-serializable resume point from {@link JsonlTail.checkpoint}. 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) can verify it is still reading
- * the same, append-only file before continuing from `offset`.
+ * 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;
@@ -151,3 +152,25 @@ export interface JsonlTail<T = unknown> {
     resumeFrom(checkpoint: unknown): boolean;
 }
 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;

package/dist/watchers/jsonlTail.js

@@ -39,6 +39,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonlTailSymlinkError = exports.JSONL_TAIL_CHECKPOINT_VERSION = exports.DEFAULT_JSONL_TAIL_MAX_LINE_BYTES = exports.DEFAULT_JSONL_TAIL_READ_BYTES = void 0;
 exports.createJsonlTail = createJsonlTail;
+exports.captureJsonlCheckpoint = captureJsonlCheckpoint;
+exports.verifyJsonlCheckpoint = verifyJsonlCheckpoint;
 const fs = __importStar(require("fs"));
 const fileHead_1 = require("../fileHead");
 const jsonl_1 = require("../parsers/jsonl");
@@ -98,6 +100,63 @@ exports.JsonlTailSymlinkError = JsonlTailSymlinkError;
 function createJsonlTail(options) {
     return new JsonlTailReader(options);
 }
+/**
+ * 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.
+ */
+function captureJsonlCheckpoint(filePath, offset) {
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        return null;
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        if (offset > stat.size)
+            return null;
+        if (offset > 0 && readAt(fd, offset - 1, 1)[0] !== 0x0a)
+            return null;
+        return checkpointOf(offset, stat, (0, fileHead_1.fileHeadOf)(readPrefix(fd, stat)));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeQuietly(fd);
+    }
+}
+/**
+ * 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.
+ */
+function verifyJsonlCheckpoint(filePath, checkpoint) {
+    const parsed = parseCheckpoint(checkpoint);
+    if (parsed === null)
+        return false;
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        return checkpointMatches(parsed, fd, stat, readPrefix(fd, stat));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        closeQuietly(fd);
+    }
+}
 class JsonlTailReader {
     options;
     active = false;
@@ -330,7 +389,7 @@ class JsonlTailReader {
     }
     probeSync(fd, stat) {
         return {
-            prefix: readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size)),
+            prefix: readPrefix(fd, stat),
             before: this.committedOffset > 0 && this.committedOffset <= stat.size
                 ? readAt(fd, this.committedOffset - 1, 1)
                 : null,
@@ -450,12 +509,7 @@ class JsonlTailReader {
         this.position(Math.max(0, offset));
     }
     checkpoint() {
-        return {
-            version: exports.JSONL_TAIL_CHECKPOINT_VERSION,
-            offset: this.committedOffset,
-            identity: this.identity ? { dev: this.identity.dev, ino: this.identity.ino } : null,
-            prefixDigest: this.head ? { bytes: this.head.bytes, hash: this.head.hash } : null,
-        };
+        return checkpointOf(this.committedOffset, this.identity, this.head);
     }
     resumeFrom(checkpoint) {
         this.generation += 1;
@@ -465,7 +519,7 @@ class JsonlTailReader {
         try {
             fd = this.openSync();
             const stat = fs.fstatSync(fd);
-            const prefix = readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size));
+            const prefix = readPrefix(fd, stat);
             const matches = parsed !== null && checkpointMatches(parsed, fd, stat, prefix);
             const offset = matches
                 ? parsed.offset
@@ -597,6 +651,15 @@ function parseCheckpoint(value) {
         prefixDigest: parsedDigest,
     };
 }
+/** A fresh checkpoint for `offset` in the file with `identity` and recorded `head`. */
+function checkpointOf(offset, identity, head) {
+    return {
+        version: exports.JSONL_TAIL_CHECKPOINT_VERSION,
+        offset,
+        identity: identity ? { dev: identity.dev, ino: identity.ino } : null,
+        prefixDigest: head ? { bytes: head.bytes, hash: head.hash } : null,
+    };
+}
 /** Whether `checkpoint` still describes the open file. */
 function checkpointMatches(checkpoint, fd, stat, prefix) {
     const { offset, identity, prefixDigest } = checkpoint;
@@ -639,6 +702,10 @@ function readAt(fd, position, length) {
     const count = length > 0 ? fs.readSync(fd, buffer, 0, length, position) : 0;
     return buffer.subarray(0, count);
 }
+/** The file's first `min(HEAD_BYTES, size)` bytes: what a checkpoint digests. */
+function readPrefix(fd, stat) {
+    return readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size));
+}
 async function readAtAsync(handle, position, length) {
     const buffer = Buffer.alloc(length);
     const count = length > 0 ? (await handle.read(buffer, 0, length, position)).bytesRead : 0;