pinesandbox 0.0.1 → 0.3.18

data/README.md

@@ -1,6 +1,670 @@
-# pinesandbox
+# PineSandbox Computer SDK (Ruby)
 
-This gem name is reserved by Pine AI for the official Pine Computer (PineSandbox) Ruby SDK,
-to prevent impersonation. This placeholder contains no SDK code.
+`pinesandbox` is the Ruby server SDK for Pine Computers. Create and reconnect
+Computers, run agent tasks, manage files, and authorize desktop access from
+your backend. Stop/Start restores saved cookies, learned skills, and localStorage.
+Pause/Resume retains live tabs, sessions, and memory when enabled for your project.
 
-Get the SDK from https://console.pinecomputer.io/docs.
+See the [integration guide](https://pinesandbox.io/docs/integration) for setup,
+authentication, and examples. This README covers the Ruby API.
+
+## Install
+
+Admitted users download the versioned Ruby SDK bundle from
+<https://pinesandbox.io/sdks/ruby>. Extract it under `vendor/`, then reference
+the bundle from your `Gemfile`:
+
+```ruby
+gem "pinesandbox", path: "vendor/pinesandbox-ruby-sdk-<version>"
+```
+
+Use the directory name of the bundle you extracted; the download page shows the
+exact line for the latest release.
+
+No GitHub account or package token is required. See the
+[integration guide §Install](https://pinesandbox.io/docs/integration#1-install)
+for the download and extraction commands.
+
+The current beta SDK is on the `0.3` compatibility line.
+
+## Create a Computer
+
+A **Computer** is the identity and saved browser state you keep. A **runtime** is
+one running allocation of it. A **session** is work inside that runtime.
+
+The examples use `store` for your application's encrypted database; it is not an
+SDK object. Save credentials **before** Create, then save the returned binding.
+
+```ruby
+require "pinesandbox"
+
+client = PineSandbox::Client.new(
+  api_key: ENV.fetch("PINE_SANDBOX_API_KEY"),
+  endpoint: ENV.fetch("PINE_SANDBOX_ENDPOINT")
+)
+
+credentials = PineSandbox::Computer.generate_credentials
+store.save_credentials(credentials.id, credentials.to_json)
+
+computer = client.create_computer(credentials)
+store.save_binding(computer.id, computer.binding.to_json)
+
+session = computer.create_session(name: "main", browser: true)
+session.create_tab(url: "https://example.com")
+```
+
+The two records have different lifetimes:
+
+| Save | When | Used for |
+|---|---|---|
+| `credentials.to_json` | Before Create; again if you change keys | Starting this Computer again and decrypting its saved state |
+| `computer.binding.to_json` | After each successful Create or Start | Reconnecting to that exact runtime from any backend |
+
+Both contain secrets. Keep them encrypted on your backend, never in a browser.
+For a one-off script, `client.with_computer { |computer| … }` creates and stops the
+Computer for you, raising if Stop cannot be confirmed.
+
+## Reuse it from another backend
+
+```ruby
+credentials = PineSandbox::Computer::Credentials.from_json(store.credentials(computer_id))
+binding = PineSandbox::Computer::Binding.from_json(store.binding(computer_id))
+computer = client.reconnect_computer(credentials, binding: binding)
+
+state = computer.status  # e.g. :running, :paused, :resuming
+```
+
+Reconnect reconstructs a handle locally. It makes no request, creates nothing,
+and does not replay work. Its next call targets the saved runtime, even if another
+backend has since replaced it. Store the binding revision alongside its JSON in
+your existing Computer record. Save a replacement only if its revision is newer
+(or it is the identical binding); a delayed reply must not overwrite a newer one.
+After confirmed Stop, clear the binding only if the stored revision and runtime
+still match the one stopped. Keep that revision and the durable credentials.
+Session records belong to a binding revision and cannot be reused after Start.
+
+To continue a session, also save its name and token when you create it, then use
+`computer.adopt_session(saved_name, saved_token)`. Session lookup does not return
+the token. Save agent turn IDs and event cursors alongside that session so another
+worker can wait for existing work rather than submit it again. See
+[Activity](#activity) for reconnecting event streams.
+
+## Stop, Start, Pause or Resume
+
+| Intent | Call | Result |
+|---|---|---|
+| Finish using compute | `computer.stop` | Saves supported state, releases the runtime and ends its sessions |
+| Start a stopped Computer | `client.start_computer(credentials)` | Restores saved state into a new runtime; create new sessions |
+| Keep live memory for later | `computer.pause` | Retains the runtime and sessions; requires project opt-in |
+| Continue paused work | `computer.resume` | Restores the retained runtime and sessions |
+| Observe after a connection failure | `computer.status` | Reads state without changing or renewing it |
+
+```ruby
+raise PineSandbox::TimeoutError, "Stop is unconfirmed" unless computer.stop
+
+# Later, at a safe boundary chosen by your application:
+computer = client.start_computer(credentials)
+store.save_binding(computer.id, computer.binding.to_json)
+```
+
+Stop/Start is also how an application replaces an old runtime. An SDK upgrade or
+Pine image rollout does not replace a running Computer. Start can receive a
+compatible older warm revision during rollout; it does not guarantee a build.
+
+`attach_computer` remains an alias for Start. **Use Reconnect for an existing
+runtime.** A failed Resume does not fall back to Start. Stop/Start restores saved
+browser state, not live tabs, session files or page memory. Export files first.
+[Persistence and teardown](#persistence--teardown) covers completion, recovery and
+permanent deletion.
+
+## Idle timeout and maximum age
+
+`timeout:` is the inactivity window (default five minutes), not an HTTP request
+timeout. Work renews it; reading status, watching events and other observation do
+not. It starts at allocation, so a one-minute window can expire during slow setup.
+
+Projects can opt into a lifetime policy. The standard allowance is one minute to
+24 hours of idle time and seven days of maximum runtime age; approved project
+limits can be higher. Existing allocations retain their admitted terms.
+Enrollment applies to new allocations from Ruby 0.3.13 / Go 0.3.15 and later,
+including integrations that do not use the new policy methods. A requested
+timeout above the allowance, including the SDK default, is rejected. Before
+enrolling a project, check its integrations' requested timeouts and handling of
+maximum age. Deployment alone does not enroll projects or alter existing runtimes.
+
+```ruby
+details = computer.runtime_details
+if details.lifecycle
+  updated = computer.set_idle_timeout(seconds: 3600)
+  puts updated.lifecycle.idle_timeout_seconds
+  puts updated.expires_at  # effective expiry; maximum age is unchanged
+end
+```
+
+For an enrolled runtime, changing idle timeout takes effect now while running,
+or on the next Resume while paused. It cannot extend maximum age or snapshot
+retention. Legacy runtimes keep their previous expiry clock while paused; enrolled
+runtimes use snapshot retention and maximum age. An identical value does nothing.
+After a conflict or lost response,
+read `runtime_details` before deciding whether to edit again.
+
+Maximum age includes paused time. Graceful Stop begins twelve minutes before the
+hard deadline; expiry is not proof that a final save succeeded. Plan Stop/Start
+at a safe point before that deadline when you need uninterrupted work.
+
+`runtime_details` describes the current allocation, including optional lifecycle
+terms and its opaque `runtime_revision`. Missing lifecycle means the runtime
+has no admitted project lifetime policy. `client.project_policy` optionally reads
+allowances for future allocations; ordinary operations do not require that call.
+
+`ready_timeout:` bounds allocation/readiness and `bind_ready_timeout:` bounds the
+following handshake. They do not change runtime expiry. For example,
+`timeout: 28_800, ready_timeout: 120` requests eight hours of idle time with a
+two-minute readiness wait. These waits are separate from transport retries and
+cleanup; see the [integration guide](https://pinesandbox.io/docs/integration).
+
+## Handle failures without replacing live work
+
+- A network error or `alive? == false` does not prove the runtime is gone.
+  Read `status`; its `NotFoundError` confirms runtime-record absence. A
+  data-plane `RuntimeGoneError` alone does not: paused/restoring Computers can
+  temporarily have no route.
+- `RuntimeRetainedError` (a `BindError`) means Start found an existing runtime.
+  Match its `runtime_id` to your saved binding, or reload the latest binding from
+  your database. Reconnect, Resume or finish Stop as appropriate; an ID alone
+  cannot reconstruct a missing token.
+- A Stop timeout means completion is unconfirmed, not canceled. Keep the binding
+  and observe or retry Stop. Older servers report `StopSaveError` for a failed or
+  unconfirmed save; current servers still release the runtime.
+- Serialize Create/Start per Computer in your application. On
+  `BindingRevisionConflictError`, reload the winner's saved binding instead of
+  retrying with a higher revision.
+- If a registered Computer's Start reply is lost before saving its binding,
+  serialize recovery, call `client.stop_computer(id)`, then Start separately with
+  the saved credentials. This releases the runtime whose token was lost.
+- An interrupted first Create can fail before registering the Computer. Stop-by-ID
+  then returns true, but Start raises `UnknownComputerError`. For that initial
+  creation, retry Create with your saved credentials after confirming the project
+  and ID are correct and the identity was not deleted. Do not treat every unknown
+  ID as permission to create. An allocation abandoned before registration may
+  remain until expiry; Stop-by-ID cannot discover it.
+- On `AttachAuthorizationCommittedError`, registration has succeeded. Retain its
+  non-nil credentials and reconcile the registered Computer before Start. Private
+  keys cannot be recovered from an ID.
+
+Allocation retries within one call reuse its create ID. A fresh call is a new
+attempt. Failed attach attempts clean up known allocations best-effort; process
+crashes rely on expiry. Longer requested timeouts can leave abandoned compute
+running longer. See [Errors](#errors) for the error types.
+
+## Stored credentials and older integrations
+
+The project API key stays on your backend. Computer credentials contain the state
+key, current and retained capture keys, prior state keys and ephemeral mode.
+Bindings contain the runtime ID, Computer token and binding revision. The SDK
+handles short-lived project and attach authorization internally.
+
+`computer.credentials` returns an independent copy. Credentials and bindings use
+versioned JSON shared with the Go SDK. Normal `inspect`/`to_s` output redacts
+secrets; their explicit JSON is for encrypted storage and **does contain secrets**.
+
+For integrations using older storage or field-based methods:
+
+- Use `to_json` / `from_json` for durable records. `to_h` contains raw Ruby values.
+  If upgrading from a credential struct with fewer members, convert native
+  `Marshal` dumps with that older SDK before upgrading.
+- `adopt_existing` remains supported, but its field-based handle lacks capture
+  keypairs. Retain the original complete credentials; prefer `reconnect_computer`
+  when both saved records are available.
+- Starting from a credentials value requires custom credential providers to
+  implement `current_binding` and `credentials`. Bare callables still support
+  Create and the field-based Attach form with an explicit binding revision.
+- `control_plane` and sandbox handles are SDK internals. Integrations use the
+  Computer methods above.
+
+## Sessions
+
+A session is the unit of work — a browser context + bash terminal. Create one, then
+drive it (next two sections). A Computer runs up to 3 sessions at once by default;
+`computer.capabilities` reports the limit (`sessions.concurrent`).
+
+```ruby
+session = computer.create_session(name: "researcher-1", browser: true)
+computer.session("researcher-1")            # metadata by name; token is redacted
+computer.sessions                           # list all on this Computer
+computer.destroy_session("researcher-1")    # tear down (keeps on-disk dir; clean: true to GC)
+```
+
+## Drive — Pine's agent (hand off the loop)
+
+For an attached Computer, `computer.require_agent_protocol!` checks public agent
+support before you enable agent UI. It returns the Computer or raises
+`PineSandbox::AgentProtocolUnsupported`; older Computers need Stop, then Start
+to update. The check never restarts or rebinds a Computer. Any agent call that
+reaches a Computer without public agent support raises the same local error,
+which has no HTTP status. Authorization, connection and other HTTP failures
+keep their own classes, status and problem type.
+
+`session.agent` delegates a **goal**; Pine's agent perceives the page and acts.
+Work is addressed by **turn**: a turn starts when a run or an answer is accepted
+and ends when the agent finishes, fails, is canceled or asks a question. Every
+ending is the turn's `result`, with its `usage`; a question is the result's
+summary (`turn.question`), and the answer starts the next turn, which continues
+the same goal. A session has
+**one persistent agent**, whose memory persists across runs; `reset` starts
+fresh. Mutations (`run`/`steer`/`answer`/`cancel`/`reset`) use `ct_`; reads
+(`wait`/`status`/`turns`/`events`) use `ps_` — the SDK picks the right one.
+
+Keep the turn ID with the record it belongs to and wait for that turn. The SDK
+does not require the submitting process to stay alive. Any process with the saved
+session and turn ID can continue:
+
+```ruby
+agent = session.agent
+# saved_message_id is your durable request identity. A run with the same key
+# returns the turn it admitted, so a lost response never starts a second run.
+turn = agent.run("Find the cheapest direct SFO→NRT flight next month and report the price",
+                 idempotency_key: saved_message_id)
+record.update!(turn_id: turn.turn_id)
+
+# Any worker, later:
+turn = agent.wait(turn_id: record.turn_id, timeout: 30)
+case turn.state
+when "running", "canceling" then schedule_another_wait(record)
+when "needs_input" then present_question(record, turn.turn_id, turn.question)
+when "answered" then record.update!(turn_id: turn.next_turn_id) # another worker answered
+else save_outcome(record, turn.state, turn.result) # completed, failed or canceled; result carries usage
+end
+
+# The process that receives the reply answers the turn that asked:
+turn = agent.answer(turn_id: reply.turn_id, answer: "Use the corporate Amex ending 4242")
+record.update!(turn_id: turn.turn_id)
+```
+
+`wait` holds while the turn runs and returns it when it ends or the timeout
+passes (still `running`). It never cancels the turn and never follows
+`next_turn_id` for you. A read whose response was lost, or whose problem is
+marked retryable, is read again within the timeout. Only the session's latest
+turn can be answered, so starting new work leaves an open question unanswered.
+Sending the same answer again returns the same new turn without delivering its
+secrets again; a different answer to an answered turn raises a `409`
+(`/errors/stale-turn`).
+`run`, `answer` and `cancel` resend a lost response themselves for up to about
+30 seconds, honoring `Retry-After` (`run` uses a key of its own when you pass
+none). A lost response is a network fault, a `408`, or a gateway `502`, `503` or
+`504`, which cannot say whether the Computer acted. If none arrives, `run`'s
+error carries `#idempotency_key`: save it and send the run again with it. The
+error is also a `PineSandbox::RunUnconfirmedError`, so you can rescue that name
+or the error's own class. Pass a
+key of your own, such as your message ID, so a process that restarts can do the
+same.
+
+- `agent.steer(turn_id:, text:)` — add guidance while that turn runs (best-effort;
+  never replay it automatically).
+- `agent.cancel(turn_id:)` — cancel that turn while it runs, or close its
+  waiting question (the turn ends `canceled`); any other ended turn is returned
+  unchanged, so retrying is safe. An answered turn raises a `409`: cancel the
+  turn its answer opened.
+- `agent.reset(expected_task_id: agent.status.task_id)` — forget the thread so the
+  next `run` is fresh memory (idle-only).
+- `agent.status` — the `AgentTask` and its latest `turn`, for discovery;
+  `agent.turns` — the retained turns, oldest first.
+
+`run` raises `409` if a turn is already running, or a person or your own agent
+holds the drive slot. Routes: `/v2/sessions/{name}/agent/*` in the
+[Computer API reference](https://pinesandbox.io/spec/computer).
+
+### Activity
+
+`events` streams what the agent does as typed, Hash-compatible `AgentEvent`
+values; each carries the `turn_id` it belongs to. Use it to show progress, not
+to detect how a turn ended: `wait` does that. The stream is continuous: a
+dropped connection reopens from the last event it delivered, and after five
+reconnects in a row that delivered nothing it raises `StreamLostError` (a
+`ConnectionError`). Break out of the block to stop reading.
+
+```ruby
+task_id = agent.status.task_id
+# A saved event cursor is valid only for the Task it was stored with.
+cursor = session_progress.last_agent_event_id if session_progress.agent_task_id == task_id
+agent.events(last_event_id: cursor, expected_task_id: task_id) do |e|
+  apply_event_and_commit_cursor!(e)
+  if (change = e.control_change)
+    update_driver_banner(change.controller, change.mode_epoch)
+  elsif (progress = e.progress)               # the agent explains what it is doing
+    narrate(progress.text)
+  elsif (step = e.activity)                   # one row per step, upserted by step.id
+    # step.title is the Computer's own description, such as "Click “Log in”";
+    # step.kind and step.facts add detail. Every step ends with one outcome,
+    # "interrupted" included.
+    upsert_step(step.id, step.state, step.title)
+  end
+end
+```
+
+A captured screen carries its matching step when known: `frame.activity`
+is a typed activity snapshot, so a frame read from partial history still has
+its action title and outcome. Attach it by activity ID without counting another
+outcome or changing completion time. An absent activity means an independent
+observation; do not guess from nearby events. A text-only update leaves the last
+captured screen and its original attribution visible. Keep historical selection
+separate from following new frames; the event ID identifies each image for replay.
+
+This SDK requires a Computer runtime with the public V2 agent contract. There is
+no fallback to native trace. Activity includes progress, questions and results;
+native commands, reasoning and provider metadata are internal-only. Upgrade
+agent consumers before moving them to the new runtime: its legacy agent routes
+reject ordinary bindings.
+
+Paged history uses the same typed events as streaming. Scope every saved cursor
+to its Task; after a session replacement, discover the new Task before replaying
+history. Reset clears agent memory while preserving the Task and its history.
+
+```ruby
+page = agent.events_page(after: saved_cursor, expected_task_id: saved_task_id)
+page.fetch("events").each { |event| apply_event!(event) }
+# Persist saved_task_id with page.fetch("next_after") only after applying.
+# A stale-task refusal requires rediscovery with a fresh cursor, never a retry
+# of saved_cursor against the replacement Task.
+```
+
+## Drive — your own agent (you drive)
+
+`session.drive` is the "bring your own agent" surface: you perceive and act. The
+vision-friendly primitive is the **observe → act loop**:
+
+```ruby
+drive = session.drive
+loop do
+  snap   = drive.observe                              # { screenshot, viewport, device_scale_factor, scroll, ... }
+  action = my_policy.next(snap)                       # your model/policy decides
+  break if action.done?
+  drive.computer_use(action.kind, **action.fields)    # e.g. :left_click, coordinate: [x, y]; :type, text: "hi"
+end
+
+drive.upload_file("input[type=file]", "resume.pdf")   # set a file input (deposit the file first)
+```
+
+`observe` is read-only (allowed even while Pine's agent runs — you can watch);
+`computer_use` / `upload_file` take the drive slot (`409` if Pine's agent or a person
+holds it). Pine's resident agent can use private DOM/browser tools through
+`session.delegate`; direct customer shell execution runs public programs and
+works with session files. It cannot invoke Pine's private browser implementation.
+Raw CDP is an image-owned runtime transport and is intentionally absent from
+the SDK surface. Tab helpers
+(`create_tab`/`tabs`/`patch_tab`/`close_tab`), `focus!`, and `epoch` round out the manual
+surface. Public routes are defined by the
+[Computer API reference](https://pinesandbox.io/spec/computer).
+
+## Files & artifacts
+
+A session has a **workdir** (where `exec` runs and the agent works), an inbound
+**attachments** root (files you hand the agent), and an **artifact registry** (the
+session's managed outputs).
+
+```ruby
+# Read the workdir (what the agent produced / your shell wrote):
+session.list_files(pattern: "*.csv")             # => [FileEntry, ...]
+session.read_file("out/report.csv")              # => bytes (binary encoding)
+
+# Deposit a material the agent should use. It lands in attachments/ and surfaces
+# to the agent via the materials preamble — a sibling of the workdir, so it is NOT
+# read_file-able (read_file serves the workdir).
+session.write_file("brief.md", File.read("brief.md"))
+
+# Artifacts — the session's managed outputs, each with metadata + a download.
+art = session.upload_artifact("logo.png", File.binread("logo.png"))  # => Models::Artifact
+session.list_artifacts                            # all, newest-first
+session.list_artifacts(turn_id: "turn_…")         # just one agent turn's outputs
+session.read_artifact(art.id)                     # => bytes
+session.zip_artifacts                             # => a .zip of all artifacts (bytes)
+session.open_artifact(art.id) { |chunk| io.write(chunk) }  # stream it without buffering
+```
+
+`created_by` names the producer: `upload` (you), `download` (a browser download,
+auto-indexed), `agent` (a turn's outputs, durably captured at the turn's result). Only
+`agent` artifacts carry a `turn_id`, so the `turn_id` filter scopes to one turn's
+outputs; uploads/downloads always appear unfiltered. Uploads are immutable +
+id-addressed (a repeated filename yields a distinct artifact). Routes: `/files`,
+`/artifacts[/{zip,artifact_id}]` in the
+[Computer API reference](https://pinesandbox.io/spec/computer).
+
+## Skills — `learn` / `teach` (and when each blocks)
+
+`session.learn` and `session.teach` author a learned-skill **draft** from
+either the agent's last finished turn (`#learn`) or the demonstration a person
+just finished and released (`#teach`). The draft lands pending in the
+Computer's `skills.drafts` queue, and you activate it before any future agent
+sees it. Both start a separate authoring model run that typically takes
+**30–180 s** of wall-clock.
+
+There are **two flavors** of each, and choosing the right one matters under
+realistic networking:
+
+| Method | Returns when | Use when |
+|---|---|---|
+| `session.learn(scaffold:)` / `session.teach(goal:)` | The authoring run ends (blocks on its event stream) | CLI tools, backend workers / Sidekiq jobs, tests, smoke scripts — anything that owns its own request budget |
+| `session.start_learn(scaffold:)` / `session.start_teach(goal:)` | Immediately, with the raw 202 envelope `{author_session, task_id[, handoff_id]}` | A web handler behind a reverse proxy (Cloudflare, ALB, GFE, Heroku) where the request timeout is 30–100 s — the proxy will sever the sync call before the terminal event |
+
+The blocking variant wraps the non-blocking one: it starts the run, follows
+its events to the terminal event, and translates that into a `LearnResult` /
+`TeachResult`. The only difference is whether **you** follow the events with
+`session.author_events` or the SDK does on your behalf.
+
+```ruby
+# Blocking — fine from a Sidekiq job
+result = session.learn(scaffold: "---\nname: book-united\ndescription: …\n---\n")
+result.learned?  # => true / false
+result.draft     # => { "name" => "book-united", "version" => 1, … }
+
+# Non-blocking — what you want from a Rails controller behind CF
+accepted = session.start_learn(scaffold: scaffold)
+# accepted["author_session"] => an opaque ID; pass it back unchanged
+# Follow the run on your own time (pass last_event_id: to resume):
+session.author_events(author_id: accepted["author_session"]) do |evt|
+  break if evt.result     # then process evt.result["terminal_reason"]
+end
+```
+
+`session.cancel_author(author_id:)` cancels a run that is still in flight.
+
+Activation, drafts review, and the rest of the lifecycle live on the
+**Computer**, not the session — `computer.skills.{list, drafts, get(name),
+activate(name, version:), deactivate(name)}`. Draft review is the safety
+gate: nothing learned reaches another agent until you activate it.
+
+## Persistence & teardown
+
+```ruby
+computer.checkpoint     # synchronous state save (content-hash dedup) — before a risky step
+computer.stop           # save cookies, learned skills and localStorage, then delete the sandbox
+computer.kill           # delete without an acknowledged save
+client.delete_computer(computer)  # PERMANENT: kill if attached, then delete id + saved state
+```
+
+`stop` and `kill` keep the Computer's identity and saved state; `delete_computer`
+(a `Computer` or its id) ends both. The id is refused for every later attach, saved
+state is purged after 24 hours, and the id is never reusable. Deleting an unknown,
+already-deleted, or other project's id also returns `true`. There is no undelete.
+
+`stop` submits graceful Stop to the runtime controller, then waits up to 390s
+(`wait_timeout:`) for compute release. The controller tries to save supported state
+before deletion and continues if the SDK process disappears. Saving is best effort:
+a save that fails or is not confirmed by the deadline still releases the runtime,
+and `stop` returns true; the next Start restores the last saved state. Reconstruct
+the saved handle with `reconnect_computer` to observe or join the same operation from
+another backend. Only an older server keeps the source and raises
+`PineSandbox::StopSaveError`; its `retryable` flag distinguishes a retryable save
+failure from an unconfirmed outcome after the Computer's services restart.
+A `false` return means completion is unconfirmed. Keep the saved binding for retry.
+After Stop returns true, clear the stored binding only if its revision and
+runtime still match the handle stopped; a concurrent Start may have replaced it.
+Keep the revision fence, identity, state key and capture keypairs for future Start. Ephemeral
+bindings skip persistence; the runtime's binding record decides this.
+
+If a Start response was lost before saving the runtime token, use
+`client.stop_computer(id)` to stop the currently bound runtime with project
+authorization alone, then call Start separately. This lookup selects one binding;
+it never follows a concurrent newer binding. Private keys remain necessary for
+Start and cannot be recovered from the ID.
+
+A true result proves compute release or authoritative runtime absence. It does
+not prove a final save by a runtime that disappeared, and provider snapshot cleanup
+can still be running. Start restores only the latest committed state. Cookies,
+learned skills and compatible localStorage survive supported saved-state recovery;
+tabs, session files, page memory and IndexedDB do not.
+
+`start_computer` reads the current binding revision once, checks that the old
+runtime is gone or released, waiting for an already accepted deletion if needed,
+and creates a new binding. A conflict stays a conflict;
+it never adopts a newer revision and displaces another worker's winner. For a
+recorded failed runtime, explicitly call
+`client.recover_computer(id, key: key, capture_keypair: keypair)`.
+Recovery accepts possible unsaved-state loss, releases the observed failed runtime
+with a version precondition, waits up to 90s for compute release, then Starts. It
+refuses healthy running/paused runtimes and an unresolved capture timeout. If
+release times out, retry later; no replacement has been allocated. `kill` remains
+an unconditional destructive operation.
+
+This SDK's retryable allocation and server-owned Stop require the updated backend
+and a compatible Computer runtime; neither requires Pause opt-in. Existing
+Computer create, capture/Finish and delete calls remain supported for applications
+keeping their prior SDK. Complete the backend rollout before upgrading, including
+the conditional-release support used by recovery. A pool image update does not
+upgrade an already-running Computer: stop old-image bindings with the prior SDK
+before upgrading their caller. Integrations using the removed generic
+public sandbox operations must migrate to the Computer contract; the private Ruby
+`ControlPlane#create` adapter is removed as well.
+
+For projects opted in to Pause/Resume on snapshot-capable runtimes:
+
+```ruby
+computer.pause(timeout: 360)  # waits for capture and confirmed source stop
+computer.resume(timeout: 360) # waits for restored routing and runtime recovery
+```
+
+Pause is disabled by default. Pine enables it for a project on request;
+refresh the project token after it is enabled. Disabling the
+feature prevents new pauses but preserves Resume and Stop for retained memory.
+Ordinary Stop/Start remains available without the opt-in.
+
+The same sandbox handle, session capabilities and retained process memory remain.
+A pool image update does not change the captured runtime. Calls include acceptance
+and completion in one bounded timeout. A timeout leaves the outcome unconfirmed;
+retry against the retained handle. The controller restores the same paused
+runtime before Stop can save it. Snapshot retention and admitted maximum age still apply; legacy expiry is unchanged.
+
+Do not rescue a failed `resume` by automatically calling `start_computer`.
+Retrying Resume keeps the existing memory-recovery intent; Start explicitly
+accepts recovery from the last saved state with new sessions and possible loss
+of unsaved work. An unavailable status or timeout alone does not prove that
+memory is lost. The [Computer API reference](https://pinesandbox.io/spec/computer)
+defines the observed states and recovery choices: retry Resume, refresh the
+status, or Start from saved state.
+
+## Errors
+
+Three typed families, one per credential exchange (see `lib/pinesandbox/errors.rb`):
+
+Data-plane runtime loss raises `PineSandbox::RuntimeGoneError`; it preserves the
+wire diagnostics and original `ApiError` cause. Errors about a resource on a
+live Computer remain distinct, including `PineSandbox::SessionNotFound` and
+`PineSandbox::ControlNotHeld`.
+
+- **`BindError`** — `Computer#attach` outcomes: `BindAuthError`,
+  `ComputerAlreadyAttachedError`, `RuntimeUnusableError`, `SavedStateUnavailableError`,
+  `BindTimeoutError`; plus `TokenRejectedError` on a post-bind 401 for the
+  Computer token (`ct_` not recognized — on a live runtime it is
+  `binding_auth_lost`; re-attach only when the runtime is confirmed gone). A 401
+  for a session token is an ordinary `UnauthorizedError`. If `create_computer` raises
+  `AttachAuthorizationCommittedError`, retain its non-nil `#credentials` and inspect `#runtime_id` before deciding
+  whether to stop or recover the failed runtime. Credential inspection redacts private material.
+- **`AttachCredentialsError`** — the portal attach-credentials flow:
+  `UnknownComputerError` (404 — deleted or cross-project),
+  `ProjectAccessDenied` (403), and `BindingRevisionConflictError` (412 — another start changed the binding; `#current_binding_revision` /
+  `#current_runtime_id` identify the winner. Do not retry automatically). A bad `pk_` (401),
+  rate limit (429), and server errors are the base `AttachCredentialsError`.
+  Inspect the stable problem `#problem_type` and optional safe `#reason`; raw
+  internal exceptions are never part of the API contract.
+- **`ControlTokenError`** — the `pk_` → project-token mint: `InvalidClientKey`
+  (401), `InsufficientScope` (403), `RateLimited` (429, carries `#retry_after`).
+  A `Retry-After` longer than the mint's 10-second backoff cap ends the mint at
+  once with that error instead of retrying early.
+
+The old names `SandboxGoneError`, `SandboxFailedError`, `PodPoisonedError`,
+`BrokerUnreachableError`, `SandboxHandle` and the `sandbox_id` readers keep
+working as deprecated aliases; they warn when Ruby's deprecation warnings are on.
+
+## Troubleshooting — reporting an issue
+
+The SDK supports saved Computer diagnostics. They require the diagnostics backend; older deployments do not serve them. The request needs an existing Computer ID, not its private keys or a live handle:
+
+```ruby
+# Persist one key per logical request if you need to retry after a lost response.
+report = client.create_diagnostic(computer_id: saved_id, session: "main",
+                                  idempotency_key: diagnostic_request_key)
+support_reference = report.fetch("id")
+# Read later. Only poll queued/running reports, with a bounded deadline.
+report = client.get_diagnostic(support_reference)
+puts report.dig("assessment", "message") if report["assessment"]
+```
+
+Supply a session name to investigate its recorded agent work; omit it for a lifecycle check. The investigation does not operate the application or repeat its work. It produces a private report for Pine support and a separate customer-safe assessment. Optional descriptions provide private context. An unavailable diagnostic does not justify repeating customer work. Requesting a report does not open a human support ticket; share its reference separately when asking Pine for help.
+
+Clients declaring `diagnostic_response_metadata?` expose `report.retry_after` and
+`PortalError#retry_after` as seconds, including HTTP-date hints. Honor the hint
+before polling or retrying, even when it exceeds your normal backoff cap. Stop
+at your application deadline instead of retrying early. The response remains
+Hash-compatible, and the metadata is not added to its JSON payload. Earlier
+packages do not expose these hints; see the changelog for release availability.
+
+Errors are **self-describing at the resource level**: every error the SDK raises off a
+gateway-fronted response folds the failing Computer + operation into `e.message` — resource
+first — so a generic handler that logs only `e.message` shows WHICH Computer and WHICH call
+failed with no extra plumbing.
+
+```ruby
+begin
+  session.agent.run("book the 9am slot")
+rescue PineSandbox::ApiError => e
+  logger.error(e.message)
+  # => "… (runtime=sbx_abc123, op=POST /v2/sessions/main/agent/run, request_id=req_abc123)"
+  Report.open(computer_id: computer.id, session: session.name,
+              at: Time.now.utc, request_id: e.request_id, op: e.op)
+end
+```
+
+Each error class exposes exactly its own typed context (the message always carries the same
+data): Computer API **`ApiError`** → `#runtime_id` / `#op` / `#request_id`; control-plane errors
+→ `#op` / `#request_id`; portal **`ControlTokenError`** / **`AttachCredentialsError`** → `#op`
+/ `#request_id`. The suffix grammar is uniform `key=value` across the Go and Ruby SDKs; Ruby
+Computer API errors use **`runtime=`** because the Ruby SDK holds the runtime id, where the Go SDK
+uses **`host=`** because its client holds the Computer host (same Computer, different handle
+each SDK already has).
+
+When you file a report, **lead with the resource spine** — the durable key Pine support uses
+to find the failure:
+
+1. **`computer_id`** (`computer.id`) — WHICH Computer. Add the **session name** (`session.name`)
+   and, for an agent-lane issue, the **`task_id`**.
+2. A **UTC time window**.
+3. **`request_id`** *when you have it* — the precision handle for a single failed call
+   (`e.request_id`, also in the message). A read or stream that fails *without* a response —
+   a `PineSandbox::TimeoutError` / `ConnectionError`, which carry no id — is still actionable
+   off the resource spine alone (the op is still in their message).
+
+## Known limitations
+
+- Pause/Resume requires a qualified snapshot-capable Computer runtime.
+  Other runtimes reject it as unsupported. Snapshot loss, expiry or
+  failed recovery surfaces an error; it never silently falls back to a fresh
+  runtime. Enrolled runtimes use snapshot retention and maximum age while paused; legacy expiry is unchanged.
+
+## Develop
+
+```bash
+make install   # bundle install
+make lint       # ruby -c syntax over lib + spec
+make test       # rspec (unit; .rspec scopes to spec/pinesandbox)
+make build      # gem build pinesandbox.gemspec
+```