handinger 0.1.0 → 0.2.0

data/lib/handinger/models/worker.rb

@@ -2,7 +2,7 @@
 
 module Handinger
   module Models
-    # @see Handinger::Resources::Workers#create
+    # @see Handinger::Resources::Workers#retrieve
     class Worker < Handinger::Internal::Type::BaseModel
       # @!attribute id
       #
@@ -69,17 +69,19 @@ module Handinger
       #   @return [Symbol, Handinger::Models::Worker::Status]
       required :status, enum: -> { Handinger::Worker::Status }
 
-      # @!attribute costs
+      # @!attribute structured_output
       #
-      #   @return [Handinger::Models::Worker::Costs, nil]
-      optional :costs, -> { Handinger::Worker::Costs }, nil?: true
+      #   @return [Hash{Symbol=>Object}, nil]
+      required :structured_output,
+               Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+               nil?: true
 
       # @!attribute usage
       #
       #   @return [Handinger::Models::Worker::Usage, nil]
       optional :usage, -> { Handinger::Worker::Usage }
 
-      # @!method initialize(id:, created_at:, error:, files:, incomplete_details:, messages:, metadata:, object:, output:, output_text:, running:, sources:, status:, costs: nil, usage: nil)
+      # @!method initialize(id:, created_at:, error:, files:, incomplete_details:, messages:, metadata:, object:, output:, output_text:, running:, sources:, status:, structured_output:, usage: nil)
       #   @param id [String]
       #   @param created_at [Integer, nil]
       #   @param error [nil]
@@ -93,7 +95,7 @@ module Handinger
       #   @param running [Boolean]
       #   @param sources [Array<Handinger::Models::Worker::Source>]
       #   @param status [Symbol, Handinger::Models::Worker::Status]
-      #   @param costs [Handinger::Models::Worker::Costs, nil]
+      #   @param structured_output [Hash{Symbol=>Object}, nil]
       #   @param usage [Handinger::Models::Worker::Usage]
 
       class File < Handinger::Internal::Type::BaseModel
@@ -268,77 +270,8 @@ module Handinger
         #   @return [Array<Symbol>]
       end
 
-      # @see Handinger::Models::Worker#costs
-      class Costs < Handinger::Internal::Type::BaseModel
-        # @!attribute internal_cost_usd
-        #
-        #   @return [Float]
-        required :internal_cost_usd, Float, api_name: :internalCostUsd
-
-        # @!attribute model_cost_usd
-        #
-        #   @return [Float]
-        required :model_cost_usd, Float, api_name: :modelCostUsd
-
-        # @!attribute sandbox_cost_usd
-        #
-        #   @return [Float]
-        required :sandbox_cost_usd, Float, api_name: :sandboxCostUsd
-
-        # @!attribute tool_cost_usd
-        #
-        #   @return [Float]
-        required :tool_cost_usd, Float, api_name: :toolCostUsd
-
-        # @!method initialize(internal_cost_usd:, model_cost_usd:, sandbox_cost_usd:, tool_cost_usd:)
-        #   @param internal_cost_usd [Float]
-        #   @param model_cost_usd [Float]
-        #   @param sandbox_cost_usd [Float]
-        #   @param tool_cost_usd [Float]
-      end
-
       # @see Handinger::Models::Worker#usage
       class Usage < Handinger::Internal::Type::BaseModel
-        # @!attribute cache_read_tokens
-        #
-        #   @return [Integer]
-        required :cache_read_tokens, Integer, api_name: :cacheReadTokens
-
-        # @!attribute cache_write_tokens
-        #
-        #   @return [Integer]
-        required :cache_write_tokens, Integer, api_name: :cacheWriteTokens
-
-        # @!attribute cost_usd
-        #
-        #   @return [Float]
-        required :cost_usd, Float, api_name: :costUsd
-
-        # @!attribute input_tokens
-        #
-        #   @return [Integer]
-        required :input_tokens, Integer, api_name: :inputTokens
-
-        # @!attribute output_tokens
-        #
-        #   @return [Integer]
-        required :output_tokens, Integer, api_name: :outputTokens
-
-        # @!attribute reasoning_tokens
-        #
-        #   @return [Integer]
-        required :reasoning_tokens, Integer, api_name: :reasoningTokens
-
-        # @!attribute steps
-        #
-        #   @return [Integer]
-        required :steps, Integer
-
-        # @!attribute total_tokens
-        #
-        #   @return [Integer]
-        required :total_tokens, Integer, api_name: :totalTokens
-
         # @!attribute credits
         #
         #   @return [Integer, nil]
