@opengeni/agent-proto 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Cloudgeni-ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -22,7 +22,15 @@ declare enum ErrorCode {
     /** 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_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
 }
 declare function errorCodeFromJSON(object: any): ErrorCode;
 declare function errorCodeToJSON(object: ErrorCode): string;
@@ -103,6 +111,45 @@ declare enum GoingOfflineReason {
 }
 declare function goingOfflineReasonFromJSON(object: any): GoingOfflineReason;
 declare function goingOfflineReasonToJSON(object: GoingOfflineReason): string;
+/** The logical byte stream an op-frame Data chunk belongs to. */
+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
+}
+declare function opChannelFromJSON(object: any): OpChannel;
+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.
+ */
+declare enum OpState {
+    OP_STATE_UNSPECIFIED = 0,
+    OP_STATE_ACCEPTED = 1,
+    OP_STATE_RUNNING = 2,
+    OP_STATE_COMPLETE = 3,
+    OP_STATE_LOST = 4
+}
+declare function opStateFromJSON(object: any): OpState;
+declare function opStateToJSON(object: OpState): string;
+/** Why a lost op is lost (present iff OpStatus.state == OP_STATE_LOST). */
+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
+}
+declare function opLostReasonFromJSON(object: any): OpLostReason;
+declare function opLostReasonToJSON(object: OpLostReason): string;
 declare enum StreamRole {
     STREAM_ROLE_UNSPECIFIED = 0,
     /** STREAM_ROLE_AGENT - The agent producing pty/desktop bytes. */
@@ -221,6 +268,24 @@ interface Capabilities {
     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;
 }
 declare const Capabilities: MessageFns<Capabilities>;
 /** Detail about the agent's graphical display, when one is present. */
@@ -593,8 +658,24 @@ interface DesktopScreenshotRequest {
 declare const DesktopScreenshotRequest: MessageFns<DesktopScreenshotRequest>;
 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;
 }
 declare const DesktopScreenshotResponse: MessageFns<DesktopScreenshotResponse>;
 /**
@@ -617,8 +698,57 @@ interface Heartbeat {
      * 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;
 }
 declare const Heartbeat: MessageFns<Heartbeat>;
+/**
+ * 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.
+ */
+interface HostCapacitySample {
+    memAvailableBytes: string;
+    diskFreeBytes: string;
+    fdHeadroom: string;
+    pidHeadroom: string;
+    nproc: string;
+}
+declare const HostCapacitySample: MessageFns<HostCapacitySample>;
+/** Point-in-time op-admission counts, per class. */
+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;
+}
+declare const AdmissionTelemetry: MessageFns<AdmissionTelemetry>;
 interface HeartbeatAck {
     /** The control plane may instruct the agent to adjust its heartbeat cadence. */
     nextIntervalMs: number;
@@ -764,6 +894,243 @@ interface UpdateMayProceedResponse {
     activeSessions: number;
 }
 declare const UpdateMayProceedResponse: MessageFns<UpdateMayProceedResponse>;
+/**
+ * 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.
+ */
+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;
+    };
+}
+declare const OpExit: MessageFns<OpExit>;
+interface OpExit_DigestsEntry {
+    key: string;
+    value: string;
+}
+declare const OpExit_DigestsEntry: MessageFns<OpExit_DigestsEntry>;
+interface OpExit_TotalsEntry {
+    key: string;
+    value: string;
+}
+declare const OpExit_TotalsEntry: MessageFns<OpExit_TotalsEntry>;
+interface OpExit_FailureDetailEntry {
+    key: string;
+    value: string;
+}
+declare const OpExit_FailureDetailEntry: MessageFns<OpExit_FailureDetailEntry>;
+/**
+ * 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).
+ */
+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;
+}
+declare const FsWriteBegin: MessageFns<FsWriteBegin>;
+/**
+ * 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).
+ */
+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;
+}
+declare const OpStart: MessageFns<OpStart>;
+interface OpStarted {
+    accepted: boolean;
+    status: OpStatus | undefined;
+}
+declare const OpStarted: MessageFns<OpStarted>;
+/**
+ * Cancel an op (server→runner). Idempotent; triggers the #344 process-tree kill and
+ * a terminal frame. Reply is OpStatus.
+ */
+interface OpCancel {
+    opId: string;
+}
+declare const OpCancel: MessageFns<OpCancel>;
+/** Query an op's status (server→runner). Reply is OpStatus. */
+interface OpQuery {
+    opId: string;
+}
+declare const OpQuery: MessageFns<OpQuery>;
+/**
+ * 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.
+ */
+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;
+}
+declare const OpAttach: MessageFns<OpAttach>;
+/**
+ * The current status of an op (server←runner reply to OpCancel/OpQuery/OpAttach,
+ * and embedded in OpStarted).
+ */
+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;
+}
+declare const OpStatus: MessageFns<OpStatus>;
+/**
+ * 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.
+ */
+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;
+}
+declare const WriteChunk: MessageFns<WriteChunk>;
+interface WriteChunkAck {
+    seq: string;
+}
+declare const WriteChunkAck: MessageFns<WriteChunkAck>;
+/**
+ * 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).
+ */
+interface OpFrame {
+    opId: string;
+    seq: string;
+    body: {
+        $case: "data";
+        data: OpData;
+    } | {
+        $case: "progress";
+        progress: OpProgress;
+    } | {
+        $case: "exit";
+        exit: OpExit;
+    } | undefined;
+}
+declare const OpFrame: MessageFns<OpFrame>;
+/** A chunk of op output on a channel (≤128 KiB per frame). */
+interface OpData {
+    channel: OpChannel;
+    bytes: Uint8Array;
+}
+declare const OpData: MessageFns<OpData>;
+/**
+ * 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.
+ */
+interface OpProgress {
+}
+declare const OpProgress: MessageFns<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.
+ */
+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;
+}
+declare const OpAck: MessageFns<OpAck>;
 /**
  * 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
@@ -835,6 +1202,26 @@ interface ControlRequest {
     } | {
         $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;
     } | undefined;
 }
 declare const ControlRequest: MessageFns<ControlRequest>;
@@ -906,6 +1293,20 @@ interface ControlResponse {
     } | {
         $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;
     } | undefined;
 }
 declare const ControlResponse: MessageFns<ControlResponse>;
@@ -1077,4 +1478,4 @@ interface MessageFns<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 };
+export { AdmissionTelemetry, 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, FsWriteBegin, FsWriteRequest, FsWriteResponse, GitFileStatus, GitOp, GitRequest, GitResponse, GitStatus, GoingOffline, GoingOfflineReason, GpuSample, Heartbeat, HeartbeatAck, Hello, HelloAck, HostCapacitySample, KeyAction, KeyEvent, type MessageFns, MetricsRequest, MetricsSample, OpAck, OpAttach, OpCancel, OpChannel, OpData, OpExit, OpExit_DigestsEntry, OpExit_FailureDetailEntry, OpExit_TotalsEntry, OpFrame, OpLostReason, OpProgress, OpQuery, OpStart, OpStarted, OpState, OpStatus, 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, WriteChunk, WriteChunkAck, archFromJSON, archToJSON, deviceAuthStateFromJSON, deviceAuthStateToJSON, errorCodeFromJSON, errorCodeToJSON, fsEntryKindFromJSON, fsEntryKindToJSON, gitOpFromJSON, gitOpToJSON, goingOfflineReasonFromJSON, goingOfflineReasonToJSON, keyActionFromJSON, keyActionToJSON, opChannelFromJSON, opChannelToJSON, opLostReasonFromJSON, opLostReasonToJSON, opStateFromJSON, opStateToJSON, osFromJSON, osToJSON, pointerActionFromJSON, pointerActionToJSON, pointerButtonFromJSON, pointerButtonToJSON, protobufPackage, streamCloseReasonFromJSON, streamCloseReasonToJSON, streamKindFromJSON, streamKindToJSON, streamRoleFromJSON, streamRoleToJSON };