cadenya 0.10.0 → 0.12.0

data/lib/cadenya/resources/objectives/tool_calls.rb

@@ -4,6 +4,45 @@ module Cadenya
   module Resources
     class Objectives
       class ToolCalls
+        # Retrieves a single tool call, including the content the tool returned. Media
+        # content (images, audio) is served as short-lived signed URLs.
+        #
+        # @overload retrieve(tool_call_id, workspace_id:, objective_id:, request_options: {})
+        #
+        # @param tool_call_id [String] The ID of the tool call to retrieve
+        #
+        # @param workspace_id [String]
+        #
+        # @param objective_id [String] The ID of the objective. Supports "external_id:" prefix for external IDs.
+        #
+        # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Cadenya::Models::Objectives::ObjectiveToolCallWithResult]
+        #
+        # @see Cadenya::Models::Objectives::ToolCallRetrieveParams
+        def retrieve(tool_call_id, params)
+          parsed, options = Cadenya::Objectives::ToolCallRetrieveParams.dump_request(params)
+          workspace_id =
+            parsed.delete(:workspace_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          objective_id =
+            parsed.delete(:objective_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: [
+              "v1/workspaces/%1$s/objectives/%2$s/tool_calls/%3$s",
+              workspace_id,
+              objective_id,
+              tool_call_id
+            ],
+            model: Cadenya::Objectives::ObjectiveToolCallWithResult,
+            options: options
+          )
+        end
+
         # Lists all tool calls for an objective
         #
         # @overload list(objective_id, workspace_id:, cursor: nil, include_info: nil, limit: nil, status: nil, request_options: {})

data/lib/cadenya/resources/objectives.rb

@@ -20,7 +20,7 @@ module Cadenya
       #
       # Creates a new objective in the workspace
       #
-      # @overload create(workspace_id, agent_id:, data:, initial_message: nil, memory_stack: nil, metadata: nil, secrets: nil, variation_id: nil, request_options: {})
+      # @overload create(workspace_id, agent_id:, data:, initial_message: nil, memory_stack: nil, metadata: nil, secrets: nil, user_data: nil, variation_id: nil, request_options: {})
       #
       # @param workspace_id [String]
       #
@@ -28,7 +28,7 @@ module Cadenya
       #
       # @param data [Hash{Symbol=>Object}] Arbitrary data for the objective. May be used in liquid templates for prompts co
       #
-      # @param initial_message [String] Optional override for initial message sent to the agent. This becomes the first
+      # @param initial_message [String] Optional override for the initial message sent to the agent. This becomes the fi
       #
       # @param memory_stack [Array<Cadenya::Models::MemoryReference>] Memory layers/entries to push onto this objective's memory stack on
       #
@@ -36,6 +36,8 @@ module Cadenya
       #
       # @param secrets [Array<Cadenya::Models::ObjectiveCreateParams::Secret>] Secrets that can be used in the headers for tool calls using the secret interpol
       #
+      # @param user_data [Hash{Symbol=>Object}] Arbitrary data rendered into the selected variation's user_message_template
+      #
       # @param variation_id [String] Optional explicit variation selection. Overrides the agent's variation_selection
       #
       # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]

data/lib/cadenya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cadenya
-  VERSION = "0.10.0"
+  VERSION = "0.12.0"
 end

data/lib/cadenya.rb

@@ -224,11 +224,18 @@ require_relative "cadenya/models/objectives/objective_tool"
 require_relative "cadenya/models/objectives/objective_tool_call"
 require_relative "cadenya/models/objectives/objective_tool_call_data"
 require_relative "cadenya/models/objectives/objective_tool_call_info"
+require_relative "cadenya/models/objectives/objective_tool_call_result"
+require_relative "cadenya/models/objectives/objective_tool_call_result_audio_block"
+require_relative "cadenya/models/objectives/objective_tool_call_result_content_block"
+require_relative "cadenya/models/objectives/objective_tool_call_result_image_block"
+require_relative "cadenya/models/objectives/objective_tool_call_result_text_block"
+require_relative "cadenya/models/objectives/objective_tool_call_with_result"
 require_relative "cadenya/models/objectives/task_list_params"
 require_relative "cadenya/models/objectives/task_retrieve_params"
 require_relative "cadenya/models/objectives/tool_call_approve_params"
 require_relative "cadenya/models/objectives/tool_call_deny_params"
 require_relative "cadenya/models/objectives/tool_call_list_params"
+require_relative "cadenya/models/objectives/tool_call_retrieve_params"
 require_relative "cadenya/models/objectives/tool_list_params"
 require_relative "cadenya/models/objective_secret"
 require_relative "cadenya/models/operation_metadata"

data/rbi/cadenya/models/agents/agent_schedule_spec.rbi

@@ -14,11 +14,6 @@ module Cadenya
             )
           end
 
