@opensteer/runtime-core 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,61 +1,9 @@
-import { BrowserCoreEngine, PageRef, NetworkRecord, HeaderEntry, BodyPayload, SessionRef } from '@opensteer/browser-core';
-import { OpensteerSemanticOperationName, OpensteerArtifactKind, ArtifactProvenance, TraceContext, HtmlSnapshot, DomSnapshot, CookieRecord, StorageSnapshot, ScriptSourceArtifactData, ArtifactRelation, ArtifactReference, OpensteerArtifact, OpensteerAuthRecipePayload, OpensteerRequestPlanPayload, OpensteerRequestPlanFreshness, OpensteerRecipePayload, OpensteerReverseCasePayload, OpensteerInteractionTracePayload, OpensteerReversePackagePayload, OpensteerReverseReportPayload, NetworkQueryRecord, NetworkResourceType, TraceOutcome, OpensteerEvent, OpensteerError, TraceRecord, TraceBundle, ReplayElementPath, OpensteerBrowserOptions, OpensteerBrowserLaunchOptions, OpensteerBrowserContextOptions, OpensteerSessionInfo, OpensteerOpenInput, OpensteerOpenOutput, OpensteerPageListInput, OpensteerPageListOutput, OpensteerPageNewInput, OpensteerPageNewOutput, OpensteerPageActivateInput, OpensteerPageActivateOutput, OpensteerPageCloseInput, OpensteerPageCloseOutput, OpensteerPageGotoInput, OpensteerPageGotoOutput, OpensteerPageEvaluateInput, OpensteerPageEvaluateOutput, OpensteerAddInitScriptInput, OpensteerAddInitScriptOutput, OpensteerPageSnapshotInput, OpensteerPageSnapshotOutput, OpensteerDomClickInput, OpensteerActionResult, OpensteerDomHoverInput, OpensteerDomInputInput, OpensteerDomScrollInput, OpensteerDomExtractInput, OpensteerDomExtractOutput, OpensteerNetworkQueryInput, OpensteerNetworkQueryOutput, OpensteerNetworkTagInput, OpensteerNetworkTagOutput, OpensteerNetworkClearInput, OpensteerNetworkClearOutput, OpensteerCaptureScriptsInput, OpensteerCaptureScriptsOutput, OpensteerNetworkMinimizeInput, OpensteerNetworkMinimizeOutput, OpensteerNetworkDiffInput, OpensteerNetworkDiffOutput, OpensteerArtifactReadInput, OpensteerArtifactReadOutput, OpensteerTransportProbeInput, OpensteerTransportProbeOutput, OpensteerReverseDiscoverInput, OpensteerReverseDiscoverOutput, OpensteerReverseQueryInput, OpensteerReverseQueryOutput, OpensteerReversePackageCreateInput, OpensteerReversePackageCreateOutput, OpensteerReversePackageRunInput, OpensteerReversePackageRunOutput, OpensteerReverseExportInput, OpensteerReverseExportOutput, OpensteerReverseReportInput, OpensteerReverseReportOutput, OpensteerReversePackageGetInput, OpensteerReversePackageGetOutput, OpensteerReversePackageListInput, OpensteerReversePackageListOutput, OpensteerReversePackagePatchInput, OpensteerReversePackagePatchOutput, OpensteerInteractionCaptureInput, OpensteerInteractionCaptureOutput, OpensteerInteractionGetInput, OpensteerInteractionGetOutput, OpensteerInteractionDiffInput, OpensteerInteractionDiffOutput, OpensteerInteractionReplayInput, OpensteerInteractionReplayOutput, OpensteerScriptBeautifyInput, OpensteerScriptBeautifyOutput, OpensteerScriptDeobfuscateInput, OpensteerScriptDeobfuscateOutput, OpensteerScriptSandboxInput, OpensteerScriptSandboxOutput, OpensteerCaptchaSolveInput, OpensteerCaptchaSolveOutput, OpensteerInferRequestPlanInput, OpensteerWriteRequestPlanInput, OpensteerGetRequestPlanInput, OpensteerListRequestPlansInput, OpensteerListRequestPlansOutput, OpensteerWriteAuthRecipeInput, OpensteerWriteRecipeInput, OpensteerGetAuthRecipeInput, OpensteerGetRecipeInput, OpensteerListAuthRecipesInput, OpensteerListAuthRecipesOutput, OpensteerListRecipesInput, OpensteerListRecipesOutput, OpensteerRunAuthRecipeInput, OpensteerRunAuthRecipeOutput, OpensteerRunRecipeInput, OpensteerRunRecipeOutput, OpensteerRawRequestInput, OpensteerRawRequestOutput, OpensteerRequestExecuteInput, OpensteerRequestExecuteOutput, OpensteerComputerExecuteInput, OpensteerComputerExecuteOutput, OpensteerSessionCloseOutput } from '@opensteer/protocol';
+import { OpensteerArtifactKind, ArtifactProvenance, TraceContext, HtmlSnapshot, DomSnapshot, CookieRecord, StorageSnapshot, ScriptSourceArtifactData, ArtifactRelation, ArtifactReference, OpensteerArtifact, ExternalBinaryLocation, OpensteerSemanticOperationName, OpensteerAuthRecipePayload, OpensteerRequestPlanPayload, OpensteerRequestPlanFreshness, OpensteerRecipePayload, OpensteerReverseCasePayload, OpensteerInteractionTracePayload, OpensteerReversePackagePayload, OpensteerReverseReportPayload, NetworkQueryRecord, NetworkResourceType, ObservationSink, ObservationSession, ObservationEvent, ObservationArtifact, ObservabilityConfig, ObservabilityProfile, TraceOutcome, OpensteerEvent, OpensteerError, TraceRecord, TraceBundle, ReplayElementPath, OpensteerBrowserOptions, OpensteerBrowserLaunchOptions, OpensteerBrowserContextOptions, OpensteerSessionInfo, OpensteerOpenInput, OpensteerOpenOutput, OpensteerPageListInput, OpensteerPageListOutput, OpensteerPageNewInput, OpensteerPageNewOutput, OpensteerPageActivateInput, OpensteerPageActivateOutput, OpensteerPageCloseInput, OpensteerPageCloseOutput, OpensteerPageGotoInput, OpensteerPageGotoOutput, OpensteerPageEvaluateInput, OpensteerPageEvaluateOutput, OpensteerAddInitScriptInput, OpensteerAddInitScriptOutput, OpensteerPageSnapshotInput, OpensteerPageSnapshotOutput, OpensteerDomClickInput, OpensteerActionResult, OpensteerDomHoverInput, OpensteerDomInputInput, OpensteerDomScrollInput, OpensteerDomExtractInput, OpensteerDomExtractOutput, OpensteerNetworkQueryInput, OpensteerNetworkQueryOutput, OpensteerNetworkTagInput, OpensteerNetworkTagOutput, OpensteerNetworkClearInput, OpensteerNetworkClearOutput, OpensteerCaptureScriptsInput, OpensteerCaptureScriptsOutput, OpensteerNetworkMinimizeInput, OpensteerNetworkMinimizeOutput, OpensteerNetworkDiffInput, OpensteerNetworkDiffOutput, OpensteerArtifactReadInput, OpensteerArtifactReadOutput, OpensteerTransportProbeInput, OpensteerTransportProbeOutput, OpensteerReverseDiscoverInput, OpensteerReverseDiscoverOutput, OpensteerReverseQueryInput, OpensteerReverseQueryOutput, OpensteerReversePackageCreateInput, OpensteerReversePackageCreateOutput, OpensteerReversePackageRunInput, OpensteerReversePackageRunOutput, OpensteerReverseExportInput, OpensteerReverseExportOutput, OpensteerReverseReportInput, OpensteerReverseReportOutput, OpensteerReversePackageGetInput, OpensteerReversePackageGetOutput, OpensteerReversePackageListInput, OpensteerReversePackageListOutput, OpensteerReversePackagePatchInput, OpensteerReversePackagePatchOutput, OpensteerInteractionCaptureInput, OpensteerInteractionCaptureOutput, OpensteerInteractionGetInput, OpensteerInteractionGetOutput, OpensteerInteractionDiffInput, OpensteerInteractionDiffOutput, OpensteerInteractionReplayInput, OpensteerInteractionReplayOutput, OpensteerScriptBeautifyInput, OpensteerScriptBeautifyOutput, OpensteerScriptDeobfuscateInput, OpensteerScriptDeobfuscateOutput, OpensteerScriptSandboxInput, OpensteerScriptSandboxOutput, OpensteerCaptchaSolveInput, OpensteerCaptchaSolveOutput, OpensteerInferRequestPlanInput, OpensteerWriteRequestPlanInput, OpensteerGetRequestPlanInput, OpensteerListRequestPlansInput, OpensteerListRequestPlansOutput, OpensteerWriteAuthRecipeInput, OpensteerWriteRecipeInput, OpensteerGetAuthRecipeInput, OpensteerGetRecipeInput, OpensteerListAuthRecipesInput, OpensteerListAuthRecipesOutput, OpensteerListRecipesInput, OpensteerListRecipesOutput, OpensteerRunAuthRecipeInput, OpensteerRunAuthRecipeOutput, OpensteerRunRecipeInput, OpensteerRunRecipeOutput, OpensteerRawRequestInput, OpensteerRawRequestOutput, OpensteerRequestExecuteInput, OpensteerRequestExecuteOutput, OpensteerComputerExecuteInput, OpensteerComputerExecuteOutput, OpensteerSessionCloseOutput } from '@opensteer/protocol';
 export { ReplayElementPath } from '@opensteer/protocol';