@@ -349,15 +282,7 @@ module Handinger
         #   @return [Integer, nil]
         optional :duration_ms, Integer, api_name: :durationMs
 
-        # @!method initialize(cache_read_tokens:, cache_write_tokens:, cost_usd:, input_tokens:, output_tokens:, reasoning_tokens:, steps:, total_tokens:, credits: nil, duration_ms: nil)
-        #   @param cache_read_tokens [Integer]
-        #   @param cache_write_tokens [Integer]
-        #   @param cost_usd [Float]
-        #   @param input_tokens [Integer]
-        #   @param output_tokens [Integer]
-        #   @param reasoning_tokens [Integer]
-        #   @param steps [Integer]
-        #   @param total_tokens [Integer]
+        # @!method initialize(credits: nil, duration_ms: nil)
         #   @param credits [Integer]
         #   @param duration_ms [Integer]
       end

data/lib/handinger/models/worker_create_response.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Models
+    # @see Handinger::Resources::Workers#create
+    class WorkerCreateResponse < Handinger::Internal::Type::BaseModel
+      # @!attribute id
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute created_at
+      #
+      #   @return [String, nil]
+      required :created_at, String, api_name: :createdAt, nil?: true
+
+      # @!attribute instructions
+      #
+      #   @return [String]
+      required :instructions, String
+
+      # @!attribute organization_id
+      #
+      #   @return [String]
+      required :organization_id, String, api_name: :organizationId
+
+      # @!attribute output_schema
+      #
+      #   @return [Hash{Symbol=>Object}, nil]
+      required :output_schema,
+               Handinger::Internal::Type::HashOf[Handinger::Internal::Type::Unknown],
+               api_name: :outputSchema,
+               nil?: true
+
+      # @!attribute summary
+      #
+      #   @return [String]
+      required :summary, String
+
+      # @!attribute title
+      #
+      #   @return [String]
+      required :title, String
+
+      # @!attribute updated_at
+      #
+      #   @return [String, nil]
+      required :updated_at, String, api_name: :updatedAt, nil?: true
+
+      # @!attribute user_id
+      #
+      #   @return [String]
+      required :user_id, String, api_name: :userId
+
+      # @!attribute visibility
+      #
+      #   @return [Symbol, Handinger::Models::WorkerCreateResponse::Visibility]
+      required :visibility, enum: -> { Handinger::Models::WorkerCreateResponse::Visibility }
+
+      # @!method initialize(id:, created_at:, instructions:, organization_id:, output_schema:, summary:, title:, updated_at:, user_id:, visibility:)
+      #   @param id [String]
+      #   @param created_at [String, nil]
+      #   @param instructions [String]
+      #   @param organization_id [String]
+      #   @param output_schema [Hash{Symbol=>Object}, nil]
+      #   @param summary [String]
+      #   @param title [String]
+      #   @param updated_at [String, nil]
+      #   @param user_id [String]
+      #   @param visibility [Symbol, Handinger::Models::WorkerCreateResponse::Visibility]
+
+      # @see Handinger::Models::WorkerCreateResponse#visibility
+      module Visibility
+        extend Handinger::Internal::Type::Enum
+
+        PUBLIC = :public
+        PRIVATE = :private
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/handinger/models/worker_retrieve_email_response.rb

@@ -2,6 +2,15 @@
 
 module Handinger
   module Models
-    WorkerRetrieveEmailResponse = String
+    # @see Handinger::Resources::Workers#retrieve_email
+    class WorkerRetrieveEmailResponse < Handinger::Internal::Type::BaseModel
+      # @!attribute email
+      #
+      #   @return [String]
+      required :email, String
+
+      # @!method initialize(email:)
+      #   @param email [String]
+    end
   end
 end

data/lib/handinger/models/worker_retrieve_params.rb

@@ -13,17 +13,35 @@ module Handinger
       required :worker_id, String
 
       # @!attribute stream
-      #   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.
       #