-        # The initial message passed to CreateObjective on each fire. Becomes the first
-        # user message in the objective's chat history.
-        sig { returns(String) }
-        attr_accessor :initial_message
-
         # Schedule defines WHEN the schedule fires. Temporal-style structured form: a list
         # of calendar rules (wall-clock) and/or interval rules (duration), OR'd together.
         # At least one rule is required.
@@ -40,6 +35,15 @@ module Cadenya
         sig { params(data: T.anything).void }
         attr_writer :data
 
+        # Optional initial message passed to CreateObjective on each fire. Becomes the
+        # first user message in the objective's chat history. When unset, the fired
+        # objective defers to the selected variation's user_message_template.
+        sig { returns(T.nilable(String)) }
+        attr_reader :initial_message
+
+        sig { params(initial_message: String).void }
+        attr_writer :initial_message
+
         # What to do when the previous run is still in flight. Defaults to SKIP.
         sig do
           returns(
@@ -58,6 +62,15 @@ module Cadenya
         end
         attr_writer :overlap_policy
 
+        # Optional data rendered into the variation's user_message_template when each
+        # fired objective is created. Separate from `data`, which renders the system
+        # prompt template.
+        sig { returns(T.nilable(T.anything)) }
+        attr_reader :user_data
+
+        sig { params(user_data: T.anything).void }
+        attr_writer :user_data
+
         # Optional explicit variation. When unset, the agent's variation_selection_mode
         # chooses per fire.
         sig { returns(T.nilable(String)) }
@@ -69,18 +82,16 @@ module Cadenya
         # AgentScheduleSpec is the user-provided configuration for a schedule.
         sig do
           params(
-            initial_message: String,
             schedule: Cadenya::Agents::AgentScheduleSpecSchedule::OrHash,
             data: T.anything,
+            initial_message: String,
             overlap_policy:
               Cadenya::Agents::AgentScheduleSpec::OverlapPolicy::OrSymbol,
+            user_data: T.anything,
             variation_id: String
           ).returns(T.attached_class)
         end
         def self.new(
-          # The initial message passed to CreateObjective on each fire. Becomes the first
-          # user message in the objective's chat history.
-          initial_message:,
           # Schedule defines WHEN the schedule fires. Temporal-style structured form: a list
           # of calendar rules (wall-clock) and/or interval rules (duration), OR'd together.
           # At least one rule is required.
@@ -88,8 +99,16 @@ module Cadenya
           # Optional input data passed to the objective. If the agent has an
           # input_data_schema, this must satisfy it.
           data: nil,
+          # Optional initial message passed to CreateObjective on each fire. Becomes the
+          # first user message in the objective's chat history. When unset, the fired
+          # objective defers to the selected variation's user_message_template.
+          initial_message: nil,
           # What to do when the previous run is still in flight. Defaults to SKIP.
           overlap_policy: nil,
+          # Optional data rendered into the variation's user_message_template when each
+          # fired objective is created. Separate from `data`, which renders the system
+          # prompt template.
+          user_data: nil,
           # Optional explicit variation. When unset, the agent's variation_selection_mode
           # chooses per fire.
           variation_id: nil
@@ -99,11 +118,12 @@ module Cadenya
         sig do
           override.returns(
             {
-              initial_message: String,
               schedule: Cadenya::Agents::AgentScheduleSpecSchedule,
               data: T.anything,
+              initial_message: String,
               overlap_policy:
                 Cadenya::Agents::AgentScheduleSpec::OverlapPolicy::OrSymbol,
+              user_data: T.anything,
               variation_id: String
             }
           )

data/rbi/cadenya/models/agents/agent_variation_spec.rbi

@@ -103,12 +103,24 @@ module Cadenya
         end
         attr_writer :progressive_discovery
 
-        # The system prompt for this variation
+        # Liquid template for the system prompt of objectives using this variation.
+        # Rendered with CreateObjectiveRequest.data into Objective.system_prompt.
         sig { returns(T.nilable(String)) }
-        attr_reader :prompt
+        attr_reader :system_prompt_template
 
-        sig { params(prompt: String).void }
-        attr_writer :prompt
+        sig { params(system_prompt_template: String).void }
+        attr_writer :system_prompt_template
+
+        # Liquid template for the initial user message of objectives using this variation.
+        # Rendered with CreateObjectiveRequest.user_data and becomes the first user
+        # message in the LLM chat history. CreateObjectiveRequest.initial_message, when
+        # set, overrides the rendered result. If neither this template nor initial_message
+        # is present, objective creation is rejected with InvalidArgument.
+        sig { returns(T.nilable(String)) }
+        attr_reader :user_message_template
+
+        sig { params(user_message_template: String).void }
+        attr_writer :user_message_template
 
         # Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
         # Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0
@@ -133,7 +145,8 @@ module Cadenya
               Cadenya::Agents::AgentVariationSpecModelConfig::OrHash,
             progressive_discovery:
               Cadenya::Agents::AgentVariationSpecProgressiveDiscovery::OrHash,
-            prompt: String,
+            system_prompt_template: String,
+            user_message_template: String,
             weight: Integer
           ).returns(T.attached_class)
         end
@@ -162,8 +175,15 @@ module Cadenya
           # tool search. These are used in conjunction with the context-aware tool search
           # and can help select the best tools for the task.
           progressive_discovery: nil,
-          # The system prompt for this variation
-          prompt: nil,
+          # Liquid template for the system prompt of objectives using this variation.
+          # Rendered with CreateObjectiveRequest.data into Objective.system_prompt.
+          system_prompt_template: nil,
+          # Liquid template for the initial user message of objectives using this variation.
+          # Rendered with CreateObjectiveRequest.user_data and becomes the first user
+          # message in the LLM chat history. CreateObjectiveRequest.initial_message, when
+          # set, overrides the rendered result. If neither this template nor initial_message
+          # is present, objective creation is rejected with InvalidArgument.
+          user_message_template: nil,
           # Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
           # Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0
           # means never auto-selected, but can still be chosen explicitly via variation_id
@@ -184,7 +204,8 @@ module Cadenya
               model_config: Cadenya::Agents::AgentVariationSpecModelConfig,
               progressive_discovery:
                 Cadenya::Agents::AgentVariationSpecProgressiveDiscovery,
-              prompt: String,
+              system_prompt_template: String,
+              user_message_template: String,
               weight: Integer
             }
           )

