handinger 0.1.0 → 0.2.0

data/rbi/handinger/models/worker.rbi

@@ -45,11 +45,8 @@ module Handinger
       sig { returns(Handinger::Worker::Status::TaggedSymbol) }
       attr_accessor :status
 
-      sig { returns(T.nilable(Handinger::Worker::Costs)) }
-      attr_reader :costs
-
-      sig { params(costs: T.nilable(Handinger::Worker::Costs::OrHash)).void }
-      attr_writer :costs
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_accessor :structured_output
 
       sig { returns(T.nilable(Handinger::Worker::Usage)) }
       attr_reader :usage
@@ -72,7 +69,7 @@ module Handinger
           running: T::Boolean,
           sources: T::Array[Handinger::Worker::Source::OrHash],
           status: Handinger::Worker::Status::OrSymbol,
-          costs: T.nilable(Handinger::Worker::Costs::OrHash),
+          structured_output: T.nilable(T::Hash[Symbol, T.anything]),
           usage: Handinger::Worker::Usage::OrHash
         ).returns(T.attached_class)
       end
@@ -90,7 +87,7 @@ module Handinger
         running:,
         sources:,
         status:,
-        costs: nil,
+        structured_output:,
         usage: nil
       )
       end
@@ -111,7 +108,7 @@ module Handinger
             running: T::Boolean,
             sources: T::Array[Handinger::Worker::Source],
             status: Handinger::Worker::Status::TaggedSymbol,
-            costs: T.nilable(Handinger::Worker::Costs),
+            structured_output: T.nilable(T::Hash[Symbol, T.anything]),
             usage: Handinger::Worker::Usage
           }
         )
@@ -413,84 +410,12 @@ module Handinger
         end
       end
 
-      class Costs < Handinger::Internal::Type::BaseModel
-        OrHash =
-          T.type_alias do
-            T.any(Handinger::Worker::Costs, Handinger::Internal::AnyHash)
-          end
-
-        sig { returns(Float) }
-        attr_accessor :internal_cost_usd
-
-        sig { returns(Float) }
-        attr_accessor :model_cost_usd
-
-        sig { returns(Float) }
-        attr_accessor :sandbox_cost_usd
-
-        sig { returns(Float) }
-        attr_accessor :tool_cost_usd
-
-        sig do
-          params(
-            internal_cost_usd: Float,
-            model_cost_usd: Float,
-            sandbox_cost_usd: Float,
-            tool_cost_usd: Float
-          ).returns(T.attached_class)
-        end
-        def self.new(
-          internal_cost_usd:,
-          model_cost_usd:,
-          sandbox_cost_usd:,
-          tool_cost_usd:
-        )
-        end
-
-        sig do
-          override.returns(
-            {
-              internal_cost_usd: Float,
-              model_cost_usd: Float,
-              sandbox_cost_usd: Float,
-              tool_cost_usd: Float
-            }
-          )
-        end
-        def to_hash
-        end
-      end
-
       class Usage < Handinger::Internal::Type::BaseModel
         OrHash =
           T.type_alias do
             T.any(Handinger::Worker::Usage, Handinger::Internal::AnyHash)
           end
 
-        sig { returns(Integer) }
-        attr_accessor :cache_read_tokens
-
-        sig { returns(Integer) }
-        attr_accessor :cache_write_tokens
-
-        sig { returns(Float) }
-        attr_accessor :cost_usd
-
-        sig { returns(Integer) }
-        attr_accessor :input_tokens
-
-        sig { returns(Integer) }
-        attr_accessor :output_tokens
-
-        sig { returns(Integer) }
-        attr_accessor :reasoning_tokens
-
-        sig { returns(Integer) }
-        attr_accessor :steps
-
-        sig { returns(Integer) }
-        attr_accessor :total_tokens
-
         sig { returns(T.nilable(Integer)) }
         attr_reader :credits
 
