sandbox-agent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61c56399f2e6900b8ecc89ccda3074f37d604ecfd424aef6e0f7b9743b48dfb4
+  data.tar.gz: 1a9881246c543c4dcb783eda829d450aaad5cb65f6987debd56568089e7ef744
+SHA512:
+  metadata.gz: 8df59d351e95189187ddc1756502b69af83669f2d31f0c617f782bfb03f1717063bdfbe26b68f4b6721740ef772aedf84347d2c7ec7170eca0e7ee0e3a60fa38
+  data.tar.gz: 414451d5cd11fc1cce04db53a23c6ea2c2e6159e549aa938b4ba0b92f6c5d60b3475ffbabb6bf008d198e85f94c580608560c31dc7922c1910f7fbc14f79cec4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nvoi
+
+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,14 @@
+# sandbox-agent
+
+Registry of coding agent CLIs. Each agent answers the same contract, so callers never branch on the vendor.
+
+- `argv(prompt:, id:, resume:, model:, instructions:)`: the command line for one turn.
+- `env` / `box_env`: the variables the CLI reads.
+- `events(line)`: one printed line to `Sandbox::Agent::Event` values (`status`, `message`, `thinking`, `tool_use`, `tool_result`, `task`, `result`, `error`, `notice`).
+
+```ruby
+agent = Sandbox::Agent.provider("claude_code")
+agent.argv(prompt: "Fix the failing test", id: session_id, resume: false, model: "sonnet")
+```
+
+Agents: Claude Code (`Sandbox::Agent::ClaudeCode`).

data/lib/sandbox/agent/claude_code/mcp_server.rb

