@locusai/shared 0.11.6 → 0.11.8

package/dist/protocol/cli-stream.d.ts

@@ -0,0 +1,270 @@
+import { z } from "zod";
+/**
+ * Event types emitted by the CLI in `--json-stream` mode.
+ * Each event is a single JSON line (NDJSON) written to stdout.
+ */
+export declare const CliStreamEventType: {
+    /** Session started — first event, always emitted */
+    readonly START: "start";
+    /** Incremental AI response text */
+    readonly TEXT_DELTA: "text_delta";
+    /** AI is thinking/reasoning */
+    readonly THINKING: "thinking";
+    /** Tool invocation started */
+    readonly TOOL_STARTED: "tool_started";
+    /** Tool invocation completed (success or failure) */
+    readonly TOOL_COMPLETED: "tool_completed";
+    /** Session status change */
+    readonly STATUS: "status";
+    /** Structured error */
+    readonly ERROR: "error";
+    /** Session finished — terminal event, always emitted last */
+    readonly DONE: "done";
+};
+export type CliStreamEventType = (typeof CliStreamEventType)[keyof typeof CliStreamEventType];
+export declare const CliStreamEventTypeSchema: z.ZodEnum<{
+    /** Session started — first event, always emitted */
+    readonly START: "start";
+    /** Incremental AI response text */
+    readonly TEXT_DELTA: "text_delta";
+    /** AI is thinking/reasoning */
+    readonly THINKING: "thinking";
+    /** Tool invocation started */
+    readonly TOOL_STARTED: "tool_started";
+    /** Tool invocation completed (success or failure) */
+    readonly TOOL_COMPLETED: "tool_completed";
+    /** Session status change */
+    readonly STATUS: "status";
+    /** Structured error */
+    readonly ERROR: "error";
+    /** Session finished — terminal event, always emitted last */
+    readonly DONE: "done";
+}>;
+export declare const CliStartEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"start">;
+    payload: z.ZodObject<{
+        command: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliStartEvent = z.infer<typeof CliStartEventSchema>;
+export declare const CliTextDeltaEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"text_delta">;
+    payload: z.ZodObject<{
+        content: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliTextDeltaEvent = z.infer<typeof CliTextDeltaEventSchema>;
+export declare const CliThinkingEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"thinking">;
+    payload: z.ZodObject<{
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliThinkingEvent = z.infer<typeof CliThinkingEventSchema>;
+export declare const CliToolStartedEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"tool_started">;
+    payload: z.ZodObject<{
+        tool: z.ZodString;
+        toolId: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliToolStartedEvent = z.infer<typeof CliToolStartedEventSchema>;
+export declare const CliToolCompletedEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"tool_completed">;
+    payload: z.ZodObject<{
+        tool: z.ZodString;
+        toolId: z.ZodOptional<z.ZodString>;
+        success: z.ZodBoolean;
+        duration: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliToolCompletedEvent = z.infer<typeof CliToolCompletedEventSchema>;
+export declare const CliStatusEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"status">;
+    payload: z.ZodObject<{
+        status: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliStatusEvent = z.infer<typeof CliStatusEventSchema>;
+export declare const CliErrorEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"error">;
+    payload: z.ZodObject<{
+        error: z.ZodObject<{
+            code: z.ZodEnum<{
+                readonly CLI_NOT_FOUND: "CLI_NOT_FOUND";
+                readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+                readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+                readonly CONTEXT_LIMIT: "CONTEXT_LIMIT";
+                readonly MALFORMED_EVENT: "MALFORMED_EVENT";
+                readonly PROCESS_CRASHED: "PROCESS_CRASHED";
+                readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+                readonly UNKNOWN: "UNKNOWN";
+            }>;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+            recoverable: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliErrorEvent = z.infer<typeof CliErrorEventSchema>;
+export declare const CliDoneEventSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"done">;
+    payload: z.ZodObject<{
+        exitCode: z.ZodNumber;
+        duration: z.ZodNumber;
+        toolsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tokensUsed: z.ZodOptional<z.ZodNumber>;
+        success: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CliDoneEvent = z.infer<typeof CliDoneEventSchema>;
+export declare const CliStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"start">;
+    payload: z.ZodObject<{
+        command: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"text_delta">;
+    payload: z.ZodObject<{
+        content: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"thinking">;
+    payload: z.ZodObject<{
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"tool_started">;
+    payload: z.ZodObject<{
+        tool: z.ZodString;
+        toolId: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"tool_completed">;
+    payload: z.ZodObject<{
+        tool: z.ZodString;
+        toolId: z.ZodOptional<z.ZodString>;
+        success: z.ZodBoolean;
+        duration: z.ZodOptional<z.ZodNumber>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"status">;
+    payload: z.ZodObject<{
+        status: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"error">;
+    payload: z.ZodObject<{
+        error: z.ZodObject<{
+            code: z.ZodEnum<{
+                readonly CLI_NOT_FOUND: "CLI_NOT_FOUND";
+                readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+                readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+                readonly CONTEXT_LIMIT: "CONTEXT_LIMIT";
+                readonly MALFORMED_EVENT: "MALFORMED_EVENT";
+                readonly PROCESS_CRASHED: "PROCESS_CRASHED";
+                readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+                readonly UNKNOWN: "UNKNOWN";
+            }>;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodUnknown>;
+            recoverable: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    timestamp: z.ZodNumber;
+    type: z.ZodLiteral<"done">;
+    payload: z.ZodObject<{
+        exitCode: z.ZodNumber;
+        duration: z.ZodNumber;
+        toolsUsed: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tokensUsed: z.ZodOptional<z.ZodNumber>;
+        success: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+export type CliStreamEvent = z.infer<typeof CliStreamEventSchema>;
+type CliStreamPayloadMap = {
+    [CliStreamEventType.START]: CliStartEvent["payload"];
+    [CliStreamEventType.TEXT_DELTA]: CliTextDeltaEvent["payload"];
+    [CliStreamEventType.THINKING]: CliThinkingEvent["payload"];
+    [CliStreamEventType.TOOL_STARTED]: CliToolStartedEvent["payload"];
+    [CliStreamEventType.TOOL_COMPLETED]: CliToolCompletedEvent["payload"];
+    [CliStreamEventType.STATUS]: CliStatusEvent["payload"];
+    [CliStreamEventType.ERROR]: CliErrorEvent["payload"];
+    [CliStreamEventType.DONE]: CliDoneEvent["payload"];
+};
+/**
+ * Create a validated CLI stream event.
+ * Validates the payload against the Zod schema before returning.
+ */
+export declare function createCliStreamEvent<T extends CliStreamEventType>(type: T, sessionId: string, payload: CliStreamPayloadMap[T]): CliStreamEvent;
+/**
+ * Parse and validate an unknown value as a CliStreamEvent.
+ * Returns `{ success: true, data }` or `{ success: false, error }`.
+ */
+export declare function parseCliStreamEvent(value: unknown): {
+    success: boolean;
+    data?: CliStreamEvent;
+    error?: unknown;
+};
+export {};
+//# sourceMappingURL=cli-stream.d.ts.map

package/dist/protocol/cli-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-stream.d.ts","sourceRoot":"","sources":["../../src/protocol/cli-stream.ts"],"names":[],"mappings":"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"}

package/dist/protocol/context.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+/**
+ * Active file context — path and optional language identifier.
+ */
+export declare const ActiveFileContextSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    languageId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ActiveFileContext = z.infer<typeof ActiveFileContextSchema>;
+/**
+ * Text selection within a file.
+ */
+export declare const SelectionContextSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    languageId: z.ZodOptional<z.ZodString>;
+    startLine: z.ZodNumber;
+    startColumn: z.ZodNumber;
+    endLine: z.ZodNumber;
+    endColumn: z.ZodNumber;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type SelectionContext = z.infer<typeof SelectionContextSchema>;
+/**
+ * Workspace context — root path of the current workspace.
+ */
+export declare const WorkspaceContextSchema: z.ZodObject<{
+    rootPath: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkspaceContext = z.infer<typeof WorkspaceContextSchema>;
+/**
+ * Composite context payload attached to prompt submissions.
+ * All fields are optional since context availability varies by command.
+ */
+export declare const ContextPayloadSchema: z.ZodObject<{
+    workspace: z.ZodOptional<z.ZodObject<{
+        rootPath: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    activeFile: z.ZodOptional<z.ZodObject<{
+        filePath: z.ZodString;
+        languageId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    selection: z.ZodOptional<z.ZodObject<{
+        filePath: z.ZodString;
+        languageId: z.ZodOptional<z.ZodString>;
+        startLine: z.ZodNumber;
+        startColumn: z.ZodNumber;
+        endLine: z.ZodNumber;
+        endColumn: z.ZodNumber;
+        text: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ContextPayload = z.infer<typeof ContextPayloadSchema>;
+//# sourceMappingURL=context.d.ts.map

package/dist/protocol/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/protocol/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;iBAQjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;iBAI/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/protocol/envelope.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/** Current protocol version. Increment on breaking changes. */
+export declare const PROTOCOL_VERSION: 1;
+export declare const ProtocolVersionSchema: z.ZodLiteral<1>;
+/**
+ * Base envelope wrapping all host↔webview messages.
+ * Every message includes `protocol` for forward compatibility.
+ */
+export declare const ProtocolEnvelopeSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<1>;
+    type: z.ZodString;
+}, z.core.$strip>;
+export type ProtocolEnvelope = z.infer<typeof ProtocolEnvelopeSchema>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/protocol/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/protocol/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAG,CAAU,CAAC;AAE3C,eAAO,MAAM,qBAAqB,iBAA8B,CAAC;AAMjE;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/protocol/errors.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const ProtocolErrorCode: {
+    readonly CLI_NOT_FOUND: "CLI_NOT_FOUND";
+    readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+    readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+    readonly CONTEXT_LIMIT: "CONTEXT_LIMIT";
+    readonly MALFORMED_EVENT: "MALFORMED_EVENT";
+    readonly PROCESS_CRASHED: "PROCESS_CRASHED";
+    readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type ProtocolErrorCode = (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
+export declare const ProtocolErrorCodeSchema: z.ZodEnum<{
+    readonly CLI_NOT_FOUND: "CLI_NOT_FOUND";
+    readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+    readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+    readonly CONTEXT_LIMIT: "CONTEXT_LIMIT";
+    readonly MALFORMED_EVENT: "MALFORMED_EVENT";
+    readonly PROCESS_CRASHED: "PROCESS_CRASHED";
+    readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+    readonly UNKNOWN: "UNKNOWN";
+}>;
+/**
+ * Structured error payload for protocol error events.
+ * Mirrors the pattern from common.ts ErrorResponseSchema but scoped
+ * to host↔webview protocol.
+ */
+export declare const ProtocolErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        readonly CLI_NOT_FOUND: "CLI_NOT_FOUND";
+        readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+        readonly NETWORK_TIMEOUT: "NETWORK_TIMEOUT";
+        readonly CONTEXT_LIMIT: "CONTEXT_LIMIT";
+        readonly MALFORMED_EVENT: "MALFORMED_EVENT";
+        readonly PROCESS_CRASHED: "PROCESS_CRASHED";
+        readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+        readonly UNKNOWN: "UNKNOWN";
+    }>;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodUnknown>;
+    recoverable: z.ZodBoolean;
+}, z.core.$strip>;
+export type ProtocolError = z.infer<typeof ProtocolErrorSchema>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/protocol/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/protocol/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,iBAAiB;;;;;;;;;CASpB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE7D,eAAO,MAAM,uBAAuB;;;;;;;;;EAA4B,CAAC;AAMjE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAK9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/protocol/helpers.d.ts

@@ -0,0 +1,58 @@
+import { type ProtocolError, ProtocolErrorCode } from "./errors";
+import { type ErrorEvent, type HostEvent, HostEventType } from "./host-events";
+import { type SessionStatus, type SessionTransitionEvent } from "./session";
+import { type UIIntent, UIIntentType } from "./ui-intents";
+type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: unknown;
+};
+/**
+ * Parse and validate an unknown message as a UIIntent.
+ * Returns `{ success: true, data }` or `{ success: false, error }`.
+ */
+export declare function parseUIIntent(message: unknown): SafeParseResult<UIIntent>;
+/**
+ * Parse and validate an unknown message as a HostEvent.
+ * Returns `{ success: true, data }` or `{ success: false, error }`.
+ */
+export declare function parseHostEvent(message: unknown): SafeParseResult<HostEvent>;
+/** Check if a validated UIIntent is a specific type. */
+export declare function isUIIntentType<T extends UIIntentType>(intent: UIIntent, type: T): intent is Extract<UIIntent, {
+    type: T;
+}>;
+/** Check if a validated HostEvent is a specific type. */
+export declare function isHostEventType<T extends HostEventType>(event: HostEvent, type: T): event is Extract<HostEvent, {
+    type: T;
+}>;
+/**
+ * Check if a transition is valid according to the session state machine.
+ */
+export declare function isValidTransition(from: SessionStatus, event: SessionTransitionEvent): boolean;
+/**
+ * Get the target state for a transition, or `null` if invalid.
+ */
+export declare function getNextStatus(from: SessionStatus, event: SessionTransitionEvent): SessionStatus | null;
+/**
+ * Check if a session status is a terminal state.
+ */
+export declare function isTerminalStatus(status: SessionStatus): boolean;
+/**
+ * Create a structured protocol error.
+ */
+export declare function createProtocolError(code: ProtocolErrorCode, message: string, options?: {
+    details?: unknown;
+    recoverable?: boolean;
+}): ProtocolError;
+/**
+ * Create a host error event from an error code and message.
+ */
+export declare function createErrorEvent(code: ProtocolErrorCode, message: string, options?: {
+    sessionId?: string;
+    details?: unknown;
+    recoverable?: boolean;
+}): ErrorEvent;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/protocol/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/protocol/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EAEd,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,QAAQ,EAAkB,YAAY,EAAE,MAAM,cAAc,CAAC;AAM3E,KAAK,eAAe,CAAC,CAAC,IAClB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAC1B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAMvC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC,QAAQ,CAAC,CAEzE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC,SAAS,CAAC,CAE3E;AAMD,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,CAAC,SAAS,YAAY,EACnD,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,CAAC,GACN,MAAM,IAAI,OAAO,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAE1C;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,CAAC,SAAS,aAAa,EACrD,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,CAAC,GACN,KAAK,IAAI,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAE1C;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,sBAAsB,GAC5B,aAAa,GAAG,IAAI,CAKtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAE/D;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GACrD,aAAa,CAOf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACA,UAAU,CAYZ"}