+import { BrowserCoreEngine, PageRef, NetworkRecord, HeaderEntry, BodyPayload, SessionRef } from '@opensteer/browser-core';
 
 declare const OPENSTEER_RUNTIME_CORE_VERSION: string;
 
-interface TimeoutResolutionInput {
-    readonly operation: OpensteerSemanticOperationName;
-    readonly signal?: AbortSignal;
-}
-interface TimeoutPolicy {
-    resolveTimeoutMs(input: TimeoutResolutionInput): number | undefined;
-}
-type SettleTrigger = "navigation" | "dom-action" | "snapshot";
-interface SettleDelayInput {
-    readonly operation: OpensteerSemanticOperationName;
-    readonly trigger: SettleTrigger;
-}
-interface SettleContext extends SettleDelayInput {
-    readonly engine: BrowserCoreEngine;
-    readonly pageRef: PageRef;
-    readonly signal: AbortSignal;
-    readonly remainingMs: number | undefined;
-}
-interface SettleObserver {
-    settle(input: SettleContext): Promise<boolean>;
-}
-interface SettlePolicy {
-    readonly observers?: readonly SettleObserver[];
-    resolveDelayMs(input: SettleDelayInput): number;
-}
-interface RetryEvaluationInput {
-    readonly operation: OpensteerSemanticOperationName;
-    readonly error: unknown;
-}
-interface RetryDecision {
-    readonly retry: false;
-}
-interface RetryPolicy {
-    evaluate(input: RetryEvaluationInput): RetryDecision | Promise<RetryDecision>;
-}
-interface FallbackEvaluationInput {
-    readonly operation: OpensteerSemanticOperationName;
-    readonly error: unknown;
-}
-interface FallbackDecision {
-    readonly fallback: false;
-}
-interface FallbackPolicy {
-    evaluate(input: FallbackEvaluationInput): FallbackDecision | Promise<FallbackDecision>;
-}
-interface OpensteerPolicy {
-    readonly timeout: TimeoutPolicy;
-    readonly settle: SettlePolicy;
-    readonly retry: RetryPolicy;
-    readonly fallback: FallbackPolicy;
-}
-
 type ArtifactPayloadType = "structured" | "binary";
 type ProtocolArtifactDelivery = "external" | "inline-if-structured";
 interface ArtifactScope extends TraceContext {
@@ -132,6 +80,76 @@ interface OpensteerArtifactStore {
         readonly delivery?: ProtocolArtifactDelivery;
     }): Promise<OpensteerArtifact | undefined>;
 }
