@devicerail/protocol 0.1.0

package/dist/generated/v1/rpc-server-message.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type RpcServerMessage = RpcResponseSchema | RpcServerNotification;
+export type RpcResponseSchema = RpcSuccessSchema | RpcFailureSchema;
+export type RpcIdSchema = string | number;
+export type JsonRpcVersion = "2.0";
+export type NullableRpcIdSchema = RpcIdSchema | null;
+export type RpcServerNotification = EventsStreamEventNotification | EventsStreamTerminalNotification;
+export type EventsStreamEventMethod = "events.stream.event";
+/**
+ * A one-based sequence number within one session.
+ *
+ * The wire value is capped at JavaScript's maximum safe integer so generated
+ * clients can sort and resume event streams without losing precision.
+ */
+export type EventSequence = number;
+/**
+ * Identifies one daemon process lifetime. A cursor from another epoch must
+ * never be accepted as a resumable position.
+ */
+export type EventStreamEpoch = string;
+export type TestEventPayload = {
+    type: "sessionStarted";
+} | {
+    outcome: SessionOutcome;
+    reason?: string | null;
+    type: "sessionEnded";
+} | {
+    observation: Observation;
+    type: "observationCaptured";
+} | {
+    call: RecordedActionCall;
+    type: "actionStarted";
+} | {
+    callId: string;
+    outcome: ActionOutcome;
+    type: "actionCompleted";
+} | {
+    stream: MediaStreamInfo;
+    type: "mediaStreamStarted";
+} | {
+    frame: MediaFrame;
+    type: "mediaFrameCaptured";
+} | {
+    frameCount: number;
+    streamId: string;
+    type: "mediaStreamEnded";
+} | {
+    type: "verdictRecorded";
+    verdict: Verdict;
+} | {
+    error: ErrorInfo;
+    type: "error";
+};
+export type SessionOutcome = "completed" | "failed" | "cancelled" | "shutdown";
+export type ScreenshotOmissionReason = "policy" | "protectedAction";
+export type UiContextKind = "native" | "web";
+export type UiSnapshotOmissionReason = "driverUnsupported" | "policy" | "protectedAction";
+/**
+ * The terminal outcome for one action call.
+ *
+ * Keeping the four outcomes structurally distinct prevents clients from
+ * having to infer timeout or cancellation from human-readable error text.
+ */
+export type ActionOutcome = {
+    outcome: "succeeded";
+    result: ActionResult;
+} | {
+    error: ErrorInfo;
+    outcome: "failed";
+} | {
+    error: ErrorInfo;
+    outcome: "cancelled";
+} | {
+    error: ErrorInfo;
+    outcome: "timedOut";
+    timeoutMs: number;
+};
+export type ActionExecution = {
+    context: UiContextRef;
+    mode: "nativeSemantic";
+} | {
+    context: UiContextRef;
+    mode: "webSemantic";
+} | {
+    context: UiContextRef;
+    fallbackReason: CoordinateFallbackReason;
+    mode: "coordinateFallback";
+};
+export type CoordinateFallbackReason = "semanticInteractionUnavailable" | "platformLimitation";
+export type MediaStreamKind = "screenshot" | "video";
+export type VerdictStatus = "pass" | "fail" | "unknown";
+export type EventsStreamTerminalMethod = "events.stream.terminal";
+/**
+ * The terminal reason is a closed tagged union so reason/error combinations
+ * cannot become ambiguous on the wire.
+ */
+export type EventsStreamTermination = {
+    reason: "sessionEnded";
+} | {
+    reason: "cancelled";
+} | {
+    error: ErrorInfo;
+    reason: "slowConsumer";
+} | {
+    error: ErrorInfo;
+    reason: "sessionDeleted";
+} | {
+    error: ErrorInfo;
+    reason: "serverShutdown";
+} | {
+    error: ErrorInfo;
+    reason: "sequenceGap";
+} | {
+    error: ErrorInfo;
+    reason: "eventTooLarge";
+} | {
+    error: ErrorInfo;
+    reason: "internalError";
+};
+export interface RpcSuccessSchema {
+    id: RpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+    result: unknown;
+}
+export interface RpcFailureSchema {
+    error: RpcError;
+    id: NullableRpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+}
+export interface RpcError {
+    code: number;
+    data: ErrorInfo;
+    message: string;
+}
+export interface ErrorInfo {
+    code: string;
+    details?: unknown;
+    message: string;
+    retryable: boolean;
+}
+export interface EventsStreamEventNotification {
+    jsonrpc: JsonRpcVersion;
+    method: EventsStreamEventMethod;
+    params: EventsStreamEventParams;
+}
+export interface EventsStreamEventParams {
+    cursor: EventStreamCursor;
+    event: TestEvent;
+    subscriptionId: string;
+}
+/**
+ * A Session-scoped, daemon-epoch-scoped application acknowledgement.
+ */
+export interface EventStreamCursor {
+    sequence: EventSequence;
+    sessionId: string;
+    streamEpoch: EventStreamEpoch;
+}
+export interface TestEvent {
+    atMs: number;
+    deviceId?: string | null;
+    eventId: string;
+    payload: TestEventPayload;
+    requestId?: RpcIdSchema | null;
+    sequence: EventSequence;
+    sessionId: string;
+}
+export interface Observation {
+    capturedAtMs: number;
+    deviceId: string;
+    id: string;
+    metadata?: {
+        [k: string]: unknown;
+    };
+    screenshot?: AssetRef | null;
+    screenshotOmission?: ScreenshotOmissionReason | null;
+    uiSnapshot?: UiSnapshotRef | null;
+    uiSnapshotOmission?: UiSnapshotOmissionReason | null;
+    viewport: Viewport;
+    [k: string]: unknown;
+}
+export interface AssetRef {
+    id: string;
+    mediaType: string;
+    sha256?: string | null;
+    uri: string;
+    [k: string]: unknown;
+}
+/**
+ * Small Observation-side reference to a UI Tree Evidence object.
+ */
+export interface UiSnapshotRef {
+    byteLength: number;
+    context: UiContextRef;
+    evidence: AssetRef;
+    formatVersion: number;
+    nodeCount: number;
+}
+/**
+ * Full identity of one native accessibility or web-document context.
+ * `documentEpoch` is required for both channels and changes after reconnect,
+ * navigation, or any replacement that invalidates prior node references.
+ */
+export interface UiContextRef {
+    contextId: string;
+    contextKind: UiContextKind;
+    documentEpoch: string;
+}
+export interface Viewport {
+    height: number;
+    scaleFactor: number;
+    width: number;
+    [k: string]: unknown;
+}
+/**
+ * Durable representation of an Action invocation.
+ *
+ * Standard calls preserve the historical wire shape. Protected and unknown
+ * calls retain only correlation fields and serialize `arguments` as `null`
+ * with an explicit `argumentsRedacted` marker.
+ */
+export interface RecordedActionCall {
+    arguments?: unknown;
+    argumentsRedacted?: boolean;
+    id: string;
+    name: string;
+    [k: string]: unknown;
+}
+export interface ActionResult {
+    after?: Observation | null;
+    before?: Observation | null;
+    callId: string;
+    evidence?: AssetRef[];
+    execution?: ActionExecution | null;
+    finishedAtMs: number;
+    output: unknown;
+    startedAtMs: number;
+    [k: string]: unknown;
+}
+export interface MediaStreamInfo {
+    id: string;
+    kind: MediaStreamKind;
+    mediaType: string;
+    viewport?: Viewport | null;
+}
+export interface MediaFrame {
+    durationMs?: number | null;
+    evidence: AssetRef;
+    frameIndex: EventSequence;
+    keyFrame?: boolean;
+    streamId: string;
+}
+export interface Verdict {
+    /**
+     * @maxItems 64
+     */
+    evidence?: AssetRef[];
+    status: VerdictStatus;
+    summary: string;
+}
+export interface EventsStreamTerminalNotification {
+    jsonrpc: JsonRpcVersion;
+    method: EventsStreamTerminalMethod;
+    params: EventsStreamTerminalParams;
+}
+export interface EventsStreamTerminalParams {
+    lastEmittedCursor?: EventStreamCursor | null;
+    sessionId: string;
+    subscriptionId: string;
+    termination: EventsStreamTermination;
+}

