@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/inspection/state-inspector/inspector.js

@@ -0,0 +1,331 @@
+import { DEFAULT_MAX_TRANSITIONS, DEFAULT_TIMELINE_BUFFER_SIZE } from './types.js';
+import { BoundedTransitionLog } from './transition-log.js';
+import { TimelineBuffer } from './timeline.js';
+import { serializeSafe } from './serialize.js';
+import { summarizeError } from '../../../utils/error-display.js';
+// ── StateInspectorProvider ────────────────────────────────────────────────────
+/**
+ * StateInspectorProvider — full-featured state inspector data provider.
+ *
+ * ### Usage
+ * ```ts
+ * const inspector = createStateInspector({
+ *   domains: [sessionDomainAdapter, conversationDomainAdapter],
+ *   maxTransitions: 500,
+ * });
+ *
+ * const snapshot = inspector.getSnapshot();
+ * const history = inspector.getTransitionHistory();
+ * const subs = inspector.getSubscriptions();
+ * ```
+ */
+export class StateInspectorProvider {
+    _domains;
+    _transitionLog;
+    _timeline;
+    _observedDomains;
+    _subscriptions = new Map();
+    _domainCache = new Map();
+    _subIdCounter = 0;
+    /**
+     * @param domains - Domain adapters to inspect.
+     * @param config - Optional configuration.
+     */
+    constructor(domains = [], config = {}) {
+        this._domains = [...domains];
+        this._transitionLog = new BoundedTransitionLog(config.maxTransitions ?? DEFAULT_MAX_TRANSITIONS);
+        this._timeline = new TimelineBuffer(config.timelineBufferSize ?? DEFAULT_TIMELINE_BUFFER_SIZE);
+        this._observedDomains = config.observedDomains
+            ? new Set(config.observedDomains)
+            : undefined;
+    }
+    // ── Domain management ───────────────────────────────────────────────────────
+    /**
+     * Register an additional domain for inspection.
+     * Triggers a notification to all subscribers.
+     *
+     * @param domain - Domain adapter to register.
+     */
+    registerDomain(domain) {
+        this._domains.push(domain);
+        this._notifyAll();
+    }
+    /** Returns the names of all currently registered domains. */
+    registeredDomainNames() {
+        return this._domains.map((d) => d.name);
+    }
+    // ── Snapshot API ────────────────────────────────────────────────────────────
+    /**
+     * Capture a point-in-time snapshot of all (or filtered) domains.
+     *
+     * @param domainFilter - Optional list of domain names to include.
+     *   When undefined, all registered domains are captured.
+     * @returns StateSnapshot.
+     */
+    getSnapshot(domainFilter) {
+        const targetDomains = this._filterDomains(domainFilter);
+        const domains = targetDomains.map((domain) => ({
+            domain: domain.name,
+            revision: domain.getRevision(),
+            lastUpdatedAt: domain.getLastUpdatedAt(),
+            state: serializeSafe(domain.getState()),
+        }));
+        return {
+            capturedAt: Date.now(),
+            domains,
+            domainCount: domains.length,
+            domainFilter,
+        };
+    }
+    // ── Transition history API ───────────────────────────────────────────────────
+    /**
+     * Poll for new transitions and record any detected domain revisions.
+     *
+     * Call this periodically (e.g. after state mutations) to keep the
+     * transition log up to date.
+     *
+     * @returns Number of new transitions recorded.
+     */
+    poll() {
+        let recorded = 0;
+        const now = Date.now();
+        for (const domain of this._domains) {
+            if (this._observedDomains && !this._observedDomains.has(domain.name))
+                continue;
+            const currentRevision = domain.getRevision();
+            const cached = this._domainCache.get(domain.name);
+            if (!cached || cached.revision !== currentRevision) {
+                const fromRevision = cached?.revision ?? 0;
+                const rawState = domain.getState();
+                // Attempt to extract 'source' from the domain state
+                const source = typeof rawState['source'] === 'string'
+                    ? rawState['source']
+                    : 'unknown';
+                const serializedState = serializeSafe(rawState);
+                const entry = this._transitionLog.append({
+                    domain: domain.name,
+                    fromRevision,
+                    toRevision: currentRevision,
+                    recordedAt: now,
+                    source,
+                    state: serializedState,
+                });
+                // Record timeline event for time-travel replay
+                this._timeline.append({
+                    capturedAt: now,
+                    domain: domain.name,
+                    transitionId: entry.id,
+                    snapshot: serializedState,
+                    label: source !== 'unknown' ? source : undefined,
+                });
+                this._domainCache.set(domain.name, {
+                    revision: currentRevision,
+                    lastUpdatedAt: domain.getLastUpdatedAt(),
+                    source,
+                });
+                recorded++;
+            }
+        }
+        if (recorded > 0)
+            this._notifyAll();
+        return recorded;
+    }
+    /**
+     * Return all retained transition entries in chronological order.
+     *
+     * @returns Ordered array of TransitionEntry.
+     */
+    getTransitionHistory() {
+        return this._transitionLog.getAll();
+    }
+    /**
+     * Return transition history filtered by domain.
+     *
+     * @param domain - Domain name to filter by.
+     */
+    getTransitionsByDomain(domain) {
+        return this._transitionLog.getByDomain(domain);
+    }
+    /**
+     * Return transitions recorded at or after the given epoch ms timestamp.
+     *
+     * @param sinceMs - Inclusive lower bound (epoch ms).
+     */
+    getTransitionsSince(sinceMs) {
+        return this._transitionLog.getSince(sinceMs);
+    }
+    /**
+     * Return the N most recent transitions.
+     *
+     * @param n - Maximum number of entries.
+     */
+    getLastTransitions(n) {
+        return this._transitionLog.getLast(n);
+    }
+    /** Total number of transitions ever recorded (not capped by maxTransitions). */
+    get totalTransitions() {
+        return this._transitionLog.totalAppended;
+    }
+    /**
+     * Clear all stored transitions and timeline events.
+     * Does not reset subscription registry or domain cache.
+     */
+    clearTransitionHistory() {
+        this._transitionLog.clear();
+        this._timeline.clear();
+    }
+    // ── Time-travel API ──────────────────────────────────────────────────────────
+    /**
+     * Return all retained timeline events in chronological order.
+     *
+     * @returns Ordered array of TimelineEvent.
+     */
+    getTimeline() {
+        return this._timeline.getAll();
+    }
+    /**
+     * Return the event at the current time-travel cursor position.
+     * Returns undefined when the cursor is at the live position.
+     *
+     * @returns TimelineEvent or undefined when live.
+     */
+    getCurrentTimelineEvent() {
+        return this._timeline.getCurrentEvent();
+    }
+    /**
+     * Current time-travel cursor state.
+     */
+    get timeTravelCursor() {
+        return this._timeline.cursorState;
+    }
+    /**
+     * Whether the inspector is currently in time-travel mode (cursor pinned).
+     */
+    get isTimeTravel() {
+        return !this._timeline.isLive;
+    }
+    /**
+     * Step the cursor one event backward (toward oldest).
+     *
+     * @returns true if the cursor moved.
+     */
+    stepBack() {
+        return this._timeline.stepBack();
+    }
+    /**
+     * Step the cursor one event forward (toward live).
+     *
+     * @returns true if the cursor moved.
+     */
+    stepForward() {
+        return this._timeline.stepForward();
+    }
+    /**
+     * Seek the cursor to an absolute logical index.
+     * Pass `timeline.size` to return to live.
+     *
+     * @param index — Target index (size = live).
+     */
+    seekTo(index) {
+        this._timeline.seekTo(index);
+    }
+    /**
+     * Seek to the nearest event at or before a given epoch ms timestamp.
+     *
+     * @param epochMs — Target timestamp.
+     */
+    seekToTime(epochMs) {
+        this._timeline.seekToTime(epochMs);
+    }
+    /**
+     * Exit time-travel mode, returning the cursor to the live tail.
+     */
+    exitTimeTravel() {
+        this._timeline.exitTimeTravel();
+    }
+    /**
+     * Get the snapshot at the current cursor position for display.
+     * Returns undefined when live (callers should use getSnapshot() instead).
+     *
+     * @returns The pinned snapshot state or undefined when live.
+     */
+    getTimeTravelSnapshot() {
+        return this._timeline.getCurrentEvent();
+    }
+    // ── Subscription API ─────────────────────────────────────────────────────────
+    /**
+     * Subscribe to state inspector change notifications.
+     *
+     * @param callback - Function invoked when a domain transition is detected.
+     * @param label - Human-readable label for this subscriber.
+     * @param domainFilter - Optional domain names to restrict notifications to.
+     * @returns Object with `id` (subscription ID) and `unsubscribe` function.
+     */
+    subscribe(callback, label, domainFilter) {
+        const id = `sub-${++this._subIdCounter}`;
+        const info = {
+            id,
+            label,
+            registeredAt: Date.now(),
+            domainFilter,
+            notificationCount: 0,
+            lastNotifiedAt: undefined,
+            callback,
+            errorCount: 0,
+            lastError: undefined,
+        };
+        this._subscriptions.set(id, info);
+        return {
+            id,
+            unsubscribe: () => this._subscriptions.delete(id),
+        };
+    }
+    /**
+     * Return metadata for all active subscriptions.
+     * Callbacks are not exposed.
+     *
+     * @returns Array of SubscriptionInfo.
+     */
+    getSubscriptions() {
+        return [...this._subscriptions.values()].map((sub) => ({
+            id: sub.id,
+            label: sub.label,
+            registeredAt: sub.registeredAt,
+            domainFilter: sub.domainFilter,
+            notificationCount: sub.notificationCount,
+            lastNotifiedAt: sub.lastNotifiedAt,
+            errorCount: sub.errorCount,
+            lastError: sub.lastError,
+        }));
+    }
+    /**
+     * Return the count of currently active subscriptions.
+     */
+    get subscriptionCount() {
+        return this._subscriptions.size;
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────────
+    /** Filter domains by the provided list, or return all if undefined. */
+    _filterDomains(filter) {
+        if (!filter)
+            return this._domains;
+        const filterSet = new Set(filter);
+        return this._domains.filter((d) => filterSet.has(d.name));
+    }
+    /** Notify all subscribers, tracking notification metadata. */
+    _notifyAll() {
+        const now = Date.now();
+        for (const sub of this._subscriptions.values()) {
+            try {
+                sub.callback();
+                sub.notificationCount++;
+                sub.lastNotifiedAt = now;
+            }
+            catch (err) {
+                // Non-fatal: subscriber errors must not crash the provider
+                sub.errorCount = (sub.errorCount ?? 0) + 1;
+                sub.lastError = summarizeError(err);
+            }
+        }
+    }
+}

package/dist/_internal/platform/runtime/inspection/state-inspector/serialize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared serialization utility for the state inspector.
+ *
+ * Converts Maps → plain objects, Sets → arrays, and replaces circular
+ * references with a sentinel string so any state snapshot is JSON-safe.
+ */
+/**
+ * Serialize a value to a JSON-safe representation.
+ * Maps → plain objects, Sets → arrays, circular refs → '[Circular]'.
+ *
+ * @param value - Value to serialize.
+ * @param seen - WeakSet tracking seen objects to detect cycles.
+ * @returns A JSON-safe representation.
+ */
+export declare function serializeSafe(value: unknown, seen?: WeakSet<WeakKey>): unknown;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/_internal/platform/runtime/inspection/state-inspector/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/inspection/state-inspector/serialize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,mBAAgB,GAAG,OAAO,CA0B3E"}

package/dist/_internal/platform/runtime/inspection/state-inspector/serialize.js

@@ -0,0 +1,39 @@
+/**
+ * Shared serialization utility for the state inspector.
+ *
+ * Converts Maps → plain objects, Sets → arrays, and replaces circular
+ * references with a sentinel string so any state snapshot is JSON-safe.
+ */
+/**
+ * Serialize a value to a JSON-safe representation.
+ * Maps → plain objects, Sets → arrays, circular refs → '[Circular]'.
+ *
+ * @param value - Value to serialize.
+ * @param seen - WeakSet tracking seen objects to detect cycles.
+ * @returns A JSON-safe representation.
+ */
+export function serializeSafe(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (value instanceof Map) {
+        const result = {};
+        for (const [k, v] of value.entries()) {
+            result[String(k)] = serializeSafe(v, seen);
+        }
+        return result;
+    }
+    if (value instanceof Set) {
+        return [...value].map((v) => serializeSafe(v, seen));
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => serializeSafe(v, seen));
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+        result[k] = serializeSafe(v, seen);
+    }
+    return result;
+}

