handinger 0.1.0 → 0.3.0

data/rbi/handinger/models/{worker_stream_updates_params.rbi → worker_delete_params.rbi}

@@ -2,16 +2,13 @@
 
 module Handinger
   module Models
-    class WorkerStreamUpdatesParams < Handinger::Internal::Type::BaseModel
+    class WorkerDeleteParams < Handinger::Internal::Type::BaseModel
       extend Handinger::Internal::Type::RequestParameters::Converter
       include Handinger::Internal::Type::RequestParameters
 
       OrHash =
         T.type_alias do
-          T.any(
-            Handinger::WorkerStreamUpdatesParams,
-            Handinger::Internal::AnyHash
-          )
+          T.any(Handinger::WorkerDeleteParams, Handinger::Internal::AnyHash)
         end
 
       sig { returns(String) }

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/worker_template.rbi

@@ -0,0 +1,110 @@
+# typed: strong
+
+module Handinger
+  module Models
+    class WorkerTemplate < Handinger::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Handinger::WorkerTemplate, 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 { returns(Handinger::WorkerTemplate::Visibility::TaggedSymbol) }
+      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::WorkerTemplate::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::WorkerTemplate::Visibility::TaggedSymbol
+          }
+        )
+      end
+      def to_hash
+      end
+
+      module Visibility
+        extend Handinger::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Handinger::WorkerTemplate::Visibility) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        PUBLIC =
+          T.let(:public, Handinger::WorkerTemplate::Visibility::TaggedSymbol)
+        PRIVATE =
+          T.let(:private, Handinger::WorkerTemplate::Visibility::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Handinger::WorkerTemplate::Visibility::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/handinger/models/{worker_continue_params.rbi → worker_update_params.rbi}

@@ -2,13 +2,13 @@
 
 module Handinger
   module Models
-    class WorkerContinueParams < Handinger::Models::CreateWorker
+    class WorkerUpdateParams < Handinger::Models::UpdateWorker
       extend Handinger::Internal::Type::RequestParameters::Converter
       include Handinger::Internal::Type::RequestParameters
 
       OrHash =
         T.type_alias do
-          T.any(Handinger::WorkerContinueParams, Handinger::Internal::AnyHash)
+          T.any(Handinger::WorkerUpdateParams, Handinger::Internal::AnyHash)
         end
 
       sig { returns(String) }

data/rbi/handinger/models.rbi

@@ -1,21 +1,39 @@
 # typed: strong
 
 module Handinger
+  CreateTask = Handinger::Models::CreateTask
+
   CreateWorker = Handinger::Models::CreateWorker
 
-  Worker = Handinger::Models::Worker
+  DeleteTaskResponse = Handinger::Models::DeleteTaskResponse
+
+  DeleteWorkerResponse = Handinger::Models::DeleteWorkerResponse
+
+  Task = Handinger::Models::Task
+
+  TaskCreateParams = Handinger::Models::TaskCreateParams
+
+  TaskDeleteParams = Handinger::Models::TaskDeleteParams
+
+  TaskRetrieveParams = Handinger::Models::TaskRetrieveParams
 
-  WorkerContinueParams = Handinger::Models::WorkerContinueParams
+  TaskWithTurns = Handinger::Models::TaskWithTurns
+
+  UpdateWorker = Handinger::Models::UpdateWorker
+
+  Worker = Handinger::Models::Worker
 
   WorkerCreateParams = Handinger::Models::WorkerCreateParams
 
-  WorkerRetrieveEmailParams = Handinger::Models::WorkerRetrieveEmailParams
+  WorkerDeleteParams = Handinger::Models::WorkerDeleteParams
 
-  WorkerRetrieveFileParams = Handinger::Models::WorkerRetrieveFileParams
+  WorkerRetrieveEmailParams = Handinger::Models::WorkerRetrieveEmailParams
 
   WorkerRetrieveParams = Handinger::Models::WorkerRetrieveParams
 
   Workers = Handinger::Models::Workers
 
-  WorkerStreamUpdatesParams = Handinger::Models::WorkerStreamUpdatesParams
+  WorkerTemplate = Handinger::Models::WorkerTemplate
+
+  WorkerUpdateParams = Handinger::Models::WorkerUpdateParams
 end

data/rbi/handinger/resources/tasks.rbi

@@ -0,0 +1,86 @@
+# typed: strong
+
+module Handinger
+  module Resources
+    # Run and inspect tasks against a worker.
+    class Tasks
+      # Run a new task against an existing worker. Send a `taskId` of a prior task to
+      # add a follow-up turn instead of starting a fresh task. 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
+
+      # Archive a task so it stops appearing in `GET /tasks` results. Turns and files
+      # are retained for audit purposes. Only the worker creator can archive a task.
+      sig do
+        params(
+          task_id: String,
+          request_options: Handinger::RequestOptions::OrHash
+        ).returns(Handinger::DeleteTaskResponse)
+      end
+      def delete(
+        # 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,101 +2,126 @@
 
 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::WorkerTemplate)
       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: {}
       )
       end
 
