pinesandbox 0.0.1 → 0.3.19

data/README.md

@@ -1,6 +1,672 @@
-# pinesandbox
+# Pine Computer Ruby SDK
 
-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://console.pinecomputer.io/docs/integration) for setup,
+authentication, and examples. This README covers the Ruby API.
+
+## Install
+
+```sh
+bundle add pinesandbox
+```
+
+Bundler pins it to the latest release's compatibility line (`"~> 0.3.<patch>"`), so
+`bundle update` takes later patches but not a new minor version. Using it needs a project key (`pk_…`) from the
+[Console](https://console.pinecomputer.io). Pine Computer is in beta:
+[request access](https://pinecomputer.io/#access) if you don't have one yet. Each
+release is also an archive on the [Ruby SDK page](https://console.pinecomputer.io/sdks/ruby),
+for vendoring.
+
+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 **session** is
+work inside the running Computer.
+[Terms](https://console.pinecomputer.io/docs/how-a-computer-works#terms) defines
+the rest.
+
+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(browser: true) # Pine picks the name: save session.name
+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 the running Computer 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. When the block raises, its
+error propagates and an unconfirmed Stop is only warned about.
+
+## 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 goes to the Computer sandbox the binding
+names, even if another backend has since started the Computer again. 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 sandbox
+id 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, shuts the Computer down and ends its sessions |
+| Start a stopped Computer | `client.start_computer(credentials)` | Runs the Computer from its saved state; create new sessions |
+| Keep live memory for later | `computer.pause` | Keeps the Computer and its sessions in memory; requires project opt-in |
+| Continue paused work | `computer.resume` | Brings back the paused Computer and its 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 updates a Computer. 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 a Computer
+that's running or paused.** 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 when the Computer starts, so a one-minute window can expire during
+slow setup.
+
+Projects have a lifetime policy unless Pine removed it for one. The standard
+allowance is one minute to 24 hours of idle time and seven days of maximum age;
+approved project limits can be higher. A project without one has no maximum age
+and no idle maximum. A running Computer keeps the terms it started with.
+A requested timeout above the allowance, including the SDK default, is rejected.
+
+```ruby
+details = computer.sandbox_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 a Computer started after enrollment, changing idle timeout takes effect now
+while running, or on the next Resume while paused. It cannot extend maximum age or
+snapshot retention. Computers started before enrollment keep their previous expiry
+clock while paused; those started after use snapshot retention and maximum age. An
+identical value does nothing.
+After a conflict or lost response,
+read `sandbox_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.
+
+`sandbox_details` describes the current Computer sandbox, including optional
+lifecycle terms and its opaque `runtime_revision`. Missing lifecycle means the Computer
+was started without a project lifetime policy. `client.project_policy` optionally reads
+allowances for future starts; ordinary operations do not require that call.
+
+`ready_timeout:` bounds waiting for the Computer to start and become ready, and
+`bind_ready_timeout:` bounds the following handshake. They do not change the
+Computer's 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://console.pinecomputer.io/docs/integration).
+
+## Handle failures without replacing live work
+
+- A network error or `alive? == false` does not prove the Computer has stopped.
+  Read `status`; its `NotFoundError` confirms that it has. A
+  data-plane `SandboxGoneError` alone does not: paused/restoring Computers can
+  temporarily have no route.
+- `SandboxRetainedError` (a `BindError`) means Start found the Computer still
+  running or paused.
+  Match its `sandbox_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 shut the Computer down.
+- 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 stops the Computer 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. A Computer sandbox started before registration may
+  run until it expires; Stop-by-ID cannot find 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.
+
+Retries within one call reuse its create ID. A fresh call is a new attempt. A
+failed attach shuts down the Computer sandbox it started, on a best-effort
+basis; after a process crash, that Computer sandbox runs until it expires.
+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 sandbox 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 the handles it returns 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://console.pinecomputer.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 that serves 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 you restart their Computers on the new release: 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). Shell commands run ordinary programs and work with the session's
+files. 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://console.pinecomputer.io/spec/computer).
+
+## Files
+
+A session has a **workdir** (where `exec` runs and the agent works) and an inbound
+**attachments** root (files you hand the agent), which appears inside the workdir as
+`attachments/`.
+
+```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)
+session.open_file("out/export.zip") { |chunk| io.write(chunk) }  # stream it without buffering
+
+# Give the agent an input file. It lands in attachments/ (readable as
+# read_file("attachments/brief.md")), and the agent sees it when its next turn starts.
+session.write_file("brief.md", File.read("brief.md"))
+
+# The files an ended turn produced, by workdir path:
+turn.result.artifacts.each do |file|
+  path = file.fetch("relative_path")
+  save(path, session.read_file(path))
+end
+```
+
+A turn's result lists its files by `relative_path` in the workdir, with size, SHA-256
+and media type. They aren't copies: read them when the turn ends, because a later turn
+or shell command can change them. A browser download isn't one of them; to get one
+back, ask for it in the goal, and the agent copies it into the workdir and lists it.
+Without a block, `open_file` returns an Enumerator of the chunks. Session files last
+until the Computer stops; save what you need first. Routes: `/files` in the
+[Computer API reference](https://console.pinecomputer.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 shut the Computer down
+computer.kill           # shut the Computer down without waiting for a 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 Pine's controller, then waits up to 390s
+(`wait_timeout:`) for the Computer to shut down. 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 shuts the Computer down,
+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
+sandbox id 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; Pine's binding record decides this.
+
+If a Start response was lost before saving the Computer token, use
+`client.stop_computer(id)` to stop the Computer 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 the Computer has shut down or was already gone.
+It does not prove a final save when the Computer had already gone, 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
+Computer has stopped, waiting for an already accepted shutdown 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
+Computer you recorded as failed, explicitly call
+`client.recover_computer(credentials)`.
+Recovery accepts possible unsaved-state loss, shuts the failed Computer down
+with a version precondition, waits up to 90s for it to shut down, then Starts. It
+refuses healthy running or paused Computers and an unresolved capture timeout. If
+shutting it down times out, retry later; nothing new has been started. `kill` remains
+an unconditional destructive operation.
+
+This SDK's retryable Start and server-owned Stop require the updated backend
+and a compatible Computer; 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 lifecycle 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 Computers that support snapshots:
+
+```ruby
+computer.pause(timeout: 360)  # waits for capture and confirmed source stop
+computer.resume(timeout: 360) # waits until the Computer is restored and reachable
+```
+
+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 Computer handle, session capabilities and retained process memory remain.
+A pool image update does not change a paused Computer. Calls include acceptance
+and completion in one bounded timeout. A timeout leaves the outcome unconfirmed;
+retry against the retained handle. The controller restores the paused Computer
+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://console.pinecomputer.io/spec/computer)
+defines the observed states and recovery choices: retry Resume, refresh the
+status, or Start from saved state.
+
+## Errors
+
+[Troubleshooting](https://console.pinecomputer.io/docs/troubleshooting) says what
+each common error means and how to fix it.
+
+Three typed families, one per credential exchange (see `lib/pinesandbox/errors.rb`):
+
+A Computer that can no longer be reached raises `PineSandbox::SandboxGoneError`;
+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`, `SandboxUnusableError`, `SavedStateUnavailableError`,
+  `BindTimeoutError`; plus `TokenRejectedError` on a post-bind 401 for the
+  Computer token (`ct_` not recognized — on a running Computer it is
+  `binding_auth_lost`; re-attach only when the Computer is confirmed stopped). A 401
+  for a session token is an ordinary `UnauthorizedError`. If `create_computer` raises
+  `AttachAuthorizationCommittedError`, retain its non-nil `#credentials` and inspect `#sandbox_id` before deciding
+  whether to stop or recover the failed Computer. 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_sandbox_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 `PodPoisonedError` (now `SandboxUnusableError`) and
+`BrokerUnreachableError` (now `SavedStateUnavailableError`) 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: saved_session_name,
+                                  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)
+  # => "… (sandbox=<sandbox-id>, 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`** → `#sandbox_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 **`sandbox=`** because the Ruby SDK holds the sandbox 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 Computer that supports snapshots; others reject it as
+  unsupported. Snapshot loss, expiry or failed recovery surfaces an error; it
+  never silently falls back to a fresh start. Computers started after enrollment
+  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
+```