@opengeni/agent-proto 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1080 @@
+import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
+
+declare const protobufPackage = "opengeni.agent.v1";
+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
+}
+declare function errorCodeFromJSON(object: any): ErrorCode;
+declare function errorCodeToJSON(object: ErrorCode): string;
+/** The operating system family the agent runs on. */
+declare enum Os {
+    OS_UNSPECIFIED = 0,
+    OS_LINUX = 1,
+    OS_MACOS = 2,
+    OS_WINDOWS = 3
+}
+declare function osFromJSON(object: any): Os;
+declare function osToJSON(object: Os): string;
+/** CPU architecture. */
+declare enum Arch {
+    ARCH_UNSPECIFIED = 0,
+    ARCH_X86_64 = 1,
+    ARCH_AARCH64 = 2
+}
+declare function archFromJSON(object: any): Arch;
+declare function archToJSON(object: Arch): string;
+/** The kind of byte stream a relay channel carries. */
+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
+}
+declare function streamKindFromJSON(object: any): StreamKind;
+declare function streamKindToJSON(object: StreamKind): string;
+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
+}
+declare function deviceAuthStateFromJSON(object: any): DeviceAuthState;
+declare function deviceAuthStateToJSON(object: DeviceAuthState): string;
+declare enum FsEntryKind {
+    FS_ENTRY_KIND_UNSPECIFIED = 0,
+    FS_ENTRY_KIND_FILE = 1,
+    FS_ENTRY_KIND_DIRECTORY = 2,
+    FS_ENTRY_KIND_SYMLINK = 3
+}
+declare function fsEntryKindFromJSON(object: any): FsEntryKind;
+declare function fsEntryKindToJSON(object: FsEntryKind): string;
+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
+}
+declare function gitOpFromJSON(object: any): GitOp;
+declare function gitOpToJSON(object: GitOp): string;
+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
+}
+declare function goingOfflineReasonFromJSON(object: any): GoingOfflineReason;
+declare function goingOfflineReasonToJSON(object: GoingOfflineReason): string;
+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
+}
+declare function streamRoleFromJSON(object: any): StreamRole;
+declare function streamRoleToJSON(object: StreamRole): string;
+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
+}
+declare function streamCloseReasonFromJSON(object: any): StreamCloseReason;
+declare function streamCloseReasonToJSON(object: StreamCloseReason): string;
+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
+}
+declare function pointerActionFromJSON(object: any): PointerAction;
+declare function pointerActionToJSON(object: PointerAction): string;
+declare enum PointerButton {
+    POINTER_BUTTON_UNSPECIFIED = 0,
+    POINTER_BUTTON_LEFT = 1,
+    POINTER_BUTTON_RIGHT = 2,
+    POINTER_BUTTON_MIDDLE = 3
+}
+declare function pointerButtonFromJSON(object: any): PointerButton;
+declare function pointerButtonToJSON(object: PointerButton): string;
+declare enum KeyAction {
+    KEY_ACTION_UNSPECIFIED = 0,
+    KEY_ACTION_DOWN = 1,
+    KEY_ACTION_UP = 2,
+    KEY_ACTION_PRESS = 3
+}
+declare function keyActionFromJSON(object: any): KeyAction;
+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.
+ */
+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;
+    };
+}
+declare const AgentError: MessageFns<AgentError>;
+interface AgentError_DetailEntry {
+    key: string;
+    value: string;
+}
+declare const AgentError_DetailEntry: MessageFns<AgentError_DetailEntry>;
+/**
+ * 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).
+ */
+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;
+}
+declare const Hello: MessageFns<Hello>;
+/**
+ * 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.
+ */
+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;
+}
+declare const Capabilities: MessageFns<Capabilities>;
+/** Detail about the agent's graphical display, when one is present. */
+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;
+}
+declare const Display: MessageFns<Display>;
+/**
+ * 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.
+ */
+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;
+}
+declare const DeviceAuthStartRequest: MessageFns<DeviceAuthStartRequest>;
+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;
+}
+declare const DeviceAuthStartResponse: MessageFns<DeviceAuthStartResponse>;
+/** The agent polls until the user authorizes (or it expires / is denied). */
+interface DeviceAuthPollRequest {
+    deviceCode: string;
+}
+declare const DeviceAuthPollRequest: MessageFns<DeviceAuthPollRequest>;
+interface DeviceAuthPollResponse {
+    state: DeviceAuthState;
+    /** Present only when state == AUTHORIZED. */
+    credentials: EnrollmentCredentials | undefined;
+}
+declare const DeviceAuthPollResponse: MessageFns<DeviceAuthPollResponse>;
+/**
+ * The scoped credentials persisted (0600) on the machine after enrollment.
+ * These are workspace-scoped — they can address only this workspace's agents.
+ */
+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 (dossier §10.1 / 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 (dossier M-AUTH).
+     */
+    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 (dossier §10.5 / 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;
+}
+declare const EnrollmentCredentials: MessageFns<EnrollmentCredentials>;
+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;
+    /** Hard wall-clock timeout; 0 means the control-plane default. */
+    timeoutMs: number;
+}
+declare const ExecRequest: MessageFns<ExecRequest>;
+interface ExecRequest_EnvEntry {
+    key: string;
+    value: string;
+}
+declare const ExecRequest_EnvEntry: MessageFns<ExecRequest_EnvEntry>;
+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;
+}
+declare const ExecResponse: MessageFns<ExecResponse>;
+interface FsReadRequest {
+    path: string;
+    /** Optional byte offset + length for ranged reads (0 length => to EOF). */
+    offset: string;
+    length: string;
+}
+declare const FsReadRequest: MessageFns<FsReadRequest>;
+interface FsReadResponse {
+    content: Uint8Array;
+    /** Total size of the file (so a ranged read knows there is more). */
+    totalSize: string;
+}
+declare const FsReadResponse: MessageFns<FsReadResponse>;
+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;
+}
+declare const FsWriteRequest: MessageFns<FsWriteRequest>;
+interface FsWriteResponse {
+    bytesWritten: string;
+}
+declare const FsWriteResponse: MessageFns<FsWriteResponse>;
+interface FsListRequest {
+    path: string;
+    /** Recurse into subdirectories. */
+    recursive: boolean;
+}
+declare const FsListRequest: MessageFns<FsListRequest>;
+interface FsListResponse {
+    entries: FsEntry[];
+}
+declare const FsListResponse: MessageFns<FsListResponse>;
+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;
+}
+declare const FsEntry: MessageFns<FsEntry>;
+interface FsMkdirRequest {
+    path: string;
+    /** Create intermediate directories (mkdir -p). */
+    parents: boolean;
+    mode: number;
+}
+declare const FsMkdirRequest: MessageFns<FsMkdirRequest>;
+interface FsMkdirResponse {
+}
+declare const FsMkdirResponse: MessageFns<FsMkdirResponse>;
+interface FsMoveRequest {
+    from: string;
+    to: string;
+    /** Overwrite the destination if it exists. */
+    overwrite: boolean;
+}
+declare const FsMoveRequest: MessageFns<FsMoveRequest>;
+interface FsMoveResponse {
+}
+declare const FsMoveResponse: MessageFns<FsMoveResponse>;
+interface FsStatRequest {
+    path: string;
+}
+declare const FsStatRequest: MessageFns<FsStatRequest>;
+interface FsStatResponse {
+    /** Absent when the path does not exist (the op still succeeds; `exists=false`). */
+    exists: boolean;
+    entry: FsEntry | undefined;
+}
+declare const FsStatResponse: MessageFns<FsStatResponse>;
+interface FsRemoveRequest {
+    path: string;
+    /** Remove directories recursively. */
+    recursive: boolean;
+}
+declare const FsRemoveRequest: MessageFns<FsRemoveRequest>;
+interface FsRemoveResponse {
+}
+declare const FsRemoveResponse: MessageFns<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.
+ */
+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[];
+}
+declare const GitRequest: MessageFns<GitRequest>;
+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;
+}
+declare const GitResponse: MessageFns<GitResponse>;
+interface GitStatus {
+    branch: string;
+    /** The upstream tracking branch, if any. */
+    upstream: string;
+    ahead: number;
+    behind: number;
+    files: GitFileStatus[];
+    clean: boolean;
+}
+declare const GitStatus: MessageFns<GitStatus>;
+interface GitFileStatus {
+    path: string;
+    /** Two-letter porcelain code (e.g. " M", "??", "A "). */
+    code: string;
+    staged: boolean;
+}
+declare const GitFileStatus: MessageFns<GitFileStatus>;
+/**
+ * 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.
+ */
+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;
+}
+declare const PtyOpenRequest: MessageFns<PtyOpenRequest>;
+interface PtyOpenRequest_EnvEntry {
+    key: string;
+    value: string;
+}
+declare const PtyOpenRequest_EnvEntry: MessageFns<PtyOpenRequest_EnvEntry>;
+interface PtyOpenResponse {
+    /** A handle for subsequent resize/close control ops. */
+    ptyId: string;
+    /** The relay stream channel carrying the PTY bytes. */
+    channel: StreamChannel | undefined;
+}
+declare const PtyOpenResponse: MessageFns<PtyOpenResponse>;
+/**
+ * Write input bytes to a PTY. (Bulk interactive bytes normally ride the stream
+ * plane as StreamFrames; this control op exists for programmatic injection.)
+ */
+interface PtyWriteRequest {
+    ptyId: string;
+    data: Uint8Array;
+}
+declare const PtyWriteRequest: MessageFns<PtyWriteRequest>;
+interface PtyWriteResponse {
+    bytesWritten: string;
+}
+declare const PtyWriteResponse: MessageFns<PtyWriteResponse>;
+interface PtyResizeRequest {
+    ptyId: string;
+    cols: number;
+    rows: number;
+}
+declare const PtyResizeRequest: MessageFns<PtyResizeRequest>;
+interface PtyResizeResponse {
+}
+declare const PtyResizeResponse: MessageFns<PtyResizeResponse>;
+interface PtyCloseRequest {
+    ptyId: string;
+}
+declare const PtyCloseRequest: MessageFns<PtyCloseRequest>;
+interface PtyCloseResponse {
+    /** The exit code of the PTY's root process, if it had exited. */
+    exitCode: number;
+}
+declare const PtyCloseResponse: MessageFns<PtyCloseResponse>;
+/**
+ * Ensure a desktop framebuffer stream exists, registering a relay channel of
+ * kind DESKTOP. Idempotent: repeated calls return the same live channel.
+ */
+interface DesktopEnsureRequest {
+    /** Request a specific geometry (0 => the display's native geometry). */
+    width: number;
+    height: number;
+}
+declare const DesktopEnsureRequest: MessageFns<DesktopEnsureRequest>;
+interface DesktopEnsureResponse {
+    channel: StreamChannel | undefined;
+    display: Display | undefined;
+}
+declare const DesktopEnsureResponse: MessageFns<DesktopEnsureResponse>;
+/**
+ * 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.
+ */
+interface DesktopInputRequest {
+    event: {
+        $case: "pointer";
+        pointer: PointerEvent;
+    } | {
+        $case: "key";
+        key: KeyEvent;
+    } | {
+        $case: "scroll";
+        scroll: ScrollEvent;
+    } | undefined;
+}
+declare const DesktopInputRequest: MessageFns<DesktopInputRequest>;
+interface DesktopInputResponse {
+}
+declare const DesktopInputResponse: MessageFns<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.
+ */
+interface DesktopScreenshotRequest {
+}
+declare const DesktopScreenshotRequest: MessageFns<DesktopScreenshotRequest>;
+interface DesktopScreenshotResponse {
+    png: Uint8Array;
+    width: number;
+    height: number;
+}
+declare const DesktopScreenshotResponse: MessageFns<DesktopScreenshotResponse>;
+/**
+ * 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.
+ */
+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;
+}
+declare const Heartbeat: MessageFns<Heartbeat>;
+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;
+}
+declare const HeartbeatAck: MessageFns<HeartbeatAck>;
+/** On-demand metrics request (the dashboard force-poll path). */
+interface MetricsRequest {
+}
+declare const MetricsRequest: MessageFns<MetricsRequest>;
+/** A point-in-time machine metrics sample. */
+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[];
+}
+declare const MetricsSample: MessageFns<MetricsSample>;
+interface GpuSample {
+    name: string;
+    /** Utilization 0..100. */
+    utilPercent: number;
+    memUsedBytes: string;
+    memTotalBytes: string;
+}
+declare const GpuSample: MessageFns<GpuSample>;
+/**
+ * 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).
+ */
+interface PingRequest {
+    /** Echoed back so the caller can correlate / measure RTT. */
+    nonce: string;
+}
+declare const PingRequest: MessageFns<PingRequest>;
+interface PingResponse {
+    nonce: string;
+    /** The agent's monotonic clock, for skew estimation. */
+    agentMonotonicMs: string;
+}
+declare const PingResponse: MessageFns<PingResponse>;
+/**
+ * Sent by the agent on a clean stop (SIGINT/SIGTERM) so the lease flips to
+ * offline IMMEDIATELY rather than waiting on heartbeat dead-detection.
+ */
+interface GoingOffline {
+    reason: GoingOfflineReason;
+    /** Optional human note (e.g. "user pressed Ctrl-C"). */
+    message: string;
+}
+declare const GoingOffline: MessageFns<GoingOffline>;
+/**
+ * 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.
+ */
+interface ResumeRequest {
+    agentId: string;
+    resumeToken: string;
+    /** The lease epoch the agent last observed, for the integer fence. */
+    lastKnownEpoch: number;
+}
+declare const ResumeRequest: MessageFns<ResumeRequest>;
+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;
+}
+declare const ResumeResponse: MessageFns<ResumeResponse>;
+/** The agent asks whether a newer build is available for its channel + target. */
+interface UpdateCheckRequest {
+    currentVersion: string;
+    channel: string;
+    os: Os;
+    arch: Arch;
+}
+declare const UpdateCheckRequest: MessageFns<UpdateCheckRequest>;
+interface UpdateCheckResponse {
+    updateAvailable: boolean;
+    manifest: UpdateManifest | undefined;
+}
+declare const UpdateCheckResponse: MessageFns<UpdateCheckResponse>;
+/**
+ * A signed channel manifest. It is itself minisign-signed out-of-band; this
+ * message is the decoded body the updater reasons over.
+ */
+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;
+}
+declare const UpdateManifest: MessageFns<UpdateManifest>;
+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;
+}
+declare const UpdateArtifact: MessageFns<UpdateArtifact>;
+/**
+ * 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.
+ */
+interface UpdateMayProceedRequest {
+    agentId: string;
+    targetVersion: string;
+}
+declare const UpdateMayProceedRequest: MessageFns<UpdateMayProceedRequest>;
+interface UpdateMayProceedResponse {
+    mayProceed: boolean;
+    /** When false, the number of live sessions blocking the update. */
+    activeSessions: number;
+}
+declare const UpdateMayProceedResponse: MessageFns<UpdateMayProceedResponse>;
+/**
+ * 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).
+ */
+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;
+    } | undefined;
+}
+declare const ControlRequest: MessageFns<ControlRequest>;
+/** Wraps an op-specific response, or an error. `request_id` echoes the request. */
+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;
+    } | undefined;
+}
+declare const ControlResponse: MessageFns<ControlResponse>;
+/**
+ * The control plane's acknowledgement of a Hello, carrying the epoch it assigned
+ * and a resume token for the next reconnect.
+ */
+interface HelloAck {
+    epoch: number;
+    resumeToken: string;
+    /** The heartbeat interval the agent should use. */
+    heartbeatIntervalMs: number;
+}
+declare const HelloAck: MessageFns<HelloAck>;
+/**
+ * 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.
+ */
+interface AgentEvent {
+    agentId: string;
+    event: {
+        $case: "heartbeat";
+        heartbeat: Heartbeat;
+    } | {
+        $case: "goingOffline";
+        goingOffline: GoingOffline;
+    } | undefined;
+}
+declare const AgentEvent: MessageFns<AgentEvent>;
+/** The control plane's ack of an AgentEvent (e.g. a HeartbeatAck). */
+interface AgentEventAck {
+    ack: {
+        $case: "heartbeat";
+        heartbeat: HeartbeatAck;
+    } | undefined;
+}
+declare const AgentEventAck: MessageFns<AgentEventAck>;
+/**
+ * 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.
+ */
+interface StreamChannel {
+    channelId: string;
+    workspaceId: string;
+    agentId: string;
+    kind: StreamKind;
+    /** The logical port the channel maps to (so resolveExposedPort can address it). */
+    port: number;
+}
+declare const StreamChannel: MessageFns<StreamChannel>;
+/**
+ * Open a stream channel on the relay. Sent by both ends (agent registers; client
+ * attaches) as the first frame of a relay connection.
+ */
+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;
+}
+declare const StreamOpen: MessageFns<StreamOpen>;
+/** The relay's acknowledgement of a StreamOpen. */
+interface StreamOpenAck {
+    accepted: boolean;
+    error: AgentError | undefined;
+    /** The sequence the peer will resume sending from. */
+    resumeFromSeq: string;
+}
+declare const StreamOpenAck: MessageFns<StreamOpenAck>;
+/**
+ * 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.
+ */
+interface StreamFrame {
+    channelId: string;
+    seq: string;
+    data: Uint8Array;
+    /** Unix epoch ms the frame was produced (for latency/lag metrics). */
+    producedAtMs: string;
+}
+declare const StreamFrame: MessageFns<StreamFrame>;
+/**
+ * Close a stream channel. Either end may send it; the relay tears down the
+ * channel and notifies the peer.
+ */
+interface StreamClose {
+    channelId: string;
+    reason: StreamCloseReason;
+    message: string;
+}
+declare const StreamClose: MessageFns<StreamClose>;
+/**
+ * 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.
+ */
+interface DesktopInput {
+    channelId: string;
+    event: {
+        $case: "pointer";
+        pointer: PointerEvent;
+    } | {
+        $case: "key";
+        key: KeyEvent;
+    } | {
+        $case: "scroll";
+        scroll: ScrollEvent;
+    } | undefined;
+}
+declare const DesktopInput: MessageFns<DesktopInput>;
+interface PointerEvent {
+    x: number;
+    y: number;
+    action: PointerAction;
+    button: PointerButton;
+}
+declare const PointerEvent: MessageFns<PointerEvent>;
+interface KeyEvent {
+    /** A platform-independent key name (e.g. "Enter", "a", "ctrl+c") OR text to type. */
+    key: string;
+    isText: boolean;
+    action: KeyAction;
+}
+declare const KeyEvent: MessageFns<KeyEvent>;
+interface ScrollEvent {
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+}
+declare const ScrollEvent: MessageFns<ScrollEvent>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+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;
+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;
+};
+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 { AgentError, AgentError_DetailEntry, AgentEvent, AgentEventAck, Arch, Capabilities, ControlRequest, ControlResponse, type DeepPartial, DesktopEnsureRequest, DesktopEnsureResponse, DesktopInput, DesktopInputRequest, DesktopInputResponse, DesktopScreenshotRequest, DesktopScreenshotResponse, DeviceAuthPollRequest, DeviceAuthPollResponse, DeviceAuthStartRequest, DeviceAuthStartResponse, DeviceAuthState, Display, EnrollmentCredentials, ErrorCode, type Exact, ExecRequest, ExecRequest_EnvEntry, ExecResponse, FsEntry, FsEntryKind, FsListRequest, FsListResponse, FsMkdirRequest, FsMkdirResponse, FsMoveRequest, FsMoveResponse, FsReadRequest, FsReadResponse, FsRemoveRequest, FsRemoveResponse, FsStatRequest, FsStatResponse, FsWriteRequest, FsWriteResponse, GitFileStatus, GitOp, GitRequest, GitResponse, GitStatus, GoingOffline, GoingOfflineReason, GpuSample, Heartbeat, HeartbeatAck, Hello, HelloAck, KeyAction, KeyEvent, type MessageFns, MetricsRequest, MetricsSample, Os, PingRequest, PingResponse, PointerAction, PointerButton, PointerEvent, PtyCloseRequest, PtyCloseResponse, PtyOpenRequest, PtyOpenRequest_EnvEntry, PtyOpenResponse, PtyResizeRequest, PtyResizeResponse, PtyWriteRequest, PtyWriteResponse, ResumeRequest, ResumeResponse, ScrollEvent, StreamChannel, StreamClose, StreamCloseReason, StreamFrame, StreamKind, StreamOpen, StreamOpenAck, StreamRole, UpdateArtifact, UpdateCheckRequest, UpdateCheckResponse, UpdateManifest, UpdateMayProceedRequest, UpdateMayProceedResponse, archFromJSON, archToJSON, deviceAuthStateFromJSON, deviceAuthStateToJSON, errorCodeFromJSON, errorCodeToJSON, fsEntryKindFromJSON, fsEntryKindToJSON, gitOpFromJSON, gitOpToJSON, goingOfflineReasonFromJSON, goingOfflineReasonToJSON, keyActionFromJSON, keyActionToJSON, osFromJSON, osToJSON, pointerActionFromJSON, pointerActionToJSON, pointerButtonFromJSON, pointerButtonToJSON, protobufPackage, streamCloseReasonFromJSON, streamCloseReasonToJSON, streamKindFromJSON, streamKindToJSON, streamRoleFromJSON, streamRoleToJSON };