cadenya 0.8.0 → 0.9.0

data/lib/cadenya/resources/objectives.rb

@@ -20,16 +20,22 @@ module Cadenya
       #
       # Creates a new objective in the workspace
       #
-      # @overload create(workspace_id, agent_id:, data:, metadata: nil, variation_id: nil, request_options: {})
+      # @overload create(workspace_id, agent_id:, data:, initial_message: nil, memory_stack: nil, metadata: nil, secrets: nil, variation_id: nil, request_options: {})
       #
       # @param workspace_id [String]
       #
       # @param agent_id [String]
       #
-      # @param data [Cadenya::Models::ObjectiveData]
+      # @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 memory_stack [Array<Cadenya::Models::MemoryReference>] Memory layers/entries to push onto this objective's memory stack on
       #
       # @param metadata [Cadenya::Models::CreateOperationMetadata] CreateOperationMetadata contains the user-provided fields for creating
       #
+      # @param secrets [Array<Cadenya::Models::ObjectiveCreateParams::Secret>] Secrets that can be used in the headers for tool calls using the secret interpol
+      #
       # @param variation_id [String] Optional explicit variation selection. Overrides the agent's variation_selection
       #
       # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
@@ -152,7 +158,7 @@ module Cadenya
           end
         @client.request(
           method: :post,
-          path: ["v1/workspaces/%1$s/objectives/%2$s/cancel", workspace_id, objective_id],
+          path: ["v1/workspaces/%1$s/objectives/%2$s:cancel", workspace_id, objective_id],
           body: parsed,
           model: Cadenya::Objective,
           options: options
@@ -186,7 +192,7 @@ module Cadenya
           end
         @client.request(
           method: :post,
-          path: ["v1/workspaces/%1$s/objectives/%2$s/compact", workspace_id, objective_id],
+          path: ["v1/workspaces/%1$s/objectives/%2$s:compact", workspace_id, objective_id],
           body: parsed,
           model: Cadenya::Models::ObjectiveCompactResponse,
           options: options
@@ -223,7 +229,7 @@ module Cadenya
           end
         @client.request(
           method: :post,
-          path: ["v1/workspaces/%1$s/objectives/%2$s/continue", workspace_id, objective_id],
+          path: ["v1/workspaces/%1$s/objectives/%2$s:continue", workspace_id, objective_id],
           body: parsed,
           model: Cadenya::Models::ObjectiveContinueResponse,
           options: options

data/lib/cadenya/version.rb

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

data/lib/cadenya.rb

@@ -189,13 +189,12 @@ require_relative "cadenya/models/objective"
 require_relative "cadenya/models/objective_cancel_params"
 require_relative "cadenya/models/objective_compact_params"
 require_relative "cadenya/models/objective_compact_response"
+require_relative "cadenya/models/objective_config_snapshot"
 require_relative "cadenya/models/objective_context_window"
 require_relative "cadenya/models/objective_context_window_data"
 require_relative "cadenya/models/objective_continue_params"
 require_relative "cadenya/models/objective_continue_response"
 require_relative "cadenya/models/objective_create_params"
-require_relative "cadenya/models/objective_data"
-require_relative "cadenya/models/objective_data_secret"
 require_relative "cadenya/models/objective_error"
 require_relative "cadenya/models/objective_event_data"
 require_relative "cadenya/models/objective_event_info"
@@ -223,7 +222,7 @@ 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_list_params"
-require_relative "cadenya/models/objective_status"
+require_relative "cadenya/models/objective_secret"
 require_relative "cadenya/models/operation_metadata"
 require_relative "cadenya/models/page"
 require_relative "cadenya/models/profile"

data/rbi/cadenya/models/objective.rbi

@@ -6,11 +6,10 @@ module Cadenya
       OrHash =
         T.type_alias { T.any(Cadenya::Objective, Cadenya::Internal::AnyHash) }
 
-      sig { returns(Cadenya::ObjectiveData) }
-      attr_reader :data
-
-      sig { params(data: Cadenya::ObjectiveData::OrHash).void }
-      attr_writer :data
+      # The initial message sent to the agent. This becomes the first user message in
+      # the LLM chat history.
+      sig { returns(String) }
+      attr_accessor :initial_message
 
       # Metadata for ephemeral operations and activities (e.g., objectives, executions,
       # runs)
@@ -20,11 +19,61 @@ module Cadenya
       sig { params(metadata: Cadenya::OperationMetadata::OrHash).void }
       attr_writer :metadata
 
-      sig { returns(Cadenya::ObjectiveStatus) }
-      attr_reader :status
+      # Memory layers/entries to push onto this objective's memory stack on top of the
+      # baseline stack inherited from the selected variation.
+      #
+      # Array order is push order: the first element sits lower in the objective's
+      # contribution to the stack; the LAST element ends up on top of the effective
+      # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
+      # position.
+      #
+      # System-managed layers (e.g., episodic) cannot be referenced here; they attach
+      # themselves automatically based on episodic_key.
+      #
+      # Stack size cap: the TOTAL effective stack (variation's memory layers
+      #
+      # - this field) must not exceed 10 entries. A request that would produce an
+      #   effective stack larger than 10 is rejected with InvalidArgument.
+      sig { returns(T.nilable(T::Array[Cadenya::MemoryReference])) }
+      attr_reader :memory_stack
+
+      sig do
+        params(memory_stack: T::Array[Cadenya::MemoryReference::OrHash]).void
+      end
+      attr_writer :memory_stack
+
+      # Secrets that can be used in the headers for tool calls using the secret
+      # interpolation format.
+      sig { returns(T.nilable(T::Array[Cadenya::ObjectiveSecret])) }
+      attr_reader :secrets
+
+      sig { params(secrets: T::Array[Cadenya::ObjectiveSecret::OrHash]).void }
+      attr_writer :secrets
 
-      sig { params(status: Cadenya::ObjectiveStatus::OrHash).void }
-      attr_writer :status
+      # ObjectiveConfigSnapshot is the point-in-time snapshot of the agent, variation,
+      # and (when applicable) schedule that an objective was started with.
+      sig { returns(Cadenya::ObjectiveConfigSnapshot) }
+      attr_reader :config_snapshot
+
+      sig do
+        params(config_snapshot: Cadenya::ObjectiveConfigSnapshot::OrHash).void
+      end
+      attr_writer :config_snapshot
+
+      # The current lifecycle state of the objective.
+      sig { returns(Cadenya::Objective::State::TaggedSymbol) }
+      attr_accessor :state
+
+      # system_prompt is read-only, derived from the selected variation's prompt
+      sig { returns(String) }
+      attr_accessor :system_prompt
+
+      # Arbitrary data for the objective
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :data
+
+      sig { params(data: T::Hash[Symbol, T.anything]).void }
+      attr_writer :data
 
       # ObjectiveInfo provides read-only aggregated statistics about an objective's
       # execution
@@ -34,57 +83,148 @@ module Cadenya
       sig { params(info: Cadenya::ObjectiveInfo::OrHash).void }
       attr_writer :info
 
-      # Read-only list of the last five windows of execution for this objective, ordered
-      # by most recent first. Is only included in singular RPC calls (GetObjective, for
-      # example).
-      sig { returns(T.nilable(T::Array[Cadenya::ObjectiveContextWindow])) }
-      attr_reader :last_five_windows
+      # The output of the objective, populated when the objective completes. Will match
+      # the schema of output_json_schema or output_json_inferred. This will only be set
+      # if the state of the objective is set to STATE_FINALIZED
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :output
 
-      sig do
-        params(
-          last_five_windows: T::Array[Cadenya::ObjectiveContextWindow::OrHash]
-        ).void
-      end
-      attr_writer :last_five_windows
+      sig { params(output: T::Hash[Symbol, T.anything]).void }
+      attr_writer :output
+
+      # A parent objective means the objective was spawned off using a separate agent to
+      # complete an objective
+      sig { returns(T.nilable(String)) }
+      attr_reader :parent_objective_id
+
+      sig { params(parent_objective_id: String).void }
+      attr_writer :parent_objective_id
 
+      # Optional human-readable detail about the current state (e.g. a failure reason).
+      sig { returns(T.nilable(String)) }
+      attr_reader :state_message
+
+      sig { params(state_message: String).void }
+      attr_writer :state_message
+
+      # 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.
       sig do
         params(
-          data: Cadenya::ObjectiveData::OrHash,
+          config_snapshot: Cadenya::ObjectiveConfigSnapshot::OrHash,
+          initial_message: String,
           metadata: Cadenya::OperationMetadata::OrHash,
-          status: Cadenya::ObjectiveStatus::OrHash,
+          state: Cadenya::Objective::State::OrSymbol,
+          system_prompt: String,
+          data: T::Hash[Symbol, T.anything],
           info: Cadenya::ObjectiveInfo::OrHash,
-          last_five_windows: T::Array[Cadenya::ObjectiveContextWindow::OrHash]
+          memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
+          output: T::Hash[Symbol, T.anything],
+          parent_objective_id: String,
+          secrets: T::Array[Cadenya::ObjectiveSecret::OrHash],
+          state_message: String
         ).returns(T.attached_class)
       end
       def self.new(
-        data:,
+        # ObjectiveConfigSnapshot is the point-in-time snapshot of the agent, variation,
+        # and (when applicable) schedule that an objective was started with.
+        config_snapshot:,
+        # The initial message sent to the agent. This becomes the first user message in
+        # the LLM chat history.
+        initial_message:,
         # Metadata for ephemeral operations and activities (e.g., objectives, executions,
         # runs)
         metadata:,
-        status:,
+        # The current lifecycle state of the objective.
+        state:,
+        # system_prompt is read-only, derived from the selected variation's prompt
+        system_prompt:,
+        # Arbitrary data for the objective
+        data: nil,
         # ObjectiveInfo provides read-only aggregated statistics about an objective's
         # execution
         info: nil,
-        # Read-only list of the last five windows of execution for this objective, ordered
-        # by most recent first. Is only included in singular RPC calls (GetObjective, for
-        # example).
-        last_five_windows: nil
+        # Memory layers/entries to push onto this objective's memory stack on top of the
+        # baseline stack inherited from the selected variation.
+        #
+        # Array order is push order: the first element sits lower in the objective's
+        # contribution to the stack; the LAST element ends up on top of the effective
+        # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
+        # position.
+        #
+        # System-managed layers (e.g., episodic) cannot be referenced here; they attach
+        # themselves automatically based on episodic_key.
+        #
+        # Stack size cap: the TOTAL effective stack (variation's memory layers
+        #
+        # - this field) must not exceed 10 entries. A request that would produce an
+        #   effective stack larger than 10 is rejected with InvalidArgument.
+        memory_stack: nil,
+        # The output of the objective, populated when the objective completes. Will match
+        # the schema of output_json_schema or output_json_inferred. This will only be set
+        # if the state of the objective is set to STATE_FINALIZED
+        output: nil,
+        # A parent objective means the objective was spawned off using a separate agent to
+        # complete an objective
+        parent_objective_id: nil,
+        # Secrets that can be used in the headers for tool calls using the secret
+        # interpolation format.
+        secrets: nil,
+        # Optional human-readable detail about the current state (e.g. a failure reason).
+        state_message: nil
       )
       end
 
       sig do
         override.returns(
           {
-            data: Cadenya::ObjectiveData,
+            config_snapshot: Cadenya::ObjectiveConfigSnapshot,
+            initial_message: String,
             metadata: Cadenya::OperationMetadata,
-            status: Cadenya::ObjectiveStatus,
+            state: Cadenya::Objective::State::TaggedSymbol,
+            system_prompt: String,
+            data: T::Hash[Symbol, T.anything],
             info: Cadenya::ObjectiveInfo,
-            last_five_windows: T::Array[Cadenya::ObjectiveContextWindow]
+            memory_stack: T::Array[Cadenya::MemoryReference],
+            output: T::Hash[Symbol, T.anything],
+            parent_objective_id: String,
+            secrets: T::Array[Cadenya::ObjectiveSecret],
+            state_message: String
           }
         )
       end
       def to_hash
       end
+
+      # The current lifecycle state of the objective.
+      module State
+        extend Cadenya::Internal::Type::Enum
+
+        TaggedSymbol = T.type_alias { T.all(Symbol, Cadenya::Objective::State) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        STATE_UNSPECIFIED =
+          T.let(:STATE_UNSPECIFIED, Cadenya::Objective::State::TaggedSymbol)
+        STATE_PENDING =
+          T.let(:STATE_PENDING, Cadenya::Objective::State::TaggedSymbol)
+        STATE_RUNNING =
+          T.let(:STATE_RUNNING, Cadenya::Objective::State::TaggedSymbol)
+        STATE_WAITING =
+          T.let(:STATE_WAITING, Cadenya::Objective::State::TaggedSymbol)
+        STATE_FAILED =
+          T.let(:STATE_FAILED, Cadenya::Objective::State::TaggedSymbol)
+        STATE_CANCELLED =
+          T.let(:STATE_CANCELLED, Cadenya::Objective::State::TaggedSymbol)
+        STATE_FINALIZED =
+          T.let(:STATE_FINALIZED, Cadenya::Objective::State::TaggedSymbol)
+
+        sig do
+          override.returns(T::Array[Cadenya::Objective::State::TaggedSymbol])
+        end
+        def self.values
+        end
+      end
     end
   end
 end

data/rbi/cadenya/models/objective_config_snapshot.rbi

@@ -0,0 +1,70 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    class ObjectiveConfigSnapshot < Cadenya::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Cadenya::ObjectiveConfigSnapshot, Cadenya::Internal::AnyHash)
+        end
+
+      # Agent resource
+      sig { returns(T.nilable(Cadenya::Agent)) }
+      attr_reader :agent
+
+      sig { params(agent: Cadenya::Agent::OrHash).void }
+      attr_writer :agent
+
+      # AgentSchedule resource — a recurring trigger attached to an agent that creates
+      # objectives on its cadence.
+      sig { returns(T.nilable(Cadenya::Agents::AgentSchedule)) }
+      attr_reader :agent_schedule
+
+      sig do
+        params(agent_schedule: Cadenya::Agents::AgentSchedule::OrHash).void
+      end
+      attr_writer :agent_schedule
+
+      # AgentVariation resource
+      sig { returns(T.nilable(Cadenya::Agents::AgentVariation)) }
+      attr_reader :agent_variation
+
+      sig do
+        params(agent_variation: Cadenya::Agents::AgentVariation::OrHash).void
+      end
+      attr_writer :agent_variation
+
+      # ObjectiveConfigSnapshot is the point-in-time snapshot of the agent, variation,
+      # and (when applicable) schedule that an objective was started with.
+      sig do
+        params(
+          agent: Cadenya::Agent::OrHash,
+          agent_schedule: Cadenya::Agents::AgentSchedule::OrHash,
+          agent_variation: Cadenya::Agents::AgentVariation::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Agent resource
+        agent: nil,
+        # AgentSchedule resource — a recurring trigger attached to an agent that creates
+        # objectives on its cadence.
+        agent_schedule: nil,
+        # AgentVariation resource
+        agent_variation: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            agent: Cadenya::Agent,
+            agent_schedule: Cadenya::Agents::AgentSchedule,
+            agent_variation: Cadenya::Agents::AgentVariation
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cadenya/models/objective_create_params.rbi

@@ -17,11 +17,42 @@ module Cadenya
       sig { returns(String) }
       attr_accessor :agent_id
 
-      sig { returns(Cadenya::ObjectiveData) }
-      attr_reader :data
+      # Arbitrary data for the objective. May be used in liquid templates for prompts
+      # configured on the agent variation
+      sig { returns(T::Hash[Symbol, T.anything]) }
+      attr_accessor :data
 
-      sig { params(data: Cadenya::ObjectiveData::OrHash).void }
-      attr_writer :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.
+      sig { returns(T.nilable(String)) }
+      attr_reader :initial_message
+
+      sig { params(initial_message: String).void }
+      attr_writer :initial_message
+
+      # Memory layers/entries to push onto this objective's memory stack on top of the
+      # baseline stack inherited from the selected variation.
+      #
+      # Array order is push order: the first element sits lower in the objective's
+      # contribution to the stack; the LAST element ends up on top of the effective
+      # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
+      # position.
+      #
+      # System-managed layers (e.g., episodic) cannot be referenced here; they attach
+      # themselves automatically based on episodic_key.
+      #
+      # Stack size cap: the TOTAL effective stack (variation's memory layers
+      #
+      # - this field) must not exceed 10 entries. A request that would produce an
+      #   effective stack larger than 10 is rejected with InvalidArgument.
+      sig { returns(T.nilable(T::Array[Cadenya::MemoryReference])) }
+      attr_reader :memory_stack
+
+      sig do
+        params(memory_stack: T::Array[Cadenya::MemoryReference::OrHash]).void
+      end
+      attr_writer :memory_stack
 
       # CreateOperationMetadata contains the user-provided fields for creating an
       # operation. Read-only fields (id, account_id, workspace_id, created_at,
@@ -32,6 +63,20 @@ module Cadenya
       sig { params(metadata: Cadenya::CreateOperationMetadata::OrHash).void }
       attr_writer :metadata
 
+      # Secrets that can be used in the headers for tool calls using the secret
+      # interpolation format.
+      sig do
+        returns(T.nilable(T::Array[Cadenya::ObjectiveCreateParams::Secret]))
+      end
+      attr_reader :secrets
+
+      sig do
+        params(
+          secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash]
+        ).void
+      end
+      attr_writer :secrets
+
       # Optional explicit variation selection. Overrides the agent's
       # variation_selection_mode.
       sig { returns(T.nilable(String)) }
@@ -44,8 +89,11 @@ module Cadenya
         params(
           workspace_id: String,
           agent_id: String,
-          data: Cadenya::ObjectiveData::OrHash,
+          data: T::Hash[Symbol, T.anything],
+          initial_message: String,
+          memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
           metadata: Cadenya::CreateOperationMetadata::OrHash,
+          secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash],
           variation_id: String,
           request_options: Cadenya::RequestOptions::OrHash
         ).returns(T.attached_class)
@@ -53,11 +101,36 @@ module Cadenya
       def self.new(
         workspace_id:,
         agent_id:,
+        # 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.
+        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.
+        #
+        # Array order is push order: the first element sits lower in the objective's
+        # contribution to the stack; the LAST element ends up on top of the effective
+        # stack. Entries pinned via memory_entry_id behave as single-entry layers at their
+        # position.
+        #
+        # System-managed layers (e.g., episodic) cannot be referenced here; they attach
+        # themselves automatically based on episodic_key.
+        #
+        # Stack size cap: the TOTAL effective stack (variation's memory layers
+        #
+        # - this field) must not exceed 10 entries. A request that would produce an
+        #   effective stack larger than 10 is rejected with InvalidArgument.
+        memory_stack: nil,
         # CreateOperationMetadata contains the user-provided fields for creating an
         # operation. Read-only fields (id, account_id, workspace_id, created_at,
         # profile_id) are excluded since they are set by the server.
         metadata: nil,
+        # Secrets that can be used in the headers for tool calls using the secret
+        # interpolation format.
+        secrets: nil,
         # Optional explicit variation selection. Overrides the agent's
         # variation_selection_mode.
         variation_id: nil,
@@ -70,8 +143,11 @@ module Cadenya
           {
             workspace_id: String,
             agent_id: String,
-            data: Cadenya::ObjectiveData,
+            data: T::Hash[Symbol, T.anything],
+            initial_message: String,
+            memory_stack: T::Array[Cadenya::MemoryReference],
             metadata: Cadenya::CreateOperationMetadata,
+            secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret],
             variation_id: String,
             request_options: Cadenya::RequestOptions
           }
@@ -79,6 +155,36 @@ module Cadenya
       end
       def to_hash
       end
+
+      class Secret < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::ObjectiveCreateParams::Secret,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :name
+
+        sig { params(name: String).void }
+        attr_writer :name
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :value
+
+        sig { params(value: String).void }
+        attr_writer :value
+
+        sig { params(name: String, value: String).returns(T.attached_class) }
+        def self.new(name: nil, value: nil)
+        end
+
+        sig { override.returns({ name: String, value: String }) }
+        def to_hash
+        end
+      end
     end
   end
 end