sidekick-shared 0.24.5 → 0.25.0

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;