@openchamber/sdk 1.24.2 → 2.0.0

package/dist/service-providers.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Contracts a service fulfils when it stands in for a host role
+ * (`contributes.service.provides`).
+ *
+ * Browser: the host's `openchamber_web` tool sends its `browser.*` actions to
+ * the service instead of the in-app browser view. The service answers with the
+ * same shapes the in-app view answers with, so the agent sees one tool whoever
+ * drives the page. The host starts the service on the first action, needs no
+ * panel, and stops it after `BROWSER_PROVIDER_IDLE_MS` without actions.
+ */
+/** Route on the service loopback the host posts every action to. */
+export declare const BROWSER_PROVIDER_PATH = "/browser-control";
+export declare const BROWSER_CONTROL_ACTIONS: readonly ["browser.open", "browser.snapshot", "browser.click", "browser.type", "browser.scroll", "browser.back", "browser.forward", "browser.inspect", "browser.capture", "browser.resize"];
+export type BrowserControlAction = (typeof BROWSER_CONTROL_ACTIONS)[number];
+export declare const BROWSER_VIEWPORT_MODES: readonly ["mobile", "tablet", "desktop", "fill"];
+export type BrowserViewportMode = (typeof BROWSER_VIEWPORT_MODES)[number];
+export declare const BROWSER_SCROLL_DIRECTIONS: readonly ["up", "down", "top", "bottom"];
+export type BrowserScrollDirection = (typeof BROWSER_SCROLL_DIRECTIONS)[number];
+/** `browser.open` may wait for a slow page; every other action is quick. */
+export declare const BROWSER_PROVIDER_OPEN_TIMEOUT_MS = 45000;
+export declare const BROWSER_PROVIDER_ACTION_TIMEOUT_MS = 20000;
+/** A screenshot is the largest answer; snapshots are capped by the provider itself. */
+export declare const BROWSER_PROVIDER_RESPONSE_MAX = 12000000;
+/** No action for this long stops the service; the next action starts it again. */
+export declare const BROWSER_PROVIDER_IDLE_MS: number;
+export type BrowserOpenParameters = {
+    url: string;
+    viewport?: BrowserViewportMode;
+};
+export type BrowserSnapshotParameters = {
+    selector?: string;
+};
+export type BrowserClickParameters = {
+    selector?: string;
+    text?: string;
+};
+export type BrowserTypeParameters = {
+    selector: string;
+    value: string;
+    submit: boolean;
+};
+export type BrowserScrollParameters = {
+    selector?: string;
+    direction?: BrowserScrollDirection;
+};
+export type BrowserInspectParameters = {
+    selector: string;
+};
+export type BrowserCaptureParameters = {
+    label?: string;
+};
+export type BrowserResizeParameters = {
+    viewport: BrowserViewportMode;
+};
+/**
+ * Where an action came from: the project the agent works in and the chat it
+ * runs in. Filled by the host from the tool call, never typed by the model.
+ * A provider that keeps one browser per project or chat keys on these; one
+ * that keeps a single browser ignores them. Either is `null` when the host
+ * had none (a call from the CLI, for example): treat that as "unknown", not
+ * as a scope of its own.
+ */
+export type BrowserProviderContext = {
+    directory: string | null;
+    sessionId: string | null;
+};
+type ProviderRequestEnvelope = {
+    requestId: string;
+    context: BrowserProviderContext;
+};
+/** One action, as the host posts it. Parameters were validated by the host. */
+export type BrowserProviderRequest = ProviderRequestEnvelope & ({
+    action: 'browser.open';
+    parameters: BrowserOpenParameters;
+} | {
+    action: 'browser.snapshot';
+    parameters: BrowserSnapshotParameters;
+} | {
+    action: 'browser.click';
+    parameters: BrowserClickParameters;
+} | {
+    action: 'browser.type';
+    parameters: BrowserTypeParameters;
+} | {
+    action: 'browser.scroll';
+    parameters: BrowserScrollParameters;
+} | {
+    action: 'browser.back';
+    parameters: Record<never, never>;
+} | {
+    action: 'browser.forward';
+    parameters: Record<never, never>;
+} | {
+    action: 'browser.inspect';
+    parameters: BrowserInspectParameters;
+} | {
+    action: 'browser.capture';
+    parameters: BrowserCaptureParameters;
+} | {
+    action: 'browser.resize';
+    parameters: BrowserResizeParameters;
+});
+export type BrowserViewportSummary = {
+    mode: BrowserViewportMode | 'custom';
+    width: number | null;
+    height: number | null;
+};
+export type BrowserElementBounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** One interactive element of a snapshot; absent fields mean empty or default. */
+export type BrowserSnapshotElement = {
+    selector: string;
+    tag: string;
+    bounds: BrowserElementBounds;
+    inViewport?: true;
+    type?: string;
+    role?: string;
+    label?: string;
+    disabled?: true;
+    missingAccessibleName?: true;
+};
+export type BrowserOpenData = {
+    url: string;
+    title: string;
+    opened: true;
+    /** `false` means the page is still loading, not that opening failed. */
+    settled: boolean;
+    viewport: BrowserViewportSummary;
+};
+export type BrowserSnapshotData = {
+    url: string;
+    title: string;
+    scope: string;
+    scrollY: number;
+    maxScrollY: number;
+    text: string;
+    elements: BrowserSnapshotElement[];
+    textTruncated?: true;
+    textTotalChars?: number;
+    elementsTruncated?: true;
+    interactiveElementsOnPage?: number;
+    viewport: BrowserViewportSummary;
+    /** Warnings and errors the page logged since it was opened; absent when none. */
+    consoleProblems?: BrowserConsoleProblem[];
+};
+export type BrowserConsoleProblem = {
+    level: 'warning' | 'error';
+    message: string;
+    source: string;
+};
+export type BrowserClickData = {
+    clicked: string;
+    label: string;
+    url: string;
+};
+export type BrowserTypeData = {
+    selector: string;
+    url: string;
+};
+export type BrowserScrollData = {
+    scrollY: number;
+    maxScrollY: number;
+    atTop: boolean;
+    atBottom: boolean;
+    scrolledTo?: string;
+    direction?: BrowserScrollDirection;
+};
+export type BrowserNavigationData = {
+    url: string;
+    title: string;
+};
+export type BrowserInspectData = {
+    selector: string;
+    tag: string;
+    label: string;
+    bounds: BrowserElementBounds;
+    inViewport: boolean;
+    styles: Record<string, string>;
+};
+/** The host writes the image to the project and hands the agent its path. */
+export type BrowserCaptureData = {
+    base64: string;
+    mime: string;
+    width: number;
+    height: number;
+    url: string;
+    title: string;
+    viewport: BrowserViewportSummary;
+};
+export type BrowserResizeData = {
+    viewport: BrowserViewportSummary;
+};
+export type BrowserProviderData = BrowserOpenData | BrowserSnapshotData | BrowserClickData | BrowserTypeData | BrowserScrollData | BrowserNavigationData | BrowserInspectData | BrowserCaptureData | BrowserResizeData;
+/**
+ * What the service answers. `error` is read by the agent, so it should say
+ * what to do differently ("No element matches #save"), not what broke inside.
+ */
+export type BrowserProviderResult = {
+    ok: true;
+    data: BrowserProviderData;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const isBrowserControlAction: (value: string) => value is BrowserControlAction;
+/**
+ * A provider's read of the body the host posted to `BROWSER_PROVIDER_PATH`.
+ * The host is trusted and validated the parameters against the action before
+ * sending, so this checks the envelope and the action, not every field, and
+ * the service bundle needs no schema library for it. `null` is a body that is
+ * not a browser action; answer it with HTTP 400.
+ */
+export declare const readBrowserProviderRequest: (body: string) => BrowserProviderRequest | null;
+export {};

package/dist/service-providers.js

@@ -0,0 +1,73 @@
+/**
+ * Contracts a service fulfils when it stands in for a host role
+ * (`contributes.service.provides`).
+ *
+ * Browser: the host's `openchamber_web` tool sends its `browser.*` actions to
+ * the service instead of the in-app browser view. The service answers with the
+ * same shapes the in-app view answers with, so the agent sees one tool whoever
+ * drives the page. The host starts the service on the first action, needs no
+ * panel, and stops it after `BROWSER_PROVIDER_IDLE_MS` without actions.
+ */
+/** Route on the service loopback the host posts every action to. */
+export const BROWSER_PROVIDER_PATH = '/browser-control';
+export const BROWSER_CONTROL_ACTIONS = [
+    'browser.open',
+    'browser.snapshot',
+    'browser.click',
+    'browser.type',
+    'browser.scroll',
+    'browser.back',
+    'browser.forward',
+    'browser.inspect',
+    'browser.capture',
+    'browser.resize',
+];
+export const BROWSER_VIEWPORT_MODES = ['mobile', 'tablet', 'desktop', 'fill'];
+export const BROWSER_SCROLL_DIRECTIONS = ['up', 'down', 'top', 'bottom'];
+/** `browser.open` may wait for a slow page; every other action is quick. */
+export const BROWSER_PROVIDER_OPEN_TIMEOUT_MS = 45_000;
+export const BROWSER_PROVIDER_ACTION_TIMEOUT_MS = 20_000;
+/** A screenshot is the largest answer; snapshots are capped by the provider itself. */
+export const BROWSER_PROVIDER_RESPONSE_MAX = 12_000_000;
+/** No action for this long stops the service; the next action starts it again. */
+export const BROWSER_PROVIDER_IDLE_MS = 10 * 60_000;
+const CONTROL_ACTIONS = new Set(BROWSER_CONTROL_ACTIONS);
+export const isBrowserControlAction = (value) => CONTROL_ACTIONS.has(value);
+/** Hosts before the context field posted none; that reads as an unknown scope. */
+const readContext = (wire) => {
+    const directory = wire?.directory;
+    const sessionId = wire?.sessionId;
+    return {
+        directory: String(directory) === directory && directory.length > 0 ? directory : null,
+        sessionId: String(sessionId) === sessionId && sessionId.length > 0 ? sessionId : null,
+    };
+};
+/**
+ * A provider's read of the body the host posted to `BROWSER_PROVIDER_PATH`.
+ * The host is trusted and validated the parameters against the action before
+ * sending, so this checks the envelope and the action, not every field, and
+ * the service bundle needs no schema library for it. `null` is a body that is
+ * not a browser action; answer it with HTTP 400.
+ */
+export const readBrowserProviderRequest = (body) => {
+    let wire;
+    try {
+        const parsed = JSON.parse(body);
+        if (Object(parsed) !== parsed || parsed === null)
+            return null;
+        wire = parsed;
+    }
+    catch {
+        return null;
+    }
+    const { requestId, action, parameters, context } = wire;
+    if (String(requestId) !== requestId || requestId.length === 0)
+        return null;
+    if (String(action) !== action || !isBrowserControlAction(action))
+        return null;
+    if (Object(parameters) !== parameters)
+        return null;
+    // SAFETY: requestId, action, and the parameters object were checked above,
+    // and the host validated the parameters for this action before posting.
+    return { requestId, action, parameters, context: readContext(context) };
+};

package/dist/service-surface-schemas.d.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+export declare const surfaceInputEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"pointer">;
+    action: z.ZodEnum<{
+        up: "up";
+        down: "down";
+        move: "move";
+    }>;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    button: z.ZodNumber;
+    buttons: z.ZodNumber;
+    modifiers: z.ZodObject<{
+        alt: z.ZodBoolean;
+        ctrl: z.ZodBoolean;
+        meta: z.ZodBoolean;
+        shift: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"wheel">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    deltaX: z.ZodNumber;
+    deltaY: z.ZodNumber;
+    modifiers: z.ZodObject<{
+        alt: z.ZodBoolean;
+        ctrl: z.ZodBoolean;
+        meta: z.ZodBoolean;
+        shift: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"key">;
+    action: z.ZodEnum<{
+        up: "up";
+        down: "down";
+    }>;
+    key: z.ZodString;
+    code: z.ZodString;
+    modifiers: z.ZodObject<{
+        alt: z.ZodBoolean;
+        ctrl: z.ZodBoolean;
+        meta: z.ZodBoolean;
+        shift: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>], "type">;
+/** What a viewer (the host panel) sends the host over the surface socket. */
+export declare const surfaceViewerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    seq: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"input">;
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"pointer">;
+        action: z.ZodEnum<{
+            up: "up";
+            down: "down";
+            move: "move";
+        }>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        button: z.ZodNumber;
+        buttons: z.ZodNumber;
+        modifiers: z.ZodObject<{
+            alt: z.ZodBoolean;
+            ctrl: z.ZodBoolean;
+            meta: z.ZodBoolean;
+            shift: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"wheel">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        deltaX: z.ZodNumber;
+        deltaY: z.ZodNumber;
+        modifiers: z.ZodObject<{
+            alt: z.ZodBoolean;
+            ctrl: z.ZodBoolean;
+            meta: z.ZodBoolean;
+            shift: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"key">;
+        action: z.ZodEnum<{
+            up: "up";
+            down: "down";
+        }>;
+        key: z.ZodString;
+        code: z.ZodString;
+        modifiers: z.ZodObject<{
+            alt: z.ZodBoolean;
+            ctrl: z.ZodBoolean;
+            meta: z.ZodBoolean;
+            shift: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"release">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resize">;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"clipboard-read">;
+    id: z.ZodString;
+}, z.core.$strip>], "type">;
+export type SurfaceViewerMessage = z.infer<typeof surfaceViewerMessageSchema>;
+export declare const surfaceControllerSchema: z.ZodEnum<{
+    user: "user";
+    none: "none";
+    agent: "agent";
+}>;
+/**
+ * What the host sends a viewer. A `frame` text message is followed by one
+ * binary message carrying exactly `bytes` bytes of the image.
+ */
+export declare const surfaceHostMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    viewerId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"frame">;
+    seq: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    mime: z.ZodEnum<{
+        "image/jpeg": "image/jpeg";
+        "image/png": "image/png";
+    }>;
+    bytes: z.ZodNumber;
+    title: z.ZodOptional<z.ZodString>;
+    agentActive: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"control">;
+    controller: z.ZodEnum<{
+        user: "user";
+        none: "none";
+        agent: "agent";
+    }>;
+    mine: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resized">;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"clipboard">;
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ended">;
+    reason: z.ZodEnum<{
+        "service-stopped": "service-stopped";
+        "extension-unavailable": "extension-unavailable";
+        "host-shutdown": "host-shutdown";
+    }>;
+}, z.core.$strip>], "type">;
+export type SurfaceHostMessage = z.infer<typeof surfaceHostMessageSchema>;
+/** Service answers the host parses. */
+export declare const surfaceResizeAnswerSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const surfaceClipboardAnswerSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;

package/dist/service-surface-schemas.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { SURFACE_CONTROLLERS, SURFACE_DIMENSION_MAX, SURFACE_FRAME_MIMES, SURFACE_INPUT_BATCH_MAX, SURFACE_TEXT_MAX, SURFACE_TITLE_MAX, } from "./service-surface.js";
+const modifiersSchema = z.object({ alt: z.boolean(), ctrl: z.boolean(), meta: z.boolean(), shift: z.boolean() });
+const finite = z.number().finite();
+export const surfaceInputEventSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('pointer'),
+        action: z.enum(['down', 'up', 'move']),
+        x: finite,
+        y: finite,
+        button: z.number().int().min(-1).max(4),
+        buttons: z.number().int().min(0).max(31),
+        modifiers: modifiersSchema,
+    }),
+    z.object({ type: z.literal('wheel'), x: finite, y: finite, deltaX: finite, deltaY: finite, modifiers: modifiersSchema }),
+    z.object({
+        type: z.literal('key'),
+        action: z.enum(['down', 'up']),
+        key: z.string().min(1).max(64),
+        code: z.string().max(64),
+        modifiers: modifiersSchema,
+    }),
+    z.object({ type: z.literal('text'), text: z.string().min(1).max(SURFACE_TEXT_MAX) }),
+]);
+const dimension = z.number().int().min(1).max(SURFACE_DIMENSION_MAX);
+/** What a viewer (the host panel) sends the host over the surface socket. */
+export const surfaceViewerMessageSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('ack'), seq: z.number().int().min(0) }),
+    z.object({ type: z.literal('input'), events: z.array(surfaceInputEventSchema).min(1).max(SURFACE_INPUT_BATCH_MAX) }),
+    z.object({ type: z.literal('release') }),
+    z.object({ type: z.literal('resize'), width: dimension, height: dimension }),
+    z.object({ type: z.literal('clipboard-read'), id: z.string().min(1).max(64) }),
+]);
+export const surfaceControllerSchema = z.enum(SURFACE_CONTROLLERS);
+/**
+ * What the host sends a viewer. A `frame` text message is followed by one
+ * binary message carrying exactly `bytes` bytes of the image.
+ */
+export const surfaceHostMessageSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('hello'), viewerId: z.string().min(1) }),
+    z.object({
+        type: z.literal('frame'),
+        seq: z.number().int().min(0),
+        width: dimension,
+        height: dimension,
+        mime: z.enum(SURFACE_FRAME_MIMES),
+        bytes: z.number().int().min(1),
+        title: z.string().max(SURFACE_TITLE_MAX).optional(),
+        agentActive: z.boolean(),
+    }),
+    z.object({ type: z.literal('control'), controller: surfaceControllerSchema, mine: z.boolean() }),
+    z.object({ type: z.literal('resized'), width: dimension, height: dimension }),
+    z.object({ type: z.literal('clipboard'), id: z.string().min(1).max(64), text: z.string().max(SURFACE_TEXT_MAX) }),
+    z.object({ type: z.literal('error'), code: z.string().min(1).max(64), message: z.string().min(1).max(500) }),
+    z.object({ type: z.literal('ended'), reason: z.enum(['service-stopped', 'extension-unavailable', 'host-shutdown']) }),
+]);
+/** Service answers the host parses. */
+export const surfaceResizeAnswerSchema = z.object({ width: dimension, height: dimension });
+export const surfaceClipboardAnswerSchema = z.object({ text: z.string().max(SURFACE_TEXT_MAX) });