package/dist/_internal/platform/runtime/inspection/state-inspector/timeline.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Timeline buffer for state inspector time-travel.
+ *
+ * Maintains a bounded circular buffer of timeline events. Each event records
+ * a full domain snapshot so an operator can step backward/forward through
+ * state history without re-running mutations.
+ *
+ * Step controls:
+ *   - `stepBack()` / `stepForward()` — move the cursor one position.
+ *   - `seekTo(index)` — jump to an absolute index.
+ *   - `seekToTime(epochMs)` — seek to the nearest event at or before a timestamp.
+ *   - `exitTimeTravel()` — return the cursor to the live tail.
+ *
+ * The "live" position is represented as cursor === size (one past the last
+ * stored event). When live, `getCurrentSnapshot()` returns undefined, signalling
+ * that callers should use the inspector's live snapshot instead.
+ */
+import type { TimelineEvent, TimeTravelCursor } from './types.js';
+/**
+ * TimelineBuffer — fixed-capacity ring buffer of TimelineEvent snapshots.
+ *
+ * Indices are stable within a session (they increment monotonically via
+ * the `seq` field on each event). The cursor is an offset into the live
+ * ring: 0 = oldest retained, size-1 = newest, size = live.
+ */
+export declare class TimelineBuffer {
+    private readonly _maxSize;
+    private readonly _ring;
+    private _head;
+    private _totalAppended;
+    private _cursor;
+    private _nextSeq;
+    /**
+     * @param maxSize — Maximum events to retain. Must be >= 2.
+     * @default DEFAULT_TIMELINE_BUFFER_SIZE
+     */
+    constructor(maxSize?: number);
+    /** Maximum events retained. */
+    get maxSize(): number;
+    /** Current number of events retained (capped at maxSize). */
+    get size(): number;
+    /** Total events ever appended (monotonically increasing). */
+    get totalAppended(): number;
+    /**
+     * Whether the cursor is at the live position (past the newest event).
+     * When live, `getCurrentSnapshot()` returns undefined.
+     */
+    get isLive(): boolean;
+    /** Current cursor state for display. */
+    get cursorState(): TimeTravelCursor;
+    /**
+     * Append a new timeline event.
+     *
+     * If the cursor is live it advances with the tail (stays live).
+     * If the cursor is pinned (time-travel mode), it stays pinned.
+     *
+     * @param event — Event without `seq` (assigned here).
+     * @returns The stored TimelineEvent with its assigned `seq`.
+     */
+    append(event: Omit<TimelineEvent, 'seq'>): TimelineEvent;
+    /**
+     * Return all retained events in chronological order.
+     *
+     * @returns Events oldest → newest.
+     */
+    getAll(): TimelineEvent[];
+    /**
+     * Return the event at a logical index (0 = oldest, size-1 = newest).
+     *
+     * @returns TimelineEvent or undefined when out of range.
+     */
+    getAt(index: number): TimelineEvent | undefined;
+    /**
+     * Return the event at the current cursor position, or undefined when live.
+     */
+    getCurrentEvent(): TimelineEvent | undefined;
+    /**
+     * Step the cursor one event backward (toward oldest).
+     * If already at index 0, the cursor stays at 0.
+     *
+     * @returns true if the cursor moved.
+     */
+    stepBack(): boolean;
+    /**
+     * Step the cursor one event forward (toward live).
+     * When the cursor reaches the live position (past the newest event),
+     * `isLive` becomes true.
+     *
+     * @returns true if the cursor moved.
+     */
+    stepForward(): boolean;
+    /**
+     * Seek the cursor to an absolute logical index.
+     * Clamps to [0, size] where size === live.
+     *
+     * @param index — Target index (size = live).
+     */
+    seekTo(index: number): void;
+    /**
+     * Seek to the nearest event at or before a given epoch ms timestamp.
+     * If no events exist before the timestamp, seeks to index 0.
+     * If all events are before or equal, seeks to the newest.
+     *
+     * @param epochMs — Target timestamp.
+     */
+    seekToTime(epochMs: number): void;
+    /**
+     * Return the cursor to the live tail (exit time-travel mode).
+     */
+    exitTimeTravel(): void;
+    /**
+     * Clear all retained events and reset to live position.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=timeline.d.ts.map

package/dist/_internal/platform/runtime/inspection/state-inspector/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../../../../../src/_internal/platform/runtime/inspection/state-inspector/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;OAGG;gBACS,OAAO,GAAE,MAAqC;IAS1D,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,6DAA6D;IAC7D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,6DAA6D;IAC7D,IAAI,aAAa,IAAI,MAAM,CAE1B;IAID;;;OAGG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,wCAAwC;IACxC,IAAI,WAAW,IAAI,gBAAgB,CAOlC;IAID;;;;;;;;OAQG;IACI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG,aAAa;IAgB/D;;;;OAIG;IACI,MAAM,IAAI,aAAa,EAAE;IAgBhC;;;;OAIG;IACI,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAWtD;;OAEG;IACI,eAAe,IAAI,aAAa,GAAG,SAAS;IAKnD;;;;;OAKG;IACI,QAAQ,IAAI,OAAO;IAM1B;;;;;;OAMG;IACI,WAAW,IAAI,OAAO;IAM7B;;;;;OAKG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKlC;;;;;;OAMG;IACI,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAexC;;OAEG;IACI,cAAc,IAAI,IAAI;IAI7B;;OAEG;IACI,KAAK,IAAI,IAAI;CAOrB"}