-      #   @return [Boolean, nil]
-      optional :stream, Handinger::Internal::Type::Boolean
+      #   @return [Symbol, Handinger::Models::WorkerRetrieveParams::Stream, nil]
+      optional :stream, enum: -> { Handinger::WorkerRetrieveParams::Stream }
 
       # @!method initialize(worker_id:, stream: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Handinger::Models::WorkerRetrieveParams} for more details.
+      #
       #   @param worker_id [String]
       #
-      #   @param stream [Boolean] Return a server-sent event stream instead of JSON.
+      #   @param stream [Symbol, Handinger::Models::WorkerRetrieveParams::Stream] Set to "true" to receive a server-sent event stream that replays all stored mess
       #
       #   @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}]
+
+      # 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
+
+        TRUE = :true
+        FALSE = :false
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
     end
   end
 end

data/lib/handinger/models.rb

@@ -39,21 +39,25 @@ module Handinger
     mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
   end
 
+  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/lib/handinger/resources/tasks.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Handinger
+  module Resources
+    # Run and inspect tasks against a worker.
+    class Tasks
+      # Some parameter documentations has been truncated, see
+      # {Handinger::Models::TaskCreateParams} for more details.
+      #
+      # 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.
+      #
+      # @overload create(worker_id:, instructions: nil, output_schema: nil, prompt: nil, summary: nil, task_id: nil, title: nil, visibility: nil, request_options: {})
+      #
+      # @param worker_id [String] Worker id the task belongs to.
+      #
+      # @param instructions [String] Persistent system prompt the worker uses for every task it runs.
+      #
+      # @param output_schema [Hash{Symbol=>Object}] Optional JSON Schema (Draft-07) describing the structured object the worker must
+      #
+      # @param prompt [String] Natural-language description of the worker to use for AI-generated instructions
+      #
+      # @param summary [String] Short one-line description of the worker's purpose. Auto-generated when omitted
+      #
+      # @param task_id [String] Optional client-provided task id. Reuse this id to add turns to an existing task
+      #
+      # @param title [String] Optional display name. When omitted, Handinger assigns a random dog-themed name.
+      #
+      # @param visibility [Symbol, Handinger::Models::CreateTask::Visibility] `public` (default) is visible to all org members. `private` is only visible to i
+      #
+      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Handinger::Models::Worker]
+      #
+      # @see Handinger::Models::TaskCreateParams
+      def create(params)
+        parsed, options = Handinger::TaskCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "api/tasks",
+          body: parsed,
+          model: Handinger::Worker,
+          options: options
+        )
+      end
+
+      # Retrieve a single task and its individual turns.
+      #
+      # @overload retrieve(task_id, request_options: {})
+      #
+      # @param task_id [String] Task id returned by the create task endpoint.
+      #
+      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Handinger::Models::TaskWithTurns]
+      #
+      # @see Handinger::Models::TaskRetrieveParams
+      def retrieve(task_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["api/tasks/%1$s", task_id],
+          model: Handinger::TaskWithTurns,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Handinger::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/handinger/resources/workers.rb

@@ -2,42 +2,60 @@
 
 module Handinger
   module Resources
+    # Create, retrieve, and manage agent worker templates.
     class Workers
       # Manage future and recurring worker tasks.
       # @return [Handinger::Resources::Workers::Schedules]
       attr_reader :schedules
 
-      # Create a new agent worker and start it with the supplied instruction.
+      # Some parameter documentations has been truncated, see
+      # {Handinger::Models::WorkerCreateParams} for more details.
       #
-      # @overload create(input:, budget: nil, stream: nil, request_options: {})
+      # 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.
+      #
+      # @overload create(instructions: nil, output_schema: nil, prompt: nil, summary: nil, title: nil, visibility: nil, request_options: {})
+      #
+      # @param instructions [String] Persistent system prompt the worker uses for every task it runs.
+      #
+      # @param output_schema [Hash{Symbol=>Object}] Optional JSON Schema (Draft-07) describing the structured object the worker must
+      #
+      # @param prompt [String] Natural-language description of the worker to use for AI-generated instructions
+      #
+      # @param summary [String] Short one-line description of the worker's purpose. Auto-generated when omitted
+      #
+      # @param title [String] Optional display name. When omitted, Handinger assigns a random dog-themed name.
+      #
+      # @param visibility [Symbol, Handinger::Models::CreateWorker::Visibility] `public` (default) is visible to all org members. `private` is only visible to i
       #
-      # @param input [String]
-      # @param budget [Symbol, Handinger::Models::CreateWorker::Budget]
-      # @param stream [Boolean]
       # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Handinger::Models::Worker]
+      # @return [Handinger::Models::WorkerCreateResponse]
       #
       # @see Handinger::Models::WorkerCreateParams
-      def create(params)
+      def create(params = {})
         parsed, options = Handinger::WorkerCreateParams.dump_request(params)
         @client.request(
           method: :post,
           path: "api/workers",
           body: parsed,
-          model: Handinger::Worker,
+          model: Handinger::Models::WorkerCreateResponse,
           options: options
         )
       end
 
-      # Retrieve the current worker state. Pass stream=true or request text/event-stream
-      # to subscribe to updates.
+      # Some parameter documentations has been truncated, see
+      # {Handinger::Models::WorkerRetrieveParams} for more details.
+      #
+      # 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`.
       #
       # @overload retrieve(worker_id, stream: nil, request_options: {})
       #
       # @param worker_id [String] Worker id returned by the create worker endpoint.
       #
-      # @param stream [Boolean] Return a server-sent event stream instead of JSON.
+      # @param stream [Symbol, Handinger::Models::WorkerRetrieveParams::Stream] Set to "true" to receive a server-sent event stream that replays all stored mess
       #
       # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -56,34 +74,6 @@ module Handinger
         )
       end
 