+declare class FilesystemArtifactStore implements OpensteerArtifactStore {
+    private readonly rootPath;
+    readonly manifestsDirectory: string;
+    readonly objectsDirectory: string;
+    constructor(rootPath: string);
+    initialize(): Promise<void>;
+    writeStructured(input: WriteStructuredArtifactInput): Promise<ArtifactManifest>;
+    writeBinary(input: WriteBinaryArtifactInput): Promise<ArtifactManifest>;
+    getManifest(artifactId: string): Promise<ArtifactManifest | undefined>;
+    read(artifactId: string): Promise<StoredArtifactRecord | undefined>;
+    toProtocolArtifactReference(artifactId: string, relation: ArtifactRelation): Promise<ArtifactReference | undefined>;
+    toProtocolArtifact(artifactId: string, options?: {
+        readonly delivery?: ProtocolArtifactDelivery;
+    }): Promise<OpensteerArtifact | undefined>;
+    private manifestPath;
+}
+declare function createArtifactStore(rootPath: string): FilesystemArtifactStore;
+declare function manifestToExternalBinaryLocation(rootPath: string, manifest: Pick<ArtifactManifest, "objectRelativePath" | "mediaType" | "byteLength" | "sha256">): ExternalBinaryLocation;
+
+interface TimeoutResolutionInput {
+    readonly operation: OpensteerSemanticOperationName;
+    readonly signal?: AbortSignal;
+}
+interface TimeoutPolicy {
+    resolveTimeoutMs(input: TimeoutResolutionInput): number | undefined;
+}
+type SettleTrigger = "navigation" | "dom-action" | "snapshot";
+interface SettleDelayInput {
+    readonly operation: OpensteerSemanticOperationName;
+    readonly trigger: SettleTrigger;
+}
+interface SettleContext extends SettleDelayInput {
+    readonly engine: BrowserCoreEngine;
+    readonly pageRef: PageRef;
+    readonly signal: AbortSignal;
+    readonly remainingMs: number | undefined;
+}
+interface SettleObserver {
+    settle(input: SettleContext): Promise<boolean>;
+}
+interface SettlePolicy {
+    readonly observers?: readonly SettleObserver[];
+    resolveDelayMs(input: SettleDelayInput): number;
+}
+interface RetryEvaluationInput {
+    readonly operation: OpensteerSemanticOperationName;
+    readonly error: unknown;
+}
+interface RetryDecision {
+    readonly retry: false;
+}
+interface RetryPolicy {
+    evaluate(input: RetryEvaluationInput): RetryDecision | Promise<RetryDecision>;
+}
+interface FallbackEvaluationInput {
+    readonly operation: OpensteerSemanticOperationName;
+    readonly error: unknown;
+}
+interface FallbackDecision {
+    readonly fallback: false;
+}
+interface FallbackPolicy {
+    evaluate(input: FallbackEvaluationInput): FallbackDecision | Promise<FallbackDecision>;
+}
+interface OpensteerPolicy {
+    readonly timeout: TimeoutPolicy;
+    readonly settle: SettlePolicy;
+    readonly retry: RetryPolicy;
+    readonly fallback: FallbackPolicy;
+}
 
 type JsonPrimitive = boolean | number | string | null;
 type JsonValue = JsonPrimitive | JsonObject | JsonArray;
