kosa8 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbd21499fe850f6b1c9055f9451c06500e9b779e60d880426afa850fc8a69ce5
-  data.tar.gz: 786b60910b4a591d9fec38b5b0b5d2623fd805934ff8508337ceec1f7e3159b4
+  metadata.gz: 17b6bb99a0c01a23ce95dcb36f7c15c3aa5450a62ff8115277199fec1d2579ba
+  data.tar.gz: ba4f1921f132bfec9de4acbdac756724d542368d9b7a44e4e981197e92ae39a9
 SHA512:
-  metadata.gz: f5e5ea9ecbde4e0fdd2085b89d00ac7145485a4f6f2866bbde4986672a9e24215e3af27b9fa89aed98adc010698359d84ad435343d737f120c7faa37c7657af8
-  data.tar.gz: 946d830b7d1ecfba2962857cded5f61c8bcb9d621fc8d0af7f3985f755272811934175bdff469aabe1a442c740a457a8ea6cecc32eba2b5c0d993344a818c799
+  metadata.gz: b04a51d55a99495a01c8bd9b627f046b1205b50cfee240d95acf91f60f36186dfb173579f6d43a370c2f998717a14fc7dcfcc99efeac567c6dbb819eeaf05d84
+  data.tar.gz: cbe1b43b35bb3c337df1e860a6f719274ee8329bf52cbe8f327066d40293f83f627e1a232bec3a67ec3e96be0d3b22e379343540f85e93a43e8185a3251e2311

data/README.md

@@ -27,12 +27,26 @@ sb.delete
 | `token:` / `KOSA8_TOKEN` | sent as `Authorization: Bearer` to a remote worker |
 | `actor:` | `"tool"` (`human`, `agent`, `tool`), sent as `X-Kosa8-Actor` |
 | `agent_token:` / `KOSA8_AGENT_TOKEN` | sent as `X-Kosa8-Agent-Token` |
+| `worker_file:` | `~/.kosa8/worker.json`; `false` or `""` reads none |
+
+Where requests go, the same as the CLI:
+
+1. `host:`, or a non-blank `KOSA8_HOST`. The token is `token:`, else `KOSA8_TOKEN` (only for a
+   host from `KOSA8_HOST`). The saved file is not read.
+2. Else, unless `socket_path:` is given, the connection the CLI saved in `~/.kosa8/worker.json`
+   (`kosa8 wsl setup` on Windows, `kosa8 worker join` anywhere): its `host`, its `token` unless
+   `token:` is given, and plain http to a LAN address only with `"insecure": true`, `insecure: true`
+   or `KOSA8_INSECURE=1`. A missing or malformed file, or a blank `host`, is ignored.
+3. Else the unix socket.
+
+On Windows the engine runs in WSL2: run `kosa8 wsl setup` once and `Kosa8::Client.new` finds it.
+`client.transport.endpoint.target` shows where requests go.
 
 ## Errors
 
 All errors inherit `Kosa8::Error` and carry the daemon's message and remediation:
 `ConnectionError`, `BadRequestError`, `AuthError`, `PolicyError` › `ApprovalRequiredError` (`#approval`),
-`NotFoundError`, `ConflictError`, `UnsupportedError`, `StreamError` (`#stdout`/`#stderr` so far),
+`NotFoundError`, `ConflictError`, `UnsupportedError`, `PaymentRequiredError` (402), `RateLimitError` (429), `StreamError` (`#stdout`/`#stderr` so far),
 `CheckpointError`, `TimeoutError`. Methods that a policy may gate take `approval:`.
 
 ## API
@@ -47,10 +61,81 @@ Snapshots: `snapshot`, `list_snapshots`, `restore_snapshot`, `delete_snapshot`,
 Checkpoints: `checkpoint`, `list_checkpoints`, `rewind` (store: `~/.kosa8/checkpoints.json`, flock-shared with the CLI).
 `client.sandbox(id)` binds them to one sandbox.
 