-      # Retrieve the inbound email address for a worker.
+      # 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.
       sig do
         params(
           worker_id: String,
+          instructions: String,
+          output_schema: T.nilable(T::Hash[Symbol, T.anything]),
+          summary: String,
+          title: String,
+          visibility: Handinger::UpdateWorker::Visibility::OrSymbol,
           request_options: Handinger::RequestOptions::OrHash
-        ).returns(String)
+        ).returns(Handinger::WorkerTemplate)
       end
-      def retrieve_email(
+      def update(
         # Worker id returned by the create worker endpoint.
         worker_id,
+        # Replaces the persistent system prompt. Subsequent tasks pick up the new
+        # instructions immediately; in-flight tasks keep using the previous version.
+        instructions: nil,
+        # Replace the worker's structured output schema. Pass `null` to clear it and
+        # return to free-form text responses.
+        output_schema: nil,
+        # Replaces the worker's short one-line summary.
+        summary: nil,
+        # New display name for the worker.
+        title: nil,
+        # Change visibility between `public` (any org member can run tasks) and `private`
+        # (only invited members).
+        visibility: nil,
         request_options: {}
       )
       end
 
-      # Retrieve a file published from a worker workspace. The runtime route accepts
-      # nested paths after /files/.
+      # 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.
       sig do
         params(
-          file_path: String,
           worker_id: String,
           request_options: Handinger::RequestOptions::OrHash
-        ).returns(StringIO)
+        ).returns(Handinger::DeleteWorkerResponse)
       end
-      def retrieve_file(
-        # Workspace file path after /files. URL-encode slashes for nested paths.
-        file_path,
+      def delete(
         # Worker id returned by the create worker endpoint.
-        worker_id:,
+        worker_id,
         request_options: {}
       )
       end
 
-      # Subscribe to a worker using server-sent events.
+      # Retrieve the inbound email address for a worker.
       sig do
         params(
           worker_id: String,
           request_options: Handinger::RequestOptions::OrHash
-        ).returns(Handinger::Internal::Stream[String])
+        ).returns(Handinger::Models::WorkerRetrieveEmailResponse)
       end
-      def stream_updates_streaming(
+      def retrieve_email(
         # Worker id returned by the create worker endpoint.
         worker_id,
         request_options: {}

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

data/sig/handinger/models/create_worker.rbs

@@ -2,47 +2,68 @@ module Handinger
   module Models
     type create_worker =
       {
-        input: String,
-        budget: Handinger::Models::CreateWorker::budget,
-        stream: bool
+        instructions: String,
+        output_schema: ::Hash[Symbol, top],
+        prompt: String,
+        summary: String,
+        title: String,
+        visibility: Handinger::Models::CreateWorker::visibility
       }
 
     class CreateWorker < Handinger::Internal::Type::BaseModel
-      attr_accessor input: String
+      attr_reader instructions: String?
 
-      attr_reader budget: Handinger::Models::CreateWorker::budget?
+      def instructions=: (String) -> String
 
-      def budget=: (
-        Handinger::Models::CreateWorker::budget
-      ) -> Handinger::Models::CreateWorker::budget
+      attr_reader output_schema: ::Hash[Symbol, top]?
 
-      attr_reader stream: bool?
+      def output_schema=: (::Hash[Symbol, top]) -> ::Hash[Symbol, top]
 
-      def stream=: (bool) -> bool
+      attr_reader prompt: String?
+
+      def prompt=: (String) -> String
+
+      attr_reader summary: String?
+
+      def summary=: (String) -> String
+
+      attr_reader title: String?
+
+      def title=: (String) -> String
+
+      attr_reader visibility: Handinger::Models::CreateWorker::visibility?
+
+      def visibility=: (
+        Handinger::Models::CreateWorker::visibility
+      ) -> Handinger::Models::CreateWorker::visibility
 
       def initialize: (
-        input: String,
-        ?budget: Handinger::Models::CreateWorker::budget,
-        ?stream: bool
+        ?instructions: String,
+        ?output_schema: ::Hash[Symbol, top],
+        ?prompt: String,
+        ?summary: String,
+        ?title: String,
+        ?visibility: Handinger::Models::CreateWorker::visibility
       ) -> void
 
       def to_hash: -> {
-        input: String,
-        budget: Handinger::Models::CreateWorker::budget,
-        stream: bool
+        instructions: String,
+        output_schema: ::Hash[Symbol, top],
+        prompt: String,
+        summary: String,
+        title: String,
+        visibility: Handinger::Models::CreateWorker::visibility
       }
 
-      type budget = :low | :standard | :high | :unlimited
+      type visibility = :public | :private
 
-      module Budget
+      module Visibility
         extend Handinger::Internal::Type::Enum
 
-        LOW: :low
-        STANDARD: :standard
-        HIGH: :high
-        UNLIMITED: :unlimited
+        PUBLIC: :public
+        PRIVATE: :private
 
-        def self?.values: -> ::Array[Handinger::Models::CreateWorker::budget]
+        def self?.values: -> ::Array[Handinger::Models::CreateWorker::visibility]
       end
     end
   end