@@ -312,6 +330,35 @@ interface SavedNetworkStore {
     }): Promise<number>;
 }
 
+interface ListObservationEventsInput {
+    readonly kind?: ObservationEvent["kind"];
+    readonly phase?: ObservationEvent["phase"];
+    readonly correlationId?: string;
+    readonly pageRef?: string;
+    readonly afterSequence?: number;
+    readonly from?: number;
+    readonly to?: number;
+    readonly limit?: number;
+}
+interface ListObservationArtifactsInput {
+    readonly kind?: ObservationArtifact["kind"];
+    readonly pageRef?: string;
+    readonly limit?: number;
+}
+interface FilesystemObservationStore extends ObservationSink {
+    readonly sessionsDirectory: string;
+    initialize(): Promise<void>;
+    getSession(sessionId: string): Promise<ObservationSession | undefined>;
+    listEvents(sessionId: string, input?: ListObservationEventsInput): Promise<readonly ObservationEvent[]>;
+    listArtifacts(sessionId: string, input?: ListObservationArtifactsInput): Promise<readonly ObservationArtifact[]>;
+    getArtifact(sessionId: string, artifactId: string): Promise<ObservationArtifact | undefined>;
+}
+interface NormalizedObservabilityConfig extends ObservabilityConfig {
+    readonly profile: ObservabilityProfile;
+}
+declare function normalizeObservabilityConfig(input: Partial<ObservabilityConfig> | undefined): NormalizedObservabilityConfig;
+declare function createObservationStore(rootPath: string, artifacts: OpensteerArtifactStore): FilesystemObservationStore;
+
 interface TraceRunManifest {
     readonly runId: string;
     readonly createdAt: number;
@@ -378,6 +425,7 @@ interface OpensteerWorkspaceManifest {
         readonly live: "live";
         readonly artifacts: "artifacts";
         readonly traces: "traces";
+        readonly observations: "observations";
         readonly registry: "registry";
     };
 }
