@wjarka/cezarion 0.15.1 → 0.16.0

package/dist/contract/preview.d.ts

@@ -0,0 +1,508 @@
+import { z } from 'zod';
+/**
+ * Live preview v1 (#781, spec 2026-10-02-live-preview-v1): the agent tool's request and result, the
+ * run-record entry a registration leaves behind, and both directions of the preview WebSocket.
+ * Everything here is Node-free; the server and the cockpit read the same definitions.
+ */
+/** `cezar_preview_serve` input. `cwd` is relative to the worktree root; the server enforces that. */
+export declare const previewServeRequestSchema: z.ZodObject<{
+    command: z.ZodString;
+    port: z.ZodNumber;
+    cwd: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PreviewServeRequest = z.infer<typeof previewServeRequestSchema>;
+export declare const previewResultCodeSchema: z.ZodEnum<{
+    cezar_port: "cezar_port";
+    cwd_outside_worktree: "cwd_outside_worktree";
+    headless: "headless";
+    invalid_input: "invalid_input";
+    port_held: "port_held";
+    preview_disabled: "preview_disabled";
+    registered: "registered";
+    replaced: "replaced";
+    too_many: "too_many";
+    unavailable: "unavailable";
+    worktree_missing: "worktree_missing";
+}>;
+export type PreviewResultCode = z.infer<typeof previewResultCodeSchema>;
+/** Every result carries a recovery hint: what the agent does next, in one step. */
+export declare const previewServeResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    code: z.ZodEnum<{
+        cezar_port: "cezar_port";
+        cwd_outside_worktree: "cwd_outside_worktree";
+        headless: "headless";
+        invalid_input: "invalid_input";
+        port_held: "port_held";
+        preview_disabled: "preview_disabled";
+        registered: "registered";
+        replaced: "replaced";
+        too_many: "too_many";
+        unavailable: "unavailable";
+        worktree_missing: "worktree_missing";
+    }>;
+    message: z.ZodString;
+    hint: z.ZodString;
+}, z.core.$strip>;
+export type PreviewServeResult = z.infer<typeof previewServeResultSchema>;
+/** Agent control carries no run identity or command: both come from its capability and approval. */
+export declare const previewStopRequestSchema: z.ZodObject<{
+    port: z.ZodNumber;
+    restart: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PreviewStopRequest = z.infer<typeof previewStopRequestSchema>;
+export declare const previewStopResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    code: z.ZodEnum<{
+        adopted: "adopted";
+        approval_required: "approval_required";
+        headless: "headless";
+        invalid_input: "invalid_input";
+        not_registered: "not_registered";
+        port_held: "port_held";
+        port_in_use: "port_in_use";
+        preview_disabled: "preview_disabled";
+        restarted: "restarted";
+        stopped: "stopped";
+        unavailable: "unavailable";
+        worktree_missing: "worktree_missing";
+    }>;
+    message: z.ZodString;
+    hint: z.ZodString;
+}, z.core.$strip>;
+export type PreviewStopResult = z.infer<typeof previewStopResultSchema>;
+/**
+ * One registered dev server, as the run record keeps it. `answeredAtRegistration` is a single TCP
+ * probe at registration: a historical observation, never a promise that Open runs nothing.
+ */
+export declare const previewServerSchema: z.ZodObject<{
+    port: z.ZodNumber;
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    label: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    registeredAt: z.ZodISODateTime;
+    answeredAtRegistration: z.ZodBoolean;
+}, z.core.$strip>;
+export type PreviewServer = z.infer<typeof previewServerSchema>;
+/** The states a registration reports on the `preview.server-state` run event and on its card. */
+export declare const previewServerStateSchema: z.ZodEnum<{
+    adopted: "adopted";
+    exited: "exited";
+    registered: "registered";
+    stalled: "stalled";
+    starting: "starting";
+    stopped: "stopped";
+    unavailable: "unavailable";
+    up: "up";
+}>;
+export type PreviewServerState = z.infer<typeof previewServerStateSchema>;
+/** Mouse and key vocabularies are the prototype's: CDP's own names, nothing else gets through. */
+export declare const previewMouseTypeSchema: z.ZodEnum<{
+    mouseMoved: "mouseMoved";
+    mousePressed: "mousePressed";
+    mouseReleased: "mouseReleased";
+    mouseWheel: "mouseWheel";
+}>;
+export declare const previewMouseButtonSchema: z.ZodEnum<{
+    left: "left";
+    middle: "middle";
+    none: "none";
+    right: "right";
+}>;
+export declare const previewKeyTypeSchema: z.ZodEnum<{
+    keyDown: "keyDown";
+    keyUp: "keyUp";
+    rawKeyDown: "rawKeyDown";
+}>;
+/** Client to server. A whitelist: a message outside it is dropped and logged once per connection. */
+export declare const previewClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"open">;
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        port: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>]>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"run">;
+    port: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"stop">;
+    port: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"keepWaiting">;
+    port: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"resize">;
+    w: z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>;
+    h: z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"mouse">;
+    type: z.ZodEnum<{
+        mouseMoved: "mouseMoved";
+        mousePressed: "mousePressed";
+        mouseReleased: "mouseReleased";
+        mouseWheel: "mouseWheel";
+    }>;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    button: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        middle: "middle";
+        none: "none";
+        right: "right";
+    }>>;
+    buttons: z.ZodOptional<z.ZodNumber>;
+    clickCount: z.ZodOptional<z.ZodNumber>;
+    deltaX: z.ZodOptional<z.ZodNumber>;
+    deltaY: z.ZodOptional<z.ZodNumber>;
+    modifiers: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"key">;
+    type: z.ZodEnum<{
+        keyDown: "keyDown";
+        keyUp: "keyUp";
+        rawKeyDown: "rawKeyDown";
+    }>;
+    key: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    modifiers: z.ZodOptional<z.ZodNumber>;
+    vk: z.ZodOptional<z.ZodNumber>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"insertText">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"nav">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"back">;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"forward">;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"reload">;
+    ignoreCache: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"dialogResult">;
+    accept: z.ZodBoolean;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"ack">;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"ping">;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"download">;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"cancelDownload">;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"retryBrowser">;
+}, z.core.$strip>], "t">;
+export type PreviewClientMessage = z.infer<typeof previewClientMessageSchema>;
+/**
+ * The pane's server-driven states (design 5.1 to 5.10, 5.15 to 5.18). Connection lost (5.11), taken
+ * over (5.12) and proxy blocked (5.14) are client transport states, not server stages.
+ */
+export declare const previewStateMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"chromium-missing">;
+    installCommand: z.ZodString;
+    canDownload: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"downloading">;
+    received: z.ZodNumber;
+    total: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"download-failed">;
+    error: z.ZodString;
+    installCommand: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"sandbox-failed">;
+    stderrTail: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"browser-exited">;
+    signal: z.ZodOptional<z.ZodString>;
+    stderrTail: z.ZodString;
+    serverUp: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"needs-approval">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    wasRunning: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"port-held">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    ownerTitle: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-starting">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    attempt: z.ZodNumber;
+    startedAt: z.ZodISODateTime;
+    logTail: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-stalled">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    logTail: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-exited">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    logTail: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-stopped">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    reason: z.ZodEnum<{
+        idle: "idle";
+        user: "user";
+    }>;
+    lastUrl: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"worktree-removed">;
+    server: z.ZodOptional<z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"loading">;
+    step: z.ZodEnum<{
+        browser: "browser";
+        frame: "frame";
+        page: "page";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"streaming">;
+    adopted: z.ZodBoolean;
+}, z.core.$strip>], "stage">;
+/** Server to client JSON messages. JPEG frames travel as binary and have no schema here. */
+export declare const previewServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"chromium-missing">;
+    installCommand: z.ZodString;
+    canDownload: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"downloading">;
+    received: z.ZodNumber;
+    total: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"download-failed">;
+    error: z.ZodString;
+    installCommand: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"sandbox-failed">;
+    stderrTail: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"browser-exited">;
+    signal: z.ZodOptional<z.ZodString>;
+    stderrTail: z.ZodString;
+    serverUp: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"needs-approval">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    wasRunning: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"port-held">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    ownerTitle: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-starting">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    attempt: z.ZodNumber;
+    startedAt: z.ZodISODateTime;
+    logTail: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-stalled">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    logTail: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-exited">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    logTail: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"server-stopped">;
+    server: z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>;
+    reason: z.ZodEnum<{
+        idle: "idle";
+        user: "user";
+    }>;
+    lastUrl: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"worktree-removed">;
+    server: z.ZodOptional<z.ZodObject<{
+        port: z.ZodNumber;
+        command: z.ZodString;
+        cwd: z.ZodOptional<z.ZodString>;
+        label: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        registeredAt: z.ZodISODateTime;
+        answeredAtRegistration: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"loading">;
+    step: z.ZodEnum<{
+        browser: "browser";
+        frame: "frame";
+        page: "page";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"state">;
+    stage: z.ZodLiteral<"streaming">;
+    adopted: z.ZodBoolean;
+}, z.core.$strip>], "stage">, z.ZodObject<{
+    t: z.ZodLiteral<"url">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"cursor">;
+    cursor: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"dialog">;
+    type: z.ZodEnum<{
+        alert: "alert";
+        beforeunload: "beforeunload";
+        confirm: "confirm";
+        prompt: "prompt";
+    }>;
+    message: z.ZodString;
+    defaultPrompt: z.ZodOptional<z.ZodString>;
+    origin: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"replaced">;
+    by: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"pong">;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"downloadProgress">;
+    received: z.ZodNumber;
+    total: z.ZodNumber;
+}, z.core.$strip>], "t">;
+export type PreviewServerMessage = z.infer<typeof previewServerMessageSchema>;
+export type PreviewStateMessage = z.infer<typeof previewStateMessageSchema>;