sidekick-shared 0.22.0 → 0.23.1

package/dist/types/observedSessionV1.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.derivePendingUserRequestV1 = derivePendingUserRequestV1;
+exports.createProviderSessionAdapterV1 = createProviderSessionAdapterV1;
+function evidence(provider, sessionId, sourcePath, event, eventIndex) {
+    return [
+        {
+            schemaVersion: 1,
+            provider,
+            sessionId,
+            sourcePath,
+            eventIndex,
+            eventId: event?.message?.id,
+            timestamp: event?.timestamp,
+        },
+    ];
+}
+function observed(value, provenance, confidence, refs) {
+    return { value, provenance, confidence, evidence: refs };
+}
+function derivePendingUserRequestV1(provider, sessionId, sourcePath, events) {
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        // A user/tool-result event after a request means the human has responded.
+        if (event.type === 'user')
+            return null;
+        const request = waitingToolRequest(event);
+        if (request) {
+            const refs = evidence(provider, sessionId, sourcePath, event, index);
+            return {
+                schemaVersion: 1,
+                id: `${provider}:${sessionId}:${request.id ?? event.message?.id ?? index}`,
+                provider,
+                sessionId,
+                kind: observed(request.kind, 'inferred', request.kind === 'question' ? 0.95 : 0.9, refs),
+                requestedAt: observed(event.timestamp, 'reported', 1, refs),
+                prompt: observed(request.prompt, request.prompt ? 'reported' : 'inferred', request.prompt ? 0.95 : 0.4, refs),
+            };
+        }
+        // A later assistant turn proves any older request was already resolved.
+        if (event.type === 'assistant' || event.type === 'tool_use')
+            return null;
+    }
+    return null;
+}
+function waitingToolRequest(event) {
+    const calls = [];
+    const message = event.message;
+    if (event.type === 'tool_use') {
+        calls.push({ id: message?.id, name: event.tool?.name, input: event.tool?.input });
+    }
+    if (Array.isArray(message?.content)) {
+        for (const block of message.content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const value = block;
+            if (value.type !== 'tool_use')
+                continue;
+            calls.push({
+                id: typeof value.id === 'string' ? value.id : undefined,
+                name: typeof value.name === 'string' ? value.name : undefined,
+                input: value.input,
+            });
+        }
+    }
+    for (let index = calls.length - 1; index >= 0; index--) {
+        const call = calls[index];
+        if (call.name !== 'AskUserQuestion' && call.name !== 'ExitPlanMode')
+            continue;
+        return {
+            id: call.id,
+            kind: call.name === 'AskUserQuestion' ? 'question' : 'tool_approval',
+            prompt: waitingToolPrompt(call.input, call.name),
+        };
+    }
+    return null;
+}
+function waitingToolPrompt(input, toolName) {
+    if (!input || typeof input !== 'object') {
+        return toolName === 'ExitPlanMode' ? 'Approve the proposed plan?' : null;
+    }
+    const record = input;
+    if (typeof record.question === 'string')
+        return record.question;
+    if (typeof record.prompt === 'string')
+        return record.prompt;
+    if (Array.isArray(record.questions)) {
+        const questions = record.questions
+            .map((question) => question && typeof question === 'object' && 'question' in question
+            ? String(question.question ?? '')
+            : '')
+            .filter(Boolean);
+        if (questions.length > 0)
+            return questions.join('\n');
+    }
+    if (toolName === 'ExitPlanMode')
+        return 'Approve the proposed plan?';
+    return null;
+}
+function providerCapabilities(provider) {
+    const refs = [];
+    const known = (value) => observed(value, 'inferred', 1, refs);
+    return {
+        schemaVersion: 1,
+        provider,
+        resume: known(true),
+        forkLineage: known(provider !== 'opencode'),
+        quotaSource: known(provider === 'claude-code' ? 'api' : provider === 'codex' ? 'mixed' : 'none'),
+        assetExtraction: known(true),
+    };
+}
+function createProviderSessionAdapterV1(sessionProvider, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+    const adapter = {
+        schemaVersion: 1,
+        provider: sessionProvider.id,
+        capabilities: providerCapabilities(sessionProvider.id),
+        async discover(cwd) {
+            return Promise.all(sessionProvider.findAllSessions(cwd).map((sessionPath) => adapter.read(sessionPath, cwd)));
+        },
+        async read(sessionPath, cwd = '') {
+            const stats = sessionProvider.readSessionStats(sessionPath);
+            const events = sessionProvider.createReader(sessionPath).readAll();
+            const refs = evidence(sessionProvider.id, stats.sessionId, sessionPath);
+            const model = Object.entries(stats.modelUsage).sort((left, right) => right[1].calls - left[1].calls)[0]?.[0] ?? null;
+            const metadata = sessionProvider.getSessionMetadata?.(sessionPath);
+            const modifiedAt = metadata?.mtime.getTime() ?? Date.parse(stats.endTime);
+            const recent = Number.isFinite(modifiedAt) && Date.now() - modifiedAt < 2 * 60_000;
+            return {
+                schemaVersion: 1,
+                identity: {
+                    provider: sessionProvider.id,
+                    sessionId: stats.sessionId,
+                    sourcePath: sessionPath,
+                },
+                cwd: observed(cwd, 'inferred', cwd ? 0.95 : 0.4, refs),
+                model: observed(model, model ? 'reported' : 'inferred', model ? 1 : 0.2, refs),
+                activity: observed(recent ? 'active' : 'idle', 'inferred', 0.8, refs),
+                usage: {
+                    inputTokens: observed(stats.tokens.input, 'reported', 1, refs),
+                    outputTokens: observed(stats.tokens.output, 'reported', 1, refs),
+                    cacheReadTokens: observed(stats.tokens.cacheRead, 'reported', 1, refs),
+                    cacheWriteTokens: observed(stats.tokens.cacheWrite, 'reported', 1, refs),
+                    costUsd: observed(stats.reportedCost, stats.reportedCost > 0 ? 'reported' : 'estimated', stats.reportedCost > 0 ? 1 : 0.5, refs),
+                },
+                pendingUserRequest: derivePendingUserRequestV1(sessionProvider.id, stats.sessionId, sessionPath, events),
+                observedAt: new Date().toISOString(),
+            };
+        },
+        watch(sessionPath, listener, cwd) {
+            let disposed = false;
+            let lastSignature = '';
+            const update = async () => {
+                if (disposed)
+                    return;
+                try {
+                    const session = await adapter.read(sessionPath, cwd);
+                    const signature = JSON.stringify({
+                        activity: session.activity,
+                        model: session.model,
+                        usage: session.usage,
+                        pendingUserRequest: session.pendingUserRequest,
+                    });
+                    if (signature !== lastSignature) {
+                        lastSignature = signature;
+                        listener(session);
+                    }
+                }
+                catch {
+                    // Observed sources can disappear between polling iterations.
+                }
+            };
+            void update();
+            const timer = setInterval(update, pollIntervalMs);
+            timer.unref?.();
+            return {
+                dispose: () => {
+                    disposed = true;
+                    clearInterval(timer);
+                },
+            };
+        },
+        dispose: () => sessionProvider.dispose(),
+    };
+    return adapter;
+}