data/rbi/cadenya/models/objective.rbi

@@ -107,6 +107,13 @@ module Cadenya
       sig { params(state_message: String).void }
       attr_writer :state_message
 
+      # Arbitrary data used to render the variation's user_message_template
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :user_data
+
+      sig { params(user_data: T::Hash[Symbol, T.anything]).void }
+      attr_writer :user_data
+
       # Objective is the data for an objective. It contains the snapshotted fields for
       # the selected agent and variation. Secrets are returned only with their names,
       # and the output definition is copied from the agent's configuration.
@@ -123,7 +130,8 @@ module Cadenya
           output: T::Hash[Symbol, T.anything],
           parent_objective_id: String,
           secrets: T::Array[Cadenya::ObjectiveSecret::OrHash],
-          state_message: String
+          state_message: String,
+          user_data: T::Hash[Symbol, T.anything]
         ).returns(T.attached_class)
       end
       def self.new(
@@ -172,7 +180,9 @@ module Cadenya
         # interpolation format.
         secrets: nil,
         # Optional human-readable detail about the current state (e.g. a failure reason).
-        state_message: nil
+        state_message: nil,
+        # Arbitrary data used to render the variation's user_message_template
+        user_data: nil
       )
       end
 
@@ -190,7 +200,8 @@ module Cadenya
             output: T::Hash[Symbol, T.anything],
             parent_objective_id: String,
             secrets: T::Array[Cadenya::ObjectiveSecret],
-            state_message: String
+            state_message: String,
+            user_data: T::Hash[Symbol, T.anything]
           }
         )
       end

data/rbi/cadenya/models/objective_create_params.rbi

@@ -22,9 +22,11 @@ module Cadenya
       sig { returns(T::Hash[Symbol, T.anything]) }
       attr_accessor :data
 
-      # Optional override for initial message sent to the agent. This becomes the first
-      # user message in the LLM chat history. The agent variation is used to set this if
-      # not present.
+      # Optional override for the initial message sent to the agent. This becomes the
+      # first user message in the LLM chat history. When not set, the selected
+      # variation's user_message_template is rendered with user_data instead. If neither
+      # this field nor a user_message_template is present, the request is rejected with
+      # InvalidArgument.
       sig { returns(T.nilable(String)) }
       attr_reader :initial_message
 