package/dist/service-surface.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared surface: a service shows the host a live picture of something an
+ * agent is working in (a browser, a simulator, a desktop app) and takes the
+ * user's pointer and keyboard back, so a person can watch, step in for a
+ * manual step, and hand control back. The host draws it in the extension's
+ * rail panel; the service only produces frames and consumes input.
+ *
+ * Declared with `contributes.service.surface: true`. The host keeps the
+ * service running while a viewer is attached and talks plain HTTP to it:
+ *
+ * - `GET /surface/frame?after=<seq>&wait=<ms>`: the next frame newer than
+ *   `seq`, held up to `wait` ms. 200 with the image bytes (`Content-Type`
+ *   `image/jpeg` or `image/png`) and the `x-surface-*` headers below; 204 when
+ *   nothing newer arrived in time. Sequence numbers start at 1, so `after=0`
+ *   is "the current picture, now". The host asks for one frame at a time per
+ *   viewer, so a slow viewer never piles up frames: that is the backpressure.
+ * - `POST /surface/input`: `{ events: SurfaceInputEvent[] }`, coordinates in
+ *   frame pixels. Sent only while the user holds control.
+ * - `POST /surface/control`: `{ controller }` whenever control changes, so the
+ *   service can pause its own automation while the user is in.
+ * - `POST /surface/resize`: `{ width, height }` the panel can show; the
+ *   service answers the size it settled on, or 400 to keep its own.
+ * - `GET /surface/clipboard`: `{ text }`, what the user copied inside the
+ *   surface; the host puts it on their clipboard.
+ */
+export declare const SURFACE_FRAME_PATH = "/surface/frame";
+export declare const SURFACE_INPUT_PATH = "/surface/input";
+export declare const SURFACE_CONTROL_PATH = "/surface/control";
+export declare const SURFACE_RESIZE_PATH = "/surface/resize";
+export declare const SURFACE_CLIPBOARD_PATH = "/surface/clipboard";
+export declare const SURFACE_SEQ_HEADER = "x-surface-seq";
+export declare const SURFACE_WIDTH_HEADER = "x-surface-width";
+export declare const SURFACE_HEIGHT_HEADER = "x-surface-height";
+export declare const SURFACE_TITLE_HEADER = "x-surface-title";
+/** `1` while the service's own automation (an agent) is driving the surface. */
+export declare const SURFACE_AGENT_ACTIVE_HEADER = "x-surface-agent-active";
+export declare const SURFACE_FRAME_MIMES: readonly ["image/jpeg", "image/png"];
+export type SurfaceFrameMime = (typeof SURFACE_FRAME_MIMES)[number];
+/** How long the host lets one frame request wait before asking again. */
+export declare const SURFACE_FRAME_WAIT_MS = 25000;
+export declare const SURFACE_FRAME_MAX_BYTES = 8000000;
+export declare const SURFACE_INPUT_BATCH_MAX = 256;
+export declare const SURFACE_TEXT_MAX = 64000;
+export declare const SURFACE_TITLE_MAX = 200;
+export declare const SURFACE_DIMENSION_MAX = 16384;
+/** After an agent action the agent counts as controlling for this long. */
+export declare const SURFACE_AGENT_HOLD_MS = 30000;
+export type SurfaceModifiers = {
+    alt: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+};
+export type SurfacePointerEvent = {
+    type: 'pointer';
+    action: 'down' | 'up' | 'move';
+    x: number;
+    y: number;
+    /** 0 left, 1 middle, 2 right; `-1` for a move without a button change. */
+    button: number;
+    /** Bitmask of buttons held, as `MouseEvent.buttons`. */
+    buttons: number;
+    modifiers: SurfaceModifiers;
+};
+export type SurfaceWheelEvent = {
+    type: 'wheel';
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+    modifiers: SurfaceModifiers;
+};
+export type SurfaceKeyEvent = {
+    type: 'key';
+    action: 'down' | 'up';
+    /** `KeyboardEvent.key`. */
+    key: string;
+    /** `KeyboardEvent.code`. */
+    code: string;
+    modifiers: SurfaceModifiers;
+};
+/** Text the user pasted or composed; type it as is. */
+export type SurfaceTextEvent = {
+    type: 'text';
+    text: string;
+};
+export type SurfaceInputEvent = SurfacePointerEvent | SurfaceWheelEvent | SurfaceKeyEvent | SurfaceTextEvent;
+export type SurfaceInputBatch = {
+    events: SurfaceInputEvent[];
+};
+export declare const SURFACE_CONTROLLERS: readonly ["none", "agent", "user"];
+export type SurfaceController = (typeof SURFACE_CONTROLLERS)[number];
+export type SurfaceControlNotice = {
+    controller: SurfaceController;
+};
+export type SurfaceResizeRequest = {
+    width: number;
+    height: number;
+};
+export type SurfaceResizeAnswer = {
+    width: number;
+    height: number;
+};
+export type SurfaceClipboardAnswer = {
+    text: string;
+};
+/**
+ * A service's read of the `POST /surface/input` body. Every event is checked
+ * field by field; one bad event refuses the whole batch (`null`), which the
+ * service answers with HTTP 400. No schema library needed.
+ */
+export declare const readSurfaceInputBatch: (body: string) => SurfaceInputBatch | null;
+/** A service's read of the `POST /surface/control` body. */
+export declare const readSurfaceControlNotice: (body: string) => SurfaceControlNotice | null;
+/** A service's read of the `POST /surface/resize` body. */
+export declare const readSurfaceResizeRequest: (body: string) => SurfaceResizeRequest | null;