handinger 0.1.0 → 0.3.0

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::WorkerTemplate]
       #
       # @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::WorkerTemplate,
           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,101 +74,81 @@ module Handinger
         )
       end
 
-      # Send another instruction to an existing worker.
+      # Some parameter documentations has been truncated, see
+      # {Handinger::Models::WorkerUpdateParams} for more details.
+      #
+      # Update a worker's instructions, title, summary, visibility, or output schema.
+      # Only the fields you send are changed; omitted fields keep their current values.
+      # Only the worker creator can update a worker.
       #
-      # @overload continue(worker_id, input:, budget: nil, stream: nil, request_options: {})
+      # @overload update(worker_id, instructions: nil, output_schema: nil, summary: nil, title: nil, visibility: nil, request_options: {})
       #
       # @param worker_id [String] Worker id returned by the create worker endpoint.
       #
-      # @param input [String]
+      # @param instructions [String] Replaces the persistent system prompt. Subsequent tasks pick up the new instruct
       #
-      # @param budget [Symbol, Handinger::Models::CreateWorker::Budget]
+      # @param output_schema [Hash{Symbol=>Object}, nil] Replace the worker's structured output schema. Pass `null` to clear it and retur
       #
-      # @param stream [Boolean]
+      # @param summary [String] Replaces the worker's short one-line summary.
+      #
+      # @param title [String] New display name for the worker.
+      #
+      # @param visibility [Symbol, Handinger::Models::UpdateWorker::Visibility] Change visibility between `public` (any org member can run tasks) and `private`
       #
       # @param request_options [Handinger::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Handinger::Models::Worker]
+      # @return [Handinger::Models::WorkerTemplate]
       #
-      # @see Handinger::Models::WorkerContinueParams
-      def continue(worker_id, params)
-        parsed, options = Handinger::WorkerContinueParams.dump_request(params)
+      # @see Handinger::Models::WorkerUpdateParams
+      def update(worker_id, params = {})
+        parsed, options = Handinger::WorkerUpdateParams.dump_request(params)
         @client.request(
-          method: :post,
+          method: :patch,
           path: ["api/workers/%1$s", worker_id],
           body: parsed,
-          model: Handinger::Worker,
+          model: Handinger::WorkerTemplate,
           options: options
         )
       end
 
-      # Retrieve the inbound email address for a worker.
+      # Permanently delete a worker template along with its tasks, turns, files,
+      # schedules, and integrations. This action is not reversible. Only the worker
+      # creator can delete a worker.
       #
-      # @overload retrieve_email(worker_id, request_options: {})
+      # @overload delete(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 [String]
+      # @return [Handinger::Models::DeleteWorkerResponse]
       #