@@ -504,49 +429,14 @@ module Handinger
         attr_writer :duration_ms
 
         sig do
-          params(
-            cache_read_tokens: Integer,
-            cache_write_tokens: Integer,
-            cost_usd: Float,
-            input_tokens: Integer,
-            output_tokens: Integer,
-            reasoning_tokens: Integer,
-            steps: Integer,
-            total_tokens: Integer,
-            credits: Integer,
-            duration_ms: Integer
-          ).returns(T.attached_class)
+          params(credits: Integer, duration_ms: Integer).returns(
+            T.attached_class
+          )
         end
-        def self.new(
-          cache_read_tokens:,
-          cache_write_tokens:,
-          cost_usd:,
-          input_tokens:,
-          output_tokens:,
-          reasoning_tokens:,
-          steps:,
-          total_tokens:,
-          credits: nil,
-          duration_ms: nil
-        )
+        def self.new(credits: nil, duration_ms: nil)
         end
 
-        sig do
-          override.returns(
-            {
-              cache_read_tokens: Integer,
-              cache_write_tokens: Integer,
-              cost_usd: Float,
-              input_tokens: Integer,
-              output_tokens: Integer,
-              reasoning_tokens: Integer,
-              steps: Integer,
-              total_tokens: Integer,
-              credits: Integer,
-              duration_ms: Integer
-            }
-          )
-        end
+        sig { override.returns({ credits: Integer, duration_ms: Integer }) }
         def to_hash
         end
       end

data/rbi/handinger/models/worker_create_response.rbi

@@ -0,0 +1,129 @@
+# typed: strong
+
+module Handinger
+  module Models
+    class WorkerCreateResponse < Handinger::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Handinger::Models::WorkerCreateResponse,
+            Handinger::Internal::AnyHash
+          )
+        end
+
+      sig { returns(String) }
+      attr_accessor :id
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :created_at
+
+      sig { returns(String) }
+      attr_accessor :instructions
+
+      sig { returns(String) }
+      attr_accessor :organization_id
+
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_accessor :output_schema
+
+      sig { returns(String) }
+      attr_accessor :summary
+
+      sig { returns(String) }
+      attr_accessor :title
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :updated_at
+
+      sig { returns(String) }
+      attr_accessor :user_id
+
+      sig do
+        returns(
+          Handinger::Models::WorkerCreateResponse::Visibility::TaggedSymbol
+        )
+      end
+      attr_accessor :visibility
+
+      sig do
+        params(
+          id: String,
+          created_at: T.nilable(String),
+          instructions: String,
+          organization_id: String,
+          output_schema: T.nilable(T::Hash[Symbol, T.anything]),
+          summary: String,
+          title: String,
+          updated_at: T.nilable(String),
+          user_id: String,
+          visibility:
+            Handinger::Models::WorkerCreateResponse::Visibility::OrSymbol
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        id:,
+        created_at:,
+        instructions:,
+        organization_id:,
+        output_schema:,
+        summary:,
+        title:,
+        updated_at:,
+        user_id:,
+        visibility:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: String,
+            created_at: T.nilable(String),
+            instructions: String,
+            organization_id: String,
+            output_schema: T.nilable(T::Hash[Symbol, T.anything]),
+            summary: String,
+            title: String,
+            updated_at: T.nilable(String),
+            user_id: String,
+            visibility:
+              Handinger::Models::WorkerCreateResponse::Visibility::TaggedSymbol
+          }
+        )
+      end
+      def to_hash
+      end
+
+      module Visibility
+        extend Handinger::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, Handinger::Models::WorkerCreateResponse::Visibility)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        PUBLIC =
+          T.let(
+            :public,
+            Handinger::Models::WorkerCreateResponse::Visibility::TaggedSymbol
+          )
+        PRIVATE =
+          T.let(
+            :private,
+            Handinger::Models::WorkerCreateResponse::Visibility::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              Handinger::Models::WorkerCreateResponse::Visibility::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/worker_retrieve_email_response.rbi

@@ -2,6 +2,25 @@
 
 module Handinger
   module Models
-    WorkerRetrieveEmailResponse = String
+    class WorkerRetrieveEmailResponse < Handinger::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Handinger::Models::WorkerRetrieveEmailResponse,
+            Handinger::Internal::AnyHash
+          )
+        end
+
+      sig { returns(String) }
+      attr_accessor :email
+
+      sig { params(email: String).returns(T.attached_class) }
+      def self.new(email:)
+      end
+
+      sig { override.returns({ email: String }) }
+      def to_hash
+      end
+    end
   end
 end