package/dist/types/opencode.d.ts

@@ -234,6 +234,7 @@ export interface DbProject {
     id: string;
     worktree: string;
     name: string | null;
+    sandboxes: string[];
     time_created: number;
     time_updated: number;
 }

package/dist/types/sessionEvent.d.ts

@@ -76,6 +76,21 @@ export interface SessionEvent {
             resetsAt: number;
         };
     };
+    /** Exact context compaction counts when reported by the provider. */
+    compaction?: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
+    /** Provider-specific signals normalized for shared analytics. */
+    providerMetadata?: {
+        retryAttempts?: number[];
+        finishReasons?: string[];
+        providerError?: {
+            type?: string;
+            message?: string;
+            code?: string | number;
+        };
+    };
     /** Tool use details (when type is 'tool_use') */
     tool?: {
         name: string;
@@ -156,7 +171,7 @@ export interface ToolCall {
     /** Truncated error message if the call failed */
     errorMessage?: string;
     /** Error category (permission, not_found, timeout, syntax, exit_code, tool_error, other) */
-    errorCategory?: string;
+    errorCategory?: import('../extractors/errorTaxonomy').ErrorCategory;
     /** Tool use ID for correlation with tool_result */
     toolUseId?: string;
     /** Truncated tool output/result content (max 5000 chars) */
@@ -206,6 +221,7 @@ export interface TimelineEvent {
     metadata?: {
         model?: string;
         toolName?: string;
+        toolUseId?: string;
         isError?: boolean;
         tokenCount?: number;
         fullText?: string;
@@ -506,6 +522,8 @@ export interface CompactionEvent {
     contextAfter: number;
     /** Tokens reclaimed (contextBefore - contextAfter) */
     tokensReclaimed: number;
+    /** Whether the provider reported exact counts or Sidekick inferred them. */
+    source: 'reported' | 'heuristic';
 }
 /**
  * Record of a tool output truncation event.

package/dist/watchers/eventBridge.js

@@ -141,6 +141,7 @@ function toFollowEvents(event, providerId) {
                 type: 'summary',
                 timestamp: ts,
                 summary: 'Context compacted',
+                compaction: event.compaction,
                 raw: event,
             });
             break;

package/dist/watchers/factory.js

@@ -56,14 +56,25 @@ function createWatcher(options) {
     }
     let sessionPath;
     if (sessionId) {
-        const match = sessions.find((s) => s.includes(sessionId));
-        if (!match) {
+        const matches = sessions.map((sessionPath) => ({
+            sessionPath,
+            id: provider.getSessionId(sessionPath),
+        }));
+        const exact = matches.filter((candidate) => candidate.id === sessionId);
+        const candidates = exact.length > 0 ? exact : matches.filter((candidate) => candidate.id.startsWith(sessionId));
+        if (candidates.length === 0) {
             throw new Error(`Session ${sessionId} not found. Available: ${sessions
                 .slice(0, 5)
                 .map((s) => path.basename(s))
                 .join(', ')}`);
         }
-        sessionPath = match;
+        if (candidates.length > 1) {
+            throw new Error(`Session ${sessionId} is ambiguous. Matches: ${candidates
+                .slice(0, 5)
+                .map((candidate) => candidate.id)
+                .join(', ')}`);
+        }
+        sessionPath = candidates[0].sessionPath;
     }
     else {
         sessionPath = sessions[0]; // most recent

package/dist/watchers/jsonlTail.js

@@ -48,7 +48,11 @@ function createJsonlTail(options) {
 class JsonlTailReader {
     options;
     active = false;
-    offset;
+    /** Physical byte position already read from the file. */
+    readOffset;
+    /** Resume-safe byte position ending immediately after a newline. */
+    committedOffset;
+    pendingBytes = Buffer.alloc(0);
     fsWatcher = null;
     debounceTimer = null;
     catchupTimer = null;
@@ -56,7 +60,8 @@ class JsonlTailReader {
     parser;
     constructor(options) {
         this.options = options;
-        this.offset = options.startOffset ?? 0;
+        this.readOffset = options.startOffset ?? 0;
+        this.committedOffset = this.readOffset;
         this.parser = new jsonl_1.JsonlParser({
             onEvent: (event) => {
                 this.eventsInCurrentBatch += 1;
@@ -74,11 +79,12 @@ class JsonlTailReader {
         this.active = true;
         if (this.options.startAtEnd && this.options.startOffset === undefined) {
             try {
-                this.offset = fs.statSync(this.options.path).size;
+                this.readOffset = fs.statSync(this.options.path).size;
             }
             catch {
-                this.offset = 0;
+                this.readOffset = 0;
             }
+            this.committedOffset = this.readOffset;
         }
         this.readNow();
         this.watchFile();
@@ -112,27 +118,39 @@ class JsonlTailReader {
         let fd = null;
         try {
             const stat = fs.statSync(this.options.path);
-            if (stat.size < this.offset) {
-                this.offset = 0;
+            if (stat.size < this.readOffset) {
+                this.readOffset = 0;
+                this.committedOffset = 0;
+                this.pendingBytes = Buffer.alloc(0);
                 this.parser.reset();
             }
-            if (stat.size <= this.offset)
+            if (stat.size <= this.readOffset)
                 return;
-            const bytesToRead = stat.size - this.offset;
+            const bytesToRead = stat.size - this.readOffset;
             const buffer = Buffer.alloc(bytesToRead);
             fd = fs.openSync(this.options.path, 'r');
-            const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, this.offset);
+            const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, this.readOffset);
             fs.closeSync(fd);
             fd = null;
             if (bytesRead <= 0)
                 return;
-            this.offset += bytesRead;
+            this.readOffset += bytesRead;
             this.eventsInCurrentBatch = 0;
-            this.parser.processChunk(buffer.toString('utf-8', 0, bytesRead));
+            const combined = Buffer.concat([this.pendingBytes, buffer.subarray(0, bytesRead)]);
+            const lastNewline = combined.lastIndexOf(0x0a);
+            if (lastNewline >= 0) {
+                const completeLines = combined.subarray(0, lastNewline + 1);
+                this.pendingBytes = Buffer.from(combined.subarray(lastNewline + 1));
+                this.parser.processChunk(completeLines.toString('utf8'));
+            }
+            else {
+                this.pendingBytes = combined;
+            }
+            this.committedOffset = this.readOffset - this.pendingBytes.length;
             this.options.onBatchComplete?.({
                 bytesRead,
                 eventsRead: this.eventsInCurrentBatch,
-                offset: this.offset,
+                offset: this.committedOffset,
             });
         }
         catch (error) {
@@ -148,10 +166,12 @@ class JsonlTailReader {
         }
     }
     getOffset() {
-        return this.offset;
+        return this.committedOffset;
     }
     seekTo(offset) {
-        this.offset = Math.max(0, offset);
+        this.readOffset = Math.max(0, offset);
+        this.committedOffset = this.readOffset;
+        this.pendingBytes = Buffer.alloc(0);
         this.parser.reset();
     }
     watchFile() {

package/dist/watchers/jsonlWatcher.js

@@ -274,9 +274,11 @@ class JsonlSessionWatcher {
             this.fsWatcher = fs.watch(this.sessionPath, { persistent: false }, () => {
                 this.debouncedRead();
             });
-            this.fsWatcher.on('error', () => {
-                // File may have been deleted; stop gracefully
-                this.stop();
+            this.fsWatcher.on('error', (error) => {
+                // Degrade to catch-up polling without killing the live session.
+                this.fsWatcher?.close();
+                this.fsWatcher = null;
+                this.callbacks.onError?.(error);
             });
         }
         catch {

package/dist/watchers/providerReaderWatcher.js

@@ -82,8 +82,10 @@ class ProviderReaderSessionWatcher {
             this.fsWatcher = fs.watch(this.sessionPath, { persistent: false }, () => {
                 this.debouncedRead();
             });
-            this.fsWatcher.on('error', () => {
-                this.stop();
+            this.fsWatcher.on('error', (error) => {
+                this.fsWatcher?.close();
+                this.fsWatcher = null;
+                this.callbacks.onError?.(error);
             });
         }
         catch {

package/dist/watchers/sqliteWatcher.d.ts

@@ -7,6 +7,8 @@ export declare class SqliteSessionWatcher implements SessionWatcher {
     private _isActive;
     private lastMessageTime;
     private lastPartTime;
+    private seenMessageVersions;
+    private seenPartVersions;
     private fsWatcher;
     private walWatcher;
     private pollTimer;

package/dist/watchers/sqliteWatcher.js

@@ -164,6 +164,8 @@ class SqliteSessionWatcher {
     _isActive = false;
     lastMessageTime = 0;
     lastPartTime = 0;
+    seenMessageVersions = new Map();
+    seenPartVersions = new Map();
     fsWatcher = null;
     walWatcher = null;
     pollTimer = null;
@@ -185,6 +187,8 @@ class SqliteSessionWatcher {
     seekTo(position) {
         this.lastMessageTime = position;
         this.lastPartTime = position;
+        this.seenMessageVersions.clear();
+        this.seenPartVersions.clear();
     }
     /** Get the current cursor position (max timestamp seen). */
     getPosition() {
@@ -266,38 +270,47 @@ class SqliteSessionWatcher {
         }, DEBOUNCE_MS);
     }
     skipToEnd() {
-        const messages = this.db.getMessagesForSession(this.sessionId);
-        const parts = this.db.getPartsForSession(this.sessionId);
-        if (messages.length > 0) {
-            this.lastMessageTime = Math.max(...messages.map((m) => m.time_created));
+        this.lastMessageTime = this.db.getLatestMessageTimeUpdated(this.sessionId);
+        this.lastPartTime = this.db.getLatestPartTimeUpdated(this.sessionId);
+        if (this.lastMessageTime > 0) {
+            for (const message of this.db.getMessagesNewerThan(this.sessionId, this.lastMessageTime - 1)) {
+                this.seenMessageVersions.set(message.id, `${message.time_updated}:${message.data}`);
+            }
         }
-        if (parts.length > 0) {
-            this.lastPartTime = Math.max(...parts.map((p) => p.time_created));
+        if (this.lastPartTime > 0) {
+            for (const part of this.db.getPartsNewerThan(this.sessionId, this.lastPartTime - 1)) {
+                this.seenPartVersions.set(part.id, `${part.time_updated}:${part.data}`);
+            }
         }
     }
     pollNewData() {
         if (!this._isActive)
             return;
         try {
-            const messages = this.db.getMessagesForSession(this.sessionId);
-            const parts = this.db.getPartsForSession(this.sessionId);
+            // Query incrementally by update time. Subtracting one millisecond lets us
+            // see distinct rows committed at the cursor timestamp; version maps
+            // suppress rows whose id/data have already been emitted.
+            const messages = this.db.getMessagesNewerThan(this.sessionId, Math.max(-1, this.lastMessageTime - 1));
+            const parts = this.db.getPartsNewerThan(this.sessionId, Math.max(-1, this.lastPartTime - 1));
             // Emit new messages
-            const newMessages = messages.filter((m) => m.time_created > this.lastMessageTime);
+            const newMessages = messages.filter((message) => this.seenMessageVersions.get(message.id) !== `${message.time_updated}:${message.data}`);
             for (const msg of newMessages) {
                 const events = normalizeMessage(msg);
                 for (const e of events)
                     this.callbacks.onEvent(e);
-                if (msg.time_created > this.lastMessageTime)
-                    this.lastMessageTime = msg.time_created;
+                this.seenMessageVersions.set(msg.id, `${msg.time_updated}:${msg.data}`);
+                if (msg.time_updated > this.lastMessageTime)
+                    this.lastMessageTime = msg.time_updated;
             }
             // Emit new parts
-            const newParts = parts.filter((p) => p.time_created > this.lastPartTime);
+            const newParts = parts.filter((part) => this.seenPartVersions.get(part.id) !== `${part.time_updated}:${part.data}`);
             for (const part of newParts) {
                 const events = normalizePart(part);
                 for (const e of events)
                     this.callbacks.onEvent(e);
-                if (part.time_created > this.lastPartTime)
-                    this.lastPartTime = part.time_created;
+                this.seenPartVersions.set(part.id, `${part.time_updated}:${part.data}`);
+                if (part.time_updated > this.lastPartTime)
+                    this.lastPartTime = part.time_updated;
             }
         }
         catch (err) {

package/dist/watchers/types.d.ts

@@ -36,6 +36,11 @@ export interface FollowEvent {
             resetsAt: number;
         };
     };
+    /** Exact compaction counts when supplied by the provider. */
+    compaction?: {
+        tokensBefore: number;
+        tokensAfter: number;
+    };
     /** Original raw event for JSON output. */
     raw?: unknown;
 }

package/dist/writers/atomic.d.ts

@@ -0,0 +1,4 @@
+export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;
+export declare function atomicWriteJsonSync(filePath: string, value: unknown): void;
+/** Serializes read-modify-write cycles across Sidekick processes. */
+export declare function updateJsonStoreAtomic<T>(filePath: string, createEmpty: () => T, update: (latest: T) => T | Promise<T>): Promise<T>;