pinesandbox 0.0.1 → 0.3.18

data/lib/pinesandbox/adapters/coordinator_adapter.rb

@@ -0,0 +1,1374 @@
+require "faraday"
+require "json"
+require "securerandom"
+require "uri"
+require_relative "../clock"
+require_relative "../errors"
+require_relative "../operations"
+require_relative "../control_state"
+require_relative "../control_events"
+require_relative "../sse_frame_parser"
+require_relative "../exec_stream_parser"
+require_relative "../response_handler"
+
+module PineSandbox
+  module Adapters
+    # @api private — the SDK's HTTP client for the Computer API, reached at the
+    # runtime's own host `https://<runtime_id>.computer.<zone>`. The subdomain
+    # selects the runtime and the PATH selects the role (the API at root);
+    # the host is port-less and header-less — no routing header.
+    #
+    # The bearer goes in `Authorization: Bearer`. The Computer gates every
+    # route on the `ct_`/`ps_` bearer, so the data-plane host being publicly
+    # routable is fine — an unbound caller has no token. Each request uses
+    # either the computer token (`ct_*`, admin scope) or a session token
+    # (`ps_*`, one session); callers pass the right token per call — this
+    # adapter does not pick.
+    #
+    # A request that is replay-safe in the public operation table is sent
+    # again after a transport fault (Operations, RetryPolicy); any other is
+    # sent once. A 401 for a Computer token raises TokenRejectedError; a 401
+    # for a session token is the plain UnauthorizedError.
+    class CoordinatorAdapter
+      include PineSandbox::ResponseHandler
+
+      DEFAULT_HTTP_TIMEOUT = 30
+      DEFAULT_OPEN_TIMEOUT = 5
+      # A non-2xx stream answer keeps this much of its body for the error.
+      STREAM_ERROR_BODY_CAP = 64 * 1024
+
+      # The runtime is reached at its own host `https://<runtime_id>.computer.<zone>`
+      # (derived from `zone`), port-less and header-less: the subdomain selects the
+      # runtime and the PATH selects the role. `zone` is a PineSandbox::Zone.
+      # `host` is the per-runtime data-plane host `<runtime_id>.computer.<zone>`
+      # (scheme-less). `scheme` is http for a .localhost zone (local-dev loop),
+      # https otherwise. `clock` paces retries and reconnects.
+      attr_reader :runtime_id, :host, :scheme, :clock
+
+      # discovery_token is the Computer token that reads the capability
+      # manifest when a request's own token, such as a session's, cannot. An
+      # adopted binding passes it; #bind records the one it issues.
+      # `sandbox_id:` is the deprecated spelling of `runtime_id:`.
+      def initialize(zone:, runtime_id: nil, sandbox_id: nil, discovery_token: nil, clock: PineSandbox::SYSTEM_CLOCK)
+        @runtime_id = runtime_id || sandbox_id
+        raise ArgumentError, "runtime_id required" if @runtime_id.to_s.empty?
+
+        @host = zone.data_host(@runtime_id)
+        @scheme = zone.http_scheme # http for a .localhost zone (local-dev loop), https otherwise
+        @discovery_token = discovery_token
+        @clock = clock
+        # This adapter's own connections dial as the zone says (#connection);
+        # base_url stays the public host, since a delegated connection hands
+        # it to a browser.
+        @zone = zone
+      end
+
+      # Deprecated: use #runtime_id.
+      def sandbox_id
+        PineSandbox.deprecated_name("CoordinatorAdapter#sandbox_id", "#runtime_id")
+        @runtime_id
+      end
+
+      # The full data-plane origin `<scheme>://<runtime_id>.computer.<zone>` — the
+      # DelegatedConnection's `computer_host` is a complete URI per the Computer API,
+      # so the web SDK derives the desktop's ws/wss scheme from it (no guessing).
+      def base_url
+        "#{@scheme}://#{@host}"
+      end
+
+      # Bind handshake. Posts the portal-issued bind_token JWS to
+      # /v1/coord/bind and returns the runtime's `ct_` from the response.
+      #
+      # Auth model: bind_token's Ed25519 signature IS the auth — no
+      # bearer token is presented here (the bind endpoint refuses
+      # tokens; `apply_token(req, nil)` short-circuits in `request`).
+      #
+      # @param bind_token [String] compact JWS Ed25519 token minted by the
+      #   portal attach-credentials endpoint (AttachCredentialsSource).
+      # @param pod_uid [String] echoed runtime identity (must match the token).
+      # @param coord_boot_id [String] echoed process boot id.
+      # @param ciphertext [String] base64url HPKE wire (enc || aead_ct).
+      # @return [Hash] { "computer_token" => ct_, "epoch" => Integer }.
+      # key_assertion rides every v2 (asymmetric) round; restore_secrets is
+      # the two-round restore's commit payload. A 200 carrying
+      # "restore_challenge" (no "computer_token") means the caller must
+      # unwrap the per-component secrets and re-bind with restore_secrets.
+      def bind(bind_token:, pod_uid:, coord_boot_id:, ciphertext:,
+               key_assertion: nil, restore_secrets: nil)
+        body = {
+          pod_uid: pod_uid,
+          coord_boot_id: coord_boot_id,
+          ciphertext: ciphertext,
+          bind_token: bind_token
+        }
+        body[:key_assertion] = key_assertion if key_assertion
+        body[:restore_secrets] = restore_secrets if restore_secrets
+        resp = post("v1/coord/bind", token: nil, json: body)
+        @discovery_token = resp.body["computer_token"] if resp.body.is_a?(Hash) && resp.body["computer_token"]
+        resp.body
+      end
+
+      # Fetches the Computer's per-process ephemeral HPKE public key and
+      # runtime identity. Public route — no token. The SDK seals the bind
+      # payload to this key and echoes pod_uid/coord_boot_id back on bind.
+      #
+      # @return [Hash] { "pod_uid", "coord_boot_id", "ephem_pub_x25519"
+      #   (base64url 32 bytes), "fetched_at" }.
+      def bind_pubkey
+        get("v1/coord/bind-pubkey", token: nil).body
+      end
+
+      # Snapshot admin API (ct_ only). Wraps GET /state — the
+      # most-recently-persisted snapshot for this Computer. Returns the
+      # raw response body (JSON shape — plaintext_v0 or envelope_v1; the
+      # SDK doesn't decode either format, the caller decides whether to
+      # forward to external storage or pass it back to a future
+      # restore-from-bytes flow). On 404 (no snapshot uploaded yet) the
+      # method returns nil; on 503 (PINE_STATE_DIR unset on coord) the
+      # adapter raises ServiceUnavailableError so callers see "state
+      # persistence not enabled on this Computer" rather than a silent nil.
+      def get_latest_snapshot(token:)
+        get("state", token: token).body
+      rescue PineSandbox::NotFoundError
+        nil
+      end
+
+      # Triggers a synchronous, durable capture (a checkpoint) of the Computer's
+      # state and returns when it is committed. The explicit durability
+      # primitive — NOT coupled to stop. Reuses coord's proven single-shot
+      # capture path (capture → encrypt → upload → commit witness at the current
+      # epoch), content-hash-gated: an unchanged state returns `{skipped:true}`
+      # and the prior snapshot stays the latest. Returns the snapshot descriptor
+      # (snapshot_id, captured_at, bytes, skipped). ct_ only.
+      def capture(token:)
+        post("v1/coord/capture", token: token, json: {}).body
+      end
+
+      # Computer-scoped custodial passkey management. All projections are
+      # metadata-only; private key material never crosses this adapter.
+      def list_passkeys(token:)
+        get("v1/passkeys", token: token).body.fetch("credentials", [])
+      end
+
+      def delete_passkey(token:, credential_id:)
+        delete("v1/passkeys/#{escape(credential_id)}", token: token)
+        true
+      end
+
+      def list_passkey_ceremonies(token:)
+        get("v1/passkeys/ceremonies", token: token).body.fetch("ceremonies", [])
+      end
+
+      def decide_passkey_ceremony(token:, ceremony_id:, decision:)
+        post("v1/passkeys/ceremonies/#{escape(ceremony_id)}", token: token,
+             json: { decision: decision })
+        true
+      end
+
+      def declare_passkey_intent(token:, name:, rp_id:)
+        post("v1/sessions/#{escape(name)}/passkeys/intents", token: token,
+             json: { rp_id: rp_id })
+        true
+      end
+
+      def list_session_passkey_ceremonies(token:, name:)
+        get("v1/sessions/#{escape(name)}/passkeys/ceremonies", token: token)
+          .body.fetch("ceremonies", [])
+      end
+
+      def decide_session_passkey_ceremony(token:, name:, ceremony_id:, decision:)
+        post("v1/sessions/#{escape(name)}/passkeys/ceremonies/#{escape(ceremony_id)}",
+             token: token, json: { decision: decision })
+        true
+      end
+
+      # Orphan tabs: browser tabs no session owns (ct_ only).
+      def list_orphan_tabs(token:)
+        get("orphans", token: token).body
+      end
+
+      def close_orphan_tab(token:, target_id:)
+        delete("orphans/#{escape(target_id)}", token: token)
+        true
+      end
+
+      # Orphan downloads: browser downloads no session owns (ct_ only).
+      def list_orphan_downloads(token:)
+        get("downloads/orphans", token: token).body
+      end
+
+      def claim_orphan_download(token:, guid:, session_name:, filename: nil)
+        body = { session_name: session_name }
+        body[:filename] = filename if filename
+        post("downloads/orphans/#{escape(guid)}/claim", token: token, json: body).body
+      end
+
+      def discard_orphan_download(token:, guid:)
+        delete("downloads/orphans/#{escape(guid)}", token: token)
+        true
+      end
+
+      def create_session(token:, name: nil, label: nil, browser: false, blind: false)
+        # Omit :name when blank so the coordinator mints a friendly name; only
+        # send :label when the caller set one. Name stays first so the on-wire
+        # body order is stable.
+        body = {}
+        body[:name] = name unless name.nil? || name.to_s.empty?
+        body[:browser] = browser
+        body[:label] = label unless label.nil? || label.to_s.empty?
+        body[:blind] = true if blind
+        post("sessions", token: token, json: body)
+          .body
+          .fetch("session")
+      end
+
+      def get_session(token:, name:)
+        get("sessions/#{escape(name)}", token: token).body.fetch("session")
+      end
+
+      def list_sessions(token:)
+        get("sessions", token: token).body.fetch("sessions", [])
+      end
+
+      # Destroy the session. Default leaves the session's files on disk so a
+      # subsequent create with the same name finds the prior workdir contents.
+      # Pass clean: true to delete them too.
+      def destroy_session(token:, name:, clean: false)
+        path = "sessions/#{escape(name)}"
+        path = "#{path}?clean=true" if clean
+        delete(path, token: token)
+        true
+      end
+
+      # Rebuild the bash terminal after an execd restart left the session
+      # with Terminal.Lost=true (coordinator returns 409 terminal_lost on
+      # /exec until this is called). The browser plane is preserved across
+      # the cycle; same primary_tab_id, window_id, epoch.
+      def recreate_terminal(token:, name:)
+        post("sessions/#{escape(name)}/terminal/recreate", token: token, json: {})
+        true
+      end
+
+      def focus(token:, name:)
+        post("sessions/#{escape(name)}/focus", token: token, json: {})
+        true
+      end
+
+      def epoch(token:, name:)
+        get("sessions/#{escape(name)}/epoch", token: token).body
+      end
+
+      def list_tabs(token:, name:)
+        body = get("sessions/#{escape(name)}/tabs", token: token).body
+        {
+          tabs: body.fetch("tabs", []),
+          session_generation: body["session_generation"]
+        }
+      end
+
+      def list_files(token:, name:, path: nil, pattern: nil)
+        query = {}
+        query[:path] = path unless path.nil?
+        query[:pattern] = pattern unless pattern.nil?
+        route = "v1/sessions/#{escape(name)}/files/list"
+        route += "?#{URI.encode_www_form(query)}" unless query.empty?
+        get(route, token: token)
+          .body
+          .fetch("entries", [])
+          .map { |entry| Models::FileEntry.from_payload(entry) }
+      end
+
+      def read_file(token:, name:, path:, &block)
+        route = "v1/sessions/#{escape(name)}/files?#{URI.encode_www_form(path: path)}"
+        return stream_bytes(route, token: token, accept: "application/octet-stream", &block) if block
+
+        bytes = get(route, token: token, accept: "application/octet-stream").body
+        bytes.is_a?(String) ? bytes.b : bytes
+      end
+
+      # PUT /v1/sessions/{name}/files?path=<name> — deposit a material (an agent
+      # INPUT) into the session's attachments/ root. `path` is a single filename
+      # ("/" and ".." are rejected — no traversal). NB: attachments/ is a SIBLING
+      # of the workdir that read_file/list_files serve, so the agent is told about
+      # a deposited material rather than finding it through read_file. Returns the parsed 201
+      # body: { "root" => "attachments", "relative_path" => ..., "size" => ... }.
+      def write_file(token:, name:, path:, content:)
+        route = "v1/sessions/#{escape(name)}/files?#{URI.encode_www_form(path: path)}"
+        put(route, token: token, body: content.to_s.b, content_type: "application/octet-stream").body
+      end
+
+      # ----- Artifacts: list / read / zip / upload -----
+
+      # GET /v1/sessions/{name}/artifacts?turn_id= — the session's artifacts
+      # (uploads + claimed downloads + every completed turn's durably-captured
+      # agent outputs).
+      def list_artifacts(token:, name:, turn_id: nil)
+        route = "v1/sessions/#{escape(name)}/artifacts"
+        route += "?#{URI.encode_www_form(turn_id: turn_id)}" if turn_id
+        get(route, token: token)
+          .body
+          .fetch("artifacts", [])
+          .map { |a| Models::Artifact.from_payload(a) }
+      end
+
+      # GET /v1/sessions/{name}/artifacts/{id} — raw artifact bytes.
+      def read_artifact(token:, name:, id:, &block)
+        route = "v1/sessions/#{escape(name)}/artifacts/#{escape(id)}"
+        return stream_bytes(route, token: token, accept: "application/octet-stream", &block) if block
+
+        bytes = get(route, token: token, accept: "application/octet-stream").body
+        bytes.is_a?(String) ? bytes.b : bytes
+      end
+
+      # GET /v1/sessions/{name}/artifacts/zip?turn_id= — a zip of the artifacts.
+      def zip_artifacts(token:, name:, turn_id: nil, &block)
+        route = "v1/sessions/#{escape(name)}/artifacts/zip"
+        route += "?#{URI.encode_www_form(turn_id: turn_id)}" if turn_id
+        return stream_bytes(route, token: token, accept: "application/zip", &block) if block
+
+        bytes = get(route, token: token, accept: "application/zip").body
+        bytes.is_a?(String) ? bytes.b : bytes
+      end
+
+      # POST /v1/sessions/{name}/artifacts?filename= — upload bytes as a new
+      # artifact (created_by:upload). Returns the created Models::Artifact.
+      def upload_artifact(token:, name:, filename:, content:)
+        route = "v1/sessions/#{escape(name)}/artifacts?#{URI.encode_www_form(filename: filename)}"
+        Models::Artifact.from_payload(
+          post(route, token: token, body: content.to_s.b, content_type: "application/octet-stream").body
+        )
+      end
+
+      def create_tab(token:, name:, url:, label: nil)
+        payload = { url: url }
+        payload[:label] = label if label
+        post("sessions/#{escape(name)}/tabs", token: token, json: payload).body.fetch("tab")
+      end
+
+      def patch_tab(token:, name:, target_id:, active: nil, label: nil)
+        body = {}
+        body[:active] = active unless active.nil?
+        body[:label] = label unless label.nil?
+        patch("sessions/#{escape(name)}/tabs/#{escape(target_id)}", token: token, json: body).body.fetch("tab")
+      end
+
+      def close_tab(token:, name:, target_id:)
+        delete("sessions/#{escape(name)}/tabs/#{escape(target_id)}", token: token)
+        true
+      end
+
+      # Control surface. All paths under
+      # `/v1/sessions/{name}/control[/*]` and `/v1/sessions/{name}/handoffs[/*]`.
+
+      # GET /v1/sessions/{name}/control. Returns a ControlState: the
+      # ControlStateV1 body plus the ETag extracted from response
+      # headers; callers use the ETag as `If-Match:` on the next PATCH.
+      def get_control(token:, name:)
+        resp = get("v1/sessions/#{escape(name)}/control", token: token)
+        ControlState.wrap(state: resp.body, etag: resp.headers["etag"])
+      end
+
+      # PATCH /v1/sessions/{name}/control. Returns the same shape as
+      # get_control (new state + new ETag). Caller passes typed args:
+      # `body` is the parsed JSON shape; `if_match` is required unless
+      # `force: true`; `idempotency_key` defaults to a fresh UUID.
+      def patch_control(token:, name:, body:, if_match: nil, force: false, idempotency_key: nil)
+        idempotency_key ||= SecureRandom.uuid
+        path = "v1/sessions/#{escape(name)}/control"
+        path += "?force=true" if force
+        headers = {}
+        headers["If-Match"] = if_match if if_match
+        headers["Idempotency-Key"] = idempotency_key if idempotency_key
+        resp = patch(path, token: token, json: body, headers: headers)
+        ControlState.wrap(state: resp.body, etag: resp.headers["etag"])
+      end
+
+      # POST /v1/sessions/{name}/control/notify. Requires If-Match per
+      # the spec (no `force` escape hatch — that's PATCH-only). Accepts
+      # `ct_` OR session-matching `ps_`.
+      def post_control_notify(token:, name:, reason:, detail: nil, if_match:)
+        path = "v1/sessions/#{escape(name)}/control/notify"
+        body = { reason: reason }
+        body[:detail] = detail if detail
+        post(path, token: token, json: body, headers: { "If-Match" => if_match })
+        true
+      end
+
+      # POST /v1/sessions/{name}/desktop-token. ct_-only mint of a short-TTL
+      # (short-TTL) browser-safe VNC desktop-stream connection token (dt_…). No
+      # request body. Returns { token:, expires_at: }. The portal hands the
+      # token to the browser as the /vnc/connect WS subprotocol
+      # (pine-vnc-token.dt_…); drive is the control lease, not this token.
+      def mint_desktop_token(token:, name:)
+        resp = post("v1/sessions/#{escape(name)}/desktop-token", token: token)
+        { token: resp.body.fetch("token"), expires_at: resp.body["expires_at"] }
+      end
+
+      # GET /v1/sessions/{name}/handoffs?limit=&before=
+      # Returns the full response body (the spec HandoffList) with string keys:
+      # { "handoffs" => [...], "next_before" => <cursor> } — pass next_before back
+      # as `before` to page older (absent = no more pages). String-keyed + the whole
+      # body (like #get_handoff) so it validates directly against the HandoffList
+      # schema and exposes every field.
+      def list_handoffs(token:, name:, limit: nil, before: nil)
+        query = []
+        query << "limit=#{limit}" if limit
+        query << "before=#{escape(before)}" if before
+        path = "v1/sessions/#{escape(name)}/handoffs"
+        path += "?" + query.join("&") unless query.empty?
+        get(path, token: token).body
+      end
+
+      # GET /v1/sessions/{name}/handoffs/{handoff_id}
+      def get_handoff(token:, name:, handoff_id:)
+        get("v1/sessions/#{escape(name)}/handoffs/#{escape(handoff_id)}", token: token).body
+      end
+
+      # stream_control_events opens ONE connection to GET
+      # /v1/sessions/{name}/control/events and yields a typed
+      # PineSandbox::ControlEvents::* struct per event. Honors
+      # `last_event_id` (sent as the Last-Event-ID header) for resume.
+      # Returns the latest event id once the server closes the stream or
+      # `stop_when` returns true for a delivered event. Session#control_events
+      # (#follow_control_events) reconnects for you.
+      def stream_control_events(token:, name:, last_event_id: nil, stop_when: nil, &block)
+        raise ArgumentError, "block required" unless block
+
+        rel = "v1/sessions/#{escape(name)}/control/events"
+        latest_id = last_event_id
+        catch(:pine_stream_stop) do
+          with_transport_norm("GET", rel) do
+            open_sse(rel, token: token, last_event_id: last_event_id) do |frame|
+              evt = decode_control_frame(frame)
+              next if evt.nil?
+
+              latest_id = evt.id if evt.id
+              block.call(evt)
+              throw :pine_stream_stop if stop_when&.call(evt)
+            end
+          end
+        end
+        latest_id
+      end
+
+      # Follows the session's control events across connections: a dropped
+      # stream reopens from the last event id, waiting RetryPolicy's stream
+      # backoff between attempts. After STREAM_RECONNECT_BUDGET reconnects in
+      # a row that delivered no event it raises StreamLostError; an error
+      # answer (401/403/404/…) raises at once. Returns the latest event id
+      # when `stop_when` returns true, or — when `max_reconnects` caps the
+      # reconnects — once that many have been used (a transport fault then
+      # raises instead).
+      def follow_control_events(token:, name:, last_event_id: nil, stop_when: nil, max_reconnects: nil, &block)
+        raise ArgumentError, "block required" unless block
+
+        rel = "v1/sessions/#{escape(name)}/control/events"
+        cursor = follow_events(
+          op: "GET /#{rel}", cursor: last_event_id, stop_when: stop_when, max_reconnects: max_reconnects,
+          open: ->(from, &on_frame) { open_sse(rel, token: token, last_event_id: from, &on_frame) },
+          decode: method(:decode_control_frame), &block
+        )
+        Integer(cursor, 10, exception: false) || cursor
+      end
+
+      # Issues an SSE-streamed exec. Yields each parsed event hash to the
+      # block; returns an ExecResult struct with `stdout`, `stderr`, and
+      # `exit_code` assembled from the stream — stdout/stderr accumulated
+      # from their respective events, exit_code read from the command error
+      # or inferred from clean completion. Caller's block can raise to abort early;
+      # the underlying connection then closes.
+      #
+      # POST /sessions/{name}/exec expects `{"command": "...", "cwd": "...",
+      # "timeout_ms": ...}` (NOT `code:`).
+      def exec(token:, name:, command:, cwd: nil, timeout_ms: nil, &block)
+        body = { command: command }
+        body[:cwd] = cwd if cwd
+        body[:timeout_ms] = timeout_ms if timeout_ms
+
+        stdout = +""
+        stderr = +""
+        exit_code = nil
+        complete = false
+        errored = false
+        error_msg = nil
+        parser = PineSandbox::ExecStreamParser.new do |event|
+          case event.type
+          # execd strips trailing \n from each line before wrapping it
+          # into an event. Re-append so stdout/stderr recompose with line
+          # boundaries — matters for regex like /^FOO=/ and for tests
+          # that iterate r.stdout.lines. Callers that want a raw trimmed
+          # value should use r.stdout.chomp.
+          when :stdout then stdout << event.text.to_s << "\n"
+          when :stderr then stderr << event.text.to_s << "\n"
+          when :execution_complete then complete = true
+          when :error
+            errored = true
+            if event.error.is_a?(Hash)
+              # The session-shell wire carries a nonzero command exit in
+              # error.evalue, not in a top-level exit_code.
+              value = event.error["evalue"]
+              exit_code = Integer(value, 10, exception: false) if value.is_a?(String)
+              traceback = Array(event.error["traceback"]).grep(String)
+              error_msg = traceback.join("\n") unless traceback.empty?
+              if error_msg.nil?
+                parts = [event.error["ename"], value].grep(String).reject(&:empty?)
+                error_msg = parts.join(": ") unless parts.empty?
+              end
+            elsif event.error.is_a?(String)
+              error_msg = event.error
+            end
+            error_msg ||= event.data.is_a?(Hash) ? (event.data["message"] || event.data[:message] || event.text) : event.text
+          end
+          # Take exit_code from ANY event that carries it explicitly.
+          if event.data.is_a?(Hash)
+            raw = event.data["exit_code"] || event.data[:exit_code] ||
+                  event.data["exitCode"] || event.data[:exitCode]
+            exit_code = raw unless raw.nil?
+          end
+          block.call(event) if block
+        end
+        # Clamp the HTTP timeout above timeout_ms so the client waits for
+        # the server's own timeout to fire an execution_complete event
+        # rather than tearing the TCP stream down mid-stream. Fallback of
+        # 60s protects against a hung coordinator when the caller passes
+        # no timeout at all.
+        http_timeout = timeout_ms ? ((timeout_ms / 1000.0).ceil + 5) : 60
+        error_body = +""
+        with_transport_norm("POST", "sessions/#{escape(name)}/exec") do
+          response = connection.post(route_path("sessions/#{escape(name)}/exec")) do |req|
+            apply_token(req, token)
+            req.headers["Content-Type"] = "application/json"
+            req.headers["Accept"] = "text/event-stream"
+            req.body = body.to_json
+            req.options.on_data = proc do |chunk, _received, env|
+              if env.nil? || env.status.to_i.between?(200, 299)
+                parser.parse(chunk)
+              else
+                keep_error_body(error_body, chunk)
+              end
+            end
+            req.options.timeout = http_timeout
+          end
+          # Non-2xx (e.g. 409 terminal_lost) is a problem+json body, not a
+          # stream; raise it so callers get ConflictError (→ recreate_terminal!)
+          # instead of a silent empty ExecResult.
+          unless response.success?
+            response.env.body = error_body if response.body.to_s.empty?
+            ensure_success!(response, token: token)
+          end
+        end
+        parser.finish
+        # execd's `execution_complete` frame does NOT carry exit_code on
+        # successful runs (only `execution_time` + `timestamp`). Mirror
+        # CommandsAdapter#infer_exit_code: if we saw completion and no
+        # explicit exit_code, assume 0. If we saw an :error event, surface
+        # it (exit_code stays nil unless the error frame carried one).
+        if exit_code.nil? && complete && !errored
+          exit_code = 0
+        end
+        ExecResult.new(stdout: stdout, stderr: stderr, exit_code: exit_code,
+                       error_message: error_msg)
+      end
+
+      # Minimal struct surfaced by #exec. Matches the shape tests expect:
+      # `r.exit_code`, `r.stdout`, `r.stderr`. `error_message` is populated
+      # when the stream surfaces an explicit :error event (e.g. command
+      # not found on execd's side, not the command's own stderr).
+      ExecResult = Struct.new(:stdout, :stderr, :exit_code, :error_message,
+                              keyword_init: true) do
+        # The command's error, when the stream reported one (#error_message).
+        def error = error_message
+      end
+
+      # ----- Agent track: /v2/sessions/{name}/agent[/*] -----
+      # Work is addressed by turn: run and answer return a turn, and the turn
+      # read, answer, steer and cancel take its turn_id. Mutations
+      # (run/steer/answer/cancel/reset) are ct_-only; reads (task/turns/events)
+      # accept ct_ OR session-matching ps_.
+
+      # idempotency_key names this submission: a run with the same key returns
+      # the turn that key admitted instead of starting another.
+      def agent_run(token:, name:, goal:, context: nil, skills: nil, constraints: nil, secrets: nil, idempotency_key: nil)
+        body = { goal: goal }
+        body[:context] = context unless context.nil?
+        body[:skills] = skills unless skills.nil?
+        body[:constraints] = constraints unless constraints.nil?
+        body[:secrets] = secrets unless secrets.nil?
+        post("v2/sessions/#{escape(name)}/agent/run", token: token, json: body,
+             headers: { "Idempotency-Key" => idempotency_key }).body
+      end
+
+      def agent_steer(token:, name:, turn_id:, text:, secrets: nil)
+        body = { turn_id: turn_id, text: text }
+        body[:secrets] = secrets unless secrets.nil?
+        post("v2/sessions/#{escape(name)}/agent/steer", token: token, json: body).body
+      end
+
+      def agent_answer(token:, name:, turn_id:, answer:, secrets: nil)
+        body = { turn_id: turn_id, answer: answer }
+        body[:secrets] = secrets unless secrets.nil?
+        post("v2/sessions/#{escape(name)}/agent/answer", token: token, json: body).body
+      end
+
+      def agent_cancel(token:, name:, turn_id:)
+        post("v2/sessions/#{escape(name)}/agent/cancel", token: token, json: { turn_id: turn_id }).body
+      end
+
+      def agent_reset(token:, name:, expected_task_id:)
+        raise ArgumentError, "expected_task_id is required" if expected_task_id.to_s.empty?
+
+        post(agent_guarded_path(name, "/reset", expected_task_id: expected_task_id), token: token, json: {}).body
+      end
+
+      def agent_task(token:, name:, expected_task_id: nil)
+        get(agent_guarded_path(name, "", expected_task_id: expected_task_id), token: token).body
+      end
+
+      # GET .../agent/turns/{turn_id}. The Computer holds the response up to
+      # wait_seconds while the turn runs, so the read timeout allows for it.
+      def agent_turn(token:, name:, turn_id:, wait_seconds: 0)
+        path = "v2/sessions/#{escape(name)}/agent/turns/#{escape(turn_id)}?wait_seconds=#{Integer(wait_seconds)}"
+        request(:get, path, token: token, timeout: DEFAULT_HTTP_TIMEOUT + wait_seconds).body
+      end
+
+      # Public history: the retained turns and cursor-addressed activity pages.
+      def agent_turns(token:, name:, expected_task_id: nil)
+        get(agent_guarded_path(name, "/turns", expected_task_id: expected_task_id), token: token).body
+      end
+
+      def agent_events_page(token:, name:, after: nil, limit: nil, expected_task_id: nil, frames: true)
+        q = []
+        q << "after=#{Integer(after)}" unless after.nil?
+        q << "limit=#{Integer(limit)}" unless limit.nil?
+        q << "expected_task_id=#{escape(expected_task_id)}" unless expected_task_id.nil?
+        q << "frames=none" unless frames
+        path = "v2/sessions/#{escape(name)}/agent/events/page"
+        path += "?#{q.join("&")}" unless q.empty?
+        get(path, token: token).body
+      end
+
+      # --- Learned skills (Computer Skills) ------------------------------------
+
+      # GET /v1/skills — the served skills (curated + activated learned).
+      def list_skills(token:)
+        get("v1/skills", token: token).body.fetch("skills", [])
+      end
+
+      # GET /v1/skills/{name} — one skill's metadata + full SKILL.md body.
+      def get_skill(token:, name:)
+        get("v1/skills/#{escape(name)}", token: token).body
+      end
+
+      # GET /v1/skills/drafts — pending drafts, each WITH its body (for review).
+      def list_skill_drafts(token:)
+        get("v1/skills/drafts", token: token).body.fetch("drafts", [])
+      end
+
+      # GET /v1/skills/versions — all visible learned versions (metadata only).
+      def list_all_skill_versions(token:)
+        get("v1/skills/versions", token: token).body.fetch("versions", [])
+      end
+
+      # GET /v1/skills/{name}/versions — visible versions for one name (metadata only).
+      def list_skill_versions(token:, name:)
+        get("v1/skills/#{escape(name)}/versions", token: token).body.fetch("versions", [])
+      end
+
+      # GET /v1/skills/{name}/versions/{version} — one version's metadata + SKILL.md body.
+      def get_skill_version(token:, name:, version:)
+        get("v1/skills/#{escape(name)}/versions/#{escape(version)}", token: token).body
+      end
+
+      # POST /v1/skills/{name}/activate — serve a reviewed draft version.
+      def activate_skill(token:, name:, version:)
+        post("v1/skills/#{escape(name)}/activate", token: token, json: { version: version }).body
+      end
+
+      # POST /v1/skills/{name}/deactivate — un-serve a skill (the version is kept).
+      def deactivate_skill(token:, name:)
+        post("v1/skills/#{escape(name)}/deactivate", token: token, json: {}).body
+      end
+
+      # PUT /v1/skills/{name}/enabled — switch one of Pine's standard or feature skills on or
+      # off for the agent processes the Computer starts next.
+      def set_skill_enabled(token:, name:, enabled:)
+        request(:put, "v1/skills/#{escape(name)}/enabled", token: token, json: { enabled: enabled }).body
+      end
+
+      # GET /v1/capabilities — product features for this binding and the Computer's limits.
+      def capabilities(token:)
+        get("v1/capabilities", token: token).body
+      end
+
+      # Explicit qualification for a binding. No cache, downgrade or mutation.
+      # A missing discovery route is an old runtime; the gateway's typed
+      # sandbox-not-found response remains a lifecycle failure.
+      def require_agent_protocol!(token:)
+        manifest = capabilities(token: token)
+        raise AgentProtocolUnsupported unless public_agent_supported?(manifest)
+
+        self
+      rescue NotFoundError => e
+        raise if e.is_a?(RuntimeGoneError)
+
+        raise AgentProtocolUnsupported
+      end
+
+      def public_agent_supported?(manifest)
+        protocols = manifest["protocols"] if manifest.is_a?(Hash)
+        versions = protocols["agent"] if protocols.is_a?(Hash)
+        versions.is_a?(Array) && versions.all? { |v| v.is_a?(Integer) && v.positive? } &&
+          versions.uniq == versions && versions.include?(2)
+      end
+      private :public_agent_supported?
+
+      # DELETE /v1/skills/{name}/versions/{version} — hide a version and un-serve it if active.
+      def delete_skill_version(token:, name:, version:)
+        delete("v1/skills/#{escape(name)}/versions/#{escape(version)}", token: token).body
+      end
+
+      # POST /v2/sessions/{name}/learn — author a draft from the session's latest finished run.
+      # `scaffold:` is an optional seed of the SKILL.md the authoring run continues
+      # from (preserved frontmatter / section headers / explicit parameter names).
+      # Capped at 32 KiB.
+      def learn_skill(token:, name:, scaffold: nil)
+        body = {}
+        body[:scaffold] = scaffold unless scaffold.nil? || scaffold.empty?
+        post("v2/sessions/#{escape(name)}/learn", token: token, json: body).body
+      end
+
+      # POST /v2/sessions/{name}/teach — author a draft from a human demonstration.
+      def teach_skill(token:, name:, goal:, handoff_id: nil, clarifications: nil, scaffold: nil)
+        body = { goal: goal }
+        body[:handoff_id] = handoff_id unless handoff_id.nil?
+        body[:clarifications] = clarifications unless clarifications.nil?
+        body[:scaffold] = scaffold unless scaffold.nil? || scaffold.empty?
+        post("v2/sessions/#{escape(name)}/teach", token: token, json: body).body
+      end
+
+      # POST /v2/sessions/{name}/refine — revise an existing skill version with a
+      # plain-language instruction. `name` is the SESSION (path); `skill`/`version`
+      # name the version to revise and `guidance` is the instruction. No navigation.
+      def refine_skill(token:, name:, skill:, version:, guidance:)
+        body = { name: skill, version: version, guidance: guidance }
+        post("v2/sessions/#{escape(name)}/refine", token: token, json: body).body
+      end
+
+      # GET /v2/sessions/{name}/skills/author/{author_id}/events — ONE
+      # connection to the SSE stream of an in-flight authoring run. Yields each
+      # parsed event to the block; tracks `id:` for Last-Event-ID resume. The
+      # closing terminal frame ends the response (its Result.terminal_reason is
+      # in the AuthorTerminal* vocabulary). Mirrors agent_events.
+      def author_events(token:, name:, author_id:, last_event_id: nil, &block)
+        raise ArgumentError, "block required" unless block
+
+        stream_json_events(
+          path: "v2/sessions/#{escape(name)}/skills/author/#{escape(author_id)}/events",
+          token: token, last_event_id: last_event_id, &block
+        )
+      end
+
+      # Follows an authoring run's events across connections until its
+      # `result` event (see #follow_control_events for the reconnect budget).
+      # Returns the last event id.
+      def follow_author_events(token:, name:, author_id:, last_event_id: nil, &block)
+        raise ArgumentError, "block required" unless block
+
+        path = "v2/sessions/#{escape(name)}/skills/author/#{escape(author_id)}/events"
+        follow_events(
+          op: "GET /#{path}", cursor: last_event_id, terminal: ->(event) { event["type"] == "result" },
+          open: ->(from, &on_frame) { open_sse(path, token: token, last_event_id: from, &on_frame) },
+          decode: method(:decode_json_frame), &block
+        )
+      end
+
+      # POST /v2/sessions/{name}/skills/author/{author_id}/cancel — cancel a
+      # running authoring run. Returns the parsed 202 body.
+      def cancel_author(token:, name:, author_id:)
+        post("v2/sessions/#{escape(name)}/skills/author/#{escape(author_id)}/cancel", token: token, json: {}).body
+      end
+
+      # await_author_terminal subscribes to the bridged author SSE stream and
+      # returns the canonical `result` event (its terminal_reason is in the
+      # AuthorTerminal* vocabulary).
+      # Used by Session#learn / #teach's sync shim to translate the streaming
+      # outcome back into the legacy LearnResult / TeachResult shape so existing
+      # callers don't see the API shape change. Returns nil if the stream ended
+      # without a terminal (unexpected; the broker always finalizes).
+      def await_author_terminal(token:, name:, author_id:)
+        terminal = nil
+        follow_author_events(token: token, name: name, author_id: author_id) do |evt|
+          terminal = evt if evt["type"] == "result"
+        end
+        terminal
+      end
+
+      # POST /v1/sessions/{name}/skills — register a draft directly (a SKILL.md your own agent wrote).
+      # `name` is the SESSION; `skill_name` is the skill's kebab-case name (also in its frontmatter).
+      def author_skill_draft(token:, name:, skill_name:, skill_md:, reason:, origin: nil, tainted: nil)
+        body = { name: skill_name, skill_md: skill_md, reason: reason }
+        body[:origin] = origin unless origin.nil?
+        body[:tainted] = tainted unless tainted.nil?
+        post("v1/sessions/#{escape(name)}/skills", token: token, json: body).body
+      end
+
+      # Streams ONE connection of the session's TaskEvent SSE feed, yielding
+      # each parsed event (the `data:` JSON) and tracking `id:` for
+      # Last-Event-ID resume. Returns the last seen event id at the end of the
+      # stream. A non-2xx is a problem+json body, not a stream — raise it so the
+      # caller treats it as terminal, not a clean EOF. frames: false asks the
+      # Computer to leave `frame` events out.
+      def agent_events(token:, name:, last_event_id: nil, frames: true, expected_task_id: nil, &block)
+        raise ArgumentError, "block required" unless block
+
+        stream_json_events(
+          path: agent_guarded_path(name, "/events", expected_task_id: expected_task_id, frames: ("none" unless frames)),
+          token: token, last_event_id: last_event_id, &block
+        )
+      end
+
+      # Follows the session's TaskEvent feed across connections (see
+      # #follow_control_events for the reconnect budget). The feed is
+      # continuous: this returns only when the block breaks out.
+      def follow_agent_events(token:, name:, last_event_id: nil, frames: true, expected_task_id: nil, &block)
+        raise ArgumentError, "block required" unless block
+
+        path = agent_guarded_path(name, "/events", expected_task_id: expected_task_id, frames: ("none" unless frames))
+        follow_events(
+          op: "GET /v2/sessions/#{escape(name)}/agent/events", cursor: last_event_id,
+          open: ->(from, &on_frame) { open_sse(path, token: token, last_event_id: from, &on_frame) },
+          decode: method(:decode_json_frame), &block
+        )
+      end
+
+      # ----- Drive track: observe / computer-use / upload_file -----
+
+      def observe(token:, name:)
+        post("v1/sessions/#{escape(name)}/observe", token: token, json: {}).body
+      end
+
+      def computer_use(token:, name:, action:, params: {})
+        post("v1/sessions/#{escape(name)}/computer-use", token: token,
+             json: { action: action }.merge(params || {})).body
+      end
+
+      def upload_file(token:, name:, selector:, file:)
+        post("v1/sessions/#{escape(name)}/upload_file", token: token,
+             json: { selector: selector, file: file }).body
+      end
+
+      private
+
+      def agent_guarded_path(name, suffix, **query)
+        path = "v2/sessions/#{escape(name)}/agent#{suffix}"
+        query = query.compact
+        query.empty? ? path : "#{path}?#{URI.encode_www_form(query)}"
+      end
+
+      # One connection of the agent or author feed — same wire (each frame's
+      # data: payload is a JSON object; id: is the resume cursor). Yields each
+      # parsed JSON object, tracks + returns the latest event id (the next
+      # reconnect cursor), and raises a typed error on a non-2xx (a
+      # problem+json body, not a stream — so the caller treats it as terminal,
+      # not a clean EOF).
+      def stream_json_events(path:, token:, last_event_id:, &block)
+        latest = last_event_id
+        with_transport_norm("GET", path) do
+          open_sse(path, token: token, last_event_id: last_event_id) do |frame|
+            # Advance the resume cursor for ANY id-bearing frame BEFORE the
+            # empty-data skip, so a reconnect can't replay a frame we've already
+            # seen and skipped (an id-bearing keepalive).
+            latest = frame.id if frame.id && !frame.id.empty?
+            parsed = decode_json_frame(frame)
+            block.call(parsed) unless parsed.nil?
+          end
+        end
+        latest
+      end
+
+      # Opens one event-stream GET and yields each SSE frame as it arrives.
+      # A transport fault raises the raw Faraday error so the caller decides
+      # whether to normalize it or reconnect; a non-2xx raises its typed error
+      # (keeping a bounded prefix of the body, so a problem keeps its type and
+      # extensions). Returns the response.
+      def open_sse(path, token:, last_event_id:)
+        parser = ::PineSandbox::SseFrameParser.new
+        error_body = +""
+        response = streaming_connection.get(route_path(path)) do |req|
+          apply_token(req, token)
+          req.headers["Accept"] = "text/event-stream"
+          req.headers["Last-Event-ID"] = last_event_id.to_s unless last_event_id.to_s.empty?
+          req.options.on_data = proc do |chunk, _bytes, env|
+            if env.nil? || env.status.to_i.between?(200, 299)
+              parser.feed(chunk) { |frame| yield frame }
+            else
+              keep_error_body(error_body, chunk)
+            end
+          end
+        end
+        parser.finish
+        unless response.success?
+          response.env.body = error_body if response.body.to_s.empty?
+          ensure_success!(response, token: token)
+        end
+        response
+      end
+
+      # Raised through Faraday's read loop in place of an exception from the
+      # caller's block, so the block's own error is never mistaken for a
+      # dropped connection.
+      class BlockError < StandardError
+        attr_reader :error
+
+        def initialize(error)
+          @error = error
+          super(error.message)
+        end
+      end
+      private_constant :BlockError
+
+      # The resuming event-stream engine. Each connection opens from the last
+      # event id seen; frames advance the cursor before any decode, so a
+      # skipped frame is never replayed. A dropped connection (a transport
+      # fault or the end of the body) reconnects after RetryPolicy's stream
+      # backoff. The budget counts consecutive reconnects that delivered no
+      # event, so a healthy feed the server recycles runs indefinitely and a
+      # dead one ends with StreamLostError. An error answer raises at once.
+      # Returns the cursor when `terminal` or `stop_when` matches an event, or
+      # when `max_reconnects` (a caller cap on total reconnects) is used up.
+      def follow_events(op:, cursor:, open:, decode:, terminal: nil, stop_when: nil, max_reconnects: nil)
+        cursor = cursor.to_s
+        failures = 0
+        reconnects = 0
+        request_id = nil
+        catch(:pine_stream_stop) do
+          loop do
+            delivered = false
+            fault = nil
+            begin
+              response = open.call(cursor) do |frame|
+                cursor = frame.id if frame.id && !frame.id.empty?
+                next if frame.data.empty?
+
+                event = decode.call(frame)
+                next if event.nil?
+
+                delivered = true
+                begin
+                  yield event
+                rescue StandardError => e
+                  raise BlockError.new(e)
+                end
+                throw :pine_stream_stop if terminal&.call(event) || stop_when&.call(event)
+              end
+              request_id = request_id_header(response) || request_id
+            rescue BlockError => e
+              raise e.error
+            rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+              fault = normalize_transport_fault(e, "GET", op.delete_prefix("GET /"))
+            end
+            failures = 0 if delivered
+            reconnects += 1
+            if max_reconnects && reconnects > max_reconnects
+              raise fault if fault
+
+              throw :pine_stream_stop
+            end
+            failures += 1
+            if failures > RetryPolicy::STREAM_RECONNECT_BUDGET
+              raise StreamLostError.new(op: op, request_id: request_id, cause: fault)
+            end
+
+            @clock.sleep(RetryPolicy.stream_backoff(failures, @clock))
+          end
+        end
+        cursor
+      end
+
+      def decode_json_frame(frame)
+        parsed = JSON.parse(frame.data)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def decode_control_frame(frame)
+        id = frame.id.to_s.empty? ? nil : Integer(frame.id, 10, exception: false)
+        ::PineSandbox::ControlEvents.decode_event(frame.event, id, frame.data)
+      end
+
+      def keep_error_body(buffer, chunk)
+        remaining = STREAM_ERROR_BODY_CAP - buffer.bytesize
+        buffer << chunk.byteslice(0, remaining) if remaining.positive?
+      end
+
+      # Passes a binary GET's body to the block in chunks as it arrives instead
+      # of buffering it. Only a 2xx body reaches the block: an error answer is
+      # kept (bounded) and raised as the same typed error the buffered read
+      # raises, before any chunk. A transport fault after the first chunk
+      # raises too, so the caller knows the body is incomplete. The default
+      # connection's read timeout bounds each wait for the next chunk.
+      def stream_bytes(path, token:, accept:)
+        error_body = +""
+        with_transport_norm("GET", path) do
+          response = connection.get(route_path(path)) do |req|
+            apply_token(req, token)
+            req.headers["Accept"] = accept
+            req.options.on_data = proc do |chunk, _received, env|
+              if env.status.to_i.between?(200, 299)
+                yield chunk.b unless chunk.empty?
+              else
+                keep_error_body(error_body, chunk)
+              end
+            end
+          end
+          response.env.body = error_body if !response.success? && response.body.to_s.empty?
+          ensure_success!(response, token: token) unless response.success?
+        end
+        nil
+      end
+
+      def get(path, token:, accept: "application/json", headers: nil)
+        request(:get, path, token: token, accept: accept, headers: headers)
+      end
+
+      def post(path, token:, json: nil, body: nil, content_type: nil, headers: nil)
+        request(:post, path, token: token, json: json, body: body, content_type: content_type, headers: headers)
+      end
+
+      def patch(path, token:, json: nil, headers: nil)
+        request(:patch, path, token: token, json: json, headers: headers)
+      end
+
+      # PUT with a raw (non-JSON) body — e.g. octet-stream file uploads. JSON PUTs
+      # would pass `json:` instead; `body:` + `content_type:` send bytes verbatim.
+      def put(path, token:, body: nil, content_type: nil, accept: "application/json", headers: nil)
+        request(:put, path, token: token, body: body, content_type: content_type, accept: accept, headers: headers)
+      end
+
+      def delete(path, token:)
+        request(:delete, path, token: token)
+      end
+
+      # Sends one request. A transport fault (no response) is retried with
+      # RetryPolicy's transient backoff only when the route is a replay-safe
+      # public operation (one whose safety rests on an Idempotency-Key only
+      # when the request carries one); a response of any status is never
+      # resent here.
+      def request(method, path, token:, json: nil, body: nil, content_type: nil, accept: "application/json", headers: nil, timeout: nil)
+        verb = method.to_s.upcase
+        operation = Operations.match(:computer, verb, route_path(path.to_s.split(/[?#]/, 2).first))
+        idempotency_key = headers&.find { |name, _| name.to_s.casecmp?("Idempotency-Key") }&.last
+        attempts = operation&.resendable?(idempotency_key) ? RetryPolicy::TRANSIENT_ATTEMPTS : 1
+        attempt = 0
+        begin
+          attempt += 1
+          response = with_transport_norm(verb, path) do
+            connection.run_request(method, route_path(path), nil, nil) do |req|
+              req.options.timeout = timeout if timeout
+              apply_token(req, token)
+              req.headers["Accept"] = accept
+              if json
+                req.headers["Content-Type"] = "application/json"
+                req.body = json.to_json
+              elsif !body.nil?
+                req.headers["Content-Type"] = content_type || "application/octet-stream"
+                req.body = body
+              end
+              headers&.each { |k, v| req.headers[k] = v if v }
+            end
+          end
+        rescue PineSandbox::TimeoutError, PineSandbox::ConnectionError
+          raise if attempt >= attempts
+
+          @clock.sleep(RetryPolicy.transient_backoff(attempt, @clock))
+          retry
+        end
+        ensure_success!(response, token: token)
+        ParsedResponse.new(response, accept)
+      end
+
+      # Map Faraday transport faults (timeout / connection drop / TLS failure)
+      # to the SDK's typed errors so NO coord call — unary OR streaming — leaks
+      # a raw Faraday class to an integrator (parity with the control-plane /
+      # attach / token adapters). HTTP-status errors stay typed via
+      # ensure_success!; a stop throw is not a Faraday error and passes through
+      # untouched. A transport fault has no response, so the op is built from
+      # method + path — QUERY-STRIPPED (a filename / cursor / selector must
+      # never leak into the message) — and folded resource-first via
+      # context_suffix, matching the response-status paths (which read the
+      # already-stripped env.url.path).
+      def with_transport_norm(method, path)
+        yield
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise normalize_transport_fault(e, method, path)
+      end
+
+      def normalize_transport_fault(error, method, path)
+        suffix = context_suffix(@runtime_id, op_from_route(method, path), nil)
+        if error.is_a?(Faraday::TimeoutError)
+          PineSandbox::TimeoutError.new("Computer request timed out: #{error.message}#{suffix}")
+        else
+          PineSandbox::ConnectionError.new("Computer connection failed: #{error.message}#{suffix}")
+        end
+      end
+
+      # "<METHOD> /<path>" with any query string / fragment stripped — the transport-fault
+      # counterpart to op_for (which reads env.url.path). `path` is the SDK route, sans the
+      # leading slash route_path adds.
+      def op_from_route(method, path)
+        route = path.to_s.split(/[?#]/, 2).first
+        "#{method.to_s.upcase} /#{route}"
+      end
+
+      # The coord route path on the gateway host. The gateway routes by subdomain
+      # and selects the role by PATH, so the path is just the coord route — no
+      # proxy prefix, no runtime id, no port.
+      def route_path(suffix)
+        "/#{suffix}"
+      end
+
+      def apply_token(req, token)
+        return if token.nil?
+
+        req.headers["Authorization"] = "Bearer #{token}"
+      end
+
+      # Raises the typed error for a non-2xx response. A 401 for a Computer
+      # token is TokenRejectedError; one for a session token stays the plain
+      # UnauthorizedError — only the binding's own token says the binding lost
+      # its authorization.
+      def ensure_success!(response, token: nil)
+        return if response.success?
+
+        classify_failure!(response, token)
+      rescue UnauthorizedError => e
+        raise unless e.status.to_i == 401 && token.to_s.start_with?("ct_")
+
+        raise TokenRejectedError.for_api_error(e), cause: e
+      end
+
+      def classify_failure!(response, token)
+        check_success!(response)
+      rescue NotFoundError => original
+        raise if original.is_a?(RuntimeGoneError) || !original.problem_type.to_s.empty?
+
+        # The session list is served by every live runtime, so an untyped 404
+        # there means the gateway no longer routes to it.
+        operation = Operations.match(:computer, response.env.method.to_s.upcase, response.env.url.path)
+        raise RuntimeGoneError.new(original), cause: original if operation&.id == "listSessions"
+
+        # Healthy V2 calls need no discovery round trip. Qualify only an
+        # ambiguous 404, without retrying the original operation.
+        if response.env.url.path.start_with?("/v2/")
+          begin
+            require_agent_protocol!(token: @discovery_token || token)
+          rescue AgentProtocolUnsupported
+            raise
+          rescue PineSandbox::Error
+            # Failed discovery cannot reclassify a resource error.
+          end
+        end
+        raise original
+      end
+
+      def check_success!(response)
+        return if response.success?
+
+        # If the body is RFC 9457 problem+json (the v1 control surface
+        # contract), delegate to the typed dispatcher in
+        # Concerns::ResponseHandler so callers can rescue specific
+        # exception classes (e.g. PineSandbox::InvalidField for
+        # Idempotency-Key body-hash conflicts, PineSandbox::HandoffExpired
+        # for 410 on /handoffs/{id}, etc). When the body is NOT
+        # problem+json (v0 surface, or text/html error pages from a TLS
+        # edge / the ingress), fall back to the older shape so
+        # existing callers that rescue ApiError / UnauthorizedError /
+        # NotFoundError keep working unchanged.
+        # The RESOURCE spine for every error this adapter raises: WHICH Computer (@runtime_id,
+        # held by the adapter) and WHICH operation ("<METHOD> <path>", off the Faraday env). We
+        # attach it to EVERY raised path so an integrator's generic handler sees the resource +
+        # op with no extra plumbing. request_id is the secondary precision handle.
+        op = op_for(response)
+
+        ctype = response.headers["content-type"].to_s
+        if ctype.start_with?("application/problem+json")
+          # raise_for_status! (shared ResponseHandler) builds + freezes the typed error's
+          # message before we can reach it, so fold the resource context in via #attach_context!
+          # (updates extensions AND rebuilds the message) and re-raise the SAME typed object —
+          # callers still rescue PineSandbox::InvalidField / HandoffExpired / … unchanged.
+          begin
+            raise_for_status!(response)
+          rescue PineSandbox::ApiError => e
+            e.attach_context!(runtime_id: @runtime_id, op: op)
+            if e.problem_type == "/errors/sandbox-not-found"
+              raise PineSandbox::RuntimeGoneError.new(e), cause: e
+            end
+            raise
+          end
+        end
+
+        # Every gateway-fronted response carries X-Request-Id (success or failure,
+        # problem+json or not). The problem+json branch above captures it via
+        # ResponseHandler; on these raw/legacy paths capture it here so a v0 / edge
+        # error is still correlatable. TimeoutError has no problem_extensions, so its
+        # context goes straight into the message; the ApiError fallback rides extensions.
+        rid = request_id_header(response)
+
+        # Timeouts (408/504) are a transport concern; they should be
+        # PineSandbox::TimeoutError regardless of body shape so the
+        # lost-response classification above us (agent resends, turn waits)
+        # sees the canonical class. A response is never resent by #request.
+        if response.status == 408 || response.status == 504
+          message = parse_legacy_error_message(response.body)
+          timeout = PineSandbox::TimeoutError.new(
+            "Computer request failed: status=#{response.status} message=#{message}#{context_suffix(@runtime_id, op, rid)}"
+          )
+          timeout.retry_after = retry_after_seconds(response)
+          raise timeout
+        end
+
+        # v0 + non-problem+json error: emit the older shape, now carrying the resource spine
+        # in problem_extensions so ApiError#build_message renders it resource-first.
+        message = parse_legacy_error_message(response.body)
+        klass =
+          case response.status
+          when 401, 403 then PineSandbox::UnauthorizedError
+          when 404 then PineSandbox::NotFoundError
+          when 409 then PineSandbox::ConflictError
+          when 503 then PineSandbox::ServiceUnavailableError
+          else PineSandbox::ApiError
+          end
+        ext = {}
+        ext["sandbox_id"] = @runtime_id if @runtime_id && !@runtime_id.to_s.empty?
+        ext["op"] = op if op && !op.to_s.empty?
+        ext["request_id"] = rid if rid
+        raise klass.new(
+          status: response.status,
+          error_message: "Computer request failed: status=#{response.status} message=#{message}",
+          response_body: response.body,
+          problem_extensions: (ext.empty? ? nil : ext)
+        )
+      rescue ApiError => e
+        e.retry_after ||= retry_after_seconds(response)
+        raise
+      end
+
+      # The response's Retry-After in whole seconds, or nil.
+      def retry_after_seconds(response)
+        seconds = Integer(response.headers["retry-after"].to_s.strip, exception: false)
+        seconds if seconds&.positive?
+      end
+
+      # "<METHOD> <path>" off the Faraday response env — WHICH operation failed. nil when the
+      # env/url is unavailable (never let a diagnostic detail mask the real error).
+      def op_for(response)
+        env = response.respond_to?(:env) ? response.env : nil
+        return nil unless env && env.method
+
+        url = env.url
+        path = url.respond_to?(:path) ? url.path : url.to_s
+        "#{env.method.to_s.upcase} #{path}"
+      rescue StandardError
+        nil
+      end
+
+      # Resource-first troubleshooting suffix for the message-only error paths (TimeoutError
+      # has no problem_extensions): runtime (WHICH Computer runtime) → op (WHICH operation) →
+      # request_id. Each part only when present; "" when all absent.
+      def context_suffix(runtime_id, op, rid)
+        parts = []
+        parts << "runtime=#{runtime_id}" if runtime_id && !runtime_id.to_s.empty?
+        parts << "op=#{op}" if op && !op.to_s.empty?
+        parts << "request_id=#{rid}" if rid && !rid.to_s.empty?
+        parts.empty? ? "" : " (#{parts.join(', ')})"
+      end
+
+      # X-Request-Id off a coord response (either header casing), nil/empty → nil.
+      def request_id_header(response)
+        rid = response.headers["x-request-id"] || response.headers["X-Request-Id"]
+        rid unless rid.to_s.empty?
+      end
+
+      def parse_legacy_error_message(body)
+        JSON.parse(body)["error"] || body.to_s
+      rescue JSON::ParserError, TypeError
+        body.to_s
+      end
+
+      # Faraday connection to the Computer's gateway host. The base URL sets the
+      # Host (and TLS SNI) to `<runtime_id>.computer.<zone>` — covered by the
+      # gateway wildcard cert `*.computer.<zone>`. Port-less and header-less: the
+      # gateway routes the subdomain to the pod and the PATH selects the role; no
+      # API key (coord gates every route on the bearer).
+      def connection
+        @connection ||= @zone.faraday(@host) do |conn|
+          conn.headers["User-Agent"] = "pinesandbox-ruby/#{PineSandbox::VERSION}"
+          conn.options.open_timeout = DEFAULT_OPEN_TIMEOUT
+          conn.options.timeout = DEFAULT_HTTP_TIMEOUT
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # Long-lived stream connection — disables the read timeout. The default
+      # `connection` above ships a 30s `options.timeout`; for SSE that's a
+      # papercut (a model-thinking turn or sparse control-event stream
+      # legitimately exceeds 30s of silence). Coord ships periodic `: ka`
+      # keepalive comments (every 20s) which reset Net::HTTP's read timer,
+      # so even with the default this rarely fires in practice — but the
+      # principled fix is to make the streaming socket actually long-lived.
+      #
+      # Faraday 2.x trap: `req.options.timeout = nil` does NOT mean "no
+      # timeout" on the Net::HTTP adapter. faraday-net_http 3.x only sets
+      # `http.read_timeout` when the option is truthy; nil falls through to
+      # Ruby's 60s default. The fix is to set it explicitly via the adapter
+      # block, which the adapter calls AFTER applying request_timeout.
+      def streaming_connection
+        @streaming_connection ||= @zone.faraday(@host) do |conn|
+          conn.headers["User-Agent"] = "pinesandbox-ruby/#{PineSandbox::VERSION}"
+          conn.options.open_timeout = DEFAULT_OPEN_TIMEOUT
+          # DELIBERATELY no conn.options.timeout — adapter block is authoritative.
+          conn.adapter Faraday.default_adapter do |http|
+            http.read_timeout = nil
+          end
+        end
+      end
+
+      # Wraps a Faraday::Response so callers can read `body` as the parsed
+      # JSON shape regardless of whether the response was JSON or text. Keeps
+      # the original response accessible for status/headers introspection.
+      class ParsedResponse
+        attr_reader :raw
+
+        def initialize(raw, accept)
+          @raw = raw
+          @accept = accept
+        end
+
+        def body
+          @body ||=
+            if @accept == "application/json" && !@raw.body.to_s.empty?
+              JSON.parse(@raw.body)
+            else
+              @raw.body
+            end
+        end
+
+        def status
+          @raw.status
+        end
+
+        def headers
+          @raw.headers
+        end
+      end
+
+      def escape(seg)
+        # Path-segment safe encode: keep coordinator's expectations simple.
+        # Names are alphanumeric + dash + underscore in normal use; URL-safe
+        # encode covers the edge cases without breaking ASCII paths.
+        seg.to_s.gsub(/[^A-Za-z0-9_\-.]/) { |c| "%#{c.unpack1('H2').upcase}" }
+      end
+    end
+  end
+end