@@ -77,6 +79,15 @@ module Cadenya
       end
       attr_writer :secrets
 
+      # Arbitrary data rendered into the selected variation's user_message_template
+      # (liquid) to produce the initial user message. Separate from `data`, which
+      # renders the system prompt template.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :user_data
+
+      sig { params(user_data: T::Hash[Symbol, T.anything]).void }
+      attr_writer :user_data
+
       # Optional explicit variation selection. Overrides the agent's
       # variation_selection_mode.
       sig { returns(T.nilable(String)) }
@@ -94,6 +105,7 @@ module Cadenya
           memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
           metadata: Cadenya::CreateOperationMetadata::OrHash,
           secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash],
+          user_data: T::Hash[Symbol, T.anything],
           variation_id: String,
           request_options: Cadenya::RequestOptions::OrHash
         ).returns(T.attached_class)
@@ -104,9 +116,11 @@ module Cadenya
         # Arbitrary data for the objective. May be used in liquid templates for prompts
         # configured on the agent variation
         data:,
-        # Optional override for initial message sent to the agent. This becomes the first
-        # user message in the LLM chat history. The agent variation is used to set this if
-        # not present.
+        # Optional override for the initial message sent to the agent. This becomes the
+        # first user message in the LLM chat history. When not set, the selected
+        # variation's user_message_template is rendered with user_data instead. If neither
+        # this field nor a user_message_template is present, the request is rejected with
+        # InvalidArgument.
         initial_message: nil,
         # Memory layers/entries to push onto this objective's memory stack on top of the
         # baseline stack inherited from the selected variation.
@@ -131,6 +145,10 @@ module Cadenya
         # Secrets that can be used in the headers for tool calls using the secret
         # interpolation format.
         secrets: nil,
+        # Arbitrary data rendered into the selected variation's user_message_template
+        # (liquid) to produce the initial user message. Separate from `data`, which
+        # renders the system prompt template.
+        user_data: nil,
         # Optional explicit variation selection. Overrides the agent's
         # variation_selection_mode.
         variation_id: nil,
@@ -148,6 +166,7 @@ module Cadenya
             memory_stack: T::Array[Cadenya::MemoryReference],
             metadata: Cadenya::CreateOperationMetadata,
             secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret],
+            user_data: T::Hash[Symbol, T.anything],
             variation_id: String,
             request_options: Cadenya::RequestOptions
           }

data/rbi/cadenya/models/objectives/objective_tool_call_data.rbi

@@ -38,13 +38,6 @@ module Cadenya
         sig { params(memo: String).void }
         attr_writer :memo
 
-        # The result content returned by the tool after execution
-        sig { returns(T.nilable(String)) }
-        attr_reader :result
-
-        sig { params(result: String).void }
-        attr_writer :result
-
         # A profile identifies a user or non-human principal (such as an API key) at the
         # account level. Profiles are account-scoped and can be granted access to multiple
         # workspaces.
@@ -59,7 +52,6 @@ module Cadenya
             callable: Cadenya::CallableTool::OrHash,
             arguments: T::Hash[Symbol, T.anything],
             memo: String,
-            result: String,
             status_changed_by: Cadenya::Profile::OrHash
           ).returns(T.attached_class)
         end
@@ -73,8 +65,6 @@ module Cadenya
           arguments: nil,
           # A memo supplied by the reviewer when denying the tool call
           memo: nil,
-          # The result content returned by the tool after execution
-          result: nil,
           # A profile identifies a user or non-human principal (such as an API key) at the
           # account level. Profiles are account-scoped and can be granted access to multiple
           # workspaces.
@@ -88,7 +78,6 @@ module Cadenya
               callable: Cadenya::CallableTool,
               arguments: T::Hash[Symbol, T.anything],
               memo: String,
-              result: String,
               status_changed_by: Cadenya::Profile
             }
           )

data/rbi/cadenya/models/objectives/objective_tool_call_result.rbi