-      # Send another instruction to an existing worker.
-      #
-      # @overload continue(worker_id, input:, budget: nil, stream: nil, request_options: {})
-      #
-      # @param worker_id [String] Worker id returned by the create worker endpoint.
-      #
-      # @param input [String]
-      #
-      # @param budget [Symbol, Handinger::Models::CreateWorker::Budget]
-      #
-      # @param stream [Boolean]
-      #
-      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
-      #
-      # @return [Handinger::Models::Worker]
-      #
-      # @see Handinger::Models::WorkerContinueParams
-      def continue(worker_id, params)
-        parsed, options = Handinger::WorkerContinueParams.dump_request(params)
-        @client.request(
-          method: :post,
-          path: ["api/workers/%1$s", worker_id],
-          body: parsed,
-          model: Handinger::Worker,
-          options: options
-        )
-      end
-
       # Retrieve the inbound email address for a worker.
       #
       # @overload retrieve_email(worker_id, request_options: {})
@@ -92,65 +82,14 @@ module Handinger
       #
       # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [String]
+      # @return [Handinger::Models::WorkerRetrieveEmailResponse]
       #
       # @see Handinger::Models::WorkerRetrieveEmailParams
       def retrieve_email(worker_id, params = {})
         @client.request(
           method: :get,
           path: ["api/workers/%1$s/email", worker_id],
-          model: String,
-          options: params[:request_options]
-        )
-      end
-
-      # Retrieve a file published from a worker workspace. The runtime route accepts
-      # nested paths after /files/.
-      #
-      # @overload retrieve_file(file_path, worker_id:, request_options: {})
-      #
-      # @param file_path [String] Workspace file path after /files. URL-encode slashes for nested paths.
-      #
-      # @param worker_id [String] Worker id returned by the create worker endpoint.
-      #
-      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
-      #
-      # @return [StringIO]
-      #
-      # @see Handinger::Models::WorkerRetrieveFileParams
-      def retrieve_file(file_path, params)
-        parsed, options = Handinger::WorkerRetrieveFileParams.dump_request(params)
-        worker_id =
-          parsed.delete(:worker_id) do
-            raise ArgumentError.new("missing required path argument #{_1}")
-          end
-        @client.request(
-          method: :get,
-          path: ["api/workers/%1$s/files/%2$s", worker_id, file_path],
-          headers: {"accept" => "application/octet-stream"},
-          model: StringIO,
-          options: options
-        )
-      end
-
-      # Subscribe to a worker using server-sent events.
-      #
-      # @overload stream_updates_streaming(worker_id, request_options: {})
-      #
-      # @param worker_id [String] Worker id returned by the create worker endpoint.
-      #
-      # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
-      #
-      # @return [Handinger::Internal::Stream<String>]
-      #
-      # @see Handinger::Models::WorkerStreamUpdatesParams
-      def stream_updates_streaming(worker_id, params = {})
-        @client.request(
-          method: :get,
-          path: ["api/workers/%1$s/stream", worker_id],
-          headers: {"accept" => "text/event-stream"},
-          stream: Handinger::Internal::Stream,
-          model: String,
+          model: Handinger::Models::WorkerRetrieveEmailResponse,
           options: params[:request_options]
         )
       end