+## Toolbox
+
+Run code, files, git, shell sessions, terminals, previews, lifecycle and templates, each one daemon
+route (see the [native API](https://docs.kosa8.com/guides/native-api/)). All of them except the
+template calls are also on `client.sandbox(id)`.
+
+```ruby
+k.create_sandbox(name: "work", egress_allow: ["github.com"], auto_stop_min: 30, ttl_min: 120)
+sb = k.sandbox("work")
+
+r = sb.run_code("print(6*7)")                  # Kosa8::CodeResult; also language: "javascript" / "typescript"
+r.stdout                                       # "42\n"; r.ok?, r.exit_code, r.timed_out
+r.artifacts.each { |a| File.binwrite(a.name, a.data) }  # matplotlib charts as PNG bytes
+
+sb.write_file("/workspace/app.py", "print(1)") # make_dir, move_file, delete_file(recursive: true)
+sb.read_text("/workspace/app.py")              # read_file gives binary bytes; list_files, stat_file
+
+sb.git_clone("https://github.com/octocat/Hello-World.git", "hw", depth: 1)
+sb.git_commit("hw", "change", author_name: "me", author_email: "me@example.com")  # stages everything first
+sb.git("log", path: "hw", n: 5).log            # any op: status, add, push, pull, checkout, branches, diff
+
+sb.shell("cd /tmp && export X=1")              # session "main", made on first use; cd/export persist
+sb.shell("echo $X; pwd").cwd                   # "/tmp"; create_session / session_exec / delete_session
+
+cid = sb.start_pty(cols: 80, rows: 24)         # then WebSocket …/containers/{cid}/tty; resize_pty
+sb.create_preview(8000, session: "main", expires_in_s: 600)  # signed link; k.revoke_previews ends them all
+sb.set_lifecycle(auto_stop_min: 0)             # nil keeps a setting, 0 turns it off
+
+k.build_template("py-data", "./ctx", build_args: { "V" => "1" }) { |out| print out }  # tars ./ctx, honours .dockerignore
+k.create_sandbox(name: "fast", template: "py-data")
+k.list_templates; k.delete_template("py-data")
+```
+
+A non-zero exit or a failed git op is a result (`ok?` false), not an exception; a failed template build
+raises `Kosa8::StreamError`.
+
+## kosa8 Cloud
+
+The same sandboxes on kosa8 Cloud instead of the local daemon. Make an API
+key in the cloud dashboard and set `KOSA8_API_KEY`.
+
+```ruby
+require "kosa8"
+
+cloud = Kosa8::Cloud.new  # or Kosa8::Cloud.new(api_key: "k8c_live_...")
+
+box = cloud.sandboxes.create(template: "python", sleep_after_s: 600)
+r = box.exec(["python3", "-c", "print(6 * 7)"])
+puts r.exit_code, r.stdout     # 0, 42
+box.sleep                      # costs only snapshot storage while asleep
+box.exec("ls /workspace")      # wakes it, files and all
+box.delete
+
+cloud.functions.deploy("hello", {
+  "runtime" => "python3.12",
+  "code" => "def handler(event):\n    return {\"hello\": event.get(\"name\", \"world\")}\n"
+})
+out = cloud.functions.invoke("hello", { "name" => "kosa8" })
+p out["ok"], out["result"]     # true, {"hello"=>"kosa8"}
+```
+
+A new organization runs nothing until a payment method is on file; until
+then creating a sandbox raises `Kosa8::PaymentRequiredError` (`code`
+`payment_required`), whose message says what to do. Every error from the
+cloud carries its stable `code`. The address is `KOSA8_CLOUD_URL` (default
+`https://api.kosa8.cloud`, https only except localhost); `cloud.me` and
+`cloud.usage` show the org and this month's bill estimate.
+
 ## Development
 
 ```sh
 ruby -w test/test_client.rb      # mock daemon on a unix socket
+ruby -w test/test_toolbox.rb
+ruby -w test/test_cloud.rb       # stub transport and a local socket
+ruby -w -Ilib -Itest -e 'Dir["test/test_*.rb"].sort.each { |f| require File.expand_path(f) }'  # all, as CI does
 ruby examples/smoke.rb           # live, against a running `kosa8 daemon`
 ```
 

data/lib/kosa8/client.rb

@@ -14,19 +14,23 @@ module Kosa8
   TRANSIENT = /connection refused|EOF|connection reset|broken pipe|no such file or directory|stream ended|ECONNREFUSED|ECONNRESET|unreachable/i.freeze
 
   # Typed client for the kosa8 native API (/kosa8/v1) over the daemon's unix
-  # socket, or a remote worker via KOSA8_HOST / KOSA8_TOKEN.
+  # socket, or a remote worker via KOSA8_HOST / KOSA8_TOKEN, or the connection
+  # the CLI saved in ~/.kosa8/worker.json (`kosa8 wsl setup`, `kosa8 worker join`).
   #
   #   k = Kosa8::Client.new
   #   k.create_sandbox(name: "demo", egress: "deny")
   #   k.pull_into_sandbox("demo", "alpine:latest")
   #   puts k.run("demo", "alpine:latest", ["echo", "hi"]).stdout
   class Client
+    include Toolbox
+
     attr_reader :transport, :checkpoints
 
     def initialize(socket_path: nil, host: nil, token: nil, insecure: false, actor: "tool", agent_token: nil,
-                   headers: {}, timeout: nil, checkpoint_store: nil, env: ENV)
+                   headers: {}, timeout: nil, checkpoint_store: nil, env: ENV, worker_file: nil)
       @transport = Transport.new(socket_path: socket_path, host: host, token: token, insecure: insecure, actor: actor,
-                                 agent_token: agent_token, headers: headers, timeout: timeout, env: env)
+                                 agent_token: agent_token, headers: headers, timeout: timeout, env: env,
+                                 worker_file: worker_file)
       @checkpoints = CheckpointBook.new(checkpoint_store || FileCheckpointStore.new)
       @stdin_sent = {}
       @stdin_mu = Mutex.new
@@ -62,8 +66,14 @@ module Kosa8
 
     # POST /kosa8/v1/sandboxes: boot a microVM sandbox.
     # egress: "deny" | "any" | "fakenet" | "allow:host,host" | { allow: [...] }
+    #
+    # auto_stop_min stops it after that many idle minutes, ttl_min that long
+    # after creation, auto_delete_min deletes it once stopped that long, and
+    # ephemeral deletes it whenever it stops. template starts it with a
+    # template's image (see build_template).
     def create_sandbox(name: nil, cpus: nil, mem_mb: nil, disk_gb: nil, mounts: nil, egress: nil, egress_allow: nil,
-                       capture: nil, labels: nil, broker: nil, approval: nil)
+                       capture: nil, labels: nil, broker: nil, auto_stop_min: nil, auto_delete_min: nil, ttl_min: nil,
+                       ephemeral: false, template: nil, approval: nil)
       body = {}
       body[:name] = name if name
       body[:cpus] = cpus if cpus
@@ -75,6 +85,11 @@ module Kosa8
       body[:capture] = capture unless capture.nil?
       body[:labels] = labels if labels
       body[:broker] = broker if broker
+      { auto_stop_min: auto_stop_min, auto_delete_min: auto_delete_min, ttl_min: ttl_min }.each do |k, v|
+        body[k] = v if v && v.positive?
+      end
+      body[:ephemeral] = true if ephemeral
+      body[:template] = template if template
       @transport.json("POST", "/kosa8/v1/sandboxes", body: body, approval: approval)
     end
 
@@ -512,6 +527,18 @@ module Kosa8
       @client.attach(@id, container, **kw)
     end
 
+    # The toolbox, bound to this sandbox: sandbox.run_code("print(1)"),
+    # sandbox.write_file("a.txt", "hi"), sandbox.shell("ls"), …
+    %i[run_code list_files stat_file read_file read_text write_file delete_file make_dir move_file git git_clone
+       git_status git_commit create_session list_sessions session_exec shell delete_session start_pty resize_pty
+       create_preview].each do |name|
+      define_method(name) { |*args, **kw, &blk| @client.public_send(name, @id, *args, **kw, &blk) }
+    end
+
+    def set_lifecycle(**kw)
+      @client.set_lifecycle(@id, **kw)
+    end
+
     { start: :start_sandbox, stop: :stop_sandbox, delete: :delete_sandbox, snapshot: :snapshot,
       checkpoint: :checkpoint, rewind: :rewind }.each do |name, target|
       define_method(name) { |**kw| @client.public_send(target, @id, **kw) }