-      # @see Handinger::Models::WorkerRetrieveEmailParams
-      def retrieve_email(worker_id, params = {})
+      # @see Handinger::Models::WorkerDeleteParams
+      def delete(worker_id, params = {})
         @client.request(
-          method: :get,
-          path: ["api/workers/%1$s/email", worker_id],
-          model: String,
+          method: :delete,
+          path: ["api/workers/%1$s", worker_id],
+          model: Handinger::DeleteWorkerResponse,
           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.
+      # Retrieve the inbound email address for a worker.
       #
-      # @overload stream_updates_streaming(worker_id, request_options: {})
+      # @overload retrieve_email(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>]
+      # @return [Handinger::Models::WorkerRetrieveEmailResponse]
       #
-      # @see Handinger::Models::WorkerStreamUpdatesParams
-      def stream_updates_streaming(worker_id, params = {})
+      # @see Handinger::Models::WorkerRetrieveEmailParams
+      def retrieve_email(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,
+          path: ["api/workers/%1$s/email", worker_id],
+          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.3.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,21 @@ 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/update_worker"
+require_relative "handinger/models/delete_task_response"
+require_relative "handinger/models/delete_worker_response"
+require_relative "handinger/models/task"
+require_relative "handinger/models/task_create_params"
+require_relative "handinger/models/task_delete_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_delete_params"
 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 +74,9 @@ 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/worker_template"
+require_relative "handinger/models/worker_update_params"
 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)

data/rbi/handinger/models/create_task.rbi

@@ -0,0 +1,40 @@
+# typed: strong
+
+module Handinger
+  module Models
+    class CreateTask < Handinger::Models::CreateWorker
+      OrHash =
+        T.type_alias do
+          T.any(Handinger::CreateTask, Handinger::Internal::AnyHash)
+        end
+
+      # Worker id the task belongs to.
+      sig { returns(String) }
+      attr_accessor :worker_id
+
+      # Optional client-provided task id. Reuse this id to add turns to an existing
+      # task.
+      sig { returns(T.nilable(String)) }
+      attr_reader :task_id
+
+      sig { params(task_id: String).void }
+      attr_writer :task_id
+
+      sig do
+        params(worker_id: String, task_id: String).returns(T.attached_class)
+      end
+      def self.new(
+        # Worker id the task belongs to.
+        worker_id:,
+        # Optional client-provided task id. Reuse this id to add turns to an existing
+        # task.
+        task_id: nil
+      )
+      end
+
+      sig { override.returns({ worker_id: String, task_id: String }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/handinger/models/create_worker.rbi

@@ -8,60 +8,118 @@ module Handinger
           T.any(Handinger::CreateWorker, Handinger::Internal::AnyHash)
         end
 
-      sig { returns(String) }
-      attr_accessor :input
+      # Persistent system prompt the worker uses for every task it runs.
+      sig { returns(T.nilable(String)) }
+      attr_reader :instructions
 
-      sig { returns(T.nilable(Handinger::CreateWorker::Budget::OrSymbol)) }
-      attr_reader :budget
+      sig { params(instructions: String).void }
+      attr_writer :instructions
 
-      sig { params(budget: Handinger::CreateWorker::Budget::OrSymbol).void }
-      attr_writer :budget
+      # 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`.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :output_schema
 
-      sig { returns(T.nilable(T::Boolean)) }
-      attr_reader :stream
+      sig { params(output_schema: T::Hash[Symbol, T.anything]).void }
+      attr_writer :output_schema
 
-      sig { params(stream: T::Boolean).void }
-      attr_writer :stream
+      # Natural-language description of the worker to use for AI-generated instructions
+      # when `instructions` is omitted.
+      sig { returns(T.nilable(String)) }
+      attr_reader :prompt
+
+      sig { params(prompt: String).void }
+      attr_writer :prompt
+
+      # Short one-line description of the worker's purpose. Auto-generated when omitted
+      # and a `prompt` is provided.
+      sig { returns(T.nilable(String)) }
+      attr_reader :summary
+
+      sig { params(summary: String).void }
+      attr_writer :summary
+
+      # Optional display name. When omitted, Handinger assigns a random dog-themed name.
+      sig { returns(T.nilable(String)) }
+      attr_reader :title
+
+      sig { params(title: String).void }
+      attr_writer :title
+
+      # `public` (default) is visible to all org members. `private` is only visible to
+      # invited members.
+      sig { returns(T.nilable(Handinger::CreateWorker::Visibility::OrSymbol)) }
+      attr_reader :visibility
+
+      sig do
+        params(visibility: Handinger::CreateWorker::Visibility::OrSymbol).void
+      end
+      attr_writer :visibility
 
       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
         ).returns(T.attached_class)
       end
-      def self.new(input:, budget: nil, stream: nil)
+      def self.new(
+        # 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
+      )
       end
 
       sig do
         override.returns(
           {
-            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
           }
         )
       end
       def to_hash
       end
 
-      module Budget
+      # `public` (default) is visible to all org members. `private` is only visible to
+      # invited members.
+      module Visibility
         extend Handinger::Internal::Type::Enum
 
         TaggedSymbol =
-          T.type_alias { T.all(Symbol, Handinger::CreateWorker::Budget) }
+          T.type_alias { T.all(Symbol, Handinger::CreateWorker::Visibility) }
         OrSymbol = T.type_alias { T.any(Symbol, String) }
 
-        LOW = T.let(:low, Handinger::CreateWorker::Budget::TaggedSymbol)
-        STANDARD =
-          T.let(:standard, Handinger::CreateWorker::Budget::TaggedSymbol)
-        HIGH = T.let(:high, Handinger::CreateWorker::Budget::TaggedSymbol)
-        UNLIMITED =
-          T.let(:unlimited, Handinger::CreateWorker::Budget::TaggedSymbol)
+        PUBLIC =
+          T.let(:public, Handinger::CreateWorker::Visibility::TaggedSymbol)
+        PRIVATE =
+          T.let(:private, Handinger::CreateWorker::Visibility::TaggedSymbol)
 
         sig do
           override.returns(
-            T::Array[Handinger::CreateWorker::Budget::TaggedSymbol]
+            T::Array[Handinger::CreateWorker::Visibility::TaggedSymbol]
           )
         end
         def self.values

data/rbi/handinger/models/delete_task_response.rbi

@@ -0,0 +1,23 @@
+# typed: strong
+
+module Handinger
+  module Models
+    class DeleteTaskResponse < Handinger::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Handinger::DeleteTaskResponse, Handinger::Internal::AnyHash)
+        end
+
+      sig { returns(T::Boolean) }
+      attr_accessor :archived
+
+      sig { params(archived: T::Boolean).returns(T.attached_class) }
+      def self.new(archived:)
+      end
+
+      sig { override.returns({ archived: T::Boolean }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/handinger/models/delete_worker_response.rbi

@@ -0,0 +1,23 @@
+# typed: strong
+
+module Handinger
+  module Models
+    class DeleteWorkerResponse < Handinger::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Handinger::DeleteWorkerResponse, Handinger::Internal::AnyHash)
+        end
+
+      sig { returns(T::Boolean) }
+      attr_accessor :deleted
+
+      sig { params(deleted: T::Boolean).returns(T.attached_class) }
+      def self.new(deleted:)
+      end
+
+      sig { override.returns({ deleted: T::Boolean }) }
+      def to_hash
+      end
+    end
+  end
+end