@opengeni/agent-proto 0.2.1 → 0.4.0

package/dist/gen/opengeni_agent.d.ts

@@ -0,0 +1,1625 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+export declare const protobufPackage = "opengeni.agent.v1";
+export declare enum ErrorCode {
+    ERROR_CODE_UNSPECIFIED = 0,
+    /** ERROR_CODE_UNSUPPORTED - The requested op is not implemented / not permitted on this platform. */
+    ERROR_CODE_UNSUPPORTED = 1,
+    /** ERROR_CODE_OS - A filesystem/exec/git op failed at the OS layer (see `detail`). */
+    ERROR_CODE_OS = 2,
+    /** ERROR_CODE_NOT_FOUND - The path/ref/target referenced by the op does not exist. */
+    ERROR_CODE_NOT_FOUND = 3,
+    /** ERROR_CODE_CONSENT_REQUIRED - The op was rejected by consent/capability gating (e.g. screen-control off). */
+    ERROR_CODE_CONSENT_REQUIRED = 4,
+    /** ERROR_CODE_TIMEOUT - The op timed out inside the agent. */
+    ERROR_CODE_TIMEOUT = 5,
+    /** ERROR_CODE_DRAINING - The agent is shutting down / draining and cannot accept new work. */
+    ERROR_CODE_DRAINING = 6,
+    /** ERROR_CODE_PROTOCOL - A protocol-level violation (bad envelope, unknown op for this version). */
+    ERROR_CODE_PROTOCOL = 7,
+    /** ERROR_CODE_STREAM - A required stream channel could not be opened on the relay. */
+    ERROR_CODE_STREAM = 8,
+    /** ERROR_CODE_AGENT_OFFLINE - The control plane synthesized this because no agent responded (offline). */
+    ERROR_CODE_AGENT_OFFLINE = 9,
+    /** ERROR_CODE_FENCED - An epoch fence rejected a stale op; caller should re-resolve and retry. */
+    ERROR_CODE_FENCED = 10,
+    /**
+     * ERROR_CODE_PAYLOAD_TOO_LARGE - The op's reply would exceed the transport's negotiated max payload and could
+     * not be published (e.g. a full-res screenshot, or an unbounded file read/exec
+     * output). The agent's wire-seam backstop synthesizes THIS instead of letting
+     * the oversized publish fail silently and the caller time out opaquely.
+     * Not retryable — the same op would produce the same oversized reply.
+     */
+    ERROR_CODE_PAYLOAD_TOO_LARGE = 11
+}
+export declare function errorCodeFromJSON(object: any): ErrorCode;
+export declare function errorCodeToJSON(object: ErrorCode): string;
+/** The operating system family the agent runs on. */
+export declare enum Os {
+    OS_UNSPECIFIED = 0,
+    OS_LINUX = 1,
+    OS_MACOS = 2,
+    OS_WINDOWS = 3
+}
+export declare function osFromJSON(object: any): Os;
+export declare function osToJSON(object: Os): string;
+/** CPU architecture. */
+export declare enum Arch {
+    ARCH_UNSPECIFIED = 0,
+    ARCH_X86_64 = 1,
+    ARCH_AARCH64 = 2
+}
+export declare function archFromJSON(object: any): Arch;
+export declare function archToJSON(object: Arch): string;
+/** The kind of byte stream a relay channel carries. */
+export declare enum StreamKind {
+    STREAM_KIND_UNSPECIFIED = 0,
+    /** STREAM_KIND_PTY - An interactive pseudo-terminal (ttyd-equivalent). */
+    STREAM_KIND_PTY = 1,
+    /** STREAM_KIND_DESKTOP - A desktop framebuffer (noVNC-equivalent) for view + computer-use. */
+    STREAM_KIND_DESKTOP = 2,
+    /**
+     * STREAM_KIND_BROWSER - Browser-native encoded frames from one BrowserSession target. The payload is
+     * the canonical OpenGeni browser-frame message, not a desktop capture.
+     */
+    STREAM_KIND_BROWSER = 3,
+    /**
+     * STREAM_KIND_COMPUTER - Native app/window/screen frames from one ComputerSession target. Browser and
+     * Computer frames share the relay transport, but never the resource label.
+     */
+    STREAM_KIND_COMPUTER = 4
+}
+export declare function streamKindFromJSON(object: any): StreamKind;
+export declare function streamKindToJSON(object: StreamKind): string;
+export declare enum DeviceAuthState {
+    DEVICE_AUTH_STATE_UNSPECIFIED = 0,
+    /** DEVICE_AUTH_STATE_PENDING - The user has not yet completed the flow; keep polling. */
+    DEVICE_AUTH_STATE_PENDING = 1,
+    /** DEVICE_AUTH_STATE_AUTHORIZED - The user authorized; `credentials` are present. */
+    DEVICE_AUTH_STATE_AUTHORIZED = 2,
+    /** DEVICE_AUTH_STATE_DENIED - The user explicitly denied the request. */
+    DEVICE_AUTH_STATE_DENIED = 3,
+    /** DEVICE_AUTH_STATE_EXPIRED - The device_code expired before authorization. */
+    DEVICE_AUTH_STATE_EXPIRED = 4,
+    /** DEVICE_AUTH_STATE_SLOW_DOWN - The agent is polling too fast and must slow down. */
+    DEVICE_AUTH_STATE_SLOW_DOWN = 5
+}
+export declare function deviceAuthStateFromJSON(object: any): DeviceAuthState;
+export declare function deviceAuthStateToJSON(object: DeviceAuthState): string;
+export declare enum FsEntryKind {
+    FS_ENTRY_KIND_UNSPECIFIED = 0,
+    FS_ENTRY_KIND_FILE = 1,
+    FS_ENTRY_KIND_DIRECTORY = 2,
+    FS_ENTRY_KIND_SYMLINK = 3
+}
+export declare function fsEntryKindFromJSON(object: any): FsEntryKind;
+export declare function fsEntryKindToJSON(object: FsEntryKind): string;
+export declare enum GitOp {
+    GIT_OP_UNSPECIFIED = 0,
+    GIT_OP_STATUS = 1,
+    GIT_OP_DIFF = 2,
+    GIT_OP_LOG = 3,
+    GIT_OP_ADD = 4,
+    GIT_OP_COMMIT = 5,
+    GIT_OP_BRANCH = 6,
+    GIT_OP_CHECKOUT = 7,
+    GIT_OP_PULL = 8,
+    GIT_OP_PUSH = 9,
+    /** GIT_OP_RAW - Any other subcommand, passed through verbatim via `args`. */
+    GIT_OP_RAW = 15
+}
+export declare function gitOpFromJSON(object: any): GitOp;
+export declare function gitOpToJSON(object: GitOp): string;
+export declare enum GoingOfflineReason {
+    GOING_OFFLINE_REASON_UNSPECIFIED = 0,
+    /** GOING_OFFLINE_REASON_USER_STOP - The user stopped the foreground process. */
+    GOING_OFFLINE_REASON_USER_STOP = 1,
+    /** GOING_OFFLINE_REASON_UPDATE - The agent is restarting itself for a self-update. */
+    GOING_OFFLINE_REASON_UPDATE = 2,
+    /** GOING_OFFLINE_REASON_HOST_SHUTDOWN - The host is shutting down / suspending. */
+    GOING_OFFLINE_REASON_HOST_SHUTDOWN = 3
+}
+export declare function goingOfflineReasonFromJSON(object: any): GoingOfflineReason;
+export declare function goingOfflineReasonToJSON(object: GoingOfflineReason): string;
+/** The logical byte stream an op-frame Data chunk belongs to. */
+export declare enum OpChannel {
+    OP_CHANNEL_UNSPECIFIED = 0,
+    OP_CHANNEL_STDOUT = 1,
+    OP_CHANNEL_STDERR = 2,
+    /** OP_CHANNEL_CONTENT - Non-exec content (fs_read bodies and similar). */
+    OP_CHANNEL_CONTENT = 3
+}
+export declare function opChannelFromJSON(object: any): OpChannel;
+export declare function opChannelToJSON(object: OpChannel): string;
+/**
+ * An op's lifecycle state on the runner: accepted → running → complete(retained)
+ * → gc; or lost. `lost` is always TYPED (see OpLostReason) — never a silent gap.
+ */
+export declare enum OpState {
+    OP_STATE_UNSPECIFIED = 0,
+    OP_STATE_ACCEPTED = 1,
+    OP_STATE_RUNNING = 2,
+    OP_STATE_COMPLETE = 3,
+    OP_STATE_LOST = 4
+}
+export declare function opStateFromJSON(object: any): OpState;
+export declare function opStateToJSON(object: OpState): string;
+/** Why a lost op is lost (present iff OpStatus.state == OP_STATE_LOST). */
+export declare enum OpLostReason {
+    OP_LOST_REASON_UNSPECIFIED = 0,
+    /**
+     * OP_LOST_REASON_EVICTED - A completed op's retained result was evicted (bounded LRU registry) before a
+     * final ack arrived — a loud, counted event, surfaced honestly on a late query.
+     */
+    OP_LOST_REASON_EVICTED = 1,
+    /**
+     * OP_LOST_REASON_AGENT_RESTARTED - The runner process restarted and the op's in-memory scope did not survive
+     * (until the journal + scope re-adoption of a later milestone).
+     */
+    OP_LOST_REASON_AGENT_RESTARTED = 2
+}
+export declare function opLostReasonFromJSON(object: any): OpLostReason;
+export declare function opLostReasonToJSON(object: OpLostReason): string;
+export declare enum StreamRole {
+    STREAM_ROLE_UNSPECIFIED = 0,
+    /** STREAM_ROLE_AGENT - The agent producing pty/desktop bytes. */
+    STREAM_ROLE_AGENT = 1,
+    /** STREAM_ROLE_CLIENT - The viewer/pty client consuming them (and sending input back). */
+    STREAM_ROLE_CLIENT = 2
+}
+export declare function streamRoleFromJSON(object: any): StreamRole;
+export declare function streamRoleToJSON(object: StreamRole): string;
+export declare enum StreamCloseReason {
+    STREAM_CLOSE_REASON_UNSPECIFIED = 0,
+    /** STREAM_CLOSE_REASON_NORMAL - Normal end (pty exited, viewer left). */
+    STREAM_CLOSE_REASON_NORMAL = 1,
+    /** STREAM_CLOSE_REASON_PROCESS_EXIT - The producing process ended. */
+    STREAM_CLOSE_REASON_PROCESS_EXIT = 2,
+    /** STREAM_CLOSE_REASON_FENCED - The epoch fence invalidated the channel (a swap-away). */
+    STREAM_CLOSE_REASON_FENCED = 3,
+    /** STREAM_CLOSE_REASON_TRANSPORT_ERROR - A relay/transport error (the client should reconnect+resume). */
+    STREAM_CLOSE_REASON_TRANSPORT_ERROR = 4,
+    /** STREAM_CLOSE_REASON_RATE_LIMITED - Rate-limit / backpressure shed the channel. */
+    STREAM_CLOSE_REASON_RATE_LIMITED = 5
+}
+export declare function streamCloseReasonFromJSON(object: any): StreamCloseReason;
+export declare function streamCloseReasonToJSON(object: StreamCloseReason): string;
+export declare enum PointerAction {
+    POINTER_ACTION_UNSPECIFIED = 0,
+    POINTER_ACTION_MOVE = 1,
+    POINTER_ACTION_DOWN = 2,
+    POINTER_ACTION_UP = 3,
+    POINTER_ACTION_CLICK = 4,
+    POINTER_ACTION_DOUBLE_CLICK = 5
+}
+export declare function pointerActionFromJSON(object: any): PointerAction;
+export declare function pointerActionToJSON(object: PointerAction): string;
+export declare enum PointerButton {
+    POINTER_BUTTON_UNSPECIFIED = 0,
+    POINTER_BUTTON_LEFT = 1,
+    POINTER_BUTTON_RIGHT = 2,
+    POINTER_BUTTON_MIDDLE = 3
+}
+export declare function pointerButtonFromJSON(object: any): PointerButton;
+export declare function pointerButtonToJSON(object: PointerButton): string;
+export declare enum KeyAction {
+    KEY_ACTION_UNSPECIFIED = 0,
+    KEY_ACTION_DOWN = 1,
+    KEY_ACTION_UP = 2,
+    KEY_ACTION_PRESS = 3
+}
+export declare function keyActionFromJSON(object: any): KeyAction;
+export declare function keyActionToJSON(object: KeyAction): string;
+/**
+ * A typed error returned by the agent (or synthesized by the control plane for
+ * a non-responding agent). `code` is a stable machine-readable discriminant;
+ * `message` is human-facing; `retryable` lets the turn layer decide whether to
+ * pause-and-retry (a reconnect blip) versus surface a hard failure.
+ */
+export interface AgentError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    /** Optional structured detail (e.g. an OS errno, a git exit code) for logs. */
+    detail: {
+        [key: string]: string;
+    };
+}
+export interface AgentError_DetailEntry {
+    key: string;
+    value: string;
+}
+/**
+ * The agent's self-description, sent on connect (the "hello") and refreshed on
+ * reconnect. The control plane folds this into the negotiated SessionCapabilities
+ * document (every capability cell is available:false+reason, never absent).
+ */
+export interface Hello {
+    agentId: string;
+    workspaceId: string;
+    /** Semantic version of the running agent binary (drives staged self-update). */
+    agentVersion: string;
+    os: Os;
+    arch: Arch;
+    /** Human-friendly machine name (hostname by default; user-overridable). */
+    machineName: string;
+    /** The agent-reported working root the control plane treats as the sandbox cwd. */
+    workspaceRoot: string;
+    /** Capabilities the agent can serve given its platform + consent grants. */
+    capabilities: Capabilities | undefined;
+    /** The update channel this agent follows (stable|beta), for fleet-pinning. */
+    updateChannel: string;
+    /**
+     * A resume token minted by a prior connection, echoed so the control plane can
+     * recognize a reconnect (vs a fresh enrollment) and fence by epoch. Empty on
+     * first connect.
+     */
+    resumeToken: string;
+}
+/**
+ * What the agent is able and consented to do. Each bool is a hard capability
+ * gate; the control plane maps a false to a CapabilityUnavailableReason.
+ */
+export interface Capabilities {
+    /** Channel-A structural surface (always true for a connected agent). */
+    exec: boolean;
+    filesystem: boolean;
+    git: boolean;
+    /** An interactive PTY can be opened over the relay. */
+    pty: boolean;
+    /** A desktop framebuffer is available (a display exists or Xvfb is enabled). */
+    desktop: boolean;
+    /** The user consented to whole-machine access during enrollment. */
+    consentedWholeMachine: boolean;
+    /** The user consented to screen capture + synthetic input (computer-use). */
+    consentedScreenControl: boolean;
+    /** Display detail (absent => headless / no display). */
+    display: Display | undefined;
+    /**
+     * When a display physically EXISTS but the OS withholds the screen-CAPTURE grant
+     * (macOS Screen Recording / TCC), `desktop` is reported false and this carries a
+     * human, actionable reason (e.g. "grant Screen Recording in System Settings").
+     * Empty when capture is permitted or the platform has no separate capture grant
+     * (Linux/x11). Advertised at Hello so the control plane degrades the desktop cell
+     * with a legible hint instead of offering a desktop it cannot capture — the
+     * machine that "claims a display it can't capture" bug the 0.1.3 incident exposed.
+     */
+    desktopUnavailableReason: string;
+    /**
+     * The runner speaks the op-stream protocol (OpStart/OpFrame/OpAck; see the
+     * op-stream section below). Advertised at Hello; the server uses the streaming
+     * path only when this is true AND its own feature flag is on, else the legacy
+     * monolithic ops run exactly as today. Additive — absent (false) on an older
+     * runner means "legacy path", no version coupling.
+     */
+    opStream: boolean;
+    /**
+     * A local attached-browser bridge is available. The bridge inventories live
+     * browser-profile endpoints separately from this machine enrollment because
+     * one machine may host multiple Chrome profiles.
+     */
+    browserBridge: boolean;
+}
+/**
+ * Capabilities of one live browser-profile bridge endpoint. This describes the
+ * transport endpoint only; reusable login/profile state is a separate control-
+ * plane BrowserIdentity resource.
+ */
+export interface AttachedBrowserDeviceCapabilities {
+    tabInventory: boolean;
+    debuggerAttachment: boolean;
+    semanticObservation: boolean;
+    screenshots: boolean;
+    liveFrames: boolean;
+    humanInput: boolean;
+    diagnostics: boolean;
+    rawCdp: boolean;
+    linkedComputer: boolean;
+}
+export interface AttachedBrowserDeviceAnnouncement {
+    id: string;
+    name: string;
+    /** Empty means Chrome did not expose a profile label. */
+    profileLabel: string;
+    browserName: string;
+    browserVersion: string;
+    extensionVersion: string;
+    platform: Os;
+    arch: Arch;
+    /** Changes whenever this extension/native-host connection restarts. */
+    connectionGeneration: string;
+    inventoryRevision: string;
+    tabCount: number;
+    capabilities: AttachedBrowserDeviceCapabilities | undefined;
+}
+/**
+ * One complete, monotonically-versioned snapshot from the machine's browser
+ * bridge. Presence on a heartbeat makes the list authoritative, including an
+ * empty list; absence means an older/no-bridge agent and changes nothing.
+ */
+export interface AttachedBrowserInventorySnapshot {
+    bridgeGeneration: string;
+    revision: string;
+    devices: AttachedBrowserDeviceAnnouncement[];
+}
+/** Detail about the agent's graphical display, when one is present. */
+export interface Display {
+    /** e.g. ":0", ":99" (Xvfb), or a platform handle. */
+    id: string;
+    width: number;
+    height: number;
+    /** True when backed by a virtual framebuffer (Xvfb) rather than a real screen. */
+    virtual: boolean;
+}
+/**
+ * The agent begins enrollment by asking the control plane to start a device
+ * flow. The control plane returns a user-code + verification URL the user visits
+ * to consent (whole-machine + optional screen-control) and authorize.
+ */
+export interface DeviceAuthStartRequest {
+    /**
+     * The agent's stable install identity (a per-install keypair fingerprint),
+     * bound to the enrollment so the issued credentials are non-transferable.
+     */
+    installFingerprint: string;
+    os: Os;
+    arch: Arch;
+    machineName: string;
+    /** The update channel the user selected at install time. */
+    updateChannel: string;
+}
+export interface DeviceAuthStartResponse {
+    /** Short code the user types at the verification URL. */
+    userCode: string;
+    /** The opaque device code the agent polls with. */
+    deviceCode: string;
+    /** Where the user goes to authorize (e.g. https://get.opengeni.ai/device). */
+    verificationUri: string;
+    /** A pre-filled convenience URL embedding the user_code. */
+    verificationUriComplete: string;
+    /** Seconds the device_code remains valid. */
+    expiresInSeconds: number;
+    /** Minimum seconds the agent must wait between polls. */
+    pollIntervalSeconds: number;
+}
+/** The agent polls until the user authorizes (or it expires / is denied). */
+export interface DeviceAuthPollRequest {
+    deviceCode: string;
+}
+export interface DeviceAuthPollResponse {
+    state: DeviceAuthState;
+    /** Present only when state == AUTHORIZED. */
+    credentials: EnrollmentCredentials | undefined;
+}
+/**
+ * The scoped credentials persisted (0600) on the machine after enrollment.
+ * These are workspace-scoped — they can address only this workspace's agents.
+ */
+export interface EnrollmentCredentials {
+    agentId: string;
+    workspaceId: string;
+    /**
+     * The NATS CONNECT AUTH-TOKEN the agent presents (the signed `oge_` enrollment
+     * bearer). The server runs with AUTH CALLOUT (M-AUTH): on connect
+     * the agent passes this as the auth-token; nats-server issues an authorization
+     * request to the control-plane's callout responder, which validates the bearer
+     * and returns a SIGNED user JWT scoping the connection to pub/sub ONLY
+     * `agent.<ws>.>` (+ `_INBOX.>`). That per-subject scope IS the per-workspace
+     * tenancy boundary — there is NO per-machine creds file to ship. (Field name kept
+     * for proto stability; it now carries the bearer, not an operator creds-file body.)
+     */
+    natsCredentials: string;
+    /**
+     * The NATS server URL(s) to dial. For the control plane these are `wss://` URLs
+     * (the relay-symmetric TLS ingress) so the agent rides the same TLS endpoint as
+     * the stream relay — no separate public TCP load balancer.
+     */
+    natsUrls: string[];
+    /** The relay edge base URL for opening stream channels. */
+    relayUrl: string;
+    /** The minisign public key the agent pins for self-update verification. */
+    updatePubkey: string;
+    /** Whether the user consented to whole-machine access. */
+    consentedWholeMachine: boolean;
+    /** Whether the user consented to screen capture + synthetic input. */
+    consentedScreenControl: boolean;
+    /**
+     * The agent's PRODUCER token for the relay edge (the relay-dial
+     * protocol). Presented as `StreamOpen.token` when the agent registers a
+     * pty/desktop channel (role=AGENT). It is a control-plane-minted, workspace+agent
+     * -scoped `ogr_` HMAC token the relay verifies on its own merits — DISTINCT from
+     * the viewer's `ogs_` stream token (which the control plane mints per viewer and
+     * the relay also verifies). The relay pairs the producer and consumer by the
+     * channel key once BOTH tokens pass. Additive proto3 field; empty for an
+     * enrollment minted before the relay-token plane is configured (the agent then
+     * presents an empty token the relay rejects, surfacing the gap loudly).
+     */
+    relayToken: string;
+}
+export interface ExecRequest {
+    /** argv[0] is the program; the agent does NOT shell-interpret unless `shell`. */
+    command: string[];
+    /** When true, `command` is joined and run through the platform shell. */
+    shell: boolean;
+    /** Working directory; defaults to the agent's workspace_root when empty. */
+    cwd: string;
+    /** Extra environment variables layered over the agent's environment. */
+    env: {
+        [key: string]: string;
+    };
+    /** Optional stdin fed to the process. */
+    stdin: Uint8Array;
+    /** Optional hard wall-clock timeout; 0 means no process deadline. */
+    timeoutMs: number;
+}
+export interface ExecRequest_EnvEntry {
+    key: string;
+    value: string;
+}
+export interface ExecResponse {
+    exitCode: number;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    /** True when the process was killed by `timeout_ms`. */
+    timedOut: boolean;
+    /** Wall-clock duration the process ran. */
+    durationMs: string;
+}
+export interface FsReadRequest {
+    path: string;
+    /** Optional byte offset + length for ranged reads (0 length => to EOF). */
+    offset: string;
+    length: string;
+}
+export interface FsReadResponse {
+    content: Uint8Array;
+    /** Total size of the file (so a ranged read knows there is more). */
+    totalSize: string;
+}
+export interface FsWriteRequest {
+    path: string;
+    content: Uint8Array;
+    /** Create parent directories as needed. */
+    createParents: boolean;
+    /** Append rather than truncate-and-write. */
+    append: boolean;
+    /** POSIX mode for a newly created file (e.g. 0644); 0 => platform default. */
+    mode: number;
+}
+export interface FsWriteResponse {
+    bytesWritten: string;
+}
+export interface FsListRequest {
+    path: string;
+    /** Recurse into subdirectories. */
+    recursive: boolean;
+}
+export interface FsListResponse {
+    entries: FsEntry[];
+}
+export interface FsEntry {
+    name: string;
+    /** Path relative to the listed directory. */
+    path: string;
+    kind: FsEntryKind;
+    size: string;
+    /** Last-modified time, unix epoch ms. */
+    modifiedMs: string;
+    mode: number;
+}
+export interface FsMkdirRequest {
+    path: string;
+    /** Create intermediate directories (mkdir -p). */
+    parents: boolean;
+    mode: number;
+}
+export interface FsMkdirResponse {
+}
+export interface FsMoveRequest {
+    from: string;
+    to: string;
+    /** Overwrite the destination if it exists. */
+    overwrite: boolean;
+}
+export interface FsMoveResponse {
+}
+export interface FsStatRequest {
+    path: string;
+}
+export interface FsStatResponse {
+    /** Absent when the path does not exist (the op still succeeds; `exists=false`). */
+    exists: boolean;
+    entry: FsEntry | undefined;
+}
+export interface FsRemoveRequest {
+    path: string;
+    /** Remove directories recursively. */
+    recursive: boolean;
+}
+export interface FsRemoveResponse {
+}
+/**
+ * A single git operation. The agent runs git against the repo rooted at `cwd`
+ * (or workspace_root) and returns structured results where it can, falling back
+ * to raw stdout for pass-through subcommands.
+ */
+export interface GitRequest {
+    op: GitOp;
+    /** Repo working directory; defaults to workspace_root. */
+    cwd: string;
+    /** Free-form args for ops that pass through (e.g. log/diff flags). */
+    args: string[];
+}
+export interface GitResponse {
+    exitCode: number;
+    /** Raw stdout/stderr for pass-through fidelity. */
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    /** Structured status, present for GIT_OP_STATUS. */
+    status: GitStatus | undefined;
+}
+export interface GitStatus {
+    branch: string;
+    /** The upstream tracking branch, if any. */
+    upstream: string;
+    ahead: number;
+    behind: number;
+    files: GitFileStatus[];
+    clean: boolean;
+}
+export interface GitFileStatus {
+    path: string;
+    /** Two-letter porcelain code (e.g. " M", "??", "A "). */
+    code: string;
+    staged: boolean;
+}
+/**
+ * Open a PTY. The agent allocates a pseudo-terminal, spawns the shell/command,
+ * and registers a relay stream channel of kind PTY. The returned `channel`
+ * identifies the stream the viewer connects to.
+ */
+export interface PtyOpenRequest {
+    /** Shell/command to run; empty => the user's default login shell. */
+    command: string[];
+    cwd: string;
+    env: {
+        [key: string]: string;
+    };
+    cols: number;
+    rows: number;
+    /** The TERM value to advertise (e.g. "xterm-256color"). */
+    term: string;
+}
+export interface PtyOpenRequest_EnvEntry {
+    key: string;
+    value: string;
+}
+export interface PtyOpenResponse {
+    /** A handle for subsequent resize/close control ops. */
+    ptyId: string;
+    /** The relay stream channel carrying the PTY bytes. */
+    channel: StreamChannel | undefined;
+}
+/**
+ * Write input bytes to a PTY. (Bulk interactive bytes normally ride the stream
+ * plane as StreamFrames; this control op exists for programmatic injection.)
+ */
+export interface PtyWriteRequest {
+    ptyId: string;
+    data: Uint8Array;
+}
+export interface PtyWriteResponse {
+    bytesWritten: string;
+}
+export interface PtyResizeRequest {
+    ptyId: string;
+    cols: number;
+    rows: number;
+}
+export interface PtyResizeResponse {
+}
+export interface PtyCloseRequest {
+    ptyId: string;
+}
+export interface PtyCloseResponse {
+    /** The exit code of the PTY's root process, if it had exited. */
+    exitCode: number;
+}
+/**
+ * Ensure a desktop framebuffer stream exists, registering a relay channel of
+ * kind DESKTOP. Idempotent: repeated calls return the same live channel.
+ */
+export interface DesktopEnsureRequest {
+    /** Request a specific geometry (0 => the display's native geometry). */
+    width: number;
+    height: number;
+}
+export interface DesktopEnsureResponse {
+    channel: StreamChannel | undefined;
+    display: Display | undefined;
+}
+/**
+ * Inject one synthetic computer-use input event on the machine's desktop — the
+ * CONTROL-PLANE twin of the relay DesktopInput (the agent drives its OWN screen
+ * for computer-use; there is no human viewer channel). Reuses the relay
+ * DesktopInput event shapes; there is no channel_id (this goes straight to the
+ * display, not a relay channel). Injection is gated on consented_screen_control:
+ * an ungated call fails with ERROR_CODE_CONSENT_REQUIRED and never touches the OS.
+ */
+export interface DesktopInputRequest {
+    event: {
+        $case: "pointer";
+        pointer: PointerEvent;
+    } | {
+        $case: "key";
+        key: KeyEvent;
+    } | {
+        $case: "scroll";
+        scroll: ScrollEvent;
+    } | undefined;
+}
+export interface DesktopInputResponse {
+}
+/**
+ * Capture a single screenshot of the machine's desktop as a PNG. A VIEW op: it
+ * needs a display, NOT screen-control consent (the view/control decoupling), so
+ * it is not consent-gated. Returns the encoded image plus its geometry so the
+ * caller can size a canvas without decoding.
+ */
+export interface DesktopScreenshotRequest {
+}
+export interface DesktopScreenshotResponse {
+    png: Uint8Array;
+    /**
+     * The geometry of the ENCODED image (what a viewer/model actually sees). When
+     * the raw capture is too large to fit the control-plane transport's max payload,
+     * the agent DOWNSCALES the PNG so the reply publishes (a full-res Retina/busy
+     * screen can exceed NATS's 1 MiB default); width/height then describe the
+     * downscaled image, and `native_width`/`native_height` below carry the original.
+     */
+    width: number;
+    height: number;
+    /**
+     * The ORIGINAL (pre-downscale) capture geometry. Equal to width/height when no
+     * downscale was needed. The computer-use coordinate mapping scales a model click
+     * (expressed in the ENCODED pixel space it saw) back up to this native pixel
+     * space before injecting, so clicks land correctly even on a downscaled frame.
+     * 0 (unset by an older agent) MUST be read as "same as width/height" (no scale).
+     */
+    nativeWidth: number;
+    nativeHeight: number;
+}
+/**
+ * Ensure the agent-owned browserd sidecar for one physical attached-browser
+ * generation. The authenticated control plane supplies the placement-scoped
+ * authority; the runner writes it owner-only and never places it in argv/logs.
+ */
+export interface BrowserControlEnsureRequest {
+    scopeId: string;
+    scopeGeneration: string;
+    adminToken: string;
+    allowedOrigins: string[];
+}
+export interface BrowserControlEnsureResponse {
+    port: number;
+    sidecarGeneration: string;
+}
+/**
+ * Open one browserd frame subscription and relay its canonical binary browser
+ * frame messages over a fresh STREAM_KIND_BROWSER channel. browserd remains
+ * loopback-only; only the short-lived view grant crosses this local boundary.
+ */
+export interface BrowserFramesOpenRequest {
+    scopeId: string;
+    scopeGeneration: string;
+    browserSessionId: string;
+    controllerGeneration: string;
+    targetId: string;
+    viewToken: string;
+    expiresAtMs: string;
+    format: string;
+    quality: number;
+    maxWidth: number;
+    maxHeight: number;
+    everyNthFrame: number;
+}
+export interface BrowserFramesOpenResponse {
+    channel: StreamChannel | undefined;
+}
+/**
+ * ComputerSession equivalent of BrowserFramesOpen. The relay carries the same
+ * canonical binary frame envelope, while the distinct resource id keeps
+ * controller authorization and URL routing unambiguous.
+ */
+export interface ComputerFramesOpenRequest {
+    scopeId: string;
+    scopeGeneration: string;
+    computerSessionId: string;
+    controllerGeneration: string;
+    targetId: string;
+    viewToken: string;
+    expiresAtMs: string;
+    format: string;
+    quality: number;
+    maxWidth: number;
+    maxHeight: number;
+    everyNthFrame: number;
+}
+export interface ComputerFramesOpenResponse {
+    channel: StreamChannel | undefined;
+}
+/**
+ * The agent's periodic liveness ping. Carries a metrics sample so the control
+ * plane can upsert the machine's last-sample without a separate RPC. The
+ * `seq` increments per heartbeat so the control plane can detect a gap.
+ */
+export interface Heartbeat {
+    seq: string;
+    /** Agent monotonic uptime in ms. */
+    uptimeMs: string;
+    /**
+     * The number of sessions currently sharing this machine (lease refcount as the
+     * agent sees it; the authoritative count lives in Postgres).
+     */
+    activeSessions: number;
+    metrics: MetricsSample | undefined;
+    /**
+     * True when the agent is draining for a pending self-update (prefer other
+     * sandboxes for new work).
+     */
+    draining: boolean;
+    /**
+     * The runner's measured host capacity — the upward report the server paces
+     * against (LIMITS-DOCTRINE: the runner holds no concurrency policy; the
+     * swarm/scheduler reads this and decides how much to throw at the machine).
+     */
+    capacity: HostCapacitySample | undefined;
+    /**
+     * Point-in-time op-admission counts (queues only ever fill once a derived
+     * pathology breaker saturates — nonzero queued figures are telemetry-worthy).
+     */
+    admission: AdmissionTelemetry | undefined;
+    /** Full live browser-profile inventory, when this runner has a browser bridge. */
+    attachedBrowserInventory: AttachedBrowserInventorySnapshot | undefined;
+}
+/**
+ * A point-in-time host-capacity sample: the impure sampler's reading of
+ * MemAvailable, spool-filesystem free space, fd/pid headroom, and CPUs. Every
+ * runner-side budget/breaker is a fraction of these (rule R), so this is also
+ * how the server understands what the machine can take.
+ */
+export interface HostCapacitySample {
+    memAvailableBytes: string;
+    diskFreeBytes: string;
+    fdHeadroom: string;
+    pidHeadroom: string;
+    nproc: string;
+}
+/** Point-in-time op-admission counts, per class. */
+export interface AdmissionTelemetry {
+    lightRunning: string;
+    lightQueued: string;
+    heavyRunning: string;
+    heavyQueued: string;
+    /**
+     * Jobs with a live mailbox (running + completed-retained awaiting final
+     * ack) — the op-engine's routing-table size.
+     */
+    liveOps: string;
+    /**
+     * Op frames dropped by the fire-and-forget publish path (bulk lane down or
+     * its channel full). Protocol-healed by replay; recorded so an undersized
+     * lane is visible before it matters (monotonic).
+     */
+    opFramesDroppedTotal: string;
+    /**
+     * Completed ops evicted before their final ack (dropped results) — the
+     * registry's loud counter (monotonic).
+     */
+    evictedUnackedTotal: string;
+}
+export interface HeartbeatAck {
+    /** The control plane may instruct the agent to adjust its heartbeat cadence. */
+    nextIntervalMs: number;
+    /** The control plane may signal a pending fleet action (e.g. update available). */
+    updateAvailable: boolean;
+}
+/** On-demand metrics request (the dashboard force-poll path). */
+export interface MetricsRequest {
+}
+/** A point-in-time machine metrics sample. */
+export interface MetricsSample {
+    /** Unix epoch ms when sampled. */
+    sampledAtMs: string;
+    /** CPU utilization 0..100 (whole machine). */
+    cpuPercent: number;
+    /** Load averages. */
+    load1: number;
+    load5: number;
+    load15: number;
+    memUsedBytes: string;
+    memTotalBytes: string;
+    diskUsedBytes: string;
+    diskTotalBytes: string;
+    /** A contention signal (run-queue length / pressure), if available. */
+    runQueue: number;
+    /** Per-GPU samples, when GPUs are present. */
+    gpus: GpuSample[];
+}
+export interface GpuSample {
+    name: string;
+    /** Utilization 0..100. */
+    utilPercent: number;
+    memUsedBytes: string;
+    memTotalBytes: string;
+}
+/**
+ * A cheap liveness probe — the control plane requests it to test that a
+ * responder exists on the subject (the NATS "is there an agent" check).
+ */
+export interface PingRequest {
+    /** Echoed back so the caller can correlate / measure RTT. */
+    nonce: string;
+}
+export interface PingResponse {
+    nonce: string;
+    /** The agent's monotonic clock, for skew estimation. */
+    agentMonotonicMs: string;
+}
+/**
+ * Sent by the agent on a clean stop (SIGINT/SIGTERM) so the lease flips to
+ * offline IMMEDIATELY rather than waiting on heartbeat dead-detection.
+ */
+export interface GoingOffline {
+    reason: GoingOfflineReason;
+    /** Optional human note (e.g. "user pressed Ctrl-C"). */
+    message: string;
+}
+/**
+ * On reconnect, the agent presents its resume token; the control plane fences by
+ * epoch and either accepts the resume (same machine, new connection generation)
+ * or, if the token is unknown/stale, requires a fresh hello.
+ */
+export interface ResumeRequest {
+    agentId: string;
+    resumeToken: string;
+    /** The lease epoch the agent last observed, for the integer fence. */
+    lastKnownEpoch: number;
+}
+export interface ResumeResponse {
+    accepted: boolean;
+    /**
+     * The new lease epoch the control plane assigned to this connection. Any op
+     * fenced by an older epoch must re-resolve and retry.
+     */
+    epoch: number;
+    /** A fresh resume token for the NEXT reconnect (tokens rotate per generation). */
+    resumeToken: string;
+}
+/** The agent asks whether a newer build is available for its channel + target. */
+export interface UpdateCheckRequest {
+    currentVersion: string;
+    channel: string;
+    os: Os;
+    arch: Arch;
+}
+export interface UpdateCheckResponse {
+    updateAvailable: boolean;
+    manifest: UpdateManifest | undefined;
+}
+/**
+ * A signed channel manifest. It is itself minisign-signed out-of-band; this
+ * message is the decoded body the updater reasons over.
+ */
+export interface UpdateManifest {
+    channel: string;
+    version: string;
+    /** The minimum version still permitted (downgrade-attack protection). */
+    minSupported: string;
+    /** Staged-rollout gate: an agent applies when blake3(agentId+salt)%100 < percent. */
+    rolloutPercent: number;
+    cohortSalt: string;
+    artifacts: UpdateArtifact[];
+    notesUrl: string;
+    signedAtMs: string;
+    /** When true, override drain and update mid-session (security CVE path). */
+    force: boolean;
+}
+export interface UpdateArtifact {
+    /** Target triple, e.g. "x86_64-unknown-linux-musl". */
+    target: string;
+    url: string;
+    size: string;
+    sha256: string;
+    /** URL of the detached minisign signature for the artifact. */
+    minisigUrl: string;
+}
+/**
+ * Before applying, the updater asks the control plane whether it may proceed
+ * (the control plane reads the Postgres lease refcount). The agent drains until
+ * the refcount reaches zero or a grace window elapses.
+ */
+export interface UpdateMayProceedRequest {
+    agentId: string;
+    targetVersion: string;
+}
+export interface UpdateMayProceedResponse {
+    mayProceed: boolean;
+    /** When false, the number of live sessions blocking the update. */
+    activeSessions: number;
+}
+/**
+ * The terminal outcome of an op — carried in the Exit frame body AND echoed in
+ * OpStatus once complete. Digests/totals are keyed by channel name
+ * ("stdout"/"stderr"/"content") for a byte-exact assembly proof.
+ */
+export interface OpExit {
+    exitCode: number;
+    /** Hit the runner-enforced deadline (process-tree killed). */
+    timedOut: boolean;
+    /** Cancelled via OpCancel. */
+    cancelled: boolean;
+    durationMs: string;
+    /** channel name → blake3 hex digest of the full channel stream. */
+    digests: {
+        [key: string]: string;
+    };
+    /** channel name → total bytes emitted on the channel. */
+    totals: {
+        [key: string]: string;
+    };
+    /**
+     * Set iff the RUNNER failed the op with a typed reason ("OP_OVERFLOW" /
+     * "OP_SPOOL_IO" / "OP_PIPE_IO"); empty for every child-decided outcome
+     * (exit/timeout/cancel). Never an exit-code sentinel — ambiguous renderings
+     * are outlawed (FAILURE-VISIBILITY.md).
+     */
+    failureCode: string;
+    /**
+     * Structured detail for failure_code (exact counters: retained bytes, the
+     * IO error text, captured byte totals) — the out-of-band plane's food.
+     */
+    failureDetail: {
+        [key: string]: string;
+    };
+}
+export interface OpExit_DigestsEntry {
+    key: string;
+    value: string;
+}
+export interface OpExit_TotalsEntry {
+    key: string;
+    value: string;
+}
+export interface OpExit_FailureDetailEntry {
+    key: string;
+    value: string;
+}
+/**
+ * The op-begin for a STREAMING fs_write (M7): the target is set up here; the bytes
+ * arrive as chunked, idempotent WriteChunk request/replies (no reverse streaming).
+ */
+export interface FsWriteBegin {
+    path: string;
+    /** Create parent directories as needed. */
+    createParents: boolean;
+    /** POSIX mode for a newly created file (0 => platform default). */
+    mode: number;
+    /**
+     * Editor safety (M6): the expected blake3 hex digest of the file's CURRENT
+     * content for a read-modify-write; empty for a plain write. On a re-dispatch a
+     * mismatch REFUSES rather than double-applying a diff.
+     */
+    expectedBaseDigest: string;
+}
+/**
+ * Start an op (server→runner). IDEMPOTENT by op_id (= ControlRequest.request_id):
+ * a known op_id returns its current status and NEVER re-runs — this closes the
+ * at-least-once re-run hazard (a re-dispatched turn re-issues OpStart{same id} and
+ * attaches).
+ */
+export interface OpStart {
+    op: {
+        $case: "exec";
+        exec: ExecRequest;
+    } | {
+        $case: "fsRead";
+        fsRead: FsReadRequest;
+    } | {
+        $case: "fsWrite";
+        fsWrite: FsWriteBegin;
+    } | undefined;
+    /** Initial send credit in bytes (0 => the runner default, ~4 MiB). */
+    windowBytes: string;
+    /**
+     * Absolute runner-enforced deadline, unix-epoch ms (0 = none). Runner-side
+     * enforcement is authoritative (process-tree kill + Exit{timed_out}); the
+     * server wall-clock is advisory.
+     */
+    deadlineMs: string;
+    /** The originating session id, for per-origin fair admission. */
+    originId: string;
+}
+export interface OpStarted {
+    accepted: boolean;
+    status: OpStatus | undefined;
+}
+/**
+ * Cancel an op (server→runner). Idempotent; triggers the #344 process-tree kill and
+ * a terminal frame. Reply is OpStatus.
+ */
+export interface OpCancel {
+    opId: string;
+}
+/** Query an op's status (server→runner). Reply is OpStatus. */
+export interface OpQuery {
+    opId: string;
+}
+/**
+ * Re-attach to an op after a reconnect or a missed frame (server→runner): the
+ * runner re-publishes frames ≥ from_seq from its ring/spool, then resumes live
+ * flow. Reply is OpStatus.
+ */
+export interface OpAttach {
+    opId: string;
+    /** Resume from this exclusive sequence (the consumer's cumulative-ack floor). */
+    fromSeq: string;
+    /**
+     * Attach generation (B2): monotonic (the consumer's Temporal attempt number).
+     * The runner serves replay/credit only for the HIGHEST generation seen; a
+     * lower-generation (zombie) consumer's acks are ignored.
+     */
+    attachGeneration: string;
+    /**
+     * The fresh send-credit window for the resumed attachment, in bytes
+     * (0 => reuse the window granted at OpStart). OpAck's absolute credit_bytes
+     * resizes it thereafter.
+     */
+    windowBytes: string;
+}
+/**
+ * The current status of an op (server←runner reply to OpCancel/OpQuery/OpAttach,
+ * and embedded in OpStarted).
+ */
+export interface OpStatus {
+    opId: string;
+    state: OpState;
+    /**
+     * The next sequence number the runner will assign (the high watermark, for gap
+     * detection).
+     */
+    nextSeq: string;
+    /** Present iff state == OP_STATE_COMPLETE. */
+    exit: OpExit | undefined;
+    /** Present iff state == OP_STATE_LOST. */
+    lostReason: OpLostReason;
+}
+/**
+ * One chunk of a streaming upload (server→runner): plain idempotent request/reply
+ * per chunk (≤512 KiB). A duplicate (op_id, seq) is acked WITHOUT re-applying.
+ */
+export interface WriteChunk {
+    opId: string;
+    /** The op-scoped monotonic chunk sequence. */
+    seq: string;
+    bytes: Uint8Array;
+    /** The final chunk: commit = digest-verify then atomic rename (M7). */
+    last: boolean;
+    /**
+     * Byte offset this chunk writes at (M7: writes land in an op-scoped temp file,
+     * committed on the last chunk — an aborted transfer leaves no visible file).
+     */
+    offset: string;
+}
+export interface WriteChunkAck {
+    seq: string;
+}
+/**
+ * A runner→server op frame, published fire-and-forget on the op subject
+ * (`agent.<ws>.<id>.op.<op_id>`). `seq` is a SINGLE monotonic sequence per op
+ * across ALL body kinds (Progress frames consume sequence numbers too, so gap
+ * detection is uniform).
+ */
+export interface OpFrame {
+    opId: string;
+    seq: string;
+    body: {
+        $case: "data";
+        data: OpData;
+    } | {
+        $case: "progress";
+        progress: OpProgress;
+    } | {
+        $case: "exit";
+        exit: OpExit;
+    } | undefined;
+}
+/** A chunk of op output on a channel (≤128 KiB per frame). */
+export interface OpData {
+    channel: OpChannel;
+    bytes: Uint8Array;
+}
+/**
+ * A liveness tick: the op is alive but produced no Data. Emitted every 5s while an
+ * op is live and quiet; consumes a sequence number like any frame.
+ */
+export interface OpProgress {
+}
+/**
+ * A server→runner cumulative ack + credit replenishment, published fire-and-forget
+ * on the ack subject (`agent.<ws>.<id>.ack`). Best-effort, healed by repetition.
+ */
+export interface OpAck {
+    opId: string;
+    /** Cumulative: every frame with seq ≤ acked_seq is acknowledged. */
+    ackedSeq: string;
+    /** The replenished ABSOLUTE send-credit window in bytes. */
+    creditBytes: string;
+    /** The server has fully consumed the terminal frame → the runner may GC the op. */
+    final: boolean;
+    /**
+     * The consumer's attach generation (matches OpAttach.attach_generation; the
+     * consumer's Temporal attempt number). The runner honors this ack — its floor
+     * advance AND its credit grant — ONLY for the HIGHEST generation it has seen for
+     * the op; a lower-generation (zombie) ack is ignored. This must ride the wire
+     * (not be inferred from monotonic acked_seq alone) because credit_bytes is an
+     * ABSOLUTE window REPLACEMENT: a stale consumer's ack could otherwise shrink the
+     * live consumer's window (stall) or grant unintended credit (B2).
+     */
+    attachGeneration: string;
+}
+/**
+ * Wraps an op-specific request. `request_id` correlates a response to a request
+ * even over fan-out; `epoch` carries the lease/active epoch the control plane
+ * resolved this op against, so the agent can reject a stale op (ERROR_CODE_FENCED).
+ */
+export interface ControlRequest {
+    requestId: string;
+    epoch: number;
+    op: {
+        $case: "ping";
+        ping: PingRequest;
+    } | {
+        $case: "hello";
+        hello: Hello;
+    } | {
+        $case: "resume";
+        resume: ResumeRequest;
+    } | {
+        $case: "exec";
+        exec: ExecRequest;
+    } | {
+        $case: "fsRead";
+        fsRead: FsReadRequest;
+    } | {
+        $case: "fsWrite";
+        fsWrite: FsWriteRequest;
+    } | {
+        $case: "fsList";
+        fsList: FsListRequest;
+    } | {
+        $case: "fsMkdir";
+        fsMkdir: FsMkdirRequest;
+    } | {
+        $case: "fsMove";
+        fsMove: FsMoveRequest;
+    } | {
+        $case: "fsStat";
+        fsStat: FsStatRequest;
+    } | {
+        $case: "fsRemove";
+        fsRemove: FsRemoveRequest;
+    } | {
+        $case: "git";
+        git: GitRequest;
+    } | {
+        $case: "ptyOpen";
+        ptyOpen: PtyOpenRequest;
+    } | {
+        $case: "ptyWrite";
+        ptyWrite: PtyWriteRequest;
+    } | {
+        $case: "ptyResize";
+        ptyResize: PtyResizeRequest;
+    } | {
+        $case: "ptyClose";
+        ptyClose: PtyCloseRequest;
+    } | {
+        $case: "desktopEnsure";
+        desktopEnsure: DesktopEnsureRequest;
+    } | {
+        $case: "metrics";
+        metrics: MetricsRequest;
+    } | {
+        $case: "updateMayProceed";
+        updateMayProceed: UpdateMayProceedRequest;
+    } | {
+        $case: "desktopInput";
+        desktopInput: DesktopInputRequest;
+    } | {
+        $case: "desktopScreenshot";
+        desktopScreenshot: DesktopScreenshotRequest;
+    } | //
+    /**
+     * Op-stream (v1.1), additive. All ride the same rpc subject; each has an
+     * idempotent, typed reply in ControlResponse.result below.
+     */
+    {
+        $case: "opStart";
+        opStart: OpStart;
+    } | {
+        $case: "opCancel";
+        opCancel: OpCancel;
+    } | {
+        $case: "opQuery";
+        opQuery: OpQuery;
+    } | {
+        $case: "opAttach";
+        opAttach: OpAttach;
+    } | {
+        $case: "writeChunk";
+        writeChunk: WriteChunk;
+    } | {
+        $case: "browserControlEnsure";
+        browserControlEnsure: BrowserControlEnsureRequest;
+    } | {
+        $case: "browserFramesOpen";
+        browserFramesOpen: BrowserFramesOpenRequest;
+    } | {
+        $case: "computerFramesOpen";
+        computerFramesOpen: ComputerFramesOpenRequest;
+    } | undefined;
+}
+/** Wraps an op-specific response, or an error. `request_id` echoes the request. */
+export interface ControlResponse {
+    requestId: string;
+    /** Present when the op failed; when set, `result` is empty. */
+    error: AgentError | undefined;
+    result: {
+        $case: "ping";
+        ping: PingResponse;
+    } | {
+        $case: "hello";
+        hello: HelloAck;
+    } | {
+        $case: "resume";
+        resume: ResumeResponse;
+    } | {
+        $case: "exec";
+        exec: ExecResponse;
+    } | {
+        $case: "fsRead";
+        fsRead: FsReadResponse;
+    } | {
+        $case: "fsWrite";
+        fsWrite: FsWriteResponse;
+    } | {
+        $case: "fsList";
+        fsList: FsListResponse;
+    } | {
+        $case: "fsMkdir";
+        fsMkdir: FsMkdirResponse;
+    } | {
+        $case: "fsMove";
+        fsMove: FsMoveResponse;
+    } | {
+        $case: "fsStat";
+        fsStat: FsStatResponse;
+    } | {
+        $case: "fsRemove";
+        fsRemove: FsRemoveResponse;
+    } | {
+        $case: "git";
+        git: GitResponse;
+    } | {
+        $case: "ptyOpen";
+        ptyOpen: PtyOpenResponse;
+    } | {
+        $case: "ptyWrite";
+        ptyWrite: PtyWriteResponse;
+    } | {
+        $case: "ptyResize";
+        ptyResize: PtyResizeResponse;
+    } | {
+        $case: "ptyClose";
+        ptyClose: PtyCloseResponse;
+    } | {
+        $case: "desktopEnsure";
+        desktopEnsure: DesktopEnsureResponse;
+    } | {
+        $case: "metrics";
+        metrics: MetricsSample;
+    } | {
+        $case: "updateMayProceed";
+        updateMayProceed: UpdateMayProceedResponse;
+    } | {
+        $case: "desktopInput";
+        desktopInput: DesktopInputResponse;
+    } | {
+        $case: "desktopScreenshot";
+        desktopScreenshot: DesktopScreenshotResponse;
+    } | //
+    /**
+     * Op-stream (v1.1) replies, additive. OpStart → OpStarted; OpCancel / OpQuery /
+     * OpAttach all reply OpStatus (op_status); WriteChunk → WriteChunkAck.
+     */
+    {
+        $case: "opStart";
+        opStart: OpStarted;
+    } | {
+        $case: "opStatus";
+        opStatus: OpStatus;
+    } | {
+        $case: "writeChunk";
+        writeChunk: WriteChunkAck;
+    } | {
+        $case: "browserControlEnsure";
+        browserControlEnsure: BrowserControlEnsureResponse;
+    } | {
+        $case: "browserFramesOpen";
+        browserFramesOpen: BrowserFramesOpenResponse;
+    } | {
+        $case: "computerFramesOpen";
+        computerFramesOpen: ComputerFramesOpenResponse;
+    } | undefined;
+}
+/**
+ * The control plane's acknowledgement of a Hello, carrying the epoch it assigned
+ * and a resume token for the next reconnect.
+ */
+export interface HelloAck {
+    epoch: number;
+    resumeToken: string;
+    /** The heartbeat interval the agent should use. */
+    heartbeatIntervalMs: number;
+}
+/**
+ * Wraps a message the AGENT originates (not a reply to a ControlRequest):
+ * heartbeats, the clean going-offline signal. These are published on the agent's
+ * outbound subject; the control plane folds them into lease/metrics state.
+ */
+export interface AgentEvent {
+    agentId: string;
+    event: {
+        $case: "heartbeat";
+        heartbeat: Heartbeat;
+    } | {
+        $case: "goingOffline";
+        goingOffline: GoingOffline;
+    } | undefined;
+}
+/** The control plane's ack of an AgentEvent (e.g. a HeartbeatAck). */
+export interface AgentEventAck {
+    ack: {
+        $case: "heartbeat";
+        heartbeat: HeartbeatAck;
+    } | undefined;
+}
+/**
+ * Identifies a relay stream channel. The viewer/pty client connects to the
+ * relay with this channel's coordinates plus a scoped `ogs_` token; the agent
+ * dials out and registers the same channel. `{workspace_id, agent_id, port}`
+ * is the routing key.
+ */
+export interface StreamChannel {
+    channelId: string;
+    workspaceId: string;
+    agentId: string;
+    kind: StreamKind;
+    /** The logical port the channel maps to (so resolveExposedPort can address it). */
+    port: number;
+}
+/**
+ * Open a stream channel on the relay. Sent by both ends (agent registers; client
+ * attaches) as the first frame of a relay connection.
+ */
+export interface StreamOpen {
+    channel: StreamChannel | undefined;
+    /**
+     * The scoped stream token (`ogs_` envelope) authorizing this channel; the
+     * relay validates authenticity + the lease/active-epoch fence.
+     */
+    token: string;
+    /** Whether the sender is the producing agent or the consuming viewer. */
+    role: StreamRole;
+    /**
+     * For resume: the last frame sequence the sender successfully processed, so
+     * the peer can replay from there after a reconnect blip.
+     */
+    resumeFromSeq: string;
+}
+/** The relay's acknowledgement of a StreamOpen. */
+export interface StreamOpenAck {
+    accepted: boolean;
+    error: AgentError | undefined;
+    /** The sequence the peer will resume sending from. */
+    resumeFromSeq: string;
+}
+/**
+ * A data frame carrying raw stream bytes in either direction. `seq` is a
+ * monotonic per-channel-per-direction counter enabling resume-from-seq. For a
+ * DESKTOP channel `data` is an encoded framebuffer chunk; for PTY it is raw tty
+ * bytes. Input (client→agent) for desktop computer-use rides DesktopInput
+ * instead so synthetic events are typed, not opaque bytes.
+ */
+export interface StreamFrame {
+    channelId: string;
+    seq: string;
+    data: Uint8Array;
+    /** Unix epoch ms the frame was produced (for latency/lag metrics). */
+    producedAtMs: string;
+}
+/**
+ * Close a stream channel. Either end may send it; the relay tears down the
+ * channel and notifies the peer.
+ */
+export interface StreamClose {
+    channelId: string;
+    reason: StreamCloseReason;
+    message: string;
+}
+/**
+ * Typed computer-use input from a client to a desktop channel (client→agent).
+ * Synthetic input is gated on consented_screen_control; an ungated input op
+ * fails with ERROR_CODE_CONSENT_REQUIRED.
+ */
+export interface DesktopInput {
+    channelId: string;
+    event: {
+        $case: "pointer";
+        pointer: PointerEvent;
+    } | {
+        $case: "key";
+        key: KeyEvent;
+    } | {
+        $case: "scroll";
+        scroll: ScrollEvent;
+    } | undefined;
+}
+export interface PointerEvent {
+    x: number;
+    y: number;
+    action: PointerAction;
+    button: PointerButton;
+}
+export interface KeyEvent {
+    /** A platform-independent key name (e.g. "Enter", "a", "ctrl+c") OR text to type. */
+    key: string;
+    isText: boolean;
+    action: KeyAction;
+}
+export interface ScrollEvent {
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+}
+export declare const AgentError: MessageFns<AgentError>;
+export declare const AgentError_DetailEntry: MessageFns<AgentError_DetailEntry>;
+export declare const Hello: MessageFns<Hello>;
+export declare const Capabilities: MessageFns<Capabilities>;
+export declare const AttachedBrowserDeviceCapabilities: MessageFns<AttachedBrowserDeviceCapabilities>;
+export declare const AttachedBrowserDeviceAnnouncement: MessageFns<AttachedBrowserDeviceAnnouncement>;
+export declare const AttachedBrowserInventorySnapshot: MessageFns<AttachedBrowserInventorySnapshot>;
+export declare const Display: MessageFns<Display>;
+export declare const DeviceAuthStartRequest: MessageFns<DeviceAuthStartRequest>;
+export declare const DeviceAuthStartResponse: MessageFns<DeviceAuthStartResponse>;
+export declare const DeviceAuthPollRequest: MessageFns<DeviceAuthPollRequest>;
+export declare const DeviceAuthPollResponse: MessageFns<DeviceAuthPollResponse>;
+export declare const EnrollmentCredentials: MessageFns<EnrollmentCredentials>;
+export declare const ExecRequest: MessageFns<ExecRequest>;
+export declare const ExecRequest_EnvEntry: MessageFns<ExecRequest_EnvEntry>;
+export declare const ExecResponse: MessageFns<ExecResponse>;
+export declare const FsReadRequest: MessageFns<FsReadRequest>;
+export declare const FsReadResponse: MessageFns<FsReadResponse>;
+export declare const FsWriteRequest: MessageFns<FsWriteRequest>;
+export declare const FsWriteResponse: MessageFns<FsWriteResponse>;
+export declare const FsListRequest: MessageFns<FsListRequest>;
+export declare const FsListResponse: MessageFns<FsListResponse>;
+export declare const FsEntry: MessageFns<FsEntry>;
+export declare const FsMkdirRequest: MessageFns<FsMkdirRequest>;
+export declare const FsMkdirResponse: MessageFns<FsMkdirResponse>;
+export declare const FsMoveRequest: MessageFns<FsMoveRequest>;
+export declare const FsMoveResponse: MessageFns<FsMoveResponse>;
+export declare const FsStatRequest: MessageFns<FsStatRequest>;
+export declare const FsStatResponse: MessageFns<FsStatResponse>;
+export declare const FsRemoveRequest: MessageFns<FsRemoveRequest>;
+export declare const FsRemoveResponse: MessageFns<FsRemoveResponse>;
+export declare const GitRequest: MessageFns<GitRequest>;
+export declare const GitResponse: MessageFns<GitResponse>;
+export declare const GitStatus: MessageFns<GitStatus>;
+export declare const GitFileStatus: MessageFns<GitFileStatus>;
+export declare const PtyOpenRequest: MessageFns<PtyOpenRequest>;
+export declare const PtyOpenRequest_EnvEntry: MessageFns<PtyOpenRequest_EnvEntry>;
+export declare const PtyOpenResponse: MessageFns<PtyOpenResponse>;
+export declare const PtyWriteRequest: MessageFns<PtyWriteRequest>;
+export declare const PtyWriteResponse: MessageFns<PtyWriteResponse>;
+export declare const PtyResizeRequest: MessageFns<PtyResizeRequest>;
+export declare const PtyResizeResponse: MessageFns<PtyResizeResponse>;
+export declare const PtyCloseRequest: MessageFns<PtyCloseRequest>;
+export declare const PtyCloseResponse: MessageFns<PtyCloseResponse>;
+export declare const DesktopEnsureRequest: MessageFns<DesktopEnsureRequest>;
+export declare const DesktopEnsureResponse: MessageFns<DesktopEnsureResponse>;
+export declare const DesktopInputRequest: MessageFns<DesktopInputRequest>;
+export declare const DesktopInputResponse: MessageFns<DesktopInputResponse>;
+export declare const DesktopScreenshotRequest: MessageFns<DesktopScreenshotRequest>;
+export declare const DesktopScreenshotResponse: MessageFns<DesktopScreenshotResponse>;
+export declare const BrowserControlEnsureRequest: MessageFns<BrowserControlEnsureRequest>;
+export declare const BrowserControlEnsureResponse: MessageFns<BrowserControlEnsureResponse>;
+export declare const BrowserFramesOpenRequest: MessageFns<BrowserFramesOpenRequest>;
+export declare const BrowserFramesOpenResponse: MessageFns<BrowserFramesOpenResponse>;
+export declare const ComputerFramesOpenRequest: MessageFns<ComputerFramesOpenRequest>;
+export declare const ComputerFramesOpenResponse: MessageFns<ComputerFramesOpenResponse>;
+export declare const Heartbeat: MessageFns<Heartbeat>;
+export declare const HostCapacitySample: MessageFns<HostCapacitySample>;
+export declare const AdmissionTelemetry: MessageFns<AdmissionTelemetry>;
+export declare const HeartbeatAck: MessageFns<HeartbeatAck>;
+export declare const MetricsRequest: MessageFns<MetricsRequest>;
+export declare const MetricsSample: MessageFns<MetricsSample>;
+export declare const GpuSample: MessageFns<GpuSample>;
+export declare const PingRequest: MessageFns<PingRequest>;
+export declare const PingResponse: MessageFns<PingResponse>;
+export declare const GoingOffline: MessageFns<GoingOffline>;
+export declare const ResumeRequest: MessageFns<ResumeRequest>;
+export declare const ResumeResponse: MessageFns<ResumeResponse>;
+export declare const UpdateCheckRequest: MessageFns<UpdateCheckRequest>;
+export declare const UpdateCheckResponse: MessageFns<UpdateCheckResponse>;
+export declare const UpdateManifest: MessageFns<UpdateManifest>;
+export declare const UpdateArtifact: MessageFns<UpdateArtifact>;
+export declare const UpdateMayProceedRequest: MessageFns<UpdateMayProceedRequest>;
+export declare const UpdateMayProceedResponse: MessageFns<UpdateMayProceedResponse>;
+export declare const OpExit: MessageFns<OpExit>;
+export declare const OpExit_DigestsEntry: MessageFns<OpExit_DigestsEntry>;
+export declare const OpExit_TotalsEntry: MessageFns<OpExit_TotalsEntry>;
+export declare const OpExit_FailureDetailEntry: MessageFns<OpExit_FailureDetailEntry>;
+export declare const FsWriteBegin: MessageFns<FsWriteBegin>;
+export declare const OpStart: MessageFns<OpStart>;
+export declare const OpStarted: MessageFns<OpStarted>;
+export declare const OpCancel: MessageFns<OpCancel>;
+export declare const OpQuery: MessageFns<OpQuery>;
+export declare const OpAttach: MessageFns<OpAttach>;
+export declare const OpStatus: MessageFns<OpStatus>;
+export declare const WriteChunk: MessageFns<WriteChunk>;
+export declare const WriteChunkAck: MessageFns<WriteChunkAck>;
+export declare const OpFrame: MessageFns<OpFrame>;
+export declare const OpData: MessageFns<OpData>;
+export declare const OpProgress: MessageFns<OpProgress>;
+export declare const OpAck: MessageFns<OpAck>;
+export declare const ControlRequest: MessageFns<ControlRequest>;
+export declare const ControlResponse: MessageFns<ControlResponse>;
+export declare const HelloAck: MessageFns<HelloAck>;
+export declare const AgentEvent: MessageFns<AgentEvent>;
+export declare const AgentEventAck: MessageFns<AgentEventAck>;
+export declare const StreamChannel: MessageFns<StreamChannel>;
+export declare const StreamOpen: MessageFns<StreamOpen>;
+export declare const StreamOpenAck: MessageFns<StreamOpenAck>;
+export declare const StreamFrame: MessageFns<StreamFrame>;
+export declare const StreamClose: MessageFns<StreamClose>;
+export declare const DesktopInput: MessageFns<DesktopInput>;
+export declare const PointerEvent: MessageFns<PointerEvent>;
+export declare const KeyEvent: MessageFns<KeyEvent>;
+export declare const ScrollEvent: MessageFns<ScrollEvent>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {
+    $case: string;
+} ? {
+    [K in keyof Omit<T, "$case">]?: DeepPartial<T[K]>;
+} & {
+    $case: T["$case"];
+} : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};