data/rbi/handinger/models/worker_retrieve_params.rbi

@@ -14,23 +14,31 @@ module Handinger
       sig { returns(String) }
       attr_accessor :worker_id
 
-      # Return a server-sent event stream instead of JSON.
-      sig { returns(T.nilable(T::Boolean)) }
+      # Set to "true" to receive a server-sent event stream that replays all stored
+      # messages and then continues with live chunks from the active task (if any)
+      # before closing.
+      sig do
+        returns(T.nilable(Handinger::WorkerRetrieveParams::Stream::OrSymbol))
+      end
       attr_reader :stream
 
-      sig { params(stream: T::Boolean).void }
+      sig do
+        params(stream: Handinger::WorkerRetrieveParams::Stream::OrSymbol).void
+      end
       attr_writer :stream
 
       sig do
         params(
           worker_id: String,
-          stream: T::Boolean,
+          stream: Handinger::WorkerRetrieveParams::Stream::OrSymbol,
           request_options: Handinger::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
         worker_id:,
-        # Return a server-sent event stream instead of JSON.
+        # Set to "true" to receive a server-sent event stream that replays all stored
+        # messages and then continues with live chunks from the active task (if any)
+        # before closing.
         stream: nil,
         request_options: {}
       )
@@ -40,13 +48,39 @@ module Handinger
         override.returns(
           {
             worker_id: String,
-            stream: T::Boolean,
+            stream: Handinger::WorkerRetrieveParams::Stream::OrSymbol,
             request_options: Handinger::RequestOptions
           }
         )
       end
       def to_hash
       end
