sai-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b354a76d6581874f8fb42a95a2c08e493e35caeff8719badd6ea1b3bcc2833f7
+  data.tar.gz: '079cf8b51f0604c50904643c772085e8a63873afa437a56286140d27273a1000'
+SHA512:
+  metadata.gz: 1b7a1c2cb4783e1b4ef6a9add4d445e6dda1b6d37794c2cb23f7b95f57026deebcbf689a0dbb12772cdda9ea3427a73bf444edf1dab60b42d22c020a22859b14
+  data.tar.gz: f568d3063e62375cbc35f6f0eb2dabdcf5a173f77ab70b1f291326e39a95d640a67d8464a7a12a131e2ebc706bb7c71a8fc08366549e2752d1abc767f89effe2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simular, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,246 @@
+# sai-sdk (Ruby)
+
+Ruby SDK for the [Sai API](https://platform.simular.ai/documentation). Hand desktop work to Sai on a
+computer (a Sai cloud computer, or your own PC with the Sai app) and get the answer back, or drive a
+cloud computer yourself.
+
+Status: **alpha (0.1), unreleased**. The surface may still change before 1.0. It matches the
+[Python SDK](../python/README.md) and the [TypeScript SDK](../typescript/README.md) method for method.
+
+| Layer          | What it is                                    | Status           |
+| -------------- | --------------------------------------------- | ---------------- |
+| `sai.sessions` | A conversation with Sai on one computer       | available        |
+| `sai.control`  | Drive a cloud computer directly with Simulang | research preview |
+| `sai.turns`    | A turn's record: typed output, evidence       | available        |
+
+## Install
+
+```bash
+gem install sai-sdk          # or: gem "sai-sdk" in your Gemfile
+export SAI_API_KEY=sapi_...  # create one at https://platform.simular.ai
+```
+
+Ruby 3.1 or later. No runtime dependencies beyond the standard library (`net/http`, `json`).
+
+## Give Sai a task
+
+```ruby
+require "sai"
+
+sai = Sai::Client.new
+pc = sai.machines.list.first
+
+session = sai.sessions.create(machine: pc)
+result = session.run("Open Notepad, type hello, save it to the desktop as hello.txt")
+
+puts result.status # idle | needs_approval | error
+puts result.text   # Sai's answer
+p result.usage     # tokens and cost for this task
+```
+
+`machine:` can be left out when the account has one computer. More `session.run(...)` calls continue
+the same conversation; `sai.sessions.create` starts a new one with no memory of the old.
+`sai.sessions.list(machine: pc)` lists your sessions on the computer (desktop, CLI and API), most
+recent first, and `sai.auth.check` says who the key acts as.
+
+### Watch it work
+
+```ruby
+turn = session.send("Find last month's invoices in Downloads and total them")
+turn.events do |ev|
+  case ev.kind
+  when "step" then puts "   #{ev.text}"
+  when "approval" then turn.respond(ev.approval, "yes")
+  end
+end
+result = turn.wait
+```
+
+`ev.kind` is one of `step`, `message`, `approval`, `tool_error`, `error`, `finished`.
+`turn.events(raw: true)` adds the wire frames (reasoning, tool calls) as `other`. Without a block,
+`events` returns an `Enumerator`. `Session#send` is the API call, as in the other SDKs; Ruby's own
+`send` is still there as `__send__` and `public_send`.
+
+### Approvals
+
+`run` / `wait` return with `status == "needs_approval"` unless you pass a handler, as a block or as
+`on_approval:` (anything that responds to `call`):
+
+```ruby
+result = session.run("Clean up the temp folder") do |approval|
+  if approval.link_only?
+    puts "Approve in a browser: #{approval.url}"
+    next nil # a person answers it; keep waiting
+  end
+  next ["yes", approval.questions.map { |q| [q["options"][0]["value"]] }] if approval.type == "choice"
+
+  "yes"
+end
+```
+
+The handler returns `"yes"`, `"no"`, `"task"`, a `[response, selections]` pair for a choice, or
+`nil` to leave the approval pending. For an unattended run, `autonomous: true` runs the turn without
+approval cards, as if `"task"` had been answered up front; link-only approvals still stop it.
+
+### Files, models, stopping
+
+```ruby
+report = sai.files.upload("report.pdf") # or data: bytes, name: "report.pdf"
+session.run("Summarise the attached report", attachments: [report])
+
+allowed = sai.models.list.select(&:allowed).map(&:id)
+session.run("...", model: "anthropic/claude-opus-5-5") # sticks to the session
+
+turn = session.send("...")
+turn.abort
+```
+
+### Let a person take over
+
+```ruby
+view = sai.machines.live(pc)
+puts "Sign in here, then tell me: #{view.live_url}" # valid until view.expires_at (ms)
+# ... once they are done
+session.run("I signed in. Carry on.")
+sai.machines.revoke_live(pc) # every open link stops working
+```
+
+## Get typed results
+
+```ruby
+result = session.run(
+  "Save \"Invoice {{invoice_number}}: {{amount}} USD\" on the Desktop as {{file_name}}. Return its path.",
+  inputs: { "invoice_number" => "INV-1001", "amount" => "42.50", "file_name" => "inv-1001.txt" },
+  output_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+  success_criteria: [
+    Sai::Check.new(id: "saved", check: "The file is saved and contains the invoice line", return_evidence: true)
+  ],
+  idempotency_key: "inv-1001", # a retry returns this turn and sends nothing
+  record_trajectory: true
+)
+if result.ok?
+  puts result.record.output["path"]
+else
+  puts result.record.reason_code # e.g. output_invalid, with result.record.raw_answer
+end
+```
+
+`inputs`, `output_schema` or `success_criteria` make the message _structured_; it is rejected with
+`Sai::ConflictError` (`code == "session_busy"`) while the session is working. `thinking_level:`
+(`off`, `low`, `medium`, `high`, `xhigh`) is refused the same way.
+
+**Reading a turn later.** Every message gets a turn id, `turn.id`:
+
+```ruby
+record = sai.turns.get(turn)               # never waits
+record = sai.turns.wait(turn, timeout: 600) # until succeeded, failed or needs_input
+sai.turns.trajectory(turn).each do |step|   # needs record_trajectory: true
+  File.binwrite("step#{step.index}.jpg", sai.turns.screenshot(turn, step.index)) if step.has_screenshot
+end
+```
+
+## Drive a computer yourself
+
+Direct control runs [Simulang](https://platform.simular.ai/documentation/concepts/direct-control)
+blocks on a cloud computer. With a block, `open` closes the lease when the block ends; while it is
+open, Sai's own tasks on that computer wait.
+
+```ruby
+sai.control.open(machine: pc) do |lease|
+  puts lease.shell("hostname").stdout
+
+  r = lease.exec(<<~JS)
+    var page = await machine.browser.newtab('https://example.com')
+    var snap = await page.snapshot()
+    snap.title
+  JS
+  p r.result # Example Domain
+  File.binwrite("page.#{r.screenshot_mime_type.split('/')[1]}", r.screenshot)
+end
+```
+
+A block that threw still returns an `ExecResult`, so check `r.error` (`exception`, `timeout`,
+`interrupted`). Bytes (screenshots) are binary `String`s.
+
+## Learn code from turns (research preview)
+
+```ruby
+learned = sai.learn.create([turn]) # turns sent with record_trajectory: true
+r = sai.control.open(machine: pc) { |lease| lease.run(learned, { "site" => "https://lobste.rs" }) }
+
+fixed = sai.learn.create(
+  initial_code: learned.code,
+  evaluations: [Sai::Evaluation.new(inputs: { "site" => "https://lobste.rs" }, result: r, passed: false)]
+)
+judgement = sai.judge.create([turn], [Sai::Check.new(id: "title", check: "The agent reported a story title")])
+
+job = sai.learn.create(task_template: "Open {{site}} and read the title of the top story",
+                       inputs: { "site" => "https://news.ycombinator.com" }, machine: pc, max_iterations: 3)
+done = sai.learn.wait(job) # timeout: to stop waiting
+run = sai.learn.rollout(job, 1, 1)
+```
+
+## Run Sai for your customers
+
+```ruby
+org = Sai::Client.new(api_key: "sapi_...", org_id: "org_...") # or SAI_API_KEY, SAI_ORG_ID
+
+tenant = org.tenants.create("Riverside Clinic", external_id: "clinic-4821")
+code = org.tenants.create_enrollment(tenant) # hand code.token to your installer
+
+machine = org.tenant_machines.create(tenant, os: "windows", request_id: SecureRandom.uuid, wait: true)
+clinic = org.tenants.client(tenant) # acts as the Tenant; renews its token
+clinic.sessions.create(machine: machine.id).run("Open the calendar and read today's appointments")
+
+org.tenants.update(tenant, cloud_machine_limit: nil) # nil removes the cap; leaving it out changes nothing
+usage = org.usage.get(granularity: "month", from: "2026-10", to: "2026-10")
+page = org.usage.sessions(tenant, from: "2026-10-01", to: "2026-10-31")
+```
+
+`usage.sessions` pages what each of a Tenant's sessions spent on AI calls, for UTC days `from:` to `to:`
+(at most 93). A page can be empty and still have a `next_cursor`: keep paging until it is `nil`.
+
+To charge for a task as soon as it ends, look its session up in real time instead of a date range:
+
+```ruby
+page = org.usage.sessions(tenant, session_ids: [session.id])
+page.sessions.each do |s|
+  puts "#{s.session_id} #{s.cost_usd} #{page.as_of}" if s.settled
+end
+```
+
+With `session_ids:` (1 to 50 of the Tenant's sessions) each session comes back with its spend so far and
+`settled`: `true` once its latest task has ended and every charge for it has come in. Ask again every
+10 seconds or so until it is. `cost_usd` and `model_calls` are `nil` when the session can't be read
+in full right now. An id that is not one of the Tenant's sessions is left out. See
+[Session spend](https://platform.simular.ai/documentation/organisations/session-spend) for the limits.
+
+## Errors
+
+Every non-2xx response raises a `Sai::Error` subclass with `status`, `code`, `message`, `body` and
+`retry_after`: `AuthenticationError` (401), `BadRequestError` (400), `PermissionDeniedError` (403),
+`NotFoundError` (404), `ConflictError` (409), `LinkOnlyApprovalError` (`approval_url`), `GoneError`
+(410), `SpendCapReachedError` (403; `resets_at`), `RateLimitError` (429), `ServiceUnavailableError`
+(503), `ConnectionError`, `BlockError`. A wait past its `timeout:` raises `Timeout::Error`.
+
+A task that ran out of credit ends with `result.status == "error"` and `result.error_code` set to
+`insufficient_credits` or `free_computer_time_exhausted`: stop retrying for today.
+
+## Configuration
+
+| Keyword        | Env           | Default                  |
+| -------------- | ------------- | ------------------------ |
+| `api_key:`     | `SAI_API_KEY` | required                 |
+| `base_url:`    | `SAI_API_URL` | `https://api.simular.ai` |
+| `timeout:`     |               | 60 seconds per request   |
+| `version_tag:` |               | none                     |
+| `org_id:`      | `SAI_ORG_ID`  | for `tenants.token`      |
+
+## Development
+
+```bash
+cd ruby
+bundle install
+bundle exec rake test   # parity, conformance cases, docs snippets (SAI_DOCS_DIR)
+gem build sai-sdk.gemspec
+```

data/lib/sai/client.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Sai
+  # The Sai API client.
+  #
+  #   sai = Sai::Client.new # SAI_API_KEY, and SAI_API_URL if set
+  #   session = sai.sessions.create
+  #   puts session.run("Open Notepad and type hello").text
+  class Client
+    attr_reader :machines, :sessions, :turns, :control, :models, :files, :account, :tenant_machines
+    # Recorded turns → Simulang code, and code repair (research preview).
+    attr_reader :learn
+    # Judge recorded turns against new criteria (research preview).
+    attr_reader :judge
+    # Who the key acts as.
+    attr_reader :auth
+    # What an Organisation is charged, per Tenant and per session. Takes an Organisation Key.
+    attr_reader :usage
+    # Your customers under an Organisation. Takes an Organisation Key.
+    attr_reader :tenants
+
+    # +api_key+ defaults to +SAI_API_KEY+, +base_url+ to +SAI_API_URL+ then
+    # +https://api.simular.ai+, +org_id+ (the Organisation +tenants.token+, +tenants.client+ and
+    # +usage+ act on; only an Organisation Key needs it) to +SAI_ORG_ID+. +timeout+ is seconds
+    # per request; +version_tag+ routes requests to a tagged API revision.
+    def initialize(api_key: nil, base_url: nil, timeout: 60, version_tag: nil, org_id: nil)
+      key = api_key || ENV.fetch("SAI_API_KEY", nil)
+      if key.nil? || key.empty?
+        raise ArgumentError, "No API key: pass api_key: or set SAI_API_KEY. Create one at https://platform.simular.ai."
+      end
+
+      setup(key, base_url: base_url, timeout: timeout, version_tag: version_tag, org_id: org_id)
+    end
+
+    # @api private
+    # A client whose bearer token comes from +credential+ before each request (+tenants.client+).
+    def self.with_credential(credential, **opts)
+      allocate.tap { |c| c.send(:setup, credential, **opts) }
+    end
+    private_class_method :with_credential
+
+    def inspect
+      "#<Sai::Client>"
+    end
+
+    private
+
+    def setup(credential, base_url:, timeout:, version_tag:, org_id:)
+      url = base_url || ENV.fetch("SAI_API_URL", nil)
+      url = DEFAULT_BASE_URL if url.nil? || url.empty?
+      org = org_id.nil? ? ENV.fetch("SAI_ORG_ID", nil) : org_id
+      http = Http.new(credential, url, timeout, version_tag)
+      opts = { base_url: base_url, timeout: timeout, version_tag: version_tag, org_id: org_id }
+      @machines = Machines.new(http)
+      @sessions = Sessions.new(http, @machines)
+      @turns = Turns.new(http)
+      @learn = Learn.new(http)
+      @judge = Judge.new(http)
+      @control = Control.new(http)
+      @models = Models.new(http)
+      @files = Files.new(http)
+      @account = AccountResource.new(http)
+      @auth = Auth.new(http)
+      @usage = UsageResource.new(http, org)
+      @tenants = Tenants.new(http, org, ->(c) { Client.send(:with_credential, c, **opts) })
+      @tenant_machines = TenantMachines.new(http)
+    end
+  end
+
+  # Models a session can run on.
+  class Models
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # +allowed+ says whether this plan may use each.
+    # @return [Array<Model>]
+    def list
+      d = Parse.obj(@http.json("GET", "/v1/agents/models"))
+      Parse.list(d["models"]).map { |m| Model.parse(Parse.obj(m)) }
+    end
+  end
+
+  # Files to attach to a message.
+  class Files
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Upload one file (max 25 MB): a path, or the bytes as +data:+ with a +name:+. +name+ defaults
+    # to the path's file name.
+    # @return [Attachment]
+    def upload(path = nil, data: nil, name: nil)
+      raise ArgumentError, "pass a path, or data: with name:" if path.nil? == data.nil?
+
+      if path
+        data = File.binread(path.to_s)
+        name ||= File.basename(path.to_s)
+      end
+      raise ArgumentError, "name: is required with data:" if name.nil?
+
+      d = @http.json("POST", "/v1/agents/upload",
+                     body: data.b,
+                     # The server reads only a body that has a Content-Type; it derives the MIME
+                     # type from the name.
+                     headers: { "Content-Type" => "application/octet-stream", "x-filename" => Util.q(name) },
+                     timeout: 120)
+      Attachment.parse(Parse.obj(d))
+    end
+  end
+
+  # The account's plan and credit.
+  class AccountResource
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Plan and spendable credit. Slow-ish (billing lookup): not for a poll loop.
+    # @return [Account]
+    def get
+      Account.parse(Parse.obj(@http.json("GET", "/v1/agents/account")))
+    end
+  end
+
+  # Who the key acts as.
+  class Auth
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Raises AuthenticationError for a missing or revoked key.
+    # @return [AuthInfo]
+    def check
+      AuthInfo.parse(Parse.obj(@http.json("GET", "/v1/agents/auth")))
+    end
+  end
+
+  # What an Organisation is charged. Takes an Organisation Key; +org_id+ defaults to the client's.
+  class UsageResource
+    # @api private
+    def initialize(http, org_id)
+      @http = http
+      @org_id = org_id
+    end
+
+    # What the Organisation is charged, in total and per Tenant, per +granularity+ (+hour+, +day+
+    # or +month+; default +day+) from +from+ to +to+: +2026-10+ for a month, +2026-10-15+ for a
+    # day, +2026-10-15T09+ for an hour. Each defaults to a range that ends now.
+    # @return [OrgUsage]
+    def get(granularity: nil, from: nil, to: nil, org_id: nil)
+      params = { "granularity" => granularity, "from" => from, "to" => to }
+      OrgUsage.parse(Parse.obj(@http.json("GET", "/v1/orgs/#{Util.q(org(org_id))}/usage", params: params)))
+    end
+
+    # One page of what each of a Tenant's sessions spent on AI calls, oldest first, for the UTC
+    # days +from+ to +to+ (+YYYY-MM-DD+, both included, at most 93 days). Keep paging with
+    # +next_cursor+ until it is nil: a page can be empty and not be the last.
+    #
+    # With +session_ids+ (1 to 50) instead of the range, the named sessions' spend right now, each
+    # with +settled+, and the page's +as_of+; no paging. Charge for a task once its session is
+    # settled.
+    # @return [SessionSpendPage]
+    def sessions(tenant, from: nil, to: nil, limit: nil, cursor: nil, session_ids: nil, org_id: nil)
+      params = { "tenantId" => Util.id_of(tenant), "from" => from, "to" => to, "limit" => limit, "cursor" => cursor,
+                 "sessionIds" => session_ids.nil? || session_ids.empty? ? nil : session_ids.join(",") }
+      d = @http.json("GET", "/v1/orgs/#{Util.q(org(org_id))}/usage/sessions", params: params)
+      SessionSpendPage.parse(Parse.obj(d))
+    end
+
+    private
+
+    def org(org_id)
+      id = org_id || @org_id
+      raise ArgumentError, "No Organisation id: pass org_id: here or to Sai::Client.new, or set SAI_ORG_ID." if id.nil? || id.empty?
+
+      id
+    end
+  end
+end

data/lib/sai/control.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sai
+  # Direct control: drive a cloud computer with Simulang. No agent. A lease on the machine: at
+  # most one per machine. Research preview; model calls the code makes are billed as usual.
+  class Control
+    OPEN_TIMEOUT = 240
+
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Take a cloud computer (a Machine or its id). Returns once the lease holds it, up to about
+    # three minutes when a Sai task holds it or it has to start. Sai's tasks on that computer wait
+    # until the lease is closed. With a block, yields the lease, closes it after, and returns the
+    # block's value.
+    # @yieldparam lease [ControlLease]
+    # @return [ControlLease]
+    def open(machine:)
+      machine_id = Util.id_of(machine)
+      d = Parse.obj(@http.json("POST", ControlLease.path(machine_id), timeout: OPEN_TIMEOUT))
+      lease = ControlLease.new(@http, machine_id, Parse.num(d["expiresAfterIdleSec"]))
+      return lease unless block_given?
+
+      begin
+        yield lease
+      ensure
+        lease.close
+      end
+    end
+  end
+
+  # The result of ControlLease#shell.
+  ShellResult = Struct.new(:stdout, :stderr, :exit_code, :timed_out, keyword_init: true)
+
+  # A lease on a cloud computer. Close it when done: Sai's tasks on that computer wait until then.
+  class ControlLease
+    attr_reader :machine_id, :idle_timeout_sec
+
+    # @api private
+    def self.path(machine_id)
+      "/v1/machines/#{Util.q(machine_id)}/control"
+    end
+
+    # @api private
+    def initialize(http, machine_id, idle_timeout_sec)
+      @http = http
+      @machine_id = machine_id
+      @idle_timeout_sec = idle_timeout_sec
+      @path = self.class.path(machine_id)
+      @closed = false
+    end
+
+    # Run one Simulang (JavaScript) block. Use +var+ for anything the next block needs. A block
+    # that throws, times out or is interrupted still returns: check +result.error+. Raises
+    # GoneError once the lease has ended: open again.
+    # @return [ExecResult]
+    def exec(code, timeout_ms: nil)
+      body = { "code" => code }
+      body["timeoutMs"] = timeout_ms unless timeout_ms.nil?
+      d = @http.json("POST", "#{@path}/exec", json: body, timeout: ((timeout_ms || 120_000) + 45_000) / 1000.0)
+      ExecResult.parse(Parse.obj(d))
+    end
+
+    # Run code from +sai.learn.create+: its +main+ with +inputs+ over the parameters' defaults.
+    # +main+'s return value is +result.result+. A string runs as code with +inputs+ as is.
+    # @return [ExecResult]
+    def run(learned, inputs = {}, timeout_ms: nil)
+      code = learned.is_a?(String) ? learned : learned.code
+      args = learned.is_a?(String) ? {} : learned.parameters.to_h { |p| [p.name, p.default_value] }
+      inputs.each { |k, v| args[k.to_s] = v }
+      exec("#{code}\nawait main(#{JSON.generate(args)})", timeout_ms: timeout_ms)
+    end
+
+    # Run a shell command.
+    # @return [ShellResult]
+    def shell(command, cwd: nil, timeout_ms: nil)
+      args = { "command" => command }
+      args["cwd"] = cwd if cwd && !cwd.empty?
+      r = exec("await machine.exec(#{JSON.generate(args)})", timeout_ms: timeout_ms)
+      raise_on_block_error(r)
+      d = Parse.obj(r.result)
+      ShellResult.new(stdout: d["stdout"], stderr: d["stderr"], exit_code: d["exitCode"], timed_out: d["timedOut"])
+    end
+
+    # @return [String]
+    def read_file(path)
+      r = exec("await machine.readFile(#{JSON.generate({ 'path' => path })})")
+      raise_on_block_error(r)
+      r.result
+    end
+
+    # @return [nil]
+    def write_file(path, text)
+      r = exec("await machine.writeToFile(#{JSON.generate({ 'path' => path, 'text' => text, 'overwrite' => true })})")
+      raise_on_block_error(r)
+      nil
+    end
+
+    # The whole screen as image bytes (usually JPEG; use +exec+ for the MIME type). Needs the
+    # computer's screen-capture service; raises BlockError where it is off.
+    # @return [String] a binary String
+    def screenshot
+      r = exec("var __sai_page = await machine.pageContent(); null")
+      raise_on_block_error(r)
+      unless r.screenshot
+        raise BlockError.new("exception", r.screenshot_omitted ? "screenshot too large to return" : "no screenshot")
+      end
+
+      r.screenshot
+    end
+
+    # Stop the running block at its next step.
+    # @return [Boolean] false if nothing was running
+    def interrupt
+      d = @http.json("POST", "#{@path}/interrupt")
+      Parse.truthy(Parse.obj(d)["interrupted"])
+    end
+
+    # The lease's state: +{ "status" => "open"|"closed", "closedReason" => ..., ... }+.
+    # @return [Hash]
+    def get
+      @http.json("GET", @path)
+    end
+
+    # Clear the REPL and release the computer. Safe to call twice.
+    # @return [nil]
+    def close
+      return if @closed
+
+      begin
+        @http.request("DELETE", @path)
+      rescue GoneError
+        # already ended
+      end
+      @closed = true
+      nil
+    end
+
+    def inspect
+      "#<Sai::ControlLease machine_id=#{machine_id.inspect} idle_timeout_sec=#{idle_timeout_sec}>"
+    end
+
+    private
+
+    def raise_on_block_error(r)
+      raise BlockError.new(r.error.kind, r.error.message) if r.error
+    end
+  end
+end