@@ -399,10 +447,12 @@ interface FilesystemOpensteerWorkspace {
     readonly liveCloudPath: string;
     readonly artifactsPath: string;
     readonly tracesPath: string;
+    readonly observationsPath: string;
     readonly registryPath: string;
     readonly lockPath: string;
     readonly artifacts: OpensteerArtifactStore;
     readonly traces: OpensteerTraceStore;
+    readonly observations: FilesystemObservationStore;
     readonly registry: {
         readonly descriptors: DescriptorRegistryStore;
         readonly requestPlans: RequestPlanRegistryStore;
@@ -609,6 +659,9 @@ interface OpensteerSessionRuntimeOptions {
     };
     readonly cleanupRootOnClose?: boolean;
     readonly sessionInfo?: Partial<Omit<OpensteerSessionInfo, "sessionId" | "activePageRef">>;
+    readonly observability?: Partial<ObservabilityConfig>;
+    readonly observationSessionId?: string;
+    readonly observationSink?: ObservationSink;
 }
 interface RuntimeOperationOptions {
     readonly signal?: AbortSignal;
@@ -625,6 +678,9 @@ declare class OpensteerSessionRuntime {
     private readonly registryOverrides;
     private readonly cleanupRootOnClose;
     private readonly sessionInfoBase;
+    private observationConfig;
+    private readonly observationSessionId;
+    private readonly injectedObservationSink;
     private root;
     private engine;
     private dom;
@@ -634,11 +690,15 @@ declare class OpensteerSessionRuntime {
     private sessionRef;
     private pageRef;
     private runId;
+    private observations;
+    private readonly operationEventStorage;
+    private readonly pendingOperationEventCaptures;
     private readonly cookieJars;
     private readonly recipeCache;
     private ownsEngine;
     constructor(options: OpensteerSessionRuntimeOptions);
     info(): Promise<OpensteerSessionInfo>;
+    setObservabilityConfig(input: Partial<ObservabilityConfig> | undefined): Promise<ObservabilityConfig>;
     open(input?: OpensteerOpenInput, options?: RuntimeOperationOptions): Promise<OpensteerOpenOutput>;
     listPages(input?: OpensteerPageListInput, options?: RuntimeOperationOptions): Promise<OpensteerPageListOutput>;
     newPage(input?: OpensteerPageNewInput, options?: RuntimeOperationOptions): Promise<OpensteerPageNewOutput>;
@@ -813,7 +873,14 @@ declare class OpensteerSessionRuntime {
     private appendTrace;
     private cleanupSessionResources;
     private resetRuntimeState;
+    private ensureObservationSession;
+    private resolveObservationSessionId;
     private runWithOperationTimeout;
+    private wrapEngineWithObservationCapture;
+    private captureObservedStepEvents;
+    private recordPendingOperationEventCapture;
+    private consumePendingOperationEventCapture;
+    private drainPendingEngineEvents;
     private navigatePage;
 }
 
@@ -890,4 +957,247 @@ declare function dispatchSemanticOperation(runtime: OpensteerSemanticRuntime, op
     readonly signal?: AbortSignal;
 }): Promise<unknown>;
 
-export { type AuthRecipeRecord, type AuthRecipeRegistryStore, type CreateFilesystemOpensteerWorkspaceOptions, type DescriptorRecord, type DescriptorRegistryStore, type DomDescriptorPayload, type DomDescriptorRecord, type DomDescriptorStore, type DomReadDescriptorInput, type DomWriteDescriptorInput, type FilesystemOpensteerWorkspace, type InteractionTraceRecord, type InteractionTraceRegistryStore, type ListRegistryRecordsInput, OPENSTEER_FILESYSTEM_WORKSPACE_LAYOUT, OPENSTEER_FILESYSTEM_WORKSPACE_VERSION, OPENSTEER_RUNTIME_CORE_VERSION, type OpensteerEngineFactory, type OpensteerEngineFactoryOptions, type OpensteerExtractionDescriptorPayload, type OpensteerExtractionDescriptorRecord, type OpensteerExtractionDescriptorStore, type OpensteerRuntimeOperationOptions, type OpensteerRuntimeWorkspace, type OpensteerSemanticRuntime, OpensteerSessionRuntime, type OpensteerSessionRuntimeOptions, type OpensteerWorkspaceManifest, type RecipeRecord, type RecipeRegistryStore, type RegistryProvenance, type RequestPlanFreshness, type RequestPlanRecord, type RequestPlanRegistryStore, type ResolveRegistryRecordInput, type ReverseCaseRecord, type ReverseCaseRegistryStore, type ReversePackageRecord, type ReversePackageRegistryStore, type ReverseReportRecord, type ReverseReportRegistryStore, type UpdateRequestPlanFreshnessInput, type UpdateReverseCaseInput, type WriteAuthRecipeInput, type WriteDescriptorInput, type WriteInteractionTraceInput, type WriteRecipeInput, type WriteRequestPlanInput, type WriteReverseCaseInput, type WriteReversePackageInput, type WriteReverseReportInput, buildDomDescriptorKey, buildDomDescriptorPayload, buildDomDescriptorVersion, createDomDescriptorStore, createFilesystemOpensteerWorkspace, createOpensteerExtractionDescriptorStore, dispatchSemanticOperation, hashDomDescriptorDescription, normalizeWorkspaceId, parseDomDescriptorRecord, parseExtractionDescriptorRecord, resolveFilesystemWorkspacePath, sanitizeReplayElementPath };
+type RecordedActionKind = "navigate" | "click" | "dblclick" | "type" | "keypress" | "scroll" | "select-option" | "new-tab" | "close-tab" | "switch-tab" | "go-back" | "go-forward" | "reload";
+interface NavigateRecordedActionDetail {
+    readonly kind: "navigate";
+    readonly url: string;
+    readonly source: "poll" | "push-state" | "replace-state" | "hashchange" | "history-traversal" | "full-navigation";
+}
+interface ClickRecordedActionDetail {
+    readonly kind: "click";
+    readonly button: number;
+    readonly modifiers: readonly string[];
+}
+interface DblclickRecordedActionDetail {
+    readonly kind: "dblclick";
+}
+interface TypeRecordedActionDetail {
+    readonly kind: "type";
+    readonly text: string;
+}
+interface KeypressRecordedActionDetail {
+    readonly kind: "keypress";
+    readonly key: string;
+    readonly modifiers: readonly string[];
+}
+interface ScrollRecordedActionDetail {
+    readonly kind: "scroll";
+    readonly deltaX: number;
+    readonly deltaY: number;
+}
+interface SelectOptionRecordedActionDetail {
+    readonly kind: "select-option";
+    readonly value: string;
+    readonly label?: string;
+}
+interface NewTabRecordedActionDetail {
+    readonly kind: "new-tab";
+    readonly openerPageId?: string;
+    readonly initialUrl: string;
+}
+interface CloseTabRecordedActionDetail {
+    readonly kind: "close-tab";
+}
+interface SwitchTabRecordedActionDetail {
+    readonly kind: "switch-tab";
+    readonly fromPageId?: string;
+    readonly toPageId: string;
+}
+interface GoBackRecordedActionDetail {
+    readonly kind: "go-back";
+    readonly url: string;
+}
+interface GoForwardRecordedActionDetail {
+    readonly kind: "go-forward";
+    readonly url: string;
+}
+interface ReloadRecordedActionDetail {
+    readonly kind: "reload";
+    readonly url: string;
+}
+type RecordedActionDetail = NavigateRecordedActionDetail | ClickRecordedActionDetail | DblclickRecordedActionDetail | TypeRecordedActionDetail | KeypressRecordedActionDetail | ScrollRecordedActionDetail | SelectOptionRecordedActionDetail | NewTabRecordedActionDetail | CloseTabRecordedActionDetail | SwitchTabRecordedActionDetail | GoBackRecordedActionDetail | GoForwardRecordedActionDetail | ReloadRecordedActionDetail;
+interface RecordedActionBase<TKind extends RecordedActionKind, TDetail extends RecordedActionDetail> {
+    readonly kind: TKind;
+    readonly timestamp: number;
+    readonly pageId: string;
+    readonly pageUrl: string;
+    readonly selector?: string;
+    readonly detail: TDetail;
+}
+type NavigateRecordedAction = RecordedActionBase<"navigate", NavigateRecordedActionDetail>;
+type ClickRecordedAction = RecordedActionBase<"click", ClickRecordedActionDetail>;
+type DblclickRecordedAction = RecordedActionBase<"dblclick", DblclickRecordedActionDetail>;
+type TypeRecordedAction = RecordedActionBase<"type", TypeRecordedActionDetail>;
+type KeypressRecordedAction = RecordedActionBase<"keypress", KeypressRecordedActionDetail>;
+type ScrollRecordedAction = RecordedActionBase<"scroll", ScrollRecordedActionDetail>;
+type SelectOptionRecordedAction = RecordedActionBase<"select-option", SelectOptionRecordedActionDetail>;
+type NewTabRecordedAction = RecordedActionBase<"new-tab", NewTabRecordedActionDetail>;
+type CloseTabRecordedAction = RecordedActionBase<"close-tab", CloseTabRecordedActionDetail>;
+type SwitchTabRecordedAction = RecordedActionBase<"switch-tab", SwitchTabRecordedActionDetail>;
+type GoBackRecordedAction = RecordedActionBase<"go-back", GoBackRecordedActionDetail>;
+type GoForwardRecordedAction = RecordedActionBase<"go-forward", GoForwardRecordedActionDetail>;
+type ReloadRecordedAction = RecordedActionBase<"reload", ReloadRecordedActionDetail>;
+type RecordedAction = NavigateRecordedAction | ClickRecordedAction | DblclickRecordedAction | TypeRecordedAction | KeypressRecordedAction | ScrollRecordedAction | SelectOptionRecordedAction | NewTabRecordedAction | CloseTabRecordedAction | SwitchTabRecordedAction | GoBackRecordedAction | GoForwardRecordedAction | ReloadRecordedAction;
+interface RecordingOptions {
+    readonly workspace: string;
+    readonly outputPath?: string;
+    readonly url: string;
+    readonly pollIntervalMs?: number;
+}
+interface RecorderInitialPageState {
+    readonly pageId: string;
+    readonly initialUrl: string;
+    readonly openerPageId?: string;
+}
+interface LocalReplayTarget {
+    readonly kind: "local";
+    readonly workspace: string;
+}
+interface CloudReplayTarget {
+    readonly kind: "cloud";
+    readonly baseUrlEnvVar?: string;
+    readonly apiKeyEnvVar?: string;
+    readonly browserProfileId?: string;
+    readonly reuseBrowserProfileIfActive?: boolean;
+}
+type ReplayTarget = LocalReplayTarget | CloudReplayTarget;
+interface CodegenOptions {
+    readonly actions: readonly RecordedAction[];
+    readonly workspace?: string;
+    readonly startUrl?: string;
+    readonly initialPages?: readonly RecorderInitialPageState[];
+    readonly activePageId?: string;
+    readonly replayTarget?: ReplayTarget;
+}
+interface RecorderPageState {
+    readonly pageId: string;
+    readonly pageRef: string;
+    readonly openerPageRef?: string;
+    readonly openerPageId?: string;
+    readonly currentUrl: string;
+}
+interface FlowRecorderSnapshot {
+    readonly url: string;
+    readonly focused: boolean;
+    readonly visibilityState: "hidden" | "visible" | "prerender";
+    readonly stopRequested: boolean;
+    readonly events: readonly RawFlowRecorderEvent[];
+}
+interface RawFlowRecorderBaseEvent {
+    readonly timestamp: number;
+    readonly selector?: string;
+}
+interface RawFlowRecorderNavigateEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "navigate";
+    readonly url: string;
+    readonly source: "push-state" | "replace-state" | "hashchange" | "history-traversal" | "full-navigation";
+}
+interface RawFlowRecorderClickEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "click";
+    readonly selector: string;
+    readonly button: number;
+    readonly modifiers: readonly string[];
+}
+interface RawFlowRecorderDblclickEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "dblclick";
+    readonly selector: string;
+}
+interface RawFlowRecorderTypeEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "type";
+    readonly selector: string;
+    readonly text: string;
+}
+interface RawFlowRecorderKeypressEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "keypress";
+    readonly key: string;
+    readonly modifiers: readonly string[];
+    readonly selector?: string;
+}
+interface RawFlowRecorderScrollEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "scroll";
+    readonly deltaX: number;
+    readonly deltaY: number;
+    readonly selector?: string;
+}
+interface RawFlowRecorderSelectOptionEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "select-option";
+    readonly selector: string;
+    readonly value: string;
+    readonly label?: string;
+}
+interface RawFlowRecorderReloadEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "reload";
+    readonly url: string;
+}
+interface RawFlowRecorderGoBackEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "go-back";
+    readonly url: string;
+}
+interface RawFlowRecorderGoForwardEvent extends RawFlowRecorderBaseEvent {
+    readonly kind: "go-forward";
+    readonly url: string;
+}
+type RawFlowRecorderEvent = RawFlowRecorderNavigateEvent | RawFlowRecorderClickEvent | RawFlowRecorderDblclickEvent | RawFlowRecorderTypeEvent | RawFlowRecorderKeypressEvent | RawFlowRecorderScrollEvent | RawFlowRecorderSelectOptionEvent | RawFlowRecorderReloadEvent | RawFlowRecorderGoBackEvent | RawFlowRecorderGoForwardEvent;
+
+interface FlowRecorderInstallScriptOptions {
+    readonly showStopButton?: boolean;
+}
+declare function createFlowRecorderInstallScript(options?: FlowRecorderInstallScriptOptions): string;
+declare const FLOW_RECORDER_INSTALL_SCRIPT: string;
+declare const FLOW_RECORDER_DRAIN_SCRIPT: string;
+
+interface RecorderRuntimeAdapter {
+    addInitScript(input: {
+        readonly script: string;
+    }): Promise<unknown>;
+    evaluate(input: {
+        readonly script: string;
+        readonly pageRef?: string;
+    }): Promise<unknown>;
+    listPages(): Promise<{
+        readonly pages: readonly {
+            readonly pageRef: string;
+            readonly url: string;
+            readonly openerPageRef?: string;
+        }[];
+    }>;
+}
+interface FlowRecorderCollectorOptions {
+    readonly pollIntervalMs?: number;
+    readonly onAction?: (action: RecordedAction) => void | Promise<void>;
+    readonly installScript?: string;
+}
+declare class FlowRecorderCollector {
+    private readonly runtime;
+    private readonly pollIntervalMs;
+    private readonly onAction;
+    private readonly installScript;
+    private readonly pages;
+    private readonly actions;
+    private nextPageOrdinal;
+    private runningLoop;
+    private loopStopRequested;
+    private stopDetected;
+    private focusedPageId;
+    private stopWaiters;
+    constructor(runtime: RecorderRuntimeAdapter, options?: FlowRecorderCollectorOptions);
+    install(): Promise<void>;
+    start(): void;
+    stop(): Promise<readonly RecordedAction[]>;
+    getActions(): readonly RecordedAction[];
+    getPages(): readonly RecorderPageState[];
+    getFocusedPageId(): string | undefined;
+    waitForStop(): Promise<void>;
+    pollOnce(): Promise<readonly RecordedAction[]>;
+    private runLoop;
+    private readEvaluatedPages;
+    private readSnapshot;
+    private normalizePoll;
+    private normalizeRawEvent;
+    private ensureKnownPage;
+    private updateKnownPage;
+}
+
+declare function generateReplayScript(options: CodegenOptions): string;
+
+export { type ArtifactManifest, type ArtifactPayloadType, type ArtifactScope, type AuthRecipeRecord, type AuthRecipeRegistryStore, type ClickRecordedActionDetail, type CloseTabRecordedActionDetail, type CloudReplayTarget, type CodegenOptions, type CreateFilesystemOpensteerWorkspaceOptions, type DblclickRecordedActionDetail, type DescriptorRecord, type DescriptorRegistryStore, type DomDescriptorPayload, type DomDescriptorRecord, type DomDescriptorStore, type DomReadDescriptorInput, type DomWriteDescriptorInput, FLOW_RECORDER_DRAIN_SCRIPT, FLOW_RECORDER_INSTALL_SCRIPT, FilesystemArtifactStore, type FilesystemObservationStore, type FilesystemOpensteerWorkspace, FlowRecorderCollector, type FlowRecorderCollectorOptions, type FlowRecorderSnapshot, type GoBackRecordedActionDetail, type GoForwardRecordedActionDetail, type InteractionTraceRecord, type InteractionTraceRegistryStore, type KeypressRecordedActionDetail, type ListObservationArtifactsInput, type ListObservationEventsInput, type ListRegistryRecordsInput, type LocalReplayTarget, type NavigateRecordedActionDetail, type NewTabRecordedActionDetail, OPENSTEER_FILESYSTEM_WORKSPACE_LAYOUT, OPENSTEER_FILESYSTEM_WORKSPACE_VERSION, OPENSTEER_RUNTIME_CORE_VERSION, type OpensteerArtifactStore, type OpensteerEngineFactory, type OpensteerEngineFactoryOptions, type OpensteerExtractionDescriptorPayload, type OpensteerExtractionDescriptorRecord, type OpensteerExtractionDescriptorStore, type OpensteerRuntimeOperationOptions, type OpensteerRuntimeWorkspace, type OpensteerSemanticRuntime, OpensteerSessionRuntime, type OpensteerSessionRuntimeOptions, type OpensteerWorkspaceManifest, type ProtocolArtifactDelivery, type RawFlowRecorderClickEvent, type RawFlowRecorderDblclickEvent, type RawFlowRecorderEvent, type RawFlowRecorderGoBackEvent, type RawFlowRecorderGoForwardEvent, type RawFlowRecorderKeypressEvent, type RawFlowRecorderNavigateEvent, type RawFlowRecorderReloadEvent, type RawFlowRecorderScrollEvent, type RawFlowRecorderSelectOptionEvent, type RawFlowRecorderTypeEvent, type RecipeRecord, type RecipeRegistryStore, type RecordedAction, type RecordedActionDetail, type RecordedActionKind, type RecorderInitialPageState, type RecorderPageState, type RecorderRuntimeAdapter, type RecordingOptions, type RegistryProvenance, type ReloadRecordedActionDetail, type ReplayTarget, type RequestPlanFreshness, type RequestPlanRecord, type RequestPlanRegistryStore, type ResolveRegistryRecordInput, type ReverseCaseRecord, type ReverseCaseRegistryStore, type ReversePackageRecord, type ReversePackageRegistryStore, type ReverseReportRecord, type ReverseReportRegistryStore, type ScrollRecordedActionDetail, type SelectOptionRecordedActionDetail, type StoredArtifactPayload, type StoredArtifactRecord, type StructuredArtifactKind, type SwitchTabRecordedActionDetail, type TypeRecordedActionDetail, type UpdateRequestPlanFreshnessInput, type UpdateReverseCaseInput, type WriteAuthRecipeInput, type WriteBinaryArtifactInput, type WriteDescriptorInput, type WriteInteractionTraceInput, type WriteRecipeInput, type WriteRequestPlanInput, type WriteReverseCaseInput, type WriteReversePackageInput, type WriteReverseReportInput, type WriteStructuredArtifactInput, buildDomDescriptorKey, buildDomDescriptorPayload, buildDomDescriptorVersion, createArtifactStore, createDomDescriptorStore, createFilesystemOpensteerWorkspace, createFlowRecorderInstallScript, createObservationStore, createOpensteerExtractionDescriptorStore, dispatchSemanticOperation, generateReplayScript, hashDomDescriptorDescription, manifestToExternalBinaryLocation, normalizeObservabilityConfig, normalizeWorkspaceId, parseDomDescriptorRecord, parseExtractionDescriptorRecord, resolveFilesystemWorkspacePath, sanitizeReplayElementPath };