oz-agent-sdk 0.1.0

data/Rakefile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require_relative 'lib/oz/version'
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  task :spec do
+    abort 'rspec is not available. Run `bundle install` first.'
+  end
+end
+
+begin
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new(:rubocop)
+rescue LoadError
+  task :rubocop do
+    abort 'rubocop is not available. Run `bundle install` first.'
+  end
+end
+
+desc 'Run the full check suite (rubocop + specs)'
+task ci: %i[rubocop spec]
+
+desc 'Release gem to RubyGems'
+task release_gem: [:build] do
+  sh "gem push pkg/oz-agent-sdk-#{Oz::VERSION}.gem"
+end
+
+task default: %i[rubocop spec]

data/docs/api_reference.md

@@ -0,0 +1,156 @@
+# API Reference
+
+All operations hang off `client.agent`. Responses are `Oz::Model` instances (see
+[Responses](#responses)); list endpoints that paginate return an `Oz::CursorPage`.
+
+## Agent
+
+### `client.agent.run(**params)` → `Oz::Model`
+
+`POST /agent/runs` — start a new agent run.
+
+| Param                | Type           | Notes                                                          |
+| -------------------- | -------------- | -------------------------------------------------------------- |
+| `prompt`             | String         | Instruction. Required unless a skill is supplied.             |
+| `config`             | Hash           | Cloud run config (`AmbientAgentConfig`), see below.           |
+| `conversation_id`    | String         | Continue an existing conversation.                            |
+| `attachments`        | Array<Hash>    | Up to 5 `{ data:, file_name:, mime_type: }` (base64 `data`).  |
+| `interactive`        | Boolean        | Whether the run is interactive (default false).              |
+| `mode`               | String         | `"normal"`, `"plan"`, or `"orchestrate"`.                     |
+| `parent_run_id`      | String         | Parent run for orchestration trees.                          |
+| `skill`              | String         | Skill spec used as the base prompt.                          |
+| `team`               | Boolean        | Create a team-owned run.                                     |
+| `title`              | String         | Custom run title.                                            |
+| `agent_identity_uid` | String         | Execution principal (team runs only).                       |
+
+Returns `{ run_id, state, task_id, at_capacity }`.
+
+Common `config` keys: `environment_id`, `model_id`, `name`, `base_prompt`, `mcp_servers`,
+`harness`, `harness_auth_secrets`, `inference_providers`, `memory_stores`, `skills`,
+`skill_spec`, `computer_use_enabled`, `idle_timeout_minutes`, `session_sharing`,
+`worker_host`.
+
+```ruby
+client.agent.run(
+  prompt: 'Fix the failing test',
+  config: { environment_id: 'env-123', model_id: 'claude-sonnet-4', name: 'ci-fix' }
+)
+```
+
+### `client.agent.list(**params)` → `Oz::Model`
+
+`GET /agent` — list available agents (skills). Params: `include_malformed_skills`,
+`refresh`, `repo` (`"owner/repo"`), `sort_by` (`"name"` | `"last_run"`). Returns
+`{ agents: [...] }`.
+
+### `client.agent.get_artifact(artifact_uid)` → `Oz::Model`
+
+`GET /agent/artifacts/{uid}` — retrieve a `PLAN`, `SCREENSHOT`, or `FILE` artifact. The
+response shape depends on `artifact_type`.
+
+### `client.agent.list_environments(sort_by: nil)` → `Oz::Model`
+
+`GET /agent/environments` — list cloud environments. `sort_by`: `"last_updated"` (default)
+or `"name"`. Returns `{ environments: [...] }`.
+
+## Runs — `client.agent.runs`
+
+### `retrieve(run_id)` → `Oz::Model`
+
+`GET /agent/runs/{id}` — a single run (`RunItem`).
+
+### `list(**params)` → `Oz::CursorPage`
+
+`GET /agent/runs` — cursor-paginated runs. Filters: `ancestor_run_id`, `artifact_type`,
+`created_after`, `created_before`, `creator`, `cursor`, `environment_id`,
+`execution_location`, `executor`, `limit`, `model_id`, `name`, `q`, `schedule_id`, `skill`,
+`skill_spec`, `sort_by`, `sort_order`, `source`, `state` (Array), `updated_after`.
+
+Time-valued filters accept a `Time`/`Date` or an ISO-8601 String. `state` is encoded as
+repeated query keys.
+
+```ruby
+page = client.agent.runs.list(state: %w[INPROGRESS], created_after: Time.now - 86_400)
+page.auto_paging_each { |run| puts run.run_id }
+```
+
+### `cancel(run_id)` → `String`
+
+`POST /agent/runs/{id}/cancel` — cancel an in-progress run. Returns a confirmation string.
+
+### `list_handoff_attachments(run_id)` → `Oz::Model`
+
+`GET /agent/runs/{id}/handoff/attachments`.
+
+### `submit_followup(run_id, message: nil, mode: nil)` → `Oz::Model`
+
+`POST /agent/runs/{id}/followups` — send a follow-up message (`mode`: `"normal"` | `"plan"`
+| `"orchestrate"`).
+
+## Schedules — `client.agent.schedules`
+
+### `create(cron_schedule:, name:, **params)` → `Oz::Model`
+
+`POST /agent/schedules`. Optional: `agent_config`, `agent_uid`, `enabled`, `mode`, `prompt`,
+`team`.
+
+### `retrieve(schedule_id)` / `update(schedule_id, **params)` / `list` → `Oz::Model`
+
+`GET` / `PUT /agent/schedules/{id}`, and `GET /agent/schedules` (returns `{ schedules: [...] }`).
+
+### `delete(schedule_id)` → `Oz::Model`
+
+`DELETE /agent/schedules/{id}` — returns `{ success: Boolean }`.
+
+### `pause(schedule_id)` / `resume(schedule_id)` → `Oz::Model`
+
+`POST /agent/schedules/{id}/pause` and `.../resume`.
+
+## Agent identities — `client.agent.identities`
+
+### `create(name:, **params)` → `Oz::Model`
+
+`POST /agent/identities`. Optional: `description`, `prompt`, `base_model`, `base_harness`,
+`environment_id`, `mcp_servers`, `memory_stores`, `secrets`, `skills`, `inference_providers`,
+`harness_auth_secrets`.
+
+### `update(uid, **params)` / `list` / `retrieve(uid)` / `delete(uid)`
+
+`PUT /agent/identities/{uid}`, `GET /agent/identities` (`{ agents: [...] }`),
+`GET /agent/identities/{uid}` (aliased as `get`), and `DELETE /agent/identities/{uid}`
+(returns `nil`).
+
+## Sessions & Conversations
+
+### `client.agent.sessions.check_redirect(session_uuid)` → `Oz::Model`
+
+`GET /agent/sessions/{uuid}/redirect`.
+
+### `client.agent.conversations.check_redirect(conversation_id)` → `Oz::Model`
+
+`GET /agent/conversations/{id}/redirect`.
+
+## Responses
+
+`Oz::Model` wraps decoded JSON. Fields are reachable as methods and via `[]`; nested
+objects/arrays are wrapped recursively; booleans get a `?` predicate; unknown/absent fields
+return `nil`.
+
+```ruby
+run.state                 # method access
+run['run_id']             # bracket access (String or Symbol key)
+run.at_capacity?          # predicate
+run.agent_config.model_id # nested
+run.key?('schedule')      # presence check
+run.to_h                  # plain Hash (string keys, deep)
+```
+
+## Pagination
+
+`Oz::CursorPage` is `Enumerable` over the current page and provides:
+
+- `data` — Array of `Oz::Model` for the page.
+- `next_page?` / `next_page` — fetch the next page (reuses filters + new cursor).
+- `auto_paging_each` — iterate every item across all pages (returns an `Enumerator`
+  without a block).
+- `has_next_page`, `next_cursor`, `size`, `empty?`.

data/docs/configuration.md

@@ -0,0 +1,84 @@
+# Configuration
+
+## Client options
+
+`Oz::Client.new` accepts the following keyword arguments:
+
+| Option            | Default                            | Description                                          |
+| ----------------- | ---------------------------------- | ---------------------------------------------------- |
+| `api_key`         | `ENV['WARP_API_KEY']`              | Bearer token for authentication.                     |
+| `base_url`        | `https://app.warp.dev/api/v1`      | API base URL (or `ENV['OZ_API_BASE_URL']`).          |
+| `timeout`         | `60`                               | Per-request timeout in seconds.                      |
+| `max_retries`     | `2`                                | Retries for transient failures (`0` disables).       |
+| `default_headers` | `{}`                               | Extra headers sent on every request.                 |
+| `logger`          | `nil`                              | A `Logger`; enables Faraday request/response logging.|
+| `adapter`         | `Faraday.default_adapter`          | Faraday adapter override.                             |
+
+```ruby
+require 'logger'
+
+client = Oz::Client.new(
+  api_key: ENV.fetch('WARP_API_KEY'),
+  timeout: 120,
+  max_retries: 4,
+  default_headers: { 'X-Request-Source' => 'my-app' },
+  logger: Logger.new($stdout)
+)
+```
+
+## Global configuration
+
+Set defaults once at boot. Every `Oz::Client.new` (and the shared `Oz.client`) inherits them
+unless overridden per call.
+
+```ruby
+Oz.configure do |config|
+  config.api_key      = ENV.fetch('WARP_API_KEY')
+  config.base_url     = 'https://app.warp.dev/api/v1'
+  config.timeout      = 60
+  config.max_retries  = 3
+  config.default_headers = { 'X-Request-Source' => 'my-app' }
+end
+
+# Lazily-built shared client using the global configuration:
+Oz.client.agent.list
+```
+
+## Environment variables
+
+| Variable                | Description                                                        |
+| ----------------------- | ----------------------------------------------------------------- |
+| `WARP_API_KEY`          | Bearer token used to authenticate requests.                       |
+| `OZ_API_BASE_URL`       | Override the API base URL.                                        |
+| `OZ_API_CUSTOM_HEADERS` | Extra headers, one `Key: Value` per line, added to every request. |
+
+Precedence for each setting is: **explicit argument → environment variable → global
+configuration → built-in default**.
+
+`OZ_API_CUSTOM_HEADERS` is parsed as newline-separated `Key: Value` pairs:
+
+```sh
+export OZ_API_CUSTOM_HEADERS="X-Team: platform
+X-Trace: enabled"
+```
+
+## Retries and backoff
+
+Transient failures are retried automatically:
+
+- Connection errors and timeouts.
+- HTTP `408`, `409`, `429`, and any `5xx` response.
+
+Backoff is exponential with jitter, starting at 0.5s and capped at 8s. A numeric
+`Retry-After` response header is honoured when present. Disable retries with
+`max_retries: 0`.
+
+## Timeouts
+
+`timeout` sets the overall request timeout (seconds). The connection-open timeout is derived
+as `min(timeout, 10)`.
+
+## Thread safety
+
+A client is safe to share for sequential use. For heavily concurrent workloads, prefer one
+client per thread.

data/docs/error_handling.md

@@ -0,0 +1,87 @@
+# Error Handling
+
+Every failure raised by the SDK descends from `Oz::Error`. API failures specifically raise
+`Oz::APIError` subclasses that carry useful metadata.
+
+## Hierarchy
+
+```
+StandardError
+└── Oz::Error
+    ├── Oz::ConfigurationError
+    └── Oz::APIError
+        ├── Oz::APIConnectionError
+        │   └── Oz::APITimeoutError
+        └── Oz::APIStatusError
+            ├── Oz::BadRequestError           (400)
+            ├── Oz::AuthenticationError       (401)
+            ├── Oz::PermissionDeniedError     (403)
+            ├── Oz::NotFoundError             (404)
+            ├── Oz::ConflictError             (409)
+            ├── Oz::UnprocessableEntityError  (422)
+            ├── Oz::RateLimitError            (429)
+            └── Oz::InternalServerError       (5xx)
+```
+
+## Error metadata
+
+`Oz::APIError` exposes:
+
+| Method        | Description                                                      |
+| ------------- | -------------------------------------------------------------- |
+| `message`     | Human-readable message (includes server `detail`/`title`).     |
+| `status_code` | HTTP status code (`nil` for connection/timeout errors).        |
+| `code`        | Machine-readable error code (e.g. `"resource_not_found"`).      |
+| `body`        | The parsed response body (Hash/String), when available.        |
+| `request_id`  | The `X-Request-Id` header, for correlating with server logs.   |
+| `response`    | The raw Faraday response, when available.                      |
+
+## Handling errors
+
+Rescue from the most specific to the most general:
+
+```ruby
+begin
+  client.agent.run(prompt: 'do the thing')
+rescue Oz::RateLimitError => e
+  warn "Rate limited; retry later. request_id=#{e.request_id}"
+rescue Oz::AuthenticationError
+  warn 'Authentication failed — check WARP_API_KEY.'
+rescue Oz::NotFoundError
+  warn 'Resource not found.'
+rescue Oz::APIStatusError => e
+  warn "API error #{e.status_code} (#{e.code}): #{e.message}"
+rescue Oz::APITimeoutError
+  warn 'Request timed out.'
+rescue Oz::APIConnectionError => e
+  warn "Connection problem: #{e.message}"
+rescue Oz::APIError => e
+  warn "Unexpected API error: #{e.message}"
+end
+```
+
+## Machine-readable error codes
+
+The platform returns a stable `code` for many failures. Common values include
+`insufficient_credits`, `feature_not_available`, `external_authentication_required`,
+`not_authorized`, `invalid_request`, `resource_not_found`, `budget_exceeded`,
+`integration_disabled`, `integration_not_configured`, `operation_not_supported`,
+`environment_setup_failed`, `content_policy_violation`, `conflict`,
+`authentication_required`, `resource_unavailable`, and `internal_error`.
+
+```ruby
+rescue Oz::APIStatusError => e
+  case e.code
+  when 'insufficient_credits' then notify_billing
+  when 'content_policy_violation' then log_and_skip(e)
+  else raise
+  end
+end
+```
+
+## Automatic retries
+
+The client retries transient failures before raising — connection errors, timeouts, and
+HTTP `408`, `409`, `429`, and `5xx` responses — with exponential backoff and jitter (honouring
+a numeric `Retry-After` header). The error is only raised after retries are exhausted.
+Configure with `max_retries:` (default `2`; `0` disables).

data/docs/getting_started.md

@@ -0,0 +1,92 @@
+# Getting Started
+
+## Requirements
+
+- Ruby >= 3.1 (the project defaults to **Ruby 4.0**, managed with
+  [mise](https://mise.jdx.dev) via [`mise.toml`](../mise.toml))
+- A Warp API key (set as the `WARP_API_KEY` environment variable)
+
+## Installation
+
+With Bundler, add to your `Gemfile`:
+
+```ruby
+gem 'oz-agent-sdk'
+```
+
+and run `bundle install`. Without Bundler:
+
+```sh
+gem install oz-agent-sdk
+```
+
+## Authentication
+
+The client authenticates with a Bearer token. By default it reads `WARP_API_KEY` from the
+environment:
+
+```sh
+export WARP_API_KEY="sk-..."
+```
+
+```ruby
+require 'oz'
+
+client = Oz::Client.new            # picks up WARP_API_KEY
+# or pass it explicitly:
+client = Oz::Client.new(api_key: 'sk-...')
+```
+
+If no key is available, the constructor raises `Oz::AuthenticationError`.
+
+## Your first agent run
+
+```ruby
+require 'oz'
+
+client = Oz::Client.new
+
+run = client.agent.run(prompt: 'Add tests for the user model')
+puts "Started run #{run.run_id} (#{run.state})"
+```
+
+`run` is an `Oz::Model`; access fields as methods or with `[]`:
+
+```ruby
+run.run_id        # => "a1b2c3..."
+run.state         # => "QUEUED"
+run['task_id']    # => "a1b2c3..." (deprecated alias of run_id)
+run.at_capacity?  # => false
+```
+
+## Polling for completion
+
+The run starts asynchronously. Poll `runs.retrieve` until it reaches a terminal state:
+
+```ruby
+TERMINAL = %w[SUCCEEDED FAILED ERROR CANCELLED].freeze
+
+run = client.agent.run(prompt: 'Add tests for the user model')
+
+loop do
+  current = client.agent.runs.retrieve(run.run_id)
+  puts current.state
+  break if TERMINAL.include?(current.state)
+
+  sleep 5
+end
+```
+
+## Continuing a conversation
+
+Pass `conversation_id` to continue from a previous run, or use a follow-up message:
+
+```ruby
+client.agent.runs.submit_followup(run.run_id, message: 'Also update the changelog')
+```
+
+## Next steps
+
+- [Configuration](configuration.md) — timeouts, retries, custom headers, logging.
+- [API Reference](api_reference.md) — the full surface area.
+- [Error Handling](error_handling.md) — robust failure handling.

data/docs/index.md

@@ -0,0 +1,56 @@
+# Oz Ruby SDK Documentation
+
+The Oz Ruby SDK is an idiomatic, resource-oriented client for the
+[Oz API](https://docs.warp.dev) — Warp's cloud agent platform.
+
+## Contents
+
+- [Getting Started](getting_started.md) — installation, authentication, your first run.
+- [Configuration](configuration.md) — client options, environment variables, retries, logging.
+- [API Reference](api_reference.md) — every resource and method.
+- [Error Handling](error_handling.md) — the exception hierarchy and retry behaviour.
+
+## At a glance
+
+```ruby
+require 'oz'
+
+client = Oz::Client.new(api_key: ENV['WARP_API_KEY'])
+
+run = client.agent.run(prompt: 'Fix the bug in auth.rb')
+puts run.run_id
+
+client.agent.runs.list(limit: 20).auto_paging_each do |r|
+  puts "#{r.run_id} #{r.state} #{r.title}"
+end
+```
+
+## Resource map
+
+| Ruby                                          | HTTP                                              |
+| --------------------------------------------- | ------------------------------------------------ |
+| `client.agent.run`                            | `POST /agent/runs`                               |
+| `client.agent.list`                           | `GET /agent`                                      |
+| `client.agent.get_artifact`                   | `GET /agent/artifacts/{uid}`                      |
+| `client.agent.list_environments`              | `GET /agent/environments`                         |
+| `client.agent.runs.retrieve`                  | `GET /agent/runs/{id}`                            |
+| `client.agent.runs.list`                      | `GET /agent/runs`                                 |
+| `client.agent.runs.cancel`                    | `POST /agent/runs/{id}/cancel`                    |
+| `client.agent.runs.list_handoff_attachments`  | `GET /agent/runs/{id}/handoff/attachments`        |
+| `client.agent.runs.submit_followup`           | `POST /agent/runs/{id}/followups`                 |
+| `client.agent.schedules.create`               | `POST /agent/schedules`                           |
+| `client.agent.schedules.retrieve`             | `GET /agent/schedules/{id}`                       |
+| `client.agent.schedules.update`               | `PUT /agent/schedules/{id}`                       |
+| `client.agent.schedules.list`                 | `GET /agent/schedules`                            |
+| `client.agent.schedules.delete`               | `DELETE /agent/schedules/{id}`                    |
+| `client.agent.schedules.pause`                | `POST /agent/schedules/{id}/pause`               |
+| `client.agent.schedules.resume`               | `POST /agent/schedules/{id}/resume`              |
+| `client.agent.identities.create`              | `POST /agent/identities`                          |
+| `client.agent.identities.update`              | `PUT /agent/identities/{uid}`                     |
+| `client.agent.identities.list`                | `GET /agent/identities`                           |
+| `client.agent.identities.retrieve`            | `GET /agent/identities/{uid}`                     |
+| `client.agent.identities.delete`              | `DELETE /agent/identities/{uid}`                  |
+| `client.agent.sessions.check_redirect`        | `GET /agent/sessions/{uuid}/redirect`             |
+| `client.agent.conversations.check_redirect`   | `GET /agent/conversations/{id}/redirect`          |
+
+See the [examples](../examples/) directory for runnable scripts.

data/examples/identities.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Manage agent identities (team-owned execution principals).
+#
+#   WARP_API_KEY=sk-... ruby examples/identities.rb
+
+require 'oz'
+
+client = Oz::Client.new
+
+identity = client.agent.identities.create(
+  name: 'ci-bot',
+  description: 'Runs nightly maintenance tasks',
+  skills: ['warpdotdev/warp-server:.claude/skills/deploy/SKILL.md']
+)
+puts "Created identity #{identity.uid}"
+
+puts 'All identities:'
+client.agent.identities.list.agents.each do |agent|
+  puts "  #{agent.uid} #{agent.name}"
+end
+
+client.agent.identities.update(identity.uid, description: 'Updated description')
+puts 'Updated.'
+
+# Use the identity as the execution principal for a team-owned run:
+run = client.agent.run(
+  prompt: 'Run the nightly checks',
+  team: true,
+  agent_identity_uid: identity.uid
+)
+puts "Started run #{run.run_id} as identity #{identity.uid}"
+
+client.agent.identities.delete(identity.uid)
+puts 'Deleted identity.'

data/examples/list_runs.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# List recent runs, paging through all results.
+#
+#   WARP_API_KEY=sk-... ruby examples/list_runs.rb
+
+require 'oz'
+
+client = Oz::Client.new
+
+# A single page:
+page = client.agent.runs.list(limit: 25, sort_by: 'created_at', sort_order: 'desc')
+puts "First page: #{page.size} run(s), more available: #{page.next_page?}"
+page.each do |run|
+  puts format('  %-38s %-11s %s', run.run_id, run.state, run.title)
+end
+
+puts
+puts 'All runs created in the last 24h that are in progress:'
+
+filtered = client.agent.runs.list(
+  state: %w[INPROGRESS QUEUED],
+  created_after: Time.now - (24 * 60 * 60)
+)
+
+count = 0
+filtered.auto_paging_each do |run|
+  count += 1
+  puts "  #{run.run_id} #{run.state}"
+end
+puts "Total: #{count}"

data/examples/run_agent.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Run a cloud agent and poll until it finishes.
+#
+#   WARP_API_KEY=sk-... ruby examples/run_agent.rb "Fix the bug in auth.rb"
+#
+# Requires the gem to be installed, or run with `bundle exec` from the repo root.
+
+require 'oz'
+
+prompt = ARGV.first || 'Summarize the README and suggest improvements'
+
+client = Oz::Client.new # reads WARP_API_KEY from the environment
+
+run = client.agent.run(
+  prompt: prompt,
+  config: {
+    # environment_id: "your-environment-id",
+    model_id: 'claude-sonnet-4',
+    name: 'sdk-example'
+  }
+)
+
+puts "Started run #{run.run_id} (state: #{run.state})"
+
+TERMINAL = %w[SUCCEEDED FAILED ERROR CANCELLED].freeze
+
+loop do
+  current = client.agent.runs.retrieve(run.run_id)
+  puts "  #{Time.now.strftime('%H:%M:%S')} #{current.state}"
+  break if TERMINAL.include?(current.state)
+
+  sleep 5
+end
+
+final = client.agent.runs.retrieve(run.run_id)
+puts "Finished: #{final.state}"
+puts "Session: #{final.session_link}" if final.session_link

data/examples/schedules.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Create, inspect, pause/resume, and delete a scheduled agent.
+#
+#   WARP_API_KEY=sk-... ruby examples/schedules.rb
+
+require 'oz'
+
+client = Oz::Client.new
+
+schedule = client.agent.schedules.create(
+  cron_schedule: '0 9 * * *', # daily at 09:00 UTC
+  name: 'nightly-dependency-check',
+  prompt: 'Check for outdated dependencies and open a PR if needed',
+  enabled: true
+)
+puts "Created schedule #{schedule.schedule_id} (#{schedule.name})"
+
+puts 'All schedules:'
+client.agent.schedules.list.schedules.each do |s|
+  puts "  #{s.schedule_id} #{s.name} #{s.cron_schedule}"
+end
+
+client.agent.schedules.pause(schedule.schedule_id)
+puts 'Paused.'
+
+client.agent.schedules.resume(schedule.schedule_id)
+puts 'Resumed.'
+
+result = client.agent.schedules.delete(schedule.schedule_id)
+puts "Deleted: #{result.success}"