@@ -0,0 +1,33 @@
+# Stdio MCP server installed on the box. Lists the tools Rails defines and answers every call with
+# "recorded": the call is parked as an event and Rails performs it after the run.
+module Sandbox::Agent::ClaudeCode::McpServer
+  NAME = "nvoi"
+  PARKED = "Queued. This action is performed for you once your turn ends and you will be told " \
+    "the outcome. This is the normal path; end your turn now with a one-line summary of what " \
+    "you asked for.".freeze
+
+  SCRIPT = <<~PY
+    #!/usr/bin/env python3
+    import json, os, sys
+
+    tools = json.loads(os.environ.get("NVOI_TOOLS", "[]"))
+
+    def reply(msg, result):
+      sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": msg["id"], "result": result}) + "\\n")
+      sys.stdout.flush()
+
+    for line in sys.stdin:
+      msg = json.loads(line)
+      method = msg.get("method")
+      if method == "initialize":
+        reply(msg, {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": {"name": "#{NAME}", "version": "1"}})
+      elif method == "tools/list":
+        reply(msg, {"tools": tools})
+      elif method == "tools/call":
+        reply(msg, {"content": [{"type": "text", "text": #{PARKED.to_json}}]})
+      elif "id" in msg:
+        reply(msg, {})
+  PY
+
+  def self.config = { mcpServers: { NAME => { command: "nvoi-mcp" } } }.to_json
+end

data/lib/sandbox/agent/claude_code/stream.rb

@@ -0,0 +1,103 @@
+# Maps one stream-json object (symbol-keyed) to zero or more Sandbox::Agent::Event.
+module Sandbox::Agent::ClaudeCode::Stream
+  # System lines that repeat what another line says, or say nothing shown.
+  QUIET = %w[thinking_tokens task_updated background_tasks_changed hook_started
+             hook_response].freeze
+  TASK = %w[task_started task_progress task_notification].freeze
+
+  def self.decode(data)
+    parent = data[:parent_tool_use_id]
+    case data[:type]
+    when "system" then system(data)
+    when "assistant" then nested(blocks(data).filter_map { assistant(_1) }, parent)
+    when "user" then nested(blocks(data).filter_map { user(_1) }, parent)
+    when "result"
+      if data[:is_error]
+        [ error(reason(data)) ]
+      else
+        [ Sandbox::Agent::Event.new(kind: "result", content: data[:result]) ]
+      end
+    when "error" then [ error(data[:message].to_s) ]
+    else []
+    end
+  end
+
+  def self.nested(events, parent) = events.map { _1.with(parent_tool_use_id: parent) }
+
+  def self.system(data)
+    subtype = data[:subtype].to_s
+    return [] if QUIET.include?(subtype)
+    return [ Sandbox::Agent::Event.new(kind: "status", content: subtype) ] unless TASK.include?(subtype)
+    return [] unless data[:tool_use_id]
+
+    content = JSON.dump(task(data))
+    [ Sandbox::Agent::Event.new(kind: "task", tool_use_id: data[:tool_use_id], content:) ]
+  end
+
+  # A sub-agent's state as of this line: what it was asked, what it is doing, how it ended. A progress
+  # line's description is the current activity, not the task's.
+  def self.task(data)
+    usage = data[:usage] || {}
+    progress = data[:subtype] == "task_progress"
+    {
+      state: data[:subtype].delete_prefix("task_"),
+      status: data[:status],
+      type: data[:subagent_type],
+      description: (data[:description] unless progress),
+      activity: (data[:description] if progress),
+      summary: data[:summary],
+      tokens: usage[:total_tokens],
+      tools: usage[:tool_uses],
+      duration_ms: usage[:duration_ms],
+      last_tool: data[:last_tool_name]
+    }.compact
+  end
+
+  LOST = /No conversation found with session ID/
+
+  # A transcript the box no longer has is not a failure of the turn: the caller starts a new one.
+  def self.error(message)
+    Sandbox::Agent::Event.new(kind: "error", content: message, lost: message.match?(LOST))
+  end
+
+  def self.blocks(data) = Array(data.dig(:message, :content))
+
+  def self.assistant(block)
+    case block[:type]
+    when "text" then Sandbox::Agent::Event.new(kind: "message", content: block[:text])
+    when "thinking" then Sandbox::Agent::Event.new(kind: "thinking", content: block[:thinking])
+    when "tool_use"
+      Sandbox::Agent::Event.new(
+        kind: "tool_use",
+        tool: block[:name],
+        content: JSON.dump(block[:input] || {}),
+        tool_use_id: block[:id]
+      )
+    end
+  end
+
+  def self.user(block)
+    return unless block[:type] == "tool_result"
+
+    Sandbox::Agent::Event.new(
+      kind: "tool_result",
+      tool_use_id: block[:tool_use_id],
+      content: text(block[:content])
+    )
+  end
+
+  def self.text(content)
+    return content.to_s unless content.is_a?(Array)
+
+    content.filter_map { |part| part[:text] if part[:type] == "text" }.join("\n")
+  end
+
+  def self.reason(data)
+    errors = Array(data[:errors]).join("; ")
+    return errors unless errors.empty?
+    return data[:result] if data[:result].is_a?(String) && !data[:result].empty?
+    return "the model API answered #{data[:api_error_status]}" if data[:api_error_status]
+
+    "the turn failed without a reason"
+  end
+end

data/lib/sandbox/agent/claude_code.rb

@@ -0,0 +1,96 @@
+# Anthropic's `claude` CLI. Everything this app knows about this vendor is here: what a credential for
+# it is, which variable each kind goes in, which models it offers, the command line that runs a turn and
+# how its output is read.
+#
+# Its whole configuration is a credential and WHICH VARIABLE it goes in: the CLI reads its own name and
+# only its own, so an API key exported as CLAUDE_CODE_OAUTH_TOKEN is "Not logged in" and the turn ends
+# having written nothing. So the kind is asked, never inferred from the token's shape: a gateway's key
+# carries no `sk-ant-` prefix.
+class Sandbox::Agent::ClaudeCode < Sandbox::Agent::Provider
+  # The kinds and the variable each one names. This map IS the enum: a kind in the form and missing here
+  # would validate, then raise as a box started.
+  CREDENTIAL_ENV = {
+    "oauth" => "CLAUDE_CODE_OAUTH_TOKEN",
+    "api_key" => "ANTHROPIC_API_KEY",
+    "bearer" => "ANTHROPIC_AUTH_TOKEN"
+  }.freeze
+  # Where a third-party endpoint is named; not a credential, but ours to set for the same reason.
+  BASE_URL_ENV = "ANTHROPIC_BASE_URL".freeze
+
+  FIELDS = [
+    { key: "kind", type: :select, label: "Credential kind", required: true,
+      help: "oauth for a Claude subscription, api_key for an Anthropic key, " \
+            "bearer for a third-party endpoint such as z.ai or Kimi",
+      options: [
+        { value: "oauth", label: "Claude subscription (OAuth)" },
+        { value: "api_key", label: "Anthropic API key" },
+        { value: "bearer", label: "Third-party endpoint (bearer)" }
+      ] },
+    { key: "token", type: :password, label: "Token", required: true, secret: true,
+      placeholder: "sk-ant-..." },
+    { key: "base_url", type: :text, label: "Base URL", placeholder: "https://api.anthropic.com",
+      help: "Only for a third-party endpoint. Leave empty for Anthropic." }
+  ].freeze
+
+  # Aliases rather than pinned ids: an alias follows the vendor's current model.
+  MODELS = [
+    { id: "opus", label: "Opus" },
+    { id: "sonnet", label: "Sonnet" },
+    { id: "haiku", label: "Haiku" }
+  ].freeze
+
+  def self.key = "claude_code"
+  def self.label = "Claude Code"
+  def self.fields = FIELDS
+  def self.models = MODELS
+  # The middle one: opus costs several times more per turn and haiku cannot hold a long tool-using
+  # conversation. A default is what most people never change.
+  def self.default_model = "sonnet"
+
+  # `fetch` throughout. A kind outside the set, or a config saved with no token, is our broken
+  # invariant; a default here hands the CLI an empty credential, which it reports as a refusal.
+  def self.env(settings, secrets)
+    settings = settings.to_h.transform_keys(&:to_s)
+    secrets = secrets.to_h.transform_keys(&:to_s)
+    env = { CREDENTIAL_ENV.fetch(settings.fetch("kind")) => secrets.fetch("token") }
+    url = settings["base_url"].to_s
+    env[BASE_URL_ENV] = url unless url.empty?
+    env
+  end
+
+  def self.env_keys = CREDENTIAL_ENV.values + [ BASE_URL_ENV ]
+
+  # Where the CLI keeps transcripts and settings: on the worktree's volume, so a paused box keeps its
+  # memory. Tool search off: the CLI would otherwise defer nvoi's MCP tools behind it, and an agent that
+  # never loads ask_user asks its questions in prose.
+  def self.box_env(layout) = { CLAUDE_CONFIG_DIR: layout.claude, ENABLE_TOOL_SEARCH: "false" }
+
+  # The CLI's own question tool has nobody to answer it in print mode; nvoi's ask_user takes its place.
+  DISALLOWED = %w[AskUserQuestion].freeze
+
+  def self.argv(prompt:, id:, resume:, model: nil, instructions: nil)
+    argv = [
+      "claude", "-p", prompt,
+      "--verbose",
+      "--output-format", "stream-json",
+      "--setting-sources", "user",
+      "--settings", JSON.dump(hooks: {}, permissions: { defaultMode: "bypassPermissions" }),
+      "--mcp-config", Sandbox::Agent::ClaudeCode::McpServer.config,
+      "--disallowedTools", DISALLOWED.join(",")
+    ]
+    argv += [ "--model", model ] if model
+    argv += [ "--append-system-prompt", instructions ] unless instructions.to_s.empty?
+    argv + [ resume ? "--resume" : "--session-id", id ]
+  end
+
+  def self.events(line)
+    data = JSON.parse(line, symbolize_names: true)
+    return [] unless data.is_a?(Hash)
+
+    Sandbox::Agent::ClaudeCode::Stream.decode(data).map { |event| event.with(session_id: data[:session_id]) }
+  rescue JSON::ParserError => e
+    # A line the CLI printed that is not an event: dropped, and said so.
+    Sandbox::Agent.reporter.report(e, handled: true, context: { line: line.to_s[0, 200] })
+    []
+  end
+end

data/lib/sandbox/agent/provider.rb

@@ -0,0 +1,58 @@
+# What one vendor is. Vendors share this contract and nothing else: each states its own credential,
+# its own variables, its own models and its own command line, and a caller reads the same shape from
+# every one of them.
+#
+# All of it is class methods. A vendor holds no state: it describes itself and builds a command.
+class Sandbox::Agent::Provider
+  # ── WHAT A CREDENTIAL FOR THIS VENDOR IS ────────────────────────────────────
+
+  # The stored key. `llm_configs.provider` holds it.
+  def self.key = raise NotImplementedError
+  # What a person calls this vendor.
+  def self.label = raise NotImplementedError
+
+  # The form, in the order it is asked. A field is
+  # { key:, type: text|password|select, label:, secret:, required:, placeholder:, help:, options: }.
+  # `secret: true` decides which half of the submitted values is encrypted, so there is no second list
+  # of sensitive keys anywhere. `options` ([{ value:, label: }]) is for a select only.
+  def self.fields = raise NotImplementedError
+
+  def self.secret_keys = fields.select { _1[:secret] }.map { _1[:key] }
+
+  # A submitted hash split into what is stored plainly and what is sealed, read off `fields` so there is
+  # no second list to disagree with the form.
+  def self.split(submitted)
+    submitted = submitted.to_h.transform_keys(&:to_s)
+    [ submitted.except(*secret_keys), submitted.slice(*secret_keys) ]
+  end
+
+  # ── WHAT IT OFFERS ──────────────────────────────────────────────────────────
+
+  # Every model this vendor can run, as { id:, label: }. Empty means we have not integrated its
+  # catalogue, and is an answer rather than permission to guess.
+  def self.models = []
+  # The model a new credential starts on, so the form does not open on a blank select. An alias where
+  # the vendor has them: an alias follows the vendor's current model, a pinned id freezes it.
+  def self.default_model = nil
+
+  # ── WHAT IT READS ───────────────────────────────────────────────────────────
+
+  # The process environment a turn runs under. Both halves of the credential are passed because the
+  # vendor declared the split and is the only thing that knows it.
+  def self.env(settings, secrets) = raise NotImplementedError
+
+  # Every variable this vendor reads, credential or otherwise. Nothing else may name one.
+  def self.env_keys = raise NotImplementedError
+
+  # What the runner needs of the box it runs on, such as where it keeps its transcripts.
+  def self.box_env(_layout) = {}
+
+  # ── HOW A TURN RUNS ─────────────────────────────────────────────────────────
+
+  # The command line for one turn. `id` is the transcript to create or, with resume, to continue.
+  def self.argv(prompt:, id:, resume:, model: nil, instructions: nil) = raise NotImplementedError
+
+  # The events in one line of what the runner printed, as Sandbox::Agent::Event. A line that carries none is an
+  # empty list, never an error: a runner prints what it likes.
+  def self.events(line) = raise NotImplementedError
+end

data/lib/sandbox/agent/version.rb

@@ -0,0 +1,5 @@
+module Sandbox
+  module Agent
+    VERSION = "0.1.0"
+  end
+end

data/lib/sandbox/agent.rb

@@ -0,0 +1,52 @@
+# The agent runners this library knows, and everything each one knows about itself: what a credential
+# for it looks like, which variables it reads, which models it offers, the command line that runs a turn
+# and how to read what that prints.
+#
+# A caller asks the registry and gets the same shape back whichever vendor answers. It never learns that
+# one wants an API key and another an OAuth token, that one prints stream-json and another something
+# else, or which variable either reads: that is the vendor's own business and it is stated once, in the
+# vendor's own class.
+module Sandbox::Agent
+  # One thing a runner said while a turn ran. kind is status, message, thinking, tool_use, tool_result,
+  # task, result, error or notice; lost marks a transcript the box no longer has. parent_tool_use_id is the
+  # sub-agent call that emitted it. A task event is a sub-agent's state, keyed by its call's tool_use_id.
+  Event = Data.define(:kind, :content, :tool, :tool_use_id, :parent_tool_use_id, :session_id,
+                      :lost) do
+    def initialize(kind:, content: nil, tool: nil, tool_use_id: nil, parent_tool_use_id: nil,
+                   session_id: nil, lost: false)
+      super
+    end
+  end
+
+  # A vendor is code, not a row, so this is a class list. Adding one is adding a file here.
+  def self.providers = [ Sandbox::Agent::ClaudeCode ]
+  def self.keys = providers.map(&:key)
+
+  # The vendor a stored key names. Raises: a row naming one we do not have is a broken invariant.
+  def self.provider(key)
+    providers.find { _1.key == key.to_s } or
+      raise ArgumentError, "no llm provider #{key.inspect}; have #{keys.inspect}"
+  end
+
+  # The one a caller gets when nothing chose.
+  def self.default = providers.first
+
+  # Every variable any vendor reads. A turn's credential arrives under one of these, so nothing else may
+  # name them: a variable that did would decide which credential the runner reads.
+  def self.env_keys = providers.flat_map(&:env_keys).uniq
+
+  # Every model any vendor offers. Not one vendor's set: what an agent may be pinned to is asked before
+  # a credential is chosen, so the vendor is not known yet.
+  def self.models = providers.flat_map(&:models)
+  def self.model_ids = models.map { _1[:id] }
+
+  # Where a line this library could not read is reported. Rails answers it; outside an app it goes
+  # nowhere rather than crashing on a missing constant.
+  NOWHERE = Object.new.tap { |o| o.define_singleton_method(:report) { |*, **| nil } }.freeze
+
+  def self.reporter = @reporter ||= (defined?(Rails) ? Rails.error : NOWHERE)
+
+  class << self
+    attr_writer :reporter
+  end
+end

data/lib/sandbox-agent.rb

@@ -0,0 +1,13 @@
+# The agent runners a box can run: what a credential for each is, which variables it reads, which models
+# it offers, the command line for one turn and how to read what it prints. It knows nothing about a box,
+# a record or a framework: a caller asks the registry and gets the same shape from every vendor.
+require "json"
+
+module Sandbox; end
+require_relative "sandbox/agent/version"
+
+require_relative "sandbox/agent"
+require_relative "sandbox/agent/provider"
+require_relative "sandbox/agent/claude_code"
+require_relative "sandbox/agent/claude_code/mcp_server"
+require_relative "sandbox/agent/claude_code/stream"

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: sandbox-agent
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- nvoi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- admin@nvoi.to
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sandbox-agent.rb
+- lib/sandbox/agent.rb
+- lib/sandbox/agent/claude_code.rb
+- lib/sandbox/agent/claude_code/mcp_server.rb
+- lib/sandbox/agent/claude_code/stream.rb
+- lib/sandbox/agent/provider.rb
+- lib/sandbox/agent/version.rb
+homepage: https://rubygems.org/gems/sandbox-agent
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: 'Coding agent CLI registry: the command line for one turn and the events
+  it prints.'
+test_files: []