sidekick-shared 0.24.4 → 0.25.0

package/dist/node.js

@@ -7,7 +7,7 @@
  * for browser bundles — use `sidekick-shared/browser` there.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
+exports.fileFingerprintParts = exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = exports.readSessionPreviewAsync = exports.readSessionPreview = exports.listSessionPreviewsAsync = exports.listSessionPreviews = exports.readCodexHistory = exports.findCodexRolloutFile = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
 var pricingCatalog_1 = require("./pricingCatalog");
 Object.defineProperty(exports, "hydratePricingCatalog", { enumerable: true, get: function () { return pricingCatalog_1.hydratePricingCatalog; } });
 Object.defineProperty(exports, "normalizeLiteLlmCatalog", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmCatalog; } });
@@ -20,7 +20,17 @@ Object.defineProperty(exports, "getObservedContextWindowPath", { enumerable: tru
 var sessionTranscripts_1 = require("./sessionTranscripts");
 Object.defineProperty(exports, "listRecentSessions", { enumerable: true, get: function () { return sessionTranscripts_1.listRecentSessions; } });
 Object.defineProperty(exports, "readSessionTranscript", { enumerable: true, get: function () { return sessionTranscripts_1.readSessionTranscript; } });
+var codex_1 = require("./providers/codex");
+Object.defineProperty(exports, "findCodexRolloutFile", { enumerable: true, get: function () { return codex_1.findCodexRolloutFile; } });
+var codexHistory_1 = require("./parsers/codexHistory");
+Object.defineProperty(exports, "readCodexHistory", { enumerable: true, get: function () { return codexHistory_1.readCodexHistory; } });
+var sessionPreviews_1 = require("./sessionPreviews");
+Object.defineProperty(exports, "listSessionPreviews", { enumerable: true, get: function () { return sessionPreviews_1.listSessionPreviews; } });
+Object.defineProperty(exports, "listSessionPreviewsAsync", { enumerable: true, get: function () { return sessionPreviews_1.listSessionPreviewsAsync; } });
+Object.defineProperty(exports, "readSessionPreview", { enumerable: true, get: function () { return sessionPreviews_1.readSessionPreview; } });
+Object.defineProperty(exports, "readSessionPreviewAsync", { enumerable: true, get: function () { return sessionPreviews_1.readSessionPreviewAsync; } });
 var observedSessionCollector_1 = require("./observedSessionCollector");
 Object.defineProperty(exports, "ObservedSessionCollector", { enumerable: true, get: function () { return observedSessionCollector_1.ObservedSessionCollector; } });
 Object.defineProperty(exports, "observedSessionSourceFromProvider", { enumerable: true, get: function () { return observedSessionCollector_1.observedSessionSourceFromProvider; } });
 Object.defineProperty(exports, "fileFingerprint", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprint; } });
+Object.defineProperty(exports, "fileFingerprintParts", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprintParts; } });

package/dist/observedContextWindows.d.ts

@@ -14,6 +14,19 @@
  * Precedence, most-trusted first: runtime → observed (here) → LiteLLM catalog →
  * static table. See `modelContext.ts`.
  *