data/lib/kosa8/cloud.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "socket"
+require "uri"
+
+module Kosa8
+  # The outcome of a cloud exec. +woke_ms+ is set when the sandbox was asleep
+  # and woke for this command.
+  CloudExecResult = Struct.new(:exit_code, :stdout, :stderr, :woke_ms, keyword_init: true) do
+    def ok?
+      exit_code == 0 # exit_code is nil when the command never ran
+    end
+  end
+
+  # kosa8 Cloud: the same sandboxes, run on kosa8's hosts (or your own, with
+  # bring-your-own-cloud) instead of the local daemon.
+  #
+  #   cloud = Kosa8::Cloud.new            # KOSA8_API_KEY from the environment
+  #   box = cloud.sandboxes.create(template: "python")
+  #   box.exec(["python3", "-c", "print(6 * 7)"]).stdout  # => "42\n"
+  #   box.delete
+  #
+  # Authentication is an API key (k8c_live_...) made in the cloud dashboard.
+  # Errors are the SDK's usual typed errors; each carries the cloud's stable
+  # +code+ (for example payment_required, quota_exceeded). Standard library only.
+  class Cloud
+    DEFAULT_URL = "https://api.kosa8.cloud"
+    KEY_PREFIX = "k8c_live_"
+    LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+    attr_reader :base_url, :timeout, :sandboxes, :functions
+
+    # transport: an optional callable (method, url, headers, body_or_nil, timeout) -> [status, body_string],
+    # used instead of Net::HTTP (tests, proxies).
+    def initialize(api_key: nil, base_url: nil, env: ENV, timeout: 120, transport: nil)
+      key = (api_key.nil? ? env["KOSA8_API_KEY"].to_s : api_key.to_s).strip
+      raise Error, "no kosa8 Cloud API key: pass api_key: or set KOSA8_API_KEY" if key.empty?
+      raise Error, "a kosa8 Cloud API key starts with #{KEY_PREFIX}" unless key.start_with?(KEY_PREFIX)
+
+      @key = key
+      base = [base_url, env["KOSA8_CLOUD_URL"]].find { |v| v && !v.to_s.empty? } || DEFAULT_URL
+      @base_url = Cloud.check_base(base.to_s)
+      @timeout = timeout
+      @transport = transport || method(:net_http)
+      @sandboxes = CloudSandboxes.new(self)
+      @functions = CloudFunctions.new(self)
+    end
+
+    # Never the key.
+    def inspect
+      "#<Kosa8::Cloud base_url=#{@base_url.inspect}>"
+    end
+    alias to_s inspect
+
+    # The org, the key in use and, for a member's key, the member.
+    def me
+      request("GET", "/v1/me")
+    end
+
+    # This month's usage, bill estimate and whether work is paused for payment.
+    def usage
+      request("GET", "/v1/usage")
+    end
+
+    # One JSON request; raises the typed error for an error answer.
+    def request(method, path, body = nil)
+      headers = { "Authorization" => "Bearer #{@key}", "Accept" => "application/json" }
+      data = nil
+      unless body.nil?
+        headers["Content-Type"] = "application/json"
+        data = JSON.generate(body)
+      end
+      begin
+        status, raw = @transport.call(method, @base_url + path, headers, data, @timeout)
+      rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error => e
+        raise TimeoutError.new("kosa8 Cloud did not answer within #{@timeout} s (#{e.message})",
+                               method: method, path: path)
+      rescue SystemCallError, IOError, SocketError, OpenSSL::SSL::SSLError => e
+        raise ConnectionError.new("could not reach kosa8 Cloud at #{@base_url}: #{e.message}",
+                                  method: method, path: path)
+      end
+      text = raw.to_s.dup.force_encoding(Encoding::UTF_8)
+      text = text.scrub unless text.valid_encoding?
+      parsed = begin
+        text.strip.empty? ? nil : JSON.parse(text)
+      rescue JSON::ParserError
+        text
+      end
+      raise Cloud.error(status.to_i, parsed, method, path) if status.to_i >= 400
+
+      parsed
+    end
+
+    # The cloud answers {"error": code, "message": sentence}: the sentence is
+    # the message, and the code is kept.
+    def self.error(status, body, method, path)
+      code = nil
+      msg_body = body
+      if body.is_a?(Hash)
+        code = body["error"] if body["error"].is_a?(String)
+        m = body["message"]
+        msg_body = { "error" => m.is_a?(String) && !m.empty? ? m : body["error"] }
+      end
+      e = Kosa8.error_from_response(status, msg_body, method: method, path: path, code: code)
+      e.instance_variable_set(:@body, body)
+      e
+    end
+
+    def self.check_base(url)
+      u = begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        nil
+      end
+      raise Error, "kosa8 Cloud address is not a URL: #{url}" if u.nil? || u.scheme.nil? || u.host.nil? || u.host.empty?
+
+      local = LOCAL_HOSTS.include?(u.hostname)
+      # The API key travels in every request.
+      unless u.scheme == "https" || (u.scheme == "http" && local)
+        raise Error, "kosa8 Cloud address must use https: #{url}"
+      end
+
+      url.sub(%r{/+\z}, "")
+    end
+
+    private
+
+    def net_http(method, url, headers, body, timeout)
+      u = URI.parse(url)
+      http = Net::HTTP.new(u.hostname, u.port)
+      http.use_ssl = u.scheme == "https"
+      if timeout
+        http.open_timeout = [timeout, 30].min
+        http.read_timeout = timeout
+        http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+      end
+      req = Net::HTTPGenericRequest.new(method, !body.nil?, true, u.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body unless body.nil?
+      http.start do |h|
+        resp = h.request(req)
+        [resp.code.to_i, resp.body.to_s]
+      end
+    end
+  end
+
+  # cloud.sandboxes
+  class CloudSandboxes
+    def initialize(cloud)
+      @cloud = cloud
+    end
+
+    def inspect
+      "#<Kosa8::CloudSandboxes>"
+    end
+
+    # Start a sandbox; returns once it is running. Unset options take the org's settings.
+    def create(template: nil, region: nil, sleep_after_s: nil)
+      body = {}
+      body["template"] = template unless template.nil?
+      body["region"] = region unless region.nil?
+      body["sleep_after_s"] = sleep_after_s unless sleep_after_s.nil?
+      CloudSandbox.new(@cloud, @cloud.request("POST", "/v1/sandboxes", body)["sandbox"])
+    end
+
+    # The org's sandboxes; with all: true, deleted ones too.
+    def list(all: false)
+      r = @cloud.request("GET", "/v1/sandboxes" + (all ? "?all=1" : ""))
+      r["sandboxes"].map { |s| CloudSandbox.new(@cloud, s) }
+    end
+
+    def get(id)
+      CloudSandbox.new(@cloud, @cloud.request("GET", "/v1/sandboxes/#{Kosa8.enc(id)}")["sandbox"])
+    end
+  end
+
+  # One cloud sandbox. +info+ is its state as of the last call.
+  class CloudSandbox
+    attr_reader :info
+
+    def initialize(cloud, info)
+      @cloud = cloud
+      @info = info
+    end
+
+    def id
+      @info["id"]
+    end
+
+    def state
+      @info["state"].to_s
+    end
+
+    def inspect
+      "#<Kosa8::CloudSandbox id=#{id.inspect} state=#{state.inspect}>"
+    end
+
+    # Run a command and wait for it. A String runs through sh -c, an Array is
+    # the argv. A sleeping sandbox wakes for it.
+    def exec(cmd, image: nil, env: nil)
+      argv = cmd.is_a?(String) ? ["sh", "-c", cmd] : cmd.to_a
+      body = { "cmd" => argv }
+      body["image"] = image unless image.nil?
+      body["env"] = env.map { |k, v| "#{k}=#{v}" } if env && !env.empty?
+      r = @cloud.request("POST", path("/exec"), body)
+      CloudExecResult.new(exit_code: r["exit"], stdout: r["stdout"] || "", stderr: r["stderr"] || "",
+                          woke_ms: r["woke_ms"])
+    end
+
+    # Snapshot it and free its VM; it then costs only snapshot storage.
+    def sleep
+      @info = @cloud.request("POST", path("/sleep"))["sandbox"]
+      self
+    end
+
+    # Restore a sleeping sandbox, files and all.
+    def wake
+      @info = @cloud.request("POST", path("/wake"))["sandbox"]
+      self
+    end
+
+    def refresh
+      @info = @cloud.request("GET", path)["sandbox"]
+      self
+    end
+
+    def delete
+      @cloud.request("DELETE", path)
+      nil
+    end
+
+    private
+
+    def path(suffix = "")
+      "/v1/sandboxes/#{Kosa8.enc(id)}#{suffix}"
+    end
+  end
+
+  # cloud.functions
+  class CloudFunctions
+    def initialize(cloud)
+      @cloud = cloud
+    end
+
+    def inspect
+      "#<Kosa8::CloudFunctions>"
+    end
+
+    # Deploy (create or replace) a function; every deploy bumps its version.
+    def deploy(name, spec)
+      @cloud.request("PUT", path(name), spec.to_h)
+    end
+
+    def list
+      @cloud.request("GET", "/v1/functions")["functions"]
+    end
+
+    def get(name)
+      @cloud.request("GET", path(name))
+    end
+
+    def delete(name)
+      @cloud.request("DELETE", path(name))
+      nil
+    end
+
+    # Call it once. A handler that raises answers "ok" => false, not an exception.
+    def invoke(name, event = nil)
+      @cloud.request("POST", path(name, "/invoke"), { "event" => event })
+    end
+
+    # One call per event, results in input order.
+    def map(name, events, concurrency: nil)
+      body = { "events" => events.to_a }
+      body["concurrency"] = concurrency unless concurrency.nil?
+      @cloud.request("POST", path(name, "/map"), body)
+    end
+
+    private
+
+    def path(name, suffix = "")
+      "/v1/functions/#{Kosa8.enc(name)}#{suffix}"
+    end
+  end
+end

data/lib/kosa8/errors.rb

@@ -4,9 +4,11 @@ module Kosa8
   # Every error this gem raises. The daemon's own words are kept in
   # +daemon_message+ and +remediation+, as @kosa8/sdk does.
   class Error < StandardError
-    attr_reader :status, :daemon_message, :remediation, :http_method, :path, :body
+    # +code+ is kosa8 Cloud's stable error code (payment_required, quota_exceeded, ...).
+    attr_reader :status, :daemon_message, :remediation, :http_method, :path, :body, :code
 
-    def initialize(message = nil, status: nil, daemon_message: nil, remediation: nil, method: nil, path: nil, body: nil)
+    def initialize(message = nil, status: nil, daemon_message: nil, remediation: nil, method: nil, path: nil, body: nil,
+                   code: nil)
       super(message)
       @status = status
       @daemon_message = daemon_message
@@ -14,6 +16,7 @@ module Kosa8
       @http_method = method
       @path = path
       @body = body
+      @code = code
     end
   end
 
@@ -25,6 +28,8 @@ module Kosa8
   class NotFoundError < ApiError; end     # 404
   class ConflictError < ApiError; end     # 409
   class UnsupportedError < ApiError; end  # 501
+  class PaymentRequiredError < ApiError; end # 402: kosa8 Cloud wants a payment method first
+  class RateLimitError < ApiError; end    # 429: too many requests, or a quota reached
 
   # 403 that a signed approval would lift; +approval+ is the daemon's refusal.
   class ApprovalRequiredError < PolicyError
@@ -54,13 +59,13 @@ module Kosa8
   class ProtocolError < Error; end
 
   BY_STATUS = {
-    400 => BadRequestError, 401 => AuthError, 403 => PolicyError,
-    404 => NotFoundError, 409 => ConflictError, 501 => UnsupportedError
+    400 => BadRequestError, 401 => AuthError, 402 => PaymentRequiredError, 403 => PolicyError,
+    404 => NotFoundError, 409 => ConflictError, 429 => RateLimitError, 501 => UnsupportedError
   }.freeze
 
   # The typed error for an HTTP error answer: the daemon's message with its
   # remediation in parentheses, as the CLI and MCP server print it.
-  def self.error_from_response(status, body, method:, path:)
+  def self.error_from_response(status, body, method:, path:, code: nil)
     msg = nil
     rem = nil
     approval = nil
@@ -73,7 +78,8 @@ module Kosa8
     end
     base = msg.is_a?(String) && !msg.empty? ? msg : "request failed with HTTP #{status}"
     text = rem ? "#{base} (#{rem})" : base
-    kw = { status: status, daemon_message: msg, remediation: rem, method: method, path: path, body: body }
+    kw = { status: status, daemon_message: msg, remediation: rem, method: method, path: path, body: body,
+           code: code }
     return ApprovalRequiredError.new(text, approval: approval, **kw) if approval
 
     (BY_STATUS[status] || ApiError).new(text, **kw)

data/lib/kosa8/toolbox.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require "base64"
+require "pathname"
+require "rubygems/package"
+require "stringio"
+
+module Kosa8
+  # A file a code run produced: today, a chart as a PNG. +data+ is a binary String.
+  Artifact = Struct.new(:type, :name, :data, keyword_init: true)
+
+  # The outcome of run_code. A non-zero exit_code is not an error.
+  CodeResult = Struct.new(:exit_code, :stdout, :stderr, :language, :image, :artifacts, :duration_ms, :timed_out,
+                          :truncated, keyword_init: true) do
+    def ok?
+      exit_code.zero? && !timed_out
+    end
+  end
+
+  # The outcome of one command in a session. +cwd+ is where the shell is now.
+  ShellResult = Struct.new(:exit_code, :stdout, :stderr, :cwd, :duration_ms, :timed_out, :truncated,
+                           keyword_init: true) do
+    def ok?
+      exit_code.zero? && !timed_out
+    end
+  end
+
+  # The outcome of a git operation; +status+, +log+ or +branches+ are filled for those ops.
+  # A git failure is ok == false, not an exception.
+  GitResult = Struct.new(:op, :ok, :exit_code, :stdout, :stderr, :path, :status, :log, :branches,
+                         keyword_init: true) do
+    def ok?
+      ok
+    end
+  end
+
+  # How long the daemon lets a snippet or session command run by default
+  # (codeTimeoutDefault), and a git operation (gitTimeout).
+  CODE_TIMEOUT_DEFAULT_S = 300
+  GIT_TIMEOUT_S = 600
+
+  # The sandbox toolbox: run code, files and git, shell sessions, terminals,
+  # previews, lifecycle and templates. Included in Kosa8::Client; every method
+  # maps to one daemon route (see https://docs.kosa8.com/guides/native-api/).
+  module Toolbox
+    # --- code -----------------------------------------------------------------
+
+    # POST …/code: run a Python, JavaScript or TypeScript snippet. It starts in
+    # /workspace. Charts a Python snippet draws with matplotlib come back in
+    # +artifacts+ as PNG bytes.
+    def run_code(sandbox, code, language: "python", image: nil, env: nil, timeout_s: nil, approval: nil)
+      body = { language: language, code: code }
+      body[:image] = image if image
+      body[:env] = env.to_h if env && !env.empty?
+      body[:timeout_s] = timeout_s if timeout_s && timeout_s.positive?
+      d = @transport.json("POST", sb(sandbox, "code"), body: body, approval: approval,
+                                                      timeout: (timeout_s || CODE_TIMEOUT_DEFAULT_S) + 120) || {}
+      CodeResult.new(
+        exit_code: d["exit"].to_i, stdout: d["stdout"].to_s, stderr: d["stderr"].to_s,
+        language: d["language"].to_s, image: d["image"].to_s,
+        artifacts: (d["artifacts"] || []).map do |a|
+          Artifact.new(type: a["type"].to_s, name: a["name"].to_s, data: Base64.decode64(a["data"].to_s).b)
+        end,
+        duration_ms: d["duration_ms"].to_i, timed_out: d["timed_out"] == true, truncated: d["truncated"] == true
+      )
+    end
+
+    # --- files ----------------------------------------------------------------
+
+    # GET …/files: a folder in the workspace (or one entry).
+    def list_files(sandbox, path = "/workspace")
+      d = @transport.json("GET", sb(sandbox, "files"), query: { path: path })
+      (d.is_a?(Hash) ? d["files"] : nil) || []
+    end
+
+    # GET …/files/stat: one entry, not following a symlink.
+    def stat_file(sandbox, path)
+      @transport.json("GET", sb(sandbox, "files", "stat"), query: { path: path })
+    end
+
+    # GET …/files/content: a file's bytes, as a binary String.
+    def read_file(sandbox, path)
+      route = sb(sandbox, "files", "content")
+      @transport.raw("GET", route, query: { path: path }) do |resp|
+        data = resp.read_body.to_s.b
+        code = resp.code.to_i
+        if code >= 400
+          raise Kosa8.error_from_response(code, decode_body(data), method: "GET", path: route)
+        end
+
+        want = resp["Content-Length"]
+        if want && want.to_i != data.bytesize
+          raise StreamError.new("#{path}: got #{data.bytesize} of #{want} bytes", method: "GET", path: route)
+        end
+
+        data
+      end
+    end
+
+    def read_text(sandbox, path, encoding: Encoding::UTF_8)
+      read_file(sandbox, path).force_encoding(encoding)
+    end
+
+    # PUT …/files/content: replace a file (a String, binary or text), making its folders.
+    def write_file(sandbox, path, data, mode: nil, approval: nil)
+      q = { path: path }
+      q[:mode] = mode if mode
+      @transport.json("PUT", sb(sandbox, "files", "content"), query: q, raw_body: data.to_s.b, approval: approval)
+    end
+
+    # DELETE …/files: a file, or with recursive: a folder.
+    def delete_file(sandbox, path, recursive: false, approval: nil)
+      @transport.json("DELETE", sb(sandbox, "files"), query: { path: path, recursive: recursive }, approval: approval)
+    end
+
+    def make_dir(sandbox, path, approval: nil)
+      @transport.json("POST", sb(sandbox, "files", "mkdir"), body: { path: path }, approval: approval)
+    end
+
+    def move_file(sandbox, from, to, approval: nil)
+      @transport.json("POST", sb(sandbox, "files", "move"), body: { from: from, to: to }, approval: approval)
+    end
+
+    # --- git ------------------------------------------------------------------
+
+    # POST …/git: +op+ is clone, status, add, commit, push, pull, checkout,
+    # branches, log or diff; +fields+ are that op's (url:, path:, branch:,
+    # message:, token:…). A git failure returns ok == false.
+    def git(sandbox, op, approval: nil, **fields)
+      body = { op: op }
+      fields.each { |k, v| body[k] = v unless v.nil? }
+      d = @transport.json("POST", sb(sandbox, "git"), body: body, approval: approval, timeout: GIT_TIMEOUT_S + 120) || {}
+      GitResult.new(op: d["op"] || op.to_s, ok: d["ok"] == true, exit_code: d["exit"].to_i, stdout: d["stdout"].to_s,
+                    stderr: d["stderr"].to_s, path: d["path"].to_s, status: d["status"], log: d["log"],
+                    branches: d["branches"])
+    end
+
+    def git_clone(sandbox, url, path = nil, **kw)
+      git(sandbox, "clone", url: url, path: path, **kw)
+    end
+
+    def git_status(sandbox, path, **kw)
+      git(sandbox, "status", path: path, **kw)
+    end
+
+    # Stage everything (unless add_all: false) and commit.
+    def git_commit(sandbox, path, message, add_all: true, **kw)
+      if add_all
+        r = git(sandbox, "add", path: path, approval: kw[:approval])
+        return r unless r.ok
+      end
+      git(sandbox, "commit", path: path, message: message, **kw)
+    end
+
+    # --- sessions -------------------------------------------------------------
+
+    # POST …/sessions: a shell that keeps cd and export between commands.
+    def create_session(sandbox, name = nil, image: nil, env: nil, approval: nil)
+      body = {}
+      body[:name] = name if name
+      body[:image] = image if image
+      body[:env] = env.to_h if env && !env.empty?
+      @transport.json("POST", sb(sandbox, "sessions"), body: body, approval: approval)
+    end
+
+    def list_sessions(sandbox)
+      @transport.json("GET", sb(sandbox, "sessions")) || []
+    end
+
+    # POST …/sessions/{name}/exec: run one command line in the session.
+    def session_exec(sandbox, session, command, timeout_s: nil, approval: nil)
+      body = { command: command }
+      body[:timeout_s] = timeout_s if timeout_s && timeout_s.positive?
+      d = @transport.json("POST", sb(sandbox, "sessions", Kosa8.enc(session), "exec"), body: body, approval: approval,
+                                                                                     timeout: (timeout_s || CODE_TIMEOUT_DEFAULT_S) + 120) || {}
+      ShellResult.new(exit_code: d["exit"].to_i, stdout: d["stdout"].to_s, stderr: d["stderr"].to_s, cwd: d["cwd"].to_s,
+                      duration_ms: d["duration_ms"].to_i, timed_out: d["timed_out"] == true,
+                      truncated: d["truncated"] == true)
+    end
+
+    # Run a command in a session, making the session on first use.
+    def shell(sandbox, command, session: "main", **kw)
+      begin
+        return session_exec(sandbox, session, command, **kw)
+      rescue NotFoundError => e
+        raise unless "#{e.daemon_message} #{e.message}".include?("no such session")
+      end
+      create_session(sandbox, session, approval: kw[:approval])
+      session_exec(sandbox, session, command, **kw)
+    end
+
+    def delete_session(sandbox, session, approval: nil)
+      @transport.json("DELETE", sb(sandbox, "sessions", Kosa8.enc(session)), approval: approval)
+    end
+
+    # --- terminals ------------------------------------------------------------
+
+    # POST …/pty: a container with a terminal; returns its id. Connect to
+    # /kosa8/v1/sandboxes/{id}/containers/{cid}/tty with any WebSocket client:
+    # binary messages are the terminal, text messages JSON control.
+    def start_pty(sandbox, image: nil, command: nil, cols: 0, rows: 0, env: nil, approval: nil)
+      body = {}
+      body[:image] = image if image
+      body[:command] = command.to_a if command && !command.empty?
+      if cols.to_i.positive? && rows.to_i.positive?
+        body[:cols] = cols
+        body[:rows] = rows
+      end
+      body[:env] = env.to_h if env && !env.empty?
+      @transport.json("POST", sb(sandbox, "pty"), body: body, approval: approval)["id"]
+    end
+
+    def resize_pty(sandbox, container, cols, rows)
+      @transport.json("POST", sb(sandbox, "containers", Kosa8.enc(container), "resize"), body: { cols: cols, rows: rows })
+    end
+
+    # --- previews -------------------------------------------------------------
+
+    # POST …/previews: a signed link to a web server in the sandbox that expires.
+    def create_preview(sandbox, port, session: nil, container: nil, expires_in_s: nil, approval: nil)
+      body = { port: port }
+      body[:session] = session if session
+      body[:container] = container if container
+      body[:expires_in_s] = expires_in_s if expires_in_s && expires_in_s.positive?
+      @transport.json("POST", sb(sandbox, "previews"), body: body, approval: approval)
+    end
+
+    # POST /kosa8/v1/previews/rotate: end every preview link at once.
+    def revoke_previews(approval: nil)
+      @transport.json("POST", "/kosa8/v1/previews/rotate", approval: approval)
+    end
+
+    # --- lifecycle ------------------------------------------------------------
+
+    # POST …/lifecycle: change auto-stop, auto-delete, TTL or ephemeral.
+    # Arguments left nil keep their value; 0 turns one off.
+    def set_lifecycle(sandbox, auto_stop_min: nil, auto_delete_min: nil, ttl_min: nil, ephemeral: nil, approval: nil)
+      body = { auto_stop_min: auto_stop_min, auto_delete_min: auto_delete_min, ttl_min: ttl_min, ephemeral: ephemeral }
+             .reject { |_, v| v.nil? }
+      @transport.json("POST", sb(sandbox, "lifecycle"), body: body, approval: approval)
+    end
+
+    # --- templates ------------------------------------------------------------
+
+    def list_templates
+      @transport.json("GET", "/kosa8/v1/templates") || []
+    end
+
+    def delete_template(name, approval: nil)
+      @transport.json("DELETE", "/kosa8/v1/templates/#{Kosa8.enc(name)}", approval: approval)
+    end
+
+    # POST /kosa8/v1/templates: build context_dir's Dockerfile in a throwaway
+    # sandbox and keep the image as a template. Build output goes to on_output
+    # (or the block) as it arrives; returns the final frame. A failed build
+    # raises Kosa8::StreamError.
+    def build_template(name, context_dir = ".", dockerfile: "Dockerfile", build_args: nil, egress: nil, replace: false,
+                       on_output: nil, approval: nil, &blk)
+      on_output ||= blk
+      q = [["name", name], ["dockerfile", dockerfile]]
+      (build_args || {}).each { |k, v| q << ["buildarg", "#{k}=#{v}"] }
+      q << ["egress", egress] if egress
+      q << %w[replace 1] if replace
+      ctx = Toolbox.tar_dir(context_dir, dockerfile)
+      route = "/kosa8/v1/templates?" + URI.encode_www_form(q)
+      last = nil
+      @transport.frames("POST", route, raw_body: ctx, approval: approval) do |f|
+        next if last
+
+        if f["done"]
+          if f["error"].is_a?(String) && !f["error"].empty?
+            raise StreamError.new(f["error"], daemon_message: f["error"], method: "POST", path: "/kosa8/v1/templates")
+          end
+
+          last = f
+          next
+        end
+        on_output&.call(f["data"]) if f["data"].is_a?(String) && !f["data"].empty?
+      end
+      last || raise(StreamError.new("template build stream ended unexpectedly (no final frame)",
+                                    method: "POST", path: "/kosa8/v1/templates"))
+    end
+
+    # Pack a build context the way `kosa8 build` does, honouring .dockerignore
+    # prefixes. Returns the tar as a binary String.
+    def self.tar_dir(path, dockerfile = "Dockerfile")
+      raise Error, "no #{dockerfile} in #{path}" unless File.exist?(File.join(path, dockerfile))
+
+      ignore = []
+      di = File.join(path, ".dockerignore")
+      if File.exist?(di)
+        ignore = File.readlines(di).reject { |l| l.strip.empty? || l.start_with?("#") }
+                     .map { |l| Pathname.new(l.strip).cleanpath.to_s }
+      end
+      skip = ->(rel) { ignore.any? { |p| rel == p || rel.start_with?(p + "/") } }
+      io = StringIO.new(+"".b)
+      Gem::Package::TarWriter.new(io) do |tar|
+        walk = lambda do |dir, rel_dir|
+          Dir.children(dir).sort.each do |name|
+            full = File.join(dir, name)
+            rel = rel_dir.empty? ? name : "#{rel_dir}/#{name}"
+            next if skip.call(rel)
+
+            st = File.lstat(full)
+            mode = st.mode & 0o7777
+            if st.symlink?
+              tar.add_symlink(rel, File.readlink(full), mode)
+            elsif st.directory?
+              tar.mkdir(rel, mode)
+              walk.call(full, rel)
+            elsif st.file?
+              tar.add_file_simple(rel, mode, st.size) { |w| File.open(full, "rb") { |f| IO.copy_stream(f, w) } }
+            end
+          end
+        end
+        walk.call(path, "")
+      end
+      io.string
+    end
+
+    private
+
+    def decode_body(data)
+      text = data.dup.force_encoding(Encoding::UTF_8).scrub
+      return nil if text.strip.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      text
+    end
+  end
+end

data/lib/kosa8/transport.rb

@@ -4,6 +4,7 @@ require "base64"
 require "json"
 require "net/http"
 require "openssl"
+require "rbconfig"
 require "socket"
 require "uri"
 
@@ -17,8 +18,16 @@ module Kosa8
     File.join(Dir.home, ".kosa8", "run", "kosa8.sock")
   end
 
-  # Where requests go: a unix socket or a remote worker.
-  Endpoint = Struct.new(:kind, :socket_path, :scheme, :host, :port, :base_path, :token, keyword_init: true) do
+  # $HOME/.kosa8/worker.json: the connection `kosa8 wsl setup` (Windows) and
+  # `kosa8 worker join` save, which the CLI uses whenever KOSA8_HOST is unset.
+  def self.default_worker_file
+    File.join(Dir.home, ".kosa8", "worker.json")
+  end
+
+  # Where requests go: a unix socket or a remote worker. default_socket is true
+  # when nothing chose the socket: no host, no saved worker, no socket_path.
+  Endpoint = Struct.new(:kind, :socket_path, :scheme, :host, :port, :base_path, :token, :default_socket,
+                        keyword_init: true) do
     def target
       kind == :unix ? "unix://#{socket_path}" : "#{scheme}://#{host}:#{port}"
     end
@@ -29,22 +38,54 @@ module Kosa8
     h == "localhost" || h == "::1" || h.start_with?("127.")
   end
 
-  # The CLI's KOSA8_HOST rules: no host means the local socket; https://,
-  # http://, tcp://, unix:// or a bare host:port select a worker; plain http to a
-  # non-loopback host is refused unless insecure (or KOSA8_INSECURE=1).
-  # KOSA8_TOKEN is used only for a host that came from KOSA8_HOST.
-  def self.resolve_endpoint(host: nil, socket_path: nil, token: nil, insecure: false, env: ENV)
+  # The saved worker connection as {"host", "token", "insecure"}, or nil when
+  # the file is missing, unreadable, not a JSON object or names no host.
+  def self.load_saved_worker(path)
+    return nil if path.nil? || path == false || path.to_s.empty?
+
+    w = JSON.parse(File.read(path.to_s))
+    return nil unless w.is_a?(Hash) && w["host"].is_a?(String) && !w["host"].strip.empty?
+
+    { "host" => w["host"], "token" => w["token"].is_a?(String) ? w["token"] : nil, "insecure" => w["insecure"] == true }
+  rescue SystemCallError, IOError, JSON::ParserError, EncodingError
+    nil
+  end
+
+  # The CLI's rules (internal/cli/worker.go targetHost/targetToken/targetInsecure):
+  # 1. an explicit host:, or a non-blank KOSA8_HOST: https://, http://, tcp://,
+  #    unix:// or a bare host:port; KOSA8_TOKEN goes only to a KOSA8_HOST host;
+  # 2. else, unless socket_path: was given, the saved worker in worker_file
+  #    (nil = ~/.kosa8/worker.json, false or "" = none), with its token unless
+  #    token: is given, and its "insecure": true;
+  # 3. else the unix socket.
+  # Plain http to a non-loopback host is refused unless insecure (or KOSA8_INSECURE=1).
+  def self.resolve_endpoint(host: nil, socket_path: nil, token: nil, insecure: false, env: ENV, worker_file: nil)
     explicit = !host.nil? && !host.empty?
-    raw = (explicit ? host : env["KOSA8_HOST"].to_s).strip.sub(%r{/+\z}, "")
-    return Endpoint.new(kind: :unix, socket_path: socket_path || default_socket_path) if raw.empty?
+    raw = (explicit ? host : env["KOSA8_HOST"].to_s).strip
+    if raw.empty?
+      saved = socket_path.nil? ? load_saved_worker(worker_file.nil? ? default_worker_file : worker_file) : nil
+      if saved.nil?
+        return Endpoint.new(kind: :unix, socket_path: socket_path || default_socket_path,
+                            default_socket: socket_path.nil?)
+      end
+
+      tok = token.nil? || token.empty? ? saved["token"] : token
+      return parse_host(saved["host"].strip, token: tok, insecure: insecure || saved["insecure"], env: env,
+                                             source: "the saved worker host (#{worker_file || default_worker_file})")
+    end
+    token = env["KOSA8_TOKEN"] if (token.nil? || token.empty?) && !explicit
+    parse_host(raw, token: token, insecure: insecure, env: env, source: explicit ? "host" : "KOSA8_HOST")
+  end
 
+  def self.parse_host(raw, token:, insecure:, env:, source:)
+    raw = raw.sub(%r{/+\z}, "")
     h = raw.sub(%r{\A([A-Za-z][A-Za-z0-9+.-]*)://}) { "#{Regexp.last_match(1).downcase}://" }
     if h.start_with?("unix://")
-      return Endpoint.new(kind: :unix, socket_path: h.sub("unix://", ""))
+      return Endpoint.new(kind: :unix, socket_path: h.sub("unix://", ""), default_socket: false)
     elsif h.start_with?("tcp://")
       h = "http://" + h.sub("tcp://", "")
     elsif h =~ %r{\A([a-z][a-z0-9+.-]*)://} && !%w[http https].include?(Regexp.last_match(1))
-      raise Error, "KOSA8_HOST scheme \"#{Regexp.last_match(1)}\" is not supported; use http://, https://, tcp:// or unix://"
+      raise Error, "#{source} scheme \"#{Regexp.last_match(1)}\" is not supported; use http://, https://, tcp:// or unix://"
     elsif h !~ %r{\Ahttps?://}
       h = "http://" + h
     end
@@ -53,16 +94,20 @@ module Kosa8
     rescue URI::InvalidURIError
       nil
     end
-    raise Error, "KOSA8_HOST #{raw.inspect} names no host" if u.nil? || u.host.nil? || u.host.empty?
+    raise Error, "#{source} #{raw.inspect} names no host" if u.nil? || u.host.nil? || u.host.empty?
 
     if u.scheme == "http" && !insecure && env["KOSA8_INSECURE"] != "1" && !loopback?(u.host)
       raise Error, "refusing to talk to #{u.host}:#{u.port} over plain http: the token and every request would cross " \
                    "the network unencrypted. Use https://#{u.host}:#{u.port} (a worker behind a TLS-terminating tunnel " \
                    "or proxy), or pass insecure: true / KOSA8_INSECURE=1 if this link is already private and trusted"
     end
-    token = env["KOSA8_TOKEN"] if (token.nil? || token.empty?) && !explicit
     Endpoint.new(kind: :tcp, scheme: u.scheme, host: u.host, port: u.port, base_path: u.path.to_s.sub(%r{/+\z}, ""),
-                 token: token && !token.empty? ? token : nil)
+                 token: token && !token.empty? ? token : nil, default_socket: false)
+  end
+  private_class_method :parse_host
+
+  def self.windows?
+    RbConfig::CONFIG["host_os"] =~ /mswin|mingw|cygwin/ ? true : false
   end
 
   def self.enc(s)
@@ -74,6 +119,8 @@ module Kosa8
     attr_accessor :socket_path
 
     def connect
+      raise Errno::EAFNOSUPPORT, "unix sockets are not available in this Ruby" unless defined?(UNIXSocket)
+
       io = UNIXSocket.new(@socket_path)
       @socket = Net::BufferedIO.new(io, read_timeout: @read_timeout, continue_timeout: @continue_timeout,
                                         debug_output: @debug_output)
@@ -121,8 +168,9 @@ module Kosa8
     attr_reader :endpoint
 
     def initialize(socket_path: nil, host: nil, token: nil, insecure: false, actor: "tool", agent_token: nil,
-                   headers: {}, timeout: nil, env: ENV)
-      @endpoint = Kosa8.resolve_endpoint(host: host, socket_path: socket_path, token: token, insecure: insecure, env: env)
+                   headers: {}, timeout: nil, env: ENV, worker_file: nil)
+      @endpoint = Kosa8.resolve_endpoint(host: host, socket_path: socket_path, token: token, insecure: insecure, env: env,
+                                         worker_file: worker_file)
       raise Error, "actor must be human, agent or tool, not #{actor.inspect}" unless %w[human agent tool].include?(actor)
 
       @actor = actor
@@ -177,7 +225,13 @@ module Kosa8
         raise TimeoutError.new("#{method} #{path} timed out talking to #{@endpoint.target}: #{e.message}",
                                method: method, path: path)
       rescue SystemCallError, IOError, SocketError, OpenSSL::SSL::SSLError => e
-        hint = e.is_a?(Errno::ENOENT) || e.is_a?(Errno::ECONNREFUSED) ? " (is kosa8 installed and its daemon running? start it with `kosa8 daemon start`)" : ""
+        # Windows reports a missing unix socket path as ENETDOWN.
+        absent = e.is_a?(Errno::ENOENT) || e.is_a?(Errno::ECONNREFUSED) ||
+                 (Kosa8.windows? && @endpoint.kind == :unix && e.is_a?(Errno::ENETDOWN))
+        hint = absent ? " (is kosa8 installed and its daemon running? start it with `kosa8 daemon start`)" : ""
+        if @endpoint.kind == :unix && @endpoint.default_socket && Kosa8.windows?
+          hint += "; on Windows the engine runs in WSL2: run `kosa8 wsl setup`, or set KOSA8_HOST"
+        end
         raise ConnectionError.new("kosa8 daemon unreachable at #{@endpoint.target}: #{e.message}#{hint}",
                                   method: method, path: path)
       end

data/lib/kosa8/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kosa8
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/kosa8.rb

@@ -6,4 +6,6 @@ require_relative "kosa8/version"
 require_relative "kosa8/errors"
 require_relative "kosa8/transport"
 require_relative "kosa8/checkpoints"
+require_relative "kosa8/toolbox"
 require_relative "kosa8/client"
+require_relative "kosa8/cloud"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kosa8
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - kosa8
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies: []
 description: 'Typed client for the kosa8 daemon: sandboxes, run/exec streams, snapshots,
   fork, best-of-N explore and checkpoints shared with the kosa8 CLI. No dependencies.'
@@ -22,7 +22,9 @@ files:
 - lib/kosa8.rb
 - lib/kosa8/checkpoints.rb
 - lib/kosa8/client.rb
+- lib/kosa8/cloud.rb
 - lib/kosa8/errors.rb
+- lib/kosa8/toolbox.rb
 - lib/kosa8/transport.rb
 - lib/kosa8/version.rb
 homepage: https://kosa8.com