pinesandbox 0.0.1 → 0.3.19

data/lib/pinesandbox/session.rb

@@ -0,0 +1,647 @@
+require "securerandom"
+require_relative "delegated_connection"
+require_relative "agent_mode"
+require_relative "drive_mode"
+
+module PineSandbox
+  # Public names for what Session#exec yields and returns. These are aliases,
+  # not new classes: `is_a?` checks against the defining classes keep working.
+  ExecEvent = ExecStreamParser::Event
+  ExecResult = Adapters::CoordinatorAdapter::ExecResult
+
+  # One session on a Computer: a browser window and a shell.
+  #
+  # Returned by {Computer#create_session} and friends; `parent` is the
+  # Computer. Holds the session-scoped `ps_*` token, never the parent's `ct_*`.
+  # Operations that accept either token use the session's own, or the
+  # Computer token for a handle read without one ({Computer#session} returns
+  # the session's metadata without its token). Session-only operations (exec,
+  # tabs, focus, epoch, drive actions, passkey intent and decisions) need the
+  # session token.
+  class Session
+    attr_reader :info, :parent
+
+    def initialize(parent:, payload:)
+      @parent = parent
+      @info = Models::Session.from_payload(payload)
+      raise PineSandbox::ApiError.new(status: 0, error_message: "empty session payload") if @info.nil?
+    end
+
+    def name
+      info.name
+    end
+
+    # Optional human-meaningful label set at create (distinct from the addressing
+    # name). nil when none was given.
+    def label
+      info.label
+    end
+
+    # The session token (ps_). A session read with Computer#session or
+    # Computer#sessions has none: only Computer#create_session returns it, so
+    # save it then.
+    def token
+      info.token
+    end
+
+    def browser
+      info.browser
+    end
+
+    def session_dir
+      info.session_dir
+    end
+
+    # session.agent.* — hand-off-the-loop driving (run/steer/answer/cancel/reset/
+    # status/result/events). The agent drives; you delegate goals. See {AgentMode}.
+    def agent
+      @agent ||= AgentMode.new(self)
+    end
+
+    # session.drive.* — drive the session with your own agent
+    # (observe/computer_use/upload_file). See {DriveMode}.
+    def drive
+      @drive ||= DriveMode.new(self)
+    end
+
+    # Attribute the next passkey enrollment for this RP to the current agent
+    # session. This grants no consent; use the session-scoped decision methods
+    # after the site starts WebAuthn.
+    def declare_passkey_intent(rp_id)
+      raise ArgumentError, "rp_id is required" if rp_id.to_s.empty?
+
+      coordinator.declare_passkey_intent(token: token, name: name, rp_id: rp_id)
+    end
+
+    # Non-secret first-enrollment decisions attributed to this agent session.
+    def pending_passkey_ceremonies
+      coordinator.list_session_passkey_ceremonies(token: token, name: name)
+    end
+
+    def approve_passkey_ceremony(ceremony_id)
+      decide_session_passkey_ceremony(ceremony_id, "approve_custodial")
+    end
+
+    def decline_passkey_ceremony(ceremony_id)
+      decide_session_passkey_ceremony(ceremony_id, "decline")
+    end
+
+    # session.learn — author a learned-skill DRAFT from THIS session's latest completed run.
+    # Authoring is a separate model run, not a task tool. Returns a {LearnResult}: a
+    # registered draft, or a not-reusable run. (An ambiguous run is simply not authored —
+    # the clarification round lives on #teach, where a person can answer.) Lifecycle/serving is on
+    # the Computer — see {Computer#skills}. Uses the Computer token (ct_).
+    #
+    # **BLOCKS until the authoring run ends — typically 30–180 s.** Use this from
+    # CLI tools, backend workers, Sidekiq-class jobs, tests, or any caller that owns its own
+    # request budget. **If you're calling from a web handler behind a reverse proxy** (Cloudflare,
+    # ALB, GFE, Heroku — all have request timeouts in the 30–100 s range), use {#start_learn}
+    # and follow {#author_events} yourself — a sync call WILL hit the proxy's idle / total cap and
+    # the connection will be severed before the terminal event arrives, even though the Computer
+    # finishes the run.
+    #
+    # `scaffold:` is an OPTIONAL seed of the SKILL.md the authoring run should
+    # continue from — frontmatter, section headers, explicit parameter names, the "## Gotchas"
+    # you already know. The run preserves its structure and fills in the body from the
+    # navigation. Capped at 32 KiB. Nil/empty authors from scratch.
+    def learn(scaffold: nil)
+      kwargs = { token: @parent.computer_token, name: name }
+      kwargs[:scaffold] = scaffold unless scaffold.nil? || scaffold.empty?
+      # /learn returns 202 + {author_session, task_id} (streaming). Subscribe
+      # to the author event stream, await the terminal Result, and translate to
+      # the LearnResult shape existing callers expect.
+      accepted = ct_call { coordinator.learn_skill(**kwargs) }
+      LearnResult.new(self, AuthorTerminalTranslator.to_learn_result(await_author(accepted["author_session"])))
+    end
+
+    # session.start_learn(scaffold:) — non-blocking variant of #learn. Returns the raw
+    # 202 envelope (`{author_session, task_id, ...}`) WITHOUT awaiting the run's end.
+    # Follow {#author_events} with the envelope's `author_session` for progress and the
+    # terminal event.
+    #
+    # Use this when the wall-clock of the run could exceed the caller's request budget
+    # (e.g. a web handler behind a proxy with a ~100 s ceiling, while authoring runs can
+    # take minutes). Mirrors {AgentMode#run}'s 202 + events pattern. Uses the Computer
+    # token (ct_).
+    def start_learn(scaffold: nil)
+      kwargs = { token: @parent.computer_token, name: name }
+      kwargs[:scaffold] = scaffold unless scaffold.nil? || scaffold.empty?
+      ct_call { coordinator.learn_skill(**kwargs) }
+    end
+
+    # session.teach(goal:) — author a draft from the human demonstration just finalized on this
+    # session (take control → demonstrate → release finalizes a handoff; then teach reads it).
+    # Returns a clarify-able {TeachResult}; the draft is tainted (a demo may touch a login/MFA
+    # field), so you still review and activate it. Uses the Computer token (ct_).
+    #
+    # **BLOCKS until the authoring run ends — typically 30–180 s.** Same reverse-
+    # proxy caveat as {#learn}: if you're calling from a web handler behind a CDN / load
+    # balancer with a 30–100 s timeout, use {#start_teach} and follow {#author_events}
+    # yourself; the proxy will sever the sync call before the terminal event.
+    #
+    # `scaffold:` mirrors #learn — an optional seed the authoring run continues from.
+    # {TeachResult#clarify} forwards it to the clarification round so your skeleton
+    # is preserved across the round-trip.
+    def teach(goal:, handoff_id: nil, clarifications: nil, scaffold: nil)
+      kwargs = {
+        token: @parent.computer_token, name: name, goal: goal,
+        handoff_id: handoff_id, clarifications: clarifications
+      }
+      kwargs[:scaffold] = scaffold unless scaffold.nil? || scaffold.empty?
+      accepted = ct_call { coordinator.teach_skill(**kwargs) }
+      term = await_author(accepted["author_session"])
+      TeachResult.new(self, goal, scaffold,
+                      AuthorTerminalTranslator.to_teach_result(term, handoff_id: accepted["handoff_id"]))
+    end
+
+    # session.start_teach(goal:, ...) — non-blocking variant of #teach. Same intent as
+    # {#start_learn}: starts teaching (or its clarification round when handoff_id +
+    # clarifications are provided) and returns the raw 202 envelope. Follow
+    # {#author_events} for the terminal event. Uses the Computer token (ct_).
+    def start_teach(goal:, handoff_id: nil, clarifications: nil, scaffold: nil)
+      kwargs = {
+        token: @parent.computer_token, name: name, goal: goal,
+        handoff_id: handoff_id, clarifications: clarifications
+      }
+      kwargs[:scaffold] = scaffold unless scaffold.nil? || scaffold.empty?
+      ct_call { coordinator.teach_skill(**kwargs) }
+    end
+
+    # session.start_refine(skill:, version:, guidance:) — non-blocking REFINE trigger.
+    # Revises an already-authored skill with a plain-language instruction. The named
+    # version's SKILL.md is the starting point, the instruction is the guidance, and —
+    # when this session holds a trustworthy completed turn — that turn's navigation is
+    # the evidence, so the session you refine FROM matters. The run registers a new
+    # draft version. Returns the raw 202 envelope (`{author_session, task_id, ...}`);
+    # follow {#author_events} for the terminal event. Guidance is capped at 64 KiB.
+    # Uses the Computer token (ct_).
+    def start_refine(skill:, version:, guidance:)
+      ct_call do
+        coordinator.refine_skill(
+          token: @parent.computer_token, name: name, skill: skill, version: version, guidance: guidance
+        )
+      end
+    end
+
+    # session.refine(skill:, version:, guidance:) — revise a skill version with a
+    # plain-language instruction and wait for the new draft. Returns a
+    # {LearnResult}. **BLOCKS until the authoring run ends**, like {#learn};
+    # behind a proxy with a short request timeout use {#start_refine} and
+    # follow {#author_events}. Uses the Computer token (ct_).
+    def refine(skill:, version:, guidance:)
+      accepted = ct_call do
+        coordinator.refine_skill(
+          token: @parent.computer_token, name: name, skill: skill, version: version, guidance: guidance
+        )
+      end
+      LearnResult.new(self, AuthorTerminalTranslator.to_learn_result(await_author(accepted["author_session"])))
+    end
+
+    # session.author_events(author_id:) — follow an authoring run started by {#start_learn},
+    # {#start_teach} or {#start_refine}. `author_id` is the `author_session` from the start
+    # call's 202 envelope. Yields each event as a typed, Hash-compatible {AgentEvent}; the
+    # run's last event is its `result` (`event.result`), whose
+    # `"terminal_reason"` says how the run ended. A dropped connection reopens
+    # from the last event seen; after five reconnects in a row that delivered
+    # nothing it raises StreamLostError. Pass `last_event_id:` (an event's
+    # `event_id`) to resume in another process. Returns the last seen event id. Without a
+    # block, returns an Enumerator that opens the stream only when iterated. Uses the
+    # session token, or the Computer token for a handle without one.
+    #
+    # @param author_id [String] the `author_session` from the start call.
+    # @param last_event_id [String, Integer, nil] resume after this event.
+    # @yieldparam event [PineSandbox::AgentEvent]
+    # @return [String, nil] the last seen event id.
+    def author_events(author_id:, last_event_id: nil, &block)
+      raise ArgumentError, "author_id is required" if author_id.to_s.empty?
+      return enum_for(:author_events, author_id: author_id, last_event_id: last_event_id) unless block
+
+      read_call do |read|
+        coordinator.follow_author_events(
+          token: read, name: name, author_id: author_id, last_event_id: last_event_id
+        ) { |event| block.call(AgentEvent.wrap(event)) }
+      end
+    end
+
+    # session.cancel_author(author_id:) — cancel an in-flight authoring run started by
+    # {#start_learn} / {#start_teach} / {#start_refine}. `author_id` is the `author_session`
+    # from the start call's 202 envelope (an opaque ID). The run ends with
+    # `terminal_reason: "canceled"` on {#author_events}. Returns the parsed 202
+    # body — `canceled: false` means the run had already finished (feedback, not an error).
+    # Uses the Computer token (ct_).
+    def cancel_author(author_id:)
+      ct_call { coordinator.cancel_author(token: @parent.computer_token, name: name, author_id: author_id) }
+    end
+
+    # session.author_skill — register a learned-skill draft DIRECTLY (your own agent
+    # wrote the SKILL.md, rather than an authoring run). `name:` is the skill's
+    # kebab-case name. Returns the draft meta. Uses the Computer token (ct_).
+    def author_skill(name:, skill_md:, reason:, origin: nil, tainted: nil)
+      ct_call do
+        coordinator.author_skill_draft(
+          token: @parent.computer_token, name: self.name, skill_name: name,
+          skill_md: skill_md, reason: reason, origin: origin, tainted: tainted
+        )
+      end
+    end
+
+    # Reads the session's latest /epoch payload. Use it to detect a browser
+    # or service restart and to read the current session_generation.
+    def epoch
+      coordinator.epoch(token: token, name: name)
+    end
+
+    def focus!
+      coordinator.focus(token: token, name: name)
+      self
+    end
+
+    # Streams an exec; yields each parsed PineSandbox::ExecEvent (type,
+    # text, data, ...). Returns a PineSandbox::ExecResult (stdout, stderr,
+    # exit_code, error_message). Block is optional.
+    def exec(command, cwd: nil, timeout_ms: nil, &block)
+      coordinator.exec(token: token, name: name, command: command, cwd: cwd, timeout_ms: timeout_ms, &block)
+    end
+
+    def tabs
+      payload = coordinator.list_tabs(token: token, name: name)
+      payload[:tabs].map { |t| Models::Tab.from_payload(t) }
+    end
+
+    # Lists files and directories under the session workdir.
+    #
+    # @param path [String, nil] workdir-relative directory to list; nil lists
+    #   the workdir root.
+    # @param pattern [String, nil] optional base-name glob filter, e.g. "*.log".
+    # @return [Array<PineSandbox::Models::FileEntry>]
+    def list_files(path: nil, pattern: nil)
+      read_call { |read| coordinator.list_files(token: read, name: name, path: path, pattern: pattern) }
+    end
+
+    # Reads one file from the session workdir. With a block, yields the file
+    # in binary chunks as they arrive instead of returning it whole, so a large
+    # file never sits in memory; an error answer raises before any chunk.
+    #
+    # @param path [String] workdir-relative file path.
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [String, nil] raw file bytes with binary encoding; nil with a block.
+    def read_file(path, &block)
+      read_call { |read| coordinator.read_file(token: read, name: name, path: path, &block) }
+    end
+
+    # A workdir file's bytes as a stream, for copying a large file onward
+    # without buffering it, such as a file a turn's result names: yields binary
+    # chunks as they arrive. Without a block, returns an Enumerator of the
+    # chunks that sends the request only when iterated
+    # (`session.open_file(path).each { |chunk| io.write(chunk) }`).
+    # An error answer raises before any chunk.
+    #
+    # @param path [String] workdir-relative file path.
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [nil, Enumerator]
+    def open_file(path, &block)
+      raise ArgumentError, "file path is required" if path.to_s.empty?
+      return enum_for(:open_file, path) unless block
+
+      read_call { |read| coordinator.read_file(token: read, name: name, path: path, &block) }
+    end
+
+    # Deposits a material (an agent INPUT file) into the session's attachments/
+    # root. `filename` is a single name — path separators ("/", "..") are
+    # rejected. The attachments root 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}.
+    #
+    # @param filename [String] single filename to deposit (no path separators).
+    # @param content [String] file bytes.
+    # @return [Hash] the response, e.g.
+    #   { "root" => "attachments", "relative_path" => "in.txt", "size" => 5 }.
+    def write_file(filename, content)
+      read_call { |read| coordinator.write_file(token: read, name: name, path: filename, content: content) }
+    end
+
+    # Lists the session's artifacts — client uploads, browser downloads,
+    # and every completed turn's agent outputs (durably captured at each turn's
+    # result). Newest-first.
+    #
+    # @param turn_id [String, nil] filter to one turn's artifacts.
+    # @return [Array<PineSandbox::Models::Artifact>]
+    def list_artifacts(turn_id: nil)
+      read_call { |read| coordinator.list_artifacts(token: read, name: name, turn_id: turn_id) }
+    end
+
+    # Reads one artifact's bytes by id. With a block, yields them in binary
+    # chunks as they arrive (see {#read_file}).
+    #
+    # @param id [String] the artifact id (from {#list_artifacts}).
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [String, nil] raw artifact bytes with binary encoding; nil with a block.
+    def read_artifact(id, &block)
+      read_call { |read| coordinator.read_artifact(token: read, name: name, id: id, &block) }
+    end
+
+    # An artifact's bytes as a stream, for copying onward without buffering
+    # the file: yields binary chunks as they arrive. Without a block, returns
+    # an Enumerator of the chunks that sends the request only when iterated
+    # (`session.open_artifact(id).each { |chunk| io.write(chunk) }`). An error
+    # answer raises before any chunk.
+    #
+    # @param id [String] the artifact id (from {#list_artifacts}).
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [nil, Enumerator]
+    def open_artifact(id, &block)
+      raise ArgumentError, "artifact id is required" if id.to_s.empty?
+      return enum_for(:open_artifact, id) unless block
+
+      read_call { |read| coordinator.read_artifact(token: read, name: name, id: id, &block) }
+    end
+
+    # Downloads the session's artifacts as a zip (optionally one turn's). With
+    # a block, yields the zip in binary chunks as they arrive (see {#read_file}).
+    #
+    # @param turn_id [String, nil] filter to one turn's artifacts.
+    # @yieldparam chunk [String] the next bytes, binary encoding.
+    # @return [String, nil] raw zip bytes with binary encoding; nil with a block.
+    def zip_artifacts(turn_id: nil, &block)
+      read_call { |read| coordinator.zip_artifacts(token: read, name: name, turn_id: turn_id, &block) }
+    end
+
+    # Deprecated: use #zip_artifacts.
+    def download_artifacts_zip(turn_id: nil, &block)
+      PineSandbox.deprecated_name("Session#download_artifacts_zip", "#zip_artifacts")
+      zip_artifacts(turn_id: turn_id, &block)
+    end
+
+    # Uploads bytes as a new artifact (created_by:upload). Storage is id-addressed
+    # and immutable — a repeated filename yields a distinct artifact.
+    #
+    # @param filename [String] a single filename (no path separators).
+    # @param content [String] the bytes.
+    # @return [PineSandbox::Models::Artifact]
+    def upload_artifact(filename, content)
+      read_call { |read| coordinator.upload_artifact(token: read, name: name, filename: filename, content: content) }
+    end
+
+    def session_generation
+      coordinator.list_tabs(token: token, name: name)[:session_generation]
+    end
+
+    def create_tab(url:, label: nil)
+      Models::Tab.from_payload(
+        coordinator.create_tab(token: token, name: name, url: url, label: label)
+      )
+    end
+
+    def patch_tab(target_id, active: nil, label: nil)
+      Models::Tab.from_payload(
+        coordinator.patch_tab(token: token, name: name, target_id: target_id, active: active, label: label)
+      )
+    end
+
+    def close_tab(target_id)
+      coordinator.close_tab(token: token, name: name, target_id: target_id)
+    end
+
+    # Destroy the session. Default leaves the session's files on disk; pass
+    # clean: true to delete them too. Deprecated alias of
+    # Computer#destroy_session, so it uses the Computer token as that does.
+    def destroy(clean: false)
+      PineSandbox.deprecated_name("Session#destroy", "Computer#destroy_session")
+      ct_call { coordinator.destroy_session(token: parent.computer_token, name: name, clean: clean) }
+    end
+
+    # Rebuild the shell after `Session#exec` returned 409 `terminal_lost`
+    # (the shell service restarted; the browser survived). After this, `exec`
+    # works again with the original PINE_* env + cwd. A second call against an
+    # already-active terminal returns 409 — treat that as success-equivalent
+    # (already rebuilt by another caller).
+    def recreate_terminal!
+      coordinator.recreate_terminal(token: token, name: name)
+    end
+
+    # Control surface.
+    #
+    # All methods below talk to `/v1/sessions/{name}/control[/*]` and
+    # `/v1/sessions/{name}/handoffs[/*]`. Mutating PATCH requires `ct_`
+    # (the Computer token, held by your backend) — `Session#token`
+    # is `ps_`-scoped, so the helpers use `parent.computer_token`. Read
+    # routes accept either; they pass `ps_` (Session#token).
+
+    # GET /v1/sessions/{name}/control. Returns a {ControlState} — the Hash
+    # { state:, etag: } — so callers can use the ETag as `If-Match:` on the
+    # next PATCH.
+    def control_state
+      read_call { |read| coordinator.get_control(token: read, name: name) }
+    end
+
+    # Raw PATCH /v1/sessions/{name}/control. Callers can supply an
+    # explicit `idempotency_key:` for cross-process retry orchestration.
+    #
+    # `actor_type:` is REQUIRED; the Computer returns 400
+    # /errors/actor-type-required when missing.
+    def update_control(controller: nil, idle_paused: nil, idle_deadline: nil,
+                       actor_type:, if_match:, force: false, idempotency_key: nil)
+      body = { actor_type: actor_type }
+      body[:controller] = controller unless controller.nil?
+      body[:idle_paused] = idle_paused unless idle_paused.nil?
+      body[:idle_deadline] = idle_deadline unless idle_deadline.nil?
+      ct_call do
+        coordinator.patch_control(
+          token: parent.computer_token, name: name, body: body,
+          if_match: if_match, force: force, idempotency_key: idempotency_key
+        )
+      end
+    end
+
+    # Hand the session to a person: GET /control for the ETag, then PATCH
+    # with it. A concurrent change (412) re-reads the state and retries once
+    # with a fresh Idempotency-Key. `force: true` (or actor_type
+    # "admin_override") records an admin override, which skips If-Match and
+    # is not retried. Returns the new {ControlState}.
+    def take_control(actor_type: "user_click", force: false)
+      set_controller("human", actor_type: actor_type, force: force)
+    end
+
+    # Hand the session back to the agent. Same handshake as #take_control.
+    def release_control(actor_type: "user_click", force: false)
+      set_controller("agent", actor_type: actor_type, force: force)
+    end
+
+    # Deprecated: use #take_control.
+    def take_human!(actor_type:)
+      PineSandbox.deprecated_name("Session#take_human!", "#take_control")
+      take_control(actor_type: actor_type)
+    end
+
+    # Deprecated: use #release_control.
+    def release!(actor_type:)
+      PineSandbox.deprecated_name("Session#release!", "#release_control")
+      release_control(actor_type: actor_type)
+    end
+
+    # POST /v1/sessions/{name}/control/notify, with the current ETag read
+    # first. Accepts `ct_` OR the session's `ps_`; this uses the session's
+    # own token when the handle has one. Returns true.
+    def notify_human(reason:, detail: nil)
+      etag = control_state.fetch(:etag)
+      read_call do |read|
+        coordinator.post_control_notify(
+          token: read, name: name, reason: reason, detail: detail,
+          if_match: etag
+        )
+      end
+    end
+
+    # POST /v1/sessions/{name}/desktop-token — ct_-only (uses
+    # parent.computer_token). Mints a short-TTL browser-safe desktop-stream
+    # connection token (dt_…). Your server hands the returned token to the
+    # browser, which presents it when opening /vnc/connect; ct_/ps_ never
+    # reach the browser. Driving needs control of the session, not this
+    # token, so the same token serves a viewer and a driver. Re-mint before
+    # each (re)connect. Returns { token:, expires_at: }. 409
+    # (NoDesktopStream) when the session is blind; 503
+    # (DesktopUnavailable) when streaming is off.
+    def desktop_token
+      ct_call { coordinator.mint_desktop_token(token: parent.computer_token, name: name) }
+    end
+
+    # Build the browser-safe {DelegatedConnection} for this session: the
+    # data-plane host, this session's name, the pinned spec major, and a
+    # freshly-minted short-TTL `dt_`. This is the ONE call a server makes to hand a
+    # browser everything it needs to connect the desktop — and NOTHING it
+    # shouldn't (no `ct_`/`ps_`/JWS). Re-call (server-side) to refresh `dt_`
+    # before each (re)connect; the web SDK drives that via a refresh callback
+    # to your server.
+    def delegate
+      dt = desktop_token
+      DelegatedConnection.new(
+        computer_host: coordinator.base_url,
+        session_name: name,
+        desktop_token: dt.fetch(:token),
+        desktop_token_expires_at: dt[:expires_at]
+      )
+    end
+
+    # GET /v1/sessions/{name}/handoffs?limit=&before=. Returns the response body
+    # { "handoffs" => [...], "next_before" => <cursor> } — pass next_before back as
+    # `before` to page older (absent = no more pages).
+    def handoffs(limit: nil, before: nil)
+      read_call { |read| coordinator.list_handoffs(token: read, name: name, limit: limit, before: before) }
+    end
+
+    # GET /v1/sessions/{name}/handoffs/{handoff_id}. Raises
+    # `PineSandbox::HandoffNotFound` (a subclass of NotFoundError) on
+    # 404, `HandoffExpired` (subclass of GoneError) on 410. The
+    # exception's `#handoff_id` accessor surfaces the same id the
+    # caller passed so error handlers can correlate without parsing
+    # the URL again.
+    def handoff(handoff_id)
+      read_call { |read| coordinator.get_handoff(token: read, name: name, handoff_id: handoff_id) }
+    end
+
+    # control_events streams the v1 SSE event feed and yields a typed
+    # struct (ControllerChanged / IdleWarning / HandoffCompleted /
+    # HandoffFailed) per emission. The block can raise to abort.
+    #
+    # Auto-resume: when the underlying HTTP stream closes (slow subscriber
+    # drop, server restart, network blip), it reconnects with the last seen
+    # event id as Last-Event-ID, waiting 0.5 s and doubling up to 5 s. After
+    # five reconnects in a row that delivered no event it raises
+    # StreamLostError; an error answer (401/403/404/…) raises at once.
+    # `max_reconnects:` additionally caps the total reconnects: once they are
+    # used up the stream returns (or raises its transport error).
+    # `reconnect_delay:` is accepted for compatibility and no longer used.
+    #
+    # Returns the most recently seen event id once the stream ends (block
+    # broke, max_reconnects exhausted, or `stop_when` returned true).
+    def control_events(last_event_id: nil, max_reconnects: nil, reconnect_delay: nil, stop_when: nil, &block)
+      raise ArgumentError, "block required" unless block
+
+      unless reconnect_delay.nil?
+        PineSandbox.deprecated_name("Session#control_events(reconnect_delay:)", "the shared reconnect backoff")
+      end
+      read_call do |read|
+        coordinator.follow_control_events(
+          token: read, name: name, last_event_id: last_event_id,
+          stop_when: stop_when, max_reconnects: max_reconnects, &block
+        )
+      end
+    end
+
+    private
+
+    def decide_session_passkey_ceremony(ceremony_id, decision)
+      raise ArgumentError, "ceremony_id is required" if ceremony_id.to_s.empty?
+
+      coordinator.decide_session_passkey_ceremony(
+        token: token, name: name, ceremony_id: ceremony_id, decision: decision
+      )
+    end
+
+    # Routes a parent-ct_ call through Computer#rebind_on_unauthorized so a
+    # rejected ct_ surfaces as the ONE documented typed signal
+    # (TokenRejectedError — a report, not an attach instruction) from Session
+    # methods too — never a raw 401. The ps_-scoped methods are deliberately
+    # NOT wrapped: a session token dies with its session, and re-attach
+    # cannot revive it.
+    def ct_call(&blk)
+      parent.rebind_on_unauthorized(&blk)
+    end
+
+    # The token for operations that accept either: the session's own, or the
+    # Computer token for a handle read without one (GET /sessions/{name}
+    # returns no ps_).
+    def read_token
+      token.to_s.empty? ? parent.computer_token : token
+    end
+
+    # Runs an either-token operation with #read_token. On the Computer token
+    # it gets the same rejected-ct_ signal as the ct_-tier methods; a session
+    # token's 401 stays an UnauthorizedError.
+    def read_call
+      return yield(token) unless token.to_s.empty?
+
+      ct_call { yield(parent.computer_token) }
+    end
+
+    # Waits out an authoring run started on this session.
+    def await_author(author_id)
+      read_call { |read| coordinator.await_author_terminal(token: read, name: name, author_id: author_id) }
+    end
+
+    def set_controller(controller, actor_type:, force:)
+      actor_type = "admin_override" if force
+      force = actor_type == "admin_override"
+      with_etag_retry(retry_precondition: !force) do |etag, key|
+        update_control(controller: controller, actor_type: actor_type, if_match: etag,
+                       force: force, idempotency_key: key)
+      end
+    end
+
+    # with_etag_retry GETs the current state, calls the block with the
+    # ETag + an Idempotency-Key, retries ONCE on 412, then raises. The retry
+    # gets a FRESH key — see below.
+    def with_etag_retry(retry_precondition: true)
+      # The mutation is ct_-only (PATCH /control); GET /control accepts either
+      # token, so read with the session's own, or the ct_ for an adopted handle.
+      fetch = -> { coordinator.get_control(token: read_token, name: name) }
+      state = fetch.call
+      begin
+        yield state.fetch(:etag), SecureRandom.uuid
+      rescue PineSandbox::ApiError => e
+        raise unless retry_precondition && e.status == 412
+        # 412 → re-GET, retry with a NEW Idempotency-Key. A 412 leaves the
+        # first attempt's key reserved but never resolved, so reusing it would
+        # wait out the reservation and then fail with 409 "duplicate
+        # Idempotency-Key did not resolve within timeout". A fresh key is a
+        # fresh side-effect — exactly what the retry intends.
+        state = fetch.call
+        yield state.fetch(:etag), SecureRandom.uuid
+      end
+    end
+
+    def coordinator
+      parent.coordinator
+    end
+  end
+end