data/lib/handinger/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Handinger
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/handinger.rb

@@ -44,7 +44,6 @@ require_relative "handinger/internal/type/array_of"
 require_relative "handinger/internal/type/hash_of"
 require_relative "handinger/internal/type/base_model"
 require_relative "handinger/internal/type/base_page"
-require_relative "handinger/internal/type/base_stream"
 require_relative "handinger/internal/type/request_parameters"
 require_relative "handinger/internal"
 require_relative "handinger/request_options"
@@ -53,14 +52,17 @@ require_relative "handinger/errors"
 require_relative "handinger/internal/transport/base_client"
 require_relative "handinger/internal/transport/pooled_net_requester"
 require_relative "handinger/client"
-require_relative "handinger/internal/stream"
 require_relative "handinger/models/create_worker"
+require_relative "handinger/models/create_task"
+require_relative "handinger/models/task"
+require_relative "handinger/models/task_create_params"
+require_relative "handinger/models/task_retrieve_params"
+require_relative "handinger/models/task_with_turns"
 require_relative "handinger/models/worker"
-require_relative "handinger/models/worker_continue_params"
 require_relative "handinger/models/worker_create_params"
+require_relative "handinger/models/worker_create_response"
 require_relative "handinger/models/worker_retrieve_email_params"
 require_relative "handinger/models/worker_retrieve_email_response"
-require_relative "handinger/models/worker_retrieve_file_params"
 require_relative "handinger/models/worker_retrieve_params"
 require_relative "handinger/models/workers/schedule_cancel_params"
 require_relative "handinger/models/workers/schedule_cancel_response"
@@ -68,8 +70,7 @@ require_relative "handinger/models/workers/schedule_create_params"
 require_relative "handinger/models/workers/schedule_list_params"
 require_relative "handinger/models/workers/schedule_list_response"
 require_relative "handinger/models/workers/worker_schedule"
-require_relative "handinger/models/worker_stream_updates_params"
-require_relative "handinger/models/worker_stream_updates_response"
 require_relative "handinger/models"
+require_relative "handinger/resources/tasks"
 require_relative "handinger/resources/workers"
 require_relative "handinger/resources/workers/schedules"

data/rbi/handinger/client.rbi

@@ -13,9 +13,14 @@ module Handinger
     sig { returns(String) }
     attr_reader :api_key
 
+    # Create, retrieve, and manage agent worker templates.
     sig { returns(Handinger::Resources::Workers) }
     attr_reader :workers
 
+    # Run and inspect tasks against a worker.
+    sig { returns(Handinger::Resources::Tasks) }
+    attr_reader :tasks
+
     # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers

data/rbi/handinger/internal/transport/base_client.rbi

@@ -49,15 +49,7 @@ module Handinger
                     ]
                   ]
                 ),
-              stream:
-                T.nilable(
-                  T::Class[
-                    Handinger::Internal::Type::BaseStream[
-                      T.anything,
-                      Handinger::Internal::Type::BaseModel
-                    ]
-                  ]
-                ),
+              stream: T.nilable(T::Class[T.anything]),
               model: T.nilable(Handinger::Internal::Type::Converter::Input),
               options: T.nilable(Handinger::RequestOptions::OrHash)
             }
@@ -277,15 +269,7 @@ module Handinger
                   ]
                 ]
               ),
-            stream:
-              T.nilable(
-                T::Class[
-                  Handinger::Internal::Type::BaseStream[
-                    T.anything,
-                    Handinger::Internal::Type::BaseModel
-                  ]
-                ]
-              ),
+            stream: T.nilable(T::Class[T.anything]),
             model: T.nilable(Handinger::Internal::Type::Converter::Input),
             options: T.nilable(Handinger::RequestOptions::OrHash)
           ).returns(T.anything)