@@ -0,0 +1,54 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    ObjectiveToolCallResult = Objectives::ObjectiveToolCallResult
+
+    module Objectives
+      class ObjectiveToolCallResult < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::Objectives::ObjectiveToolCallResult,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        sig do
+          returns(
+            T::Array[Cadenya::Objectives::ObjectiveToolCallResultContentBlock]
+          )
+        end
+        attr_accessor :content
+
+        # ObjectiveToolCallResult is the content a tool returned after execution. Tools
+        # can return multiple content blocks, and blocks can be multi-modal (text, image,
+        # audio). Media blocks are stored by Cadenya and served as short-lived signed URLs
+        # rather than inline bytes.
+        sig do
+          params(
+            content:
+              T::Array[
+                Cadenya::Objectives::ObjectiveToolCallResultContentBlock::OrHash
+              ]
+          ).returns(T.attached_class)
+        end
+        def self.new(content:)
+        end
+
+        sig do
+          override.returns(
+            {
+              content:
+                T::Array[
+                  Cadenya::Objectives::ObjectiveToolCallResultContentBlock
+                ]
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/cadenya/models/objectives/objective_tool_call_result_audio_block.rbi

@@ -0,0 +1,69 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    ObjectiveToolCallResultAudioBlock =
+      Objectives::ObjectiveToolCallResultAudioBlock
+
+    module Objectives
+      class ObjectiveToolCallResultAudioBlock < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::Objectives::ObjectiveToolCallResultAudioBlock,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        # When the signed URL expires.
+        sig { returns(Time) }
+        attr_accessor :expires_at
+
+        # IANA media type of the stored audio, e.g. audio/wav.
+        sig { returns(String) }
+        attr_accessor :mime_type
+
+        # Size of the stored audio in bytes.
+        sig { returns(String) }
+        attr_accessor :size_bytes
+
+        # Short-lived signed URL to download the stored audio.
+        sig { returns(String) }
+        attr_accessor :url
+
+        sig do
+          params(
+            expires_at: Time,
+            mime_type: String,
+            size_bytes: String,
+            url: String
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # When the signed URL expires.
+          expires_at:,
+          # IANA media type of the stored audio, e.g. audio/wav.
+          mime_type:,
+          # Size of the stored audio in bytes.
+          size_bytes:,
+          # Short-lived signed URL to download the stored audio.
+          url:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              expires_at: Time,
+              mime_type: String,
+              size_bytes: String,
+              url: String
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/cadenya/models/objectives/objective_tool_call_result_content_block.rbi

@@ -0,0 +1,90 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    ObjectiveToolCallResultContentBlock =
+      Objectives::ObjectiveToolCallResultContentBlock
+
+    module Objectives
+      class ObjectiveToolCallResultContentBlock < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::Objectives::ObjectiveToolCallResultContentBlock,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        sig do
+          returns(
+            T.nilable(Cadenya::Objectives::ObjectiveToolCallResultAudioBlock)
+          )
+        end
+        attr_reader :audio
+
+        sig do
+          params(
+            audio:
+              Cadenya::Objectives::ObjectiveToolCallResultAudioBlock::OrHash
+          ).void
+        end
+        attr_writer :audio
+
+        sig do
+          returns(
+            T.nilable(Cadenya::Objectives::ObjectiveToolCallResultImageBlock)
+          )
+        end
+        attr_reader :image
+
+        sig do
+          params(
+            image:
+              Cadenya::Objectives::ObjectiveToolCallResultImageBlock::OrHash
+          ).void
+        end
+        attr_writer :image
+
+        sig do
+          returns(
+            T.nilable(Cadenya::Objectives::ObjectiveToolCallResultTextBlock)
+          )
+        end
+        attr_reader :text
+
+        sig do
+          params(
+            text: Cadenya::Objectives::ObjectiveToolCallResultTextBlock::OrHash
+          ).void
+        end
+        attr_writer :text
+
+        # ContentBlock is a single block of tool result content. Exactly one of the
+        # variants is set.
+        sig do
+          params(
+            audio:
+              Cadenya::Objectives::ObjectiveToolCallResultAudioBlock::OrHash,
+            image:
+              Cadenya::Objectives::ObjectiveToolCallResultImageBlock::OrHash,
+            text: Cadenya::Objectives::ObjectiveToolCallResultTextBlock::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(audio: nil, image: nil, text: nil)
+        end
+
+        sig do
+          override.returns(
+            {
+              audio: Cadenya::Objectives::ObjectiveToolCallResultAudioBlock,
+              image: Cadenya::Objectives::ObjectiveToolCallResultImageBlock,
+              text: Cadenya::Objectives::ObjectiveToolCallResultTextBlock
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end