package/dist/generated/v1/rpc-server-notification.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type RpcServerNotification = EventsStreamEventNotification | EventsStreamTerminalNotification;
+export type JsonRpcVersion = "2.0";
+export type EventsStreamEventMethod = "events.stream.event";
+/**
+ * A one-based sequence number within one session.
+ *
+ * The wire value is capped at JavaScript's maximum safe integer so generated
+ * clients can sort and resume event streams without losing precision.
+ */
+export type EventSequence = number;
+/**
+ * Identifies one daemon process lifetime. A cursor from another epoch must
+ * never be accepted as a resumable position.
+ */
+export type EventStreamEpoch = string;
+export type TestEventPayload = {
+    type: "sessionStarted";
+} | {
+    outcome: SessionOutcome;
+    reason?: string | null;
+    type: "sessionEnded";
+} | {
+    observation: Observation;
+    type: "observationCaptured";
+} | {
+    call: RecordedActionCall;
+    type: "actionStarted";
+} | {
+    callId: string;
+    outcome: ActionOutcome;
+    type: "actionCompleted";
+} | {
+    stream: MediaStreamInfo;
+    type: "mediaStreamStarted";
+} | {
+    frame: MediaFrame;
+    type: "mediaFrameCaptured";
+} | {
+    frameCount: number;
+    streamId: string;
+    type: "mediaStreamEnded";
+} | {
+    type: "verdictRecorded";
+    verdict: Verdict;
+} | {
+    error: ErrorInfo;
+    type: "error";
+};
+export type SessionOutcome = "completed" | "failed" | "cancelled" | "shutdown";
+export type ScreenshotOmissionReason = "policy" | "protectedAction";
+export type UiContextKind = "native" | "web";
+export type UiSnapshotOmissionReason = "driverUnsupported" | "policy" | "protectedAction";
+/**
+ * The terminal outcome for one action call.
+ *
+ * Keeping the four outcomes structurally distinct prevents clients from
+ * having to infer timeout or cancellation from human-readable error text.
+ */
+export type ActionOutcome = {
+    outcome: "succeeded";
+    result: ActionResult;
+} | {
+    error: ErrorInfo;
+    outcome: "failed";
+} | {
+    error: ErrorInfo;
+    outcome: "cancelled";
+} | {
+    error: ErrorInfo;
+    outcome: "timedOut";
+    timeoutMs: number;
+};
+export type ActionExecution = {
+    context: UiContextRef;
+    mode: "nativeSemantic";
+} | {
+    context: UiContextRef;
+    mode: "webSemantic";
+} | {
+    context: UiContextRef;
+    fallbackReason: CoordinateFallbackReason;
+    mode: "coordinateFallback";
+};
+export type CoordinateFallbackReason = "semanticInteractionUnavailable" | "platformLimitation";
+export type MediaStreamKind = "screenshot" | "video";
+export type VerdictStatus = "pass" | "fail" | "unknown";
+export type RpcIdSchema = string | number;
+export type EventsStreamTerminalMethod = "events.stream.terminal";
+/**
+ * The terminal reason is a closed tagged union so reason/error combinations
+ * cannot become ambiguous on the wire.
+ */
+export type EventsStreamTermination = {
+    reason: "sessionEnded";
+} | {
+    reason: "cancelled";
+} | {
+    error: ErrorInfo;
+    reason: "slowConsumer";
+} | {
+    error: ErrorInfo;
+    reason: "sessionDeleted";
+} | {
+    error: ErrorInfo;
+    reason: "serverShutdown";
+} | {
+    error: ErrorInfo;
+    reason: "sequenceGap";
+} | {
+    error: ErrorInfo;
+    reason: "eventTooLarge";
+} | {
+    error: ErrorInfo;
+    reason: "internalError";
+};
+export interface EventsStreamEventNotification {
+    jsonrpc: JsonRpcVersion;
+    method: EventsStreamEventMethod;
+    params: EventsStreamEventParams;
+}
+export interface EventsStreamEventParams {
+    cursor: EventStreamCursor;
+    event: TestEvent;
+    subscriptionId: string;
+}
+/**
+ * A Session-scoped, daemon-epoch-scoped application acknowledgement.
+ */
+export interface EventStreamCursor {
+    sequence: EventSequence;
+    sessionId: string;
+    streamEpoch: EventStreamEpoch;
+}
+export interface TestEvent {
+    atMs: number;
+    deviceId?: string | null;
+    eventId: string;
+    payload: TestEventPayload;
+    requestId?: RpcIdSchema | null;
+    sequence: EventSequence;
+    sessionId: string;
+}
+export interface Observation {
+    capturedAtMs: number;
+    deviceId: string;
+    id: string;
+    metadata?: {
+        [k: string]: unknown;
+    };
+    screenshot?: AssetRef | null;
+    screenshotOmission?: ScreenshotOmissionReason | null;
+    uiSnapshot?: UiSnapshotRef | null;
+    uiSnapshotOmission?: UiSnapshotOmissionReason | null;
+    viewport: Viewport;
+    [k: string]: unknown;
+}
+export interface AssetRef {
+    id: string;
+    mediaType: string;
+    sha256?: string | null;
+    uri: string;
+    [k: string]: unknown;
+}
+/**
+ * Small Observation-side reference to a UI Tree Evidence object.
+ */
+export interface UiSnapshotRef {
+    byteLength: number;
+    context: UiContextRef;
+    evidence: AssetRef;
+    formatVersion: number;
+    nodeCount: number;
+}
+/**
+ * Full identity of one native accessibility or web-document context.
+ * `documentEpoch` is required for both channels and changes after reconnect,
+ * navigation, or any replacement that invalidates prior node references.
+ */
+export interface UiContextRef {
+    contextId: string;
+    contextKind: UiContextKind;
+    documentEpoch: string;
+}
+export interface Viewport {
+    height: number;
+    scaleFactor: number;
+    width: number;
+    [k: string]: unknown;
+}
+/**
+ * Durable representation of an Action invocation.
+ *
+ * Standard calls preserve the historical wire shape. Protected and unknown
+ * calls retain only correlation fields and serialize `arguments` as `null`
+ * with an explicit `argumentsRedacted` marker.
+ */
+export interface RecordedActionCall {
+    arguments?: unknown;
+    argumentsRedacted?: boolean;
+    id: string;
+    name: string;
+    [k: string]: unknown;
+}
+export interface ActionResult {
+    after?: Observation | null;
+    before?: Observation | null;
+    callId: string;
+    evidence?: AssetRef[];
+    execution?: ActionExecution | null;
+    finishedAtMs: number;
+    output: unknown;
+    startedAtMs: number;
+    [k: string]: unknown;
+}
+export interface ErrorInfo {
+    code: string;
+    details?: unknown;
+    message: string;
+    retryable: boolean;
+}
+export interface MediaStreamInfo {
+    id: string;
+    kind: MediaStreamKind;
+    mediaType: string;
+    viewport?: Viewport | null;
+}
+export interface MediaFrame {
+    durationMs?: number | null;
+    evidence: AssetRef;
+    frameIndex: EventSequence;
+    keyFrame?: boolean;
+    streamId: string;
+}
+export interface Verdict {
+    /**
+     * @maxItems 64
+     */
+    evidence?: AssetRef[];
+    status: VerdictStatus;
+    summary: string;
+}
+export interface EventsStreamTerminalNotification {
+    jsonrpc: JsonRpcVersion;
+    method: EventsStreamTerminalMethod;
+    params: EventsStreamTerminalParams;
+}
+export interface EventsStreamTerminalParams {
+    lastEmittedCursor?: EventStreamCursor | null;
+    sessionId: string;
+    subscriptionId: string;
+    termination: EventsStreamTermination;
+}

