@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/idempotency/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Idempotency — types.
+ *
+ * Defines the record structure and configuration for the in-process idempotency
+ * store used by the phased tool executor and orchestrator turn submission.
+ */
+/**
+ * Lifecycle status of an idempotency record.
+ *
+ * - `in-flight`  — execution has started but not yet completed.
+ * - `completed`  — execution finished successfully; result is cached.
+ * - `failed`     — execution finished with an error; `checkAndRecord` will return `'new'` allowing retry.
+ */
+export type IdempotencyStatus = 'in-flight' | 'completed' | 'failed';
+/**
+ * A single idempotency record stored per unique key.
+ */
+export interface IdempotencyRecord {
+    /** The idempotency key that identifies this operation. */
+    readonly key: string;
+    /** Current lifecycle status. */
+    status: IdempotencyStatus;
+    /** Unix timestamp (ms) when the record was first created. */
+    readonly createdAt: number;
+    /** Unix timestamp (ms) when the record transitioned out of `in-flight`. */
+    completedAt?: number;
+    /**
+     * Cached result from a completed execution.
+     * Returned verbatim to duplicate callers instead of re-running the operation.
+     */
+    result?: unknown;
+}
+/**
+ * Input context used to generate a deterministic idempotency key.
+ *
+ * All three fields are required because:
+ * - `sessionId`   — scopes keys to a single session (prevents cross-session collisions).
+ * - `turnId`      — distinguishes between turns in the same session.
+ * - `callId`      — distinguishes between concurrent tool calls in the same turn.
+ */
+export interface IdempotencyKeyContext {
+    /** Stable session identifier. */
+    readonly sessionId: string;
+    /** Per-turn identifier. */
+    readonly turnId: string;
+    /** Per-tool-call identifier. */
+    readonly callId: string;
+}
+/**
+ * Configuration for `IdempotencyStore`.
+ */
+export interface IdempotencyStoreConfig {
+    /**
+     * Time-to-live for completed/failed records in milliseconds.
+     *
+     * Records older than this value are eligible for eviction.
+     * In-flight records are never evicted.
+     *
+     * @default 300_000 (5 minutes)
+     */
+    ttlMs?: number;
+    /**
+     * Maximum number of records retained before a sweep evicts TTL-expired entries.
+     *
+     * @default 5_000
+     */
+    maxRecords?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/runtime/idempotency/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/idempotency/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/platform/runtime/idempotency/types.js

@@ -0,0 +1,7 @@
+/**
+ * Idempotency — types.
+ *
+ * Defines the record structure and configuration for the in-process idempotency
+ * store used by the phased tool executor and orchestrator turn submission.
+ */
+export {};

package/dist/platform/runtime/inspection/state-inspector/hotspot-sampler.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Selector hotspot sampler for the state inspector.
+ *
+ * Tracks invocation frequency and execution duration for named selectors.
+ * An operator can inspect which selectors fire most often (churn hotspots)
+ * or take the longest (latency hotspots) to isolate render/subscription
+ * performance problems.
+ *
+ * ### Usage
+ * ```ts
+ * const sampler = new SelectorHotspotSampler({ windowMs: 10_000 });
+ *
+ * // Instrument a selector call site:
+ * const t0 = performance.now();
+ * const result = selectRunningTasks(state);
+ * sampler.record('selectRunningTasks', performance.now() - t0);
+ *
+ * const report = sampler.getReport();
+ * ```
+ *
+ * The sampler uses a sliding-window of raw samples to compute p50/p95/p99
+ * latencies and a calls-per-second rate. Samples older than `windowMs`
+ * are dropped on each `record()` call (lazy GC).
+ */
+import type { SelectorHotspot, HotspotReport, HotspotSamplerConfig } from './types.js';
+/**
+ * SelectorHotspotSampler — sliding-window latency + frequency tracker.
+ *
+ * Thread-safety note: synchronous JS — no concurrency concerns.
+ */
+export declare class SelectorHotspotSampler {
+    private readonly _windowMs;
+    private readonly _maxSamplesPerKey;
+    private readonly _selectors;
+    /**
+     * @param config — Optional sampler configuration.
+     */
+    constructor(config?: HotspotSamplerConfig);
+    /** Current sliding window duration in ms. */
+    get windowMs(): number;
+    /**
+     * Record a selector invocation.
+     *
+     * @param key — Selector name / identifier.
+     * @param durationMs — Execution time in milliseconds (may be 0 for sync).
+     */
+    record(key: string, durationMs: number): void;
+    /**
+     * Return a sorted hotspot report.
+     *
+     * Hotspots are sorted by `callsInWindow` descending (churn first),
+     * then by `p95Ms` descending as a tiebreaker.
+     *
+     * @returns HotspotReport.
+     */
+    getReport(): HotspotReport;
+    /**
+     * Return the hotspot for a single selector key, or undefined if never recorded.
+     *
+     * @param key — Selector identifier.
+     */
+    getHotspot(key: string): SelectorHotspot | undefined;
+    /**
+     * Return the top N selectors by call count in the current window.
+     *
+     * @param n — Maximum number of hotspots to return.
+     */
+    getTopHotspots(n: number): SelectorHotspot[];
+    /** Number of distinct selector keys tracked. */
+    get trackedKeyCount(): number;
+    /**
+     * Clear all recorded samples and reset tracking.
+     * Does not reset configuration.
+     */
+    reset(): void;
+    private _evictOldSamples;
+    private _computeHotspot;
+    private _percentiles;
+}
+//# sourceMappingURL=hotspot-sampler.d.ts.map

package/dist/platform/runtime/inspection/state-inspector/hotspot-sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotspot-sampler.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/inspection/state-inspector/hotspot-sampler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAiBvF;;;;GAIG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAE/D;;OAEG;gBACS,MAAM,GAAE,oBAAyB;IAO7C,6CAA6C;IAC7C,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;OAKG;IACI,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAsBpD;;;;;;;OAOG;IACI,SAAS,IAAI,aAAa;IAoBjC;;;;OAIG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAQ3D;;;;OAIG;IACI,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE;IAInD,gDAAgD;IAChD,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;OAGG;IACI,KAAK,IAAI,IAAI;IAMpB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,YAAY;CAwBrB"}

package/dist/platform/runtime/inspection/state-inspector/hotspot-sampler.js

@@ -0,0 +1,153 @@
+import { DEFAULT_HOTSPOT_WINDOW_MS, DEFAULT_HOTSPOT_MAX_SAMPLES_PER_KEY } from './types.js';
+/**
+ * SelectorHotspotSampler — sliding-window latency + frequency tracker.
+ *
+ * Thread-safety note: synchronous JS — no concurrency concerns.
+ */
+export class SelectorHotspotSampler {
+    _windowMs;
+    _maxSamplesPerKey;
+    _selectors = new Map();
+    /**
+     * @param config — Optional sampler configuration.
+     */
+    constructor(config = {}) {
+        this._windowMs = config.windowMs ?? DEFAULT_HOTSPOT_WINDOW_MS;
+        this._maxSamplesPerKey = config.maxSamplesPerKey ?? DEFAULT_HOTSPOT_MAX_SAMPLES_PER_KEY;
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    /** Current sliding window duration in ms. */
+    get windowMs() {
+        return this._windowMs;
+    }
+    /**
+     * Record a selector invocation.
+     *
+     * @param key — Selector name / identifier.
+     * @param durationMs — Execution time in milliseconds (may be 0 for sync).
+     */
+    record(key, durationMs) {
+        const now = Date.now();
+        let state = this._selectors.get(key);
+        if (!state) {
+            state = { key, samples: [], totalCalls: 0, totalDurationMs: 0 };
+            this._selectors.set(key, state);
+        }
+        // Lazy GC: drop samples outside the window
+        this._evictOldSamples(state, now);
+        // Enforce per-key sample cap (drop oldest when over limit)
+        if (state.samples.length >= this._maxSamplesPerKey) {
+            state.samples.shift();
+        }
+        state.samples.push({ ts: now, durationMs });
+        state.totalCalls++;
+        state.totalDurationMs += durationMs;
+    }
+    /**
+     * Return a sorted hotspot report.
+     *
+     * Hotspots are sorted by `callsInWindow` descending (churn first),
+     * then by `p95Ms` descending as a tiebreaker.
+     *
+     * @returns HotspotReport.
+     */
+    getReport() {
+        const now = Date.now();
+        const hotspots = [];
+        for (const state of this._selectors.values()) {
+            this._evictOldSamples(state, now);
+            hotspots.push(this._computeHotspot(state, now));
+        }
+        hotspots.sort((a, b) => b.callsInWindow - a.callsInWindow || b.p95Ms - a.p95Ms);
+        return {
+            generatedAt: now,
+            windowMs: this._windowMs,
+            hotspots,
+        };
+    }
+    /**
+     * Return the hotspot for a single selector key, or undefined if never recorded.
+     *
+     * @param key — Selector identifier.
+     */
+    getHotspot(key) {
+        const state = this._selectors.get(key);
+        if (!state)
+            return undefined;
+        const now = Date.now();
+        this._evictOldSamples(state, now);
+        return this._computeHotspot(state, now);
+    }
+    /**
+     * Return the top N selectors by call count in the current window.
+     *
+     * @param n — Maximum number of hotspots to return.
+     */
+    getTopHotspots(n) {
+        return this.getReport().hotspots.slice(0, n);
+    }
+    /** Number of distinct selector keys tracked. */
+    get trackedKeyCount() {
+        return this._selectors.size;
+    }
+    /**
+     * Clear all recorded samples and reset tracking.
+     * Does not reset configuration.
+     */
+    reset() {
+        this._selectors.clear();
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    _evictOldSamples(state, now) {
+        const cutoff = now - this._windowMs;
+        // Samples are chronological oldest-first; trim from front
+        let i = 0;
+        while (i < state.samples.length && state.samples[i].ts < cutoff) {
+            i++;
+        }
+        if (i > 0) {
+            state.samples = state.samples.slice(i);
+        }
+    }
+    _computeHotspot(state, now) {
+        const windowSec = this._windowMs / 1_000;
+        const samples = state.samples;
+        const callsInWindow = samples.length;
+        // Calls-per-second in window
+        const callsPerSecond = windowSec > 0 ? callsInWindow / windowSec : 0;
+        // Compute latency percentiles from windowed samples
+        const { p50, p95, p99, avgMs, maxMs } = this._percentiles(samples);
+        return {
+            key: state.key,
+            callsInWindow,
+            callsPerSecond: Math.round(callsPerSecond * 100) / 100,
+            totalCalls: state.totalCalls,
+            avgMs,
+            p50Ms: p50,
+            p95Ms: p95,
+            p99Ms: p99,
+            maxMs,
+            isChurnHotspot: callsPerSecond > 10, // >10 calls/sec
+            isLatencyHotspot: p95 > 5, // p95 > 5ms
+        };
+    }
+    _percentiles(samples) {
+        if (samples.length === 0) {
+            return { p50: 0, p95: 0, p99: 0, avgMs: 0, maxMs: 0 };
+        }
+        const durations = samples.map((s) => s.durationMs).sort((a, b) => a - b);
+        const len = durations.length;
+        const sum = durations.reduce((acc, v) => acc + v, 0);
+        const pAt = (pct) => {
+            const idx = Math.min(Math.ceil(len * pct) - 1, len - 1);
+            return Math.round((durations[Math.max(idx, 0)] ?? 0) * 100) / 100;
+        };
+        return {
+            p50: pAt(0.5),
+            p95: pAt(0.95),
+            p99: pAt(0.99),
+            avgMs: Math.round((sum / len) * 100) / 100,
+            maxMs: Math.round((durations[len - 1] ?? 0) * 100) / 100,
+        };
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * State inspector subsystem exports.
+ *
+ * Import from here to access types, the provider class, and the factory.
+ *
+ * Usage:
+ * ```ts
+ * import { createStateInspector } from '../runtime/inspection/state-inspector/index.js';
+ *
+ * const inspector = createStateInspector({
+ *   domains: [sessionAdapter, conversationAdapter],
+ *   maxTransitions: 500,
+ * });
+ * ```
+ *
+ * Devtools / State Inspector.
+ */
+export type { DomainSnapshot, StateSnapshot, TransitionEntry, SubscriptionInfo, StateInspectorConfig, TimelineEvent, TimeTravelCursor, SelectorHotspot, HotspotReport, HotspotSamplerConfig, } from './types.js';
+export { DEFAULT_MAX_TRANSITIONS, DEFAULT_TIMELINE_BUFFER_SIZE, DEFAULT_HOTSPOT_WINDOW_MS, DEFAULT_HOTSPOT_MAX_SAMPLES_PER_KEY, } from './types.js';
+export { BoundedTransitionLog } from './transition-log.js';
+export { TimelineBuffer } from './timeline.js';
+export { SelectorHotspotSampler } from './hotspot-sampler.js';
+export { StateInspectorProvider } from './inspector.js';
+export type { InspectableDomain } from '../../diagnostics/panels/state-inspector.js';
+import { StateInspectorProvider } from './inspector.js';
+import type { InspectableDomain } from '../../diagnostics/panels/state-inspector.js';
+import type { StateInspectorConfig } from './types.js';
+/**
+ * Factory parameters for createStateInspector.
+ */
+export interface CreateStateInspectorOptions extends StateInspectorConfig {
+    /** Domain adapters to register at construction time. */
+    readonly domains?: InspectableDomain[];
+}
+/**
+ * Create a fully configured StateInspectorProvider.
+ *
+ * @param options - Configuration including domains and capacity limits.
+ * @returns A ready-to-use StateInspectorProvider instance.
+ */
+export declare function createStateInspector(options?: CreateStateInspectorOptions): StateInspectorProvider;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/inspection/state-inspector/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,yBAAyB,EACzB,mCAAmC,GACpC,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAGrF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CAGxB"}

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

@@ -0,0 +1,38 @@
+/**
+ * State inspector subsystem exports.
+ *
+ * Import from here to access types, the provider class, and the factory.
+ *
+ * Usage:
+ * ```ts
+ * import { createStateInspector } from '../runtime/inspection/state-inspector/index.js';
+ *
+ * const inspector = createStateInspector({
+ *   domains: [sessionAdapter, conversationAdapter],
+ *   maxTransitions: 500,
+ * });
+ * ```
+ *
+ * Devtools / State Inspector.
+ */
+export { DEFAULT_MAX_TRANSITIONS, DEFAULT_TIMELINE_BUFFER_SIZE, DEFAULT_HOTSPOT_WINDOW_MS, DEFAULT_HOTSPOT_MAX_SAMPLES_PER_KEY, } from './types.js';
+// ── Transition log ────────────────────────────────────────────────────────────
+export { BoundedTransitionLog } from './transition-log.js';
+// ── Timeline buffer ───────────────────────────────────────────────────────────
+export { TimelineBuffer } from './timeline.js';
+// ── Hotspot sampler ───────────────────────────────────────────────────────────
+export { SelectorHotspotSampler } from './hotspot-sampler.js';
+// ── Provider ─────────────────────────────────────────────────────────────────
+export { StateInspectorProvider } from './inspector.js';
+// ── Factory ───────────────────────────────────────────────────────────────────
+import { StateInspectorProvider } from './inspector.js';
+/**
+ * Create a fully configured StateInspectorProvider.
+ *
+ * @param options - Configuration including domains and capacity limits.
+ * @returns A ready-to-use StateInspectorProvider instance.
+ */
+export function createStateInspector(options = {}) {
+    const { domains = [], ...config } = options;
+    return new StateInspectorProvider(domains, config);
+}

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

@@ -0,0 +1,184 @@
+/**
+ * StateInspectorProvider — enhanced runtime state inspector data provider.
+ *
+ * Extends the basic StateInspectorPanel from diagnostics with:
+ * - Bounded transition history via BoundedTransitionLog
+ * - Domain-filtered snapshots
+ * - Subscription registry showing active consumers with notification metadata
+ *
+ * This is a DATA PROVIDER — no UI rendering logic.
+ * State inspector provider implementation.
+ */
+import type { StateSnapshot, TransitionEntry, SubscriptionInfo, StateInspectorConfig, TimelineEvent, TimeTravelCursor } from './types.js';
+import type { InspectableDomain } from '../../diagnostics/panels/state-inspector.js';
+/**
+ * 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 declare class StateInspectorProvider {
+    private readonly _domains;
+    private readonly _transitionLog;
+    private readonly _timeline;
+    private readonly _observedDomains;
+    private readonly _subscriptions;
+    private readonly _domainCache;
+    private _subIdCounter;
+    /**
+     * @param domains - Domain adapters to inspect.
+     * @param config - Optional configuration.
+     */
+    constructor(domains?: InspectableDomain[], config?: StateInspectorConfig);
+    /**
+     * Register an additional domain for inspection.
+     * Triggers a notification to all subscribers.
+     *
+     * @param domain - Domain adapter to register.
+     */
+    registerDomain(domain: InspectableDomain): void;
+    /** Returns the names of all currently registered domains. */
+    registeredDomainNames(): string[];
+    /**
+     * 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?: readonly string[]): StateSnapshot;
+    /**
+     * 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(): number;
+    /**
+     * Return all retained transition entries in chronological order.
+     *
+     * @returns Ordered array of TransitionEntry.
+     */
+    getTransitionHistory(): TransitionEntry[];
+    /**
+     * Return transition history filtered by domain.
+     *
+     * @param domain - Domain name to filter by.
+     */
+    getTransitionsByDomain(domain: string): TransitionEntry[];
+    /**
+     * Return transitions recorded at or after the given epoch ms timestamp.
+     *
+     * @param sinceMs - Inclusive lower bound (epoch ms).
+     */
+    getTransitionsSince(sinceMs: number): TransitionEntry[];
+    /**
+     * Return the N most recent transitions.
+     *
+     * @param n - Maximum number of entries.
+     */
+    getLastTransitions(n: number): TransitionEntry[];
+    /** Total number of transitions ever recorded (not capped by maxTransitions). */
+    get totalTransitions(): number;
+    /**
+     * Clear all stored transitions and timeline events.
+     * Does not reset subscription registry or domain cache.
+     */
+    clearTransitionHistory(): void;
+    /**
+     * Return all retained timeline events in chronological order.
+     *
+     * @returns Ordered array of TimelineEvent.
+     */
+    getTimeline(): TimelineEvent[];
+    /**
+     * 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(): TimelineEvent | undefined;
+    /**
+     * Current time-travel cursor state.
+     */
+    get timeTravelCursor(): TimeTravelCursor;
+    /**
+     * Whether the inspector is currently in time-travel mode (cursor pinned).
+     */
+    get isTimeTravel(): boolean;
+    /**
+     * Step the cursor one event backward (toward oldest).
+     *
+     * @returns true if the cursor moved.
+     */
+    stepBack(): boolean;
+    /**
+     * Step the cursor one event forward (toward live).
+     *
+     * @returns true if the cursor moved.
+     */
+    stepForward(): boolean;
+    /**
+     * Seek the cursor to an absolute logical index.
+     * Pass `timeline.size` to return to live.
+     *
+     * @param index — Target index (size = live).
+     */
+    seekTo(index: number): void;
+    /**
+     * Seek to the nearest event at or before a given epoch ms timestamp.
+     *
+     * @param epochMs — Target timestamp.
+     */
+    seekToTime(epochMs: number): void;
+    /**
+     * Exit time-travel mode, returning the cursor to the live tail.
+     */
+    exitTimeTravel(): void;
+    /**
+     * 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(): TimelineEvent | undefined;
+    /**
+     * 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: () => void, label: string, domainFilter?: readonly string[]): {
+        id: string;
+        unsubscribe: () => void;
+    };
+    /**
+     * Return metadata for all active subscriptions.
+     * Callbacks are not exposed.
+     *
+     * @returns Array of SubscriptionInfo.
+     */
+    getSubscriptions(): SubscriptionInfo[];
+    /**
+     * Return the count of currently active subscriptions.
+     */
+    get subscriptionCount(): number;
+    /** Filter domains by the provided list, or return all if undefined. */
+    private _filterDomains;
+    /** Notify all subscribers, tracking notification metadata. */
+    private _notifyAll;
+}
+//# sourceMappingURL=inspector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspector.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/inspection/state-inspector/inspector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,aAAa,EAEb,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AA8BrF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8C;IAC7E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,aAAa,CAAK;IAE1B;;;OAGG;gBAED,OAAO,GAAE,iBAAiB,EAAO,EACjC,MAAM,GAAE,oBAAyB;IAgBnC;;;;;OAKG;IACI,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAKtD,6DAA6D;IACtD,qBAAqB,IAAI,MAAM,EAAE;IAMxC;;;;;;OAMG;IACI,WAAW,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa;IAmBnE;;;;;;;OAOG;IACI,IAAI,IAAI,MAAM;IAqDrB;;;;OAIG;IACI,oBAAoB,IAAI,eAAe,EAAE;IAIhD;;;;OAIG;IACI,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAIhE;;;;OAIG;IACI,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,EAAE;IAI9D;;;;OAIG;IACI,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE;IAIvD,gFAAgF;IAChF,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;;OAGG;IACI,sBAAsB,IAAI,IAAI;IAOrC;;;;OAIG;IACI,WAAW,IAAI,aAAa,EAAE;IAIrC;;;;;OAKG;IACI,uBAAuB,IAAI,aAAa,GAAG,SAAS;IAI3D;;OAEG;IACH,IAAI,gBAAgB,IAAI,gBAAgB,CAEvC;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;;OAIG;IACI,QAAQ,IAAI,OAAO;IAI1B;;;;OAIG;IACI,WAAW,IAAI,OAAO;IAI7B;;;;;OAKG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACI,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIxC;;OAEG;IACI,cAAc,IAAI,IAAI;IAI7B;;;;;OAKG;IACI,qBAAqB,IAAI,aAAa,GAAG,SAAS;IAMzD;;;;;;;OAOG;IACI,SAAS,CACd,QAAQ,EAAE,MAAM,IAAI,EACpB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAC/B;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,IAAI,CAAA;KAAE;IAoB1C;;;;;OAKG;IACI,gBAAgB,IAAI,gBAAgB,EAAE;IAa7C;;OAEG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAID,uEAAuE;IACvE,OAAO,CAAC,cAAc;IAMtB,8DAA8D;IAC9D,OAAO,CAAC,UAAU;CAcnB"}