+ * ## Where the store lives — two seams, one story
+ *
+ * Reader ({@link loadObservedContextWindows}) and writer
+ * ({@link recordObservedContextWindow}) resolve the store path identically:
+ * explicit `cacheDir` option → `setConfigDir()` / `SIDEKICK_CONFIG_DIR` (via
+ * `getConfigDir()`) → platform default. The global config-dir override is the
+ * deployment-level seam external consumers use to relocate every Sidekick
+ * store at once; the per-call `cacheDir` is the isolation seam for tests and
+ * multi-tenant hosts. Providers deliberately do NOT thread `cacheDir` —
+ * `CodexProvider` records observations with default options, which follow the
+ * global override, so a default-options load always sees what a
+ * default-options record wrote.
+ *
  * @module observedContextWindows
  */
 export interface ObservedContextWindowOptions {

package/dist/observedContextWindows.js

@@ -15,6 +15,19 @@
  * Precedence, most-trusted first: runtime → observed (here) → LiteLLM catalog →
  * static table. See `modelContext.ts`.
  *
+ * ## Where the store lives — two seams, one story
+ *
+ * Reader ({@link loadObservedContextWindows}) and writer
+ * ({@link recordObservedContextWindow}) resolve the store path identically:
+ * explicit `cacheDir` option → `setConfigDir()` / `SIDEKICK_CONFIG_DIR` (via
+ * `getConfigDir()`) → platform default. The global config-dir override is the
+ * deployment-level seam external consumers use to relocate every Sidekick
+ * store at once; the per-call `cacheDir` is the isolation seam for tests and
+ * multi-tenant hosts. Providers deliberately do NOT thread `cacheDir` —
+ * `CodexProvider` records observations with default options, which follow the
+ * global override, so a default-options load always sees what a
+ * default-options record wrote.
+ *
  * @module observedContextWindows
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {

package/dist/observedSessionCollector.d.ts

@@ -1,24 +1,43 @@
-import type { ObservedAgentSessionV1, ProviderCapabilitiesV1 } from './types/observedSessionV1';
+import type { ObservedAgentSessionV1, ProviderCapabilitiesV1, ProviderSessionAdapterV1Options } from './types/observedSessionV1';
 import type { SessionProviderBase } from './providers/types';
+export interface ObservedSessionFingerprintParts {
+    sizeBytes: number;
+    mtimeMs: number;
+}
 export interface ObservedSessionReference {
     sessionId: string;
     /** Opaque source locator used only by the source implementation. Never emitted in diagnostics. */
     sourceKey?: string;
+    /** Backward-compatible opaque fingerprint. */
     fingerprintHint?: string;
+    /** Structured fingerprint for consumers that previously parsed fingerprintHint. */
+    fingerprintParts?: ObservedSessionFingerprintParts;
+}
+export interface ObservedSessionSourceSubscribeOptions {
+    pollIntervalMs?: number;
 }
 export interface ObservedSessionCollectionSource<T = unknown> {
     providerId: string;
     discover(): Promise<ObservedSessionReference[]> | ObservedSessionReference[];
     read(reference: ObservedSessionReference): Promise<T> | T;
+    refreshCached?(reference: ObservedSessionReference, value: T, observedAt: string): Promise<T> | T;
+    /** Low-level invalidation signal; the collector performs fingerprint reconciliation. */
+    subscribe?(listener: () => void, options?: ObservedSessionSourceSubscribeOptions): {
+        dispose(): void;
+    };
     dispose?(): void;
 }
 export interface ProviderObservedSessionCollectionSource extends ObservedSessionCollectionSource<ObservedAgentSessionV1> {
     capabilities: ProviderCapabilitiesV1;
 }
 export type ObservedSessionDiagnosticKind = 'provider-discovery-failed' | 'session-read-failed' | 'provider-recovered' | 'session-recovered';
+export type ObservedSessionDiagnosticSeverity = 'info' | 'warning' | 'error';
+export type ObservedSessionDiagnosticPhase = 'discover' | 'read' | 'recover';
 /** Content-safe diagnostics: identifiers and retry metadata only. */
 export interface ObservedSessionDiagnostic {
     kind: ObservedSessionDiagnosticKind;
+    severity: ObservedSessionDiagnosticSeverity;
+    phase: ObservedSessionDiagnosticPhase;
     providerId: string;
     sessionId?: string;
     attempt?: number;
@@ -28,6 +47,13 @@ export interface ObservedSessionCollection<T = unknown> {
     providerId: string;
     sessionId: string;
     value: T;
+    fingerprint: string | null;
+    fingerprintParts: ObservedSessionFingerprintParts | null;
+    cacheHit: boolean;
+    /** Time this observation was returned. */
+    observedAt: string;
+    /** Time content was last parsed; unchanged on a cache hit. */
+    contentObservedAt: string;
 }
 export interface ObservedSessionCollectorOptions<T = unknown> {
     sources: ObservedSessionCollectionSource<T>[];
@@ -37,26 +63,69 @@ export interface ObservedSessionCollectorOptions<T = unknown> {
         now(): number;
     };
     fingerprint?: (source: ObservedSessionCollectionSource<T>, reference: ObservedSessionReference) => Promise<string | null> | string | null;
+    maxConcurrentReads?: number;
+    yieldBetweenReads?: () => Promise<void> | void;
     onObservation?: (observation: ObservedSessionCollection<T>) => void;
     onDiagnostic?: (diagnostic: ObservedSessionDiagnostic) => void;
 }
+export type ObservedSessionChangeType = 'added' | 'changed' | 'removed';
+export interface ObservedSessionChange {
+    type: ObservedSessionChangeType;
+    reference: ObservedSessionReference;
+    previousFingerprint: string | null;
+    previousFingerprintParts: ObservedSessionFingerprintParts | null;
+    fingerprint: string | null;
+    fingerprintParts: ObservedSessionFingerprintParts | null;
+}
+export interface ObservedSessionChangeBatch {
+    providerId: string;
+    changes: ObservedSessionChange[];
+    observedAt: string;
+}
+export interface KnownObservedSessionFingerprint {
+    providerId: string;
+    sessionId: string;
+    fingerprint: string;
+    fingerprintParts?: ObservedSessionFingerprintParts;
+}
+export interface ObservedSessionSubscribeOptions {
+    debounceMs?: number;
+    pollIntervalMs?: number;
+    knownFingerprints?: readonly KnownObservedSessionFingerprint[];
+}
 /**
- * One-shot, host-scheduled observed-session collection with independent
- * provider/session isolation and bounded retry state.
+ * Fail-soft observed-session collection with fingerprint-keyed parse caching,
+ * cooperative reads, and optional provider-level subscriptions.
  */
 export declare class ObservedSessionCollector<T = unknown> {
     private readonly options;
     private readonly failures;
+    private readonly cache;
+    private readonly subscriptions;
     private readonly initialBackoffMs;
     private readonly maxBackoffMs;
     private readonly clock;
+    private readonly maxConcurrentReads;
+    private readonly yieldBetweenReads;
     constructor(options: ObservedSessionCollectorOptions<T>);
     collect(): Promise<ObservedSessionCollection<T>[]>;
+    /**
+     * Subscribe to debounced provider changes. The listener receives fingerprints
+     * only; call collect() to consume changed sessions through the parse cache.
+     */
+    subscribe(listener: (batch: ObservedSessionChangeBatch) => void, options?: ObservedSessionSubscribeOptions): {
+        dispose(): void;
+    };
     reset(): void;
     dispose(): void;
     private collectSource;
     private collectSession;
+    private makeObservation;
+    private emitObservation;
+    private reconcileSource;
     private fingerprint;
+    private evictMissing;
+    private mapWithConcurrency;
     private fail;
     private recover;
     private emitDiagnostic;
@@ -66,6 +135,8 @@ export declare class ObservedSessionCollector<T = unknown> {
  * Adapt a provider using path-only discovery and independent adapter reads, so
  * one malformed session cannot reject discovery of its healthy siblings.
  */
-export declare function observedSessionSourceFromProvider(provider: SessionProviderBase, cwd: string): ProviderObservedSessionCollectionSource;
+export declare function observedSessionSourceFromProvider(provider: SessionProviderBase, cwd: string, options?: ProviderSessionAdapterV1Options): ProviderObservedSessionCollectionSource;
+/** Structured size/mtime fingerprint; returns null for inaccessible or synthetic paths. */
+export declare function fileFingerprintParts(sourcePath: string): ObservedSessionFingerprintParts | null;
 /** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
 export declare function fileFingerprint(sourcePath: string): string | null;