+
+      # Set to "true" to receive a server-sent event stream that replays all stored
+      # messages and then continues with live chunks from the active task (if any)
+      # before closing.
+      module Stream
+        extend Handinger::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, Handinger::WorkerRetrieveParams::Stream)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        TRUE =
+          T.let(:true, Handinger::WorkerRetrieveParams::Stream::TaggedSymbol)
+        FALSE =
+          T.let(:false, Handinger::WorkerRetrieveParams::Stream::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Handinger::WorkerRetrieveParams::Stream::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
     end
   end
 end

data/rbi/handinger/models.rbi

@@ -1,21 +1,25 @@
 # typed: strong
 
 module Handinger
+  CreateTask = Handinger::Models::CreateTask
+
   CreateWorker = Handinger::Models::CreateWorker
 
-  Worker = Handinger::Models::Worker
+  Task = Handinger::Models::Task
+
+  TaskCreateParams = Handinger::Models::TaskCreateParams
+
+  TaskRetrieveParams = Handinger::Models::TaskRetrieveParams
 
-  WorkerContinueParams = Handinger::Models::WorkerContinueParams
+  TaskWithTurns = Handinger::Models::TaskWithTurns
+
+  Worker = Handinger::Models::Worker
 
   WorkerCreateParams = Handinger::Models::WorkerCreateParams
 
   WorkerRetrieveEmailParams = Handinger::Models::WorkerRetrieveEmailParams
 
-  WorkerRetrieveFileParams = Handinger::Models::WorkerRetrieveFileParams
-
   WorkerRetrieveParams = Handinger::Models::WorkerRetrieveParams
 
   Workers = Handinger::Models::Workers
-
-  WorkerStreamUpdatesParams = Handinger::Models::WorkerStreamUpdatesParams
 end

data/rbi/handinger/resources/tasks.rbi

@@ -0,0 +1,70 @@
+# typed: strong
+
+module Handinger
+  module Resources
+    # Run and inspect tasks against a worker.
+    class Tasks
+      # Run a new task against an existing worker. Send `multipart/form-data` to attach
+      # files; the bytes are bootstrapped into the worker's workspace before the task
+      # starts.
+      sig do
+        params(
+          worker_id: String,
+          instructions: String,
+          output_schema: T::Hash[Symbol, T.anything],
+          prompt: String,
+          summary: String,
+          task_id: String,
+          title: String,
+          visibility: Handinger::CreateTask::Visibility::OrSymbol,
+          request_options: Handinger::RequestOptions::OrHash
+        ).returns(Handinger::Worker)
+      end
+      def create(
+        # Worker id the task belongs to.
+        worker_id:,
+        # Persistent system prompt the worker uses for every task it runs.
+        instructions: nil,
+        # Optional JSON Schema (Draft-07) describing the structured object the worker must
+        # produce. When set, every task response is validated against the schema and
+        # exposed as `structuredOutput`.
+        output_schema: nil,
+        # Natural-language description of the worker to use for AI-generated instructions
+        # when `instructions` is omitted.
+        prompt: nil,
+        # Short one-line description of the worker's purpose. Auto-generated when omitted
+        # and a `prompt` is provided.
+        summary: nil,
+        # Optional client-provided task id. Reuse this id to add turns to an existing
+        # task.
+        task_id: nil,
+        # Optional display name. When omitted, Handinger assigns a random dog-themed name.
+        title: nil,
+        # `public` (default) is visible to all org members. `private` is only visible to
+        # invited members.
+        visibility: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a single task and its individual turns.
+      sig do
+        params(
+          task_id: String,
+          request_options: Handinger::RequestOptions::OrHash
+        ).returns(Handinger::TaskWithTurns)
+      end
+      def retrieve(
+        # Task id returned by the create task endpoint.
+        task_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Handinger::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/handinger/resources/workers.rbi

@@ -2,56 +2,63 @@
 
 module Handinger
   module Resources
+    # Create, retrieve, and manage agent worker templates.
     class Workers
       # Manage future and recurring worker tasks.
       sig { returns(Handinger::Resources::Workers::Schedules) }
       attr_reader :schedules
 
-      # Create a new agent worker and start it with the supplied instruction.
+      # Create a new worker. The worker is a reusable agent template; tasks are runs
+      # against this template. Use `POST /tasks` to actually run the agent.
       sig do
         params(
-          input: String,
-          budget: Handinger::CreateWorker::Budget::OrSymbol,
-          stream: T::Boolean,
+          instructions: String,
+          output_schema: T::Hash[Symbol, T.anything],
+          prompt: String,
+          summary: String,
+          title: String,
+          visibility: Handinger::CreateWorker::Visibility::OrSymbol,
           request_options: Handinger::RequestOptions::OrHash
-        ).returns(Handinger::Worker)
-      end
-      def create(input:, budget: nil, stream: nil, request_options: {})
-      end
-
-      # Retrieve the current worker state. Pass stream=true or request text/event-stream
-      # to subscribe to updates.
-      sig do
-        params(
-          worker_id: String,
-          stream: T::Boolean,
-          request_options: Handinger::RequestOptions::OrHash
-        ).returns(Handinger::Worker)
+        ).returns(Handinger::Models::WorkerCreateResponse)
       end
-      def retrieve(
-        # Worker id returned by the create worker endpoint.
-        worker_id,
-        # Return a server-sent event stream instead of JSON.
-        stream: nil,
+      def create(
+        # Persistent system prompt the worker uses for every task it runs.
+        instructions: nil,
+        # Optional JSON Schema (Draft-07) describing the structured object the worker must
+        # produce. When set, every task response is validated against the schema and
+        # exposed as `structuredOutput`.
+        output_schema: nil,
+        # Natural-language description of the worker to use for AI-generated instructions
+        # when `instructions` is omitted.
+        prompt: nil,
+        # Short one-line description of the worker's purpose. Auto-generated when omitted
+        # and a `prompt` is provided.
+        summary: nil,
+        # Optional display name. When omitted, Handinger assigns a random dog-themed name.
+        title: nil,
+        # `public` (default) is visible to all org members. `private` is only visible to
+        # invited members.
+        visibility: nil,
         request_options: {}
       )
       end
 
-      # Send another instruction to an existing worker.
+      # Retrieve the current worker state and messages from its most recent task.
+      # Returns a JSON worker object by default, or a server-sent event stream when
+      # `stream=true`.
       sig do
         params(
           worker_id: String,
-          input: String,
-          budget: Handinger::CreateWorker::Budget::OrSymbol,
-          stream: T::Boolean,
+          stream: Handinger::WorkerRetrieveParams::Stream::OrSymbol,
           request_options: Handinger::RequestOptions::OrHash
         ).returns(Handinger::Worker)
       end
-      def continue(
+      def retrieve(
         # Worker id returned by the create worker endpoint.
         worker_id,
-        input:,
-        budget: nil,
+        # Set to "true" to receive a server-sent event stream that replays all stored
+        # messages and then continues with live chunks from the active task (if any)
+        # before closing.
         stream: nil,
         request_options: {}
       )
@@ -62,7 +69,7 @@ module Handinger
         params(
           worker_id: String,
           request_options: Handinger::RequestOptions::OrHash
-        ).returns(String)
+        ).returns(Handinger::Models::WorkerRetrieveEmailResponse)
       end
       def retrieve_email(
         # Worker id returned by the create worker endpoint.
@@ -71,38 +78,6 @@ module Handinger
       )
       end
 
-      # Retrieve a file published from a worker workspace. The runtime route accepts
-      # nested paths after /files/.
-      sig do
-        params(
-          file_path: String,
-          worker_id: String,
-          request_options: Handinger::RequestOptions::OrHash
-        ).returns(StringIO)
-      end
-      def retrieve_file(
-        # Workspace file path after /files. URL-encode slashes for nested paths.
-        file_path,
-        # Worker id returned by the create worker endpoint.
-        worker_id:,
-        request_options: {}
-      )
-      end
-
-      # Subscribe to a worker using server-sent events.
-      sig do
-        params(
-          worker_id: String,
-          request_options: Handinger::RequestOptions::OrHash
-        ).returns(Handinger::Internal::Stream[String])
-      end
-      def stream_updates_streaming(
-        # Worker id returned by the create worker endpoint.
-        worker_id,
-        request_options: {}
-      )
-      end
-
       # @api private
       sig { params(client: Handinger::Client).returns(T.attached_class) }
       def self.new(client:)

data/sig/handinger/client.rbs

@@ -12,6 +12,8 @@ module Handinger
 
     attr_reader workers: Handinger::Resources::Workers
 
+    attr_reader tasks: Handinger::Resources::Tasks
+
     private def auth_headers: -> ::Hash[String, String]
 
     def initialize: (

data/sig/handinger/models/create_task.rbs

@@ -0,0 +1,19 @@
+module Handinger
+  module Models
+    type create_task = { worker_id: String, task_id: String }
+
+    class CreateTask < Handinger::Models::CreateWorker
+      def worker_id: -> String
+
+      def worker_id=: (String _) -> String
+
+      def task_id: -> String?
+
+      def task_id=: (String _) -> String
+
+      def initialize: (worker_id: String, ?task_id: String) -> void
+
+      def to_hash: -> { worker_id: String, task_id: String }
+    end
+  end
+end