package/dist/generated/v1/screenshot-omission-reason.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type ScreenshotOmissionReason = "policy" | "protectedAction";

package/dist/generated/v1/session-current-request.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type RpcIdSchema = string | number;
+export type JsonRpcVersion = "2.0";
+export type SessionCurrentMethodSchema = "session.current";
+export type NoParamsSchema = EmptyParamsObjectSchema | [];
+export interface SessionCurrentRequest {
+    id: RpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+    method: SessionCurrentMethodSchema;
+    params?: NoParamsSchema;
+}
+export type EmptyParamsObjectSchema = Record<string, never>;

package/dist/generated/v1/session-current-response.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type SessionCurrentResponse = SessionCurrentSuccessSchema | SystemHelloFailureSchema;
+export type RpcIdSchema = string | number;
+export type JsonRpcVersion = "2.0";
+export type NullableRpcIdSchema = RpcIdSchema | null;
+export interface SessionCurrentSuccessSchema {
+    id: RpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+    result: SessionCurrentResult;
+}
+/**
+ * Result returned by `session.current`.
+ */
+export interface SessionCurrentResult {
+    sessionId: string;
+}
+export interface SystemHelloFailureSchema {
+    error: RpcError;
+    id: NullableRpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+}
+export interface RpcError {
+    code: number;
+    data: ErrorInfo;
+    message: string;
+}
+export interface ErrorInfo {
+    code: string;
+    details?: unknown;
+    message: string;
+    retryable: boolean;
+}

package/dist/generated/v1/session-current-result.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+/**
+ * Result returned by `session.current`.
+ */
+export interface SessionCurrentResult {
+    sessionId: string;
+}

package/dist/generated/v1/session-end-params.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type SessionOutcome = "completed" | "failed" | "cancelled" | "shutdown";
+/**
+ * Optional parameters accepted by `session.end`.
+ */
+export interface SessionEndParams {
+    outcome?: SessionOutcome | null;
+    reason?: string | null;
+}

package/dist/generated/v1/session-end-request.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type RpcIdSchema = string | number;
+export type JsonRpcVersion = "2.0";
+export type SessionEndMethodSchema = "session.end";
+export type SessionOutcome = "completed" | "failed" | "cancelled" | "shutdown";
+export interface SessionEndRequest {
+    id: RpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+    method: SessionEndMethodSchema;
+    params?: SessionEndParams;
+}
+/**
+ * Optional parameters accepted by `session.end`.
+ */
+export interface SessionEndParams {
+    outcome?: SessionOutcome | null;
+    reason?: string | null;
+}

package/dist/generated/v1/session-end-response.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+export type SessionEndResponse = SessionEndSuccessSchema | SystemHelloFailureSchema;
+export type RpcIdSchema = string | number;
+export type JsonRpcVersion = "2.0";
+/**
+ * A one-based sequence number within one session.
+ *
+ * The wire value is capped at JavaScript's maximum safe integer so generated
+ * clients can sort and resume event streams without losing precision.
+ */
+export type EventSequence = number;
+export type SessionState = "active" | "ended";
+export type NullableRpcIdSchema = RpcIdSchema | null;
+export interface SessionEndSuccessSchema {
+    id: RpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+    result: SessionInfo;
+}
+export interface SessionInfo {
+    endedAtMs?: number | null;
+    eventCount: EventSequence;
+    id: string;
+    lastSequence: EventSequence;
+    startedAtMs: number;
+    state: SessionState;
+}
+export interface SystemHelloFailureSchema {
+    error: RpcError;
+    id: NullableRpcIdSchema;
+    jsonrpc: JsonRpcVersion;
+}
+export interface RpcError {
+    code: number;
+    data: ErrorInfo;
+    message: string;
+}
+export interface ErrorInfo {
+    code: string;
+    details?: unknown;
+    message: string;
+    retryable: boolean;
+}

package/dist/generated/v1/session-end-result.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generated from the checked-in DeviceRail JSON Schema. DO NOT EDIT.
+ * Run `pnpm protocol:types:generate` from the repository root.
+ */
+/**
+ * A one-based sequence number within one session.
+ *
+ * The wire value is capped at JavaScript's maximum safe integer so generated
+ * clients can sort and resume event streams without losing precision.
+ */
+export type EventSequence = number;
+export type SessionState = "active" | "ended";
+export interface SessionEndResult {
+    endedAtMs?: number | null;
+    eventCount: EventSequence;
+    id: string;
+    lastSequence: EventSequence;
+    startedAtMs: number;
+    state: SessionState;
+}