cadenya 0.26.0 → 0.28.0

data/rbi/cadenya/models/objective.rbi

@@ -6,10 +6,10 @@ module Cadenya
       OrHash =
         T.type_alias { T.any(Cadenya::Objective, Cadenya::Internal::AnyHash) }
 
-      # The initial message sent to the agent. This becomes the first user message in
-      # the LLM chat history.
+      # The first user message in the LLM chat history, either provided explicitly at
+      # creation or rendered from the variation's first_user_message_template.
       sig { returns(String) }
-      attr_accessor :initial_message
+      attr_accessor :first_user_message
 
       # Metadata for ephemeral operations and activities (e.g., objectives, executions,
       # runs)
@@ -75,12 +75,12 @@ module Cadenya
       sig { returns(String) }
       attr_accessor :system_prompt
 
-      # Arbitrary data for the objective
+      # Arbitrary data rendered into the variation's first_user_message_template
       sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-      attr_reader :data
+      attr_reader :first_user_message_data
 
-      sig { params(data: T::Hash[Symbol, T.anything]).void }
-      attr_writer :data
+      sig { params(first_user_message_data: T::Hash[Symbol, T.anything]).void }
+      attr_writer :first_user_message_data
 
       # ObjectiveInfo provides read-only aggregated statistics about an objective's
       # execution
@@ -114,12 +114,12 @@ module Cadenya
       sig { params(state_message: String).void }
       attr_writer :state_message
 
-      # Arbitrary data used to render the variation's user_message_template
+      # Arbitrary data rendered into the variation's system_prompt_template
       sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-      attr_reader :user_data
+      attr_reader :system_prompt_data
 
-      sig { params(user_data: T::Hash[Symbol, T.anything]).void }
-      attr_writer :user_data
+      sig { params(system_prompt_data: T::Hash[Symbol, T.anything]).void }
+      attr_writer :system_prompt_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,
@@ -127,28 +127,28 @@ module Cadenya
       sig do
         params(
           config_snapshot: Cadenya::ObjectiveConfigSnapshot::OrHash,
-          initial_message: String,
+          first_user_message: String,
           metadata: Cadenya::OperationMetadata::OrHash,
           state: Cadenya::Objective::State::OrSymbol,
           system_prompt: String,
-          data: T::Hash[Symbol, T.anything],
           episodic_memory: Cadenya::Objective::EpisodicMemory::OrHash,
+          first_user_message_data: T::Hash[Symbol, T.anything],
           info: Cadenya::ObjectiveInfo::OrHash,
           memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
           output: T::Hash[Symbol, T.anything],
           parent_objective_id: String,
           secrets: T::Array[Cadenya::ObjectiveSecret::OrHash],
           state_message: String,
-          user_data: T::Hash[Symbol, T.anything]
+          system_prompt_data: T::Hash[Symbol, T.anything]
         ).returns(T.attached_class)
       end
       def self.new(
         # 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:,
+        # The first user message in the LLM chat history, either provided explicitly at
+        # creation or rendered from the variation's first_user_message_template.
+        first_user_message:,
         # Metadata for ephemeral operations and activities (e.g., objectives, executions,
         # runs)
         metadata:,
@@ -156,10 +156,10 @@ module Cadenya
         state:,
         # system_prompt is read-only, derived from the selected variation's prompt
         system_prompt:,
-        # Arbitrary data for the objective
-        data: nil,
         # Episodic is used to configure the episodic memory for the objective
         episodic_memory: nil,
+        # Arbitrary data rendered into the variation's first_user_message_template
+        first_user_message_data: nil,
         # ObjectiveInfo provides read-only aggregated statistics about an objective's
         # execution
         info: nil,
@@ -189,8 +189,8 @@ module Cadenya
         secrets: nil,
         # Optional human-readable detail about the current state (e.g. a failure reason).
         state_message: nil,
-        # Arbitrary data used to render the variation's user_message_template
-        user_data: nil
+        # Arbitrary data rendered into the variation's system_prompt_template
+        system_prompt_data: nil
       )
       end
 
@@ -198,19 +198,19 @@ module Cadenya
         override.returns(
           {
             config_snapshot: Cadenya::ObjectiveConfigSnapshot,
-            initial_message: String,
+            first_user_message: String,
             metadata: Cadenya::OperationMetadata,
             state: Cadenya::Objective::State::TaggedSymbol,
             system_prompt: String,
-            data: T::Hash[Symbol, T.anything],
             episodic_memory: Cadenya::Objective::EpisodicMemory,
+            first_user_message_data: T::Hash[Symbol, T.anything],
             info: Cadenya::ObjectiveInfo,
             memory_cascade: T::Array[Cadenya::MemoryReference],
             output: T::Hash[Symbol, T.anything],
             parent_objective_id: String,
             secrets: T::Array[Cadenya::ObjectiveSecret],
             state_message: String,
-            user_data: T::Hash[Symbol, T.anything]
+            system_prompt_data: T::Hash[Symbol, T.anything]
           }
         )
       end

data/rbi/cadenya/models/objective_continue_params.rbi

@@ -32,27 +32,12 @@ module Cadenya
       sig { params(message: String).void }
       attr_writer :message
 
-      # Secrets that should be included with the message. Helpful for when you need to
-      # update secrets on the objective (IE: A secret expires and needs to be refreshed)
-      sig do
-        returns(T.nilable(T::Array[Cadenya::ObjectiveContinueParams::Secret]))
-      end
-      attr_reader :secrets
-
-      sig do
-        params(
-          secrets: T::Array[Cadenya::ObjectiveContinueParams::Secret::OrHash]
-        ).void
-      end
-      attr_writer :secrets
-
       sig do
         params(
           workspace_id: String,
           objective_id: String,
           enqueue: T::Boolean,
           message: String,
-          secrets: T::Array[Cadenya::ObjectiveContinueParams::Secret::OrHash],
           request_options: Cadenya::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
@@ -64,9 +49,6 @@ module Cadenya
         enqueue: nil,
         # The message to continue an objective that has completed (or you are enqueing)
         message: nil,
-        # Secrets that should be included with the message. Helpful for when you need to
-        # update secrets on the objective (IE: A secret expires and needs to be refreshed)
-        secrets: nil,
         request_options: {}
       )
       end
@@ -78,43 +60,12 @@ module Cadenya
             objective_id: String,
             enqueue: T::Boolean,
             message: String,
-            secrets: T::Array[Cadenya::ObjectiveContinueParams::Secret],
             request_options: Cadenya::RequestOptions
           }
         )
       end
       def to_hash
       end
-
-      class Secret < Cadenya::Internal::Type::BaseModel
-        OrHash =
-          T.type_alias do
-            T.any(
-              Cadenya::ObjectiveContinueParams::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

data/rbi/cadenya/models/objective_create_params.rbi

@@ -17,10 +17,11 @@ module Cadenya
       sig { returns(String) }
       attr_accessor :agent_id
 
-      # Arbitrary data for the objective. May be used in liquid templates for prompts
-      # configured on the agent variation
+      # Arbitrary data rendered into the selected variation's system_prompt_template
+      # (liquid) to produce the objective's system prompt. If the agent has a
+      # system_prompt_data_schema, this must satisfy it.
       sig { returns(T::Hash[Symbol, T.anything]) }
-      attr_accessor :data
+      attr_accessor :system_prompt_data
 
       # Episodic is used to configure the episodic memory for the objective
       sig { returns(T.nilable(Cadenya::ObjectiveCreateParams::EpisodicMemory)) }
@@ -34,16 +35,25 @@ module Cadenya
       end
       attr_writer :episodic_memory
 
-      # 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
+      # Optional explicit first user message for the LLM chat history. When not set, the
+      # selected variation's first_user_message_template is rendered with
+      # first_user_message_data instead. If neither this field nor a
+      # first_user_message_template is present, the request is rejected with
       # InvalidArgument.
       sig { returns(T.nilable(String)) }
-      attr_reader :initial_message
+      attr_reader :first_user_message
 
-      sig { params(initial_message: String).void }
-      attr_writer :initial_message
+      sig { params(first_user_message: String).void }
+      attr_writer :first_user_message
+
+      # Arbitrary data rendered into the selected variation's
+      # first_user_message_template (liquid) to produce the first user message. Separate
+      # from `system_prompt_data`, which renders the system prompt template.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :first_user_message_data
+
+      sig { params(first_user_message_data: T::Hash[Symbol, T.anything]).void }
+      attr_writer :first_user_message_data
 
       # Memory layers/entries layered over the baseline cascade inherited from the
       # selected variation — element-level rules over inherited styles, in CSS terms.
@@ -89,15 +99,6 @@ 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)) }
@@ -110,14 +111,14 @@ module Cadenya
         params(
           workspace_id: String,
           agent_id: String,
-          data: T::Hash[Symbol, T.anything],
+          system_prompt_data: T::Hash[Symbol, T.anything],
           episodic_memory:
             Cadenya::ObjectiveCreateParams::EpisodicMemory::OrHash,
-          initial_message: String,
+          first_user_message: String,
+          first_user_message_data: T::Hash[Symbol, T.anything],
           memory_cascade: 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)
@@ -125,17 +126,22 @@ 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:,
+        # Arbitrary data rendered into the selected variation's system_prompt_template
+        # (liquid) to produce the objective's system prompt. If the agent has a
+        # system_prompt_data_schema, this must satisfy it.
+        system_prompt_data:,
         # Episodic is used to configure the episodic memory for the objective
         episodic_memory: nil,
-        # 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
+        # Optional explicit first user message for the LLM chat history. When not set, the
+        # selected variation's first_user_message_template is rendered with
+        # first_user_message_data instead. If neither this field nor a
+        # first_user_message_template is present, the request is rejected with
         # InvalidArgument.
-        initial_message: nil,
+        first_user_message: nil,
+        # Arbitrary data rendered into the selected variation's
+        # first_user_message_template (liquid) to produce the first user message. Separate
+        # from `system_prompt_data`, which renders the system prompt template.
+        first_user_message_data: nil,
         # Memory layers/entries layered over the baseline cascade inherited from the
         # selected variation — element-level rules over inherited styles, in CSS terms.
         #
@@ -157,10 +163,6 @@ 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,
@@ -173,13 +175,13 @@ module Cadenya
           {
             workspace_id: String,
             agent_id: String,
-            data: T::Hash[Symbol, T.anything],
+            system_prompt_data: T::Hash[Symbol, T.anything],
             episodic_memory: Cadenya::ObjectiveCreateParams::EpisodicMemory,
-            initial_message: String,
+            first_user_message: String,
+            first_user_message_data: T::Hash[Symbol, T.anything],
             memory_cascade: 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/objective_event_data.rbi

@@ -61,6 +61,17 @@ module Cadenya
       sig { params(memory_read: Cadenya::MemoryRead::OrHash).void }
       attr_writer :memory_read
 
+      # Notice is a non-terminal diagnostic emitted by the runtime when something
+      # noteworthy but non-fatal happens during an objective — for example a
+      # just-in-time tool set failing to load, or a previously loaded tool being dropped
+      # because it was archived. Notices carry no structured payload; they exist to make
+      # the objective timeline self-explanatory.
+      sig { returns(T.nilable(Cadenya::ObjectiveEventData::Notice)) }
+      attr_reader :notice
+
+      sig { params(notice: Cadenya::ObjectiveEventData::Notice::OrHash).void }
+      attr_writer :notice
+
       sig { returns(T.nilable(Cadenya::SubAgentSpawned)) }
       attr_reader :sub_agent_spawned
 
@@ -133,6 +144,7 @@ module Cadenya
           error: Cadenya::ObjectiveError::OrHash,
           finalized: Cadenya::ObjectiveEventData::Finalized::OrHash,
           memory_read: Cadenya::MemoryRead::OrHash,
+          notice: Cadenya::ObjectiveEventData::Notice::OrHash,
           sub_agent_spawned: Cadenya::SubAgentSpawned::OrHash,
           sub_agent_updated: Cadenya::SubAgentUpdated::OrHash,
           tool_approval_requested: Cadenya::ToolApprovalRequested::OrHash,
@@ -161,6 +173,12 @@ module Cadenya
         # cascade and loads an entry. Lookups that miss (key not found in any layer) do
         # not emit this event.
         memory_read: nil,
+        # Notice is a non-terminal diagnostic emitted by the runtime when something
+        # noteworthy but non-fatal happens during an objective — for example a
+        # just-in-time tool set failing to load, or a previously loaded tool being dropped
+        # because it was archived. Notices carry no structured payload; they exist to make
+        # the objective timeline self-explanatory.
+        notice: nil,
         sub_agent_spawned: nil,
         sub_agent_updated: nil,
         tool_approval_requested: nil,
@@ -183,6 +201,7 @@ module Cadenya
             error: Cadenya::ObjectiveError,
             finalized: Cadenya::ObjectiveEventData::Finalized,
             memory_read: Cadenya::MemoryRead,
+            notice: Cadenya::ObjectiveEventData::Notice,
             sub_agent_spawned: Cadenya::SubAgentSpawned,
             sub_agent_updated: Cadenya::SubAgentUpdated,
             tool_approval_requested: Cadenya::ToolApprovalRequested,
@@ -268,6 +287,115 @@ module Cadenya
         def to_hash
         end
       end
+
+      class Notice < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::ObjectiveEventData::Notice,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        # Stable machine-readable identifier for the notice kind (for example
+        # "tool_set_load_failed", "tool_archived"). Clients can switch on it or use it as
+        # an i18n key; the message is the English fallback.
+        sig { returns(T.nilable(String)) }
+        attr_reader :key
+
+        sig { params(key: String).void }
+        attr_writer :key
+
+        sig do
+          returns(
+            T.nilable(Cadenya::ObjectiveEventData::Notice::Level::TaggedSymbol)
+          )
+        end
+        attr_reader :level
+
+        sig do
+          params(
+            level: Cadenya::ObjectiveEventData::Notice::Level::OrSymbol
+          ).void
+        end
+        attr_writer :level
+
+        # Human-readable description of what happened.
+        sig { returns(T.nilable(String)) }
+        attr_reader :message
+
+        sig { params(message: String).void }
+        attr_writer :message
+
+        # Notice is a non-terminal diagnostic emitted by the runtime when something
+        # noteworthy but non-fatal happens during an objective — for example a
+        # just-in-time tool set failing to load, or a previously loaded tool being dropped
+        # because it was archived. Notices carry no structured payload; they exist to make
+        # the objective timeline self-explanatory.
+        sig do
+          params(
+            key: String,
+            level: Cadenya::ObjectiveEventData::Notice::Level::OrSymbol,
+            message: String
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Stable machine-readable identifier for the notice kind (for example
+          # "tool_set_load_failed", "tool_archived"). Clients can switch on it or use it as
+          # an i18n key; the message is the English fallback.
+          key: nil,
+          level: nil,
+          # Human-readable description of what happened.
+          message: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              key: String,
+              level: Cadenya::ObjectiveEventData::Notice::Level::TaggedSymbol,
+              message: String
+            }
+          )
+        end
+        def to_hash
+        end
+
+        module Level
+          extend Cadenya::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Cadenya::ObjectiveEventData::Notice::Level)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          LEVEL_UNSPECIFIED =
+            T.let(
+              :LEVEL_UNSPECIFIED,
+              Cadenya::ObjectiveEventData::Notice::Level::TaggedSymbol
+            )
+          LEVEL_INFO =
+            T.let(
+              :LEVEL_INFO,
+              Cadenya::ObjectiveEventData::Notice::Level::TaggedSymbol
+            )
+          LEVEL_WARN =
+            T.let(
+              :LEVEL_WARN,
+              Cadenya::ObjectiveEventData::Notice::Level::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[Cadenya::ObjectiveEventData::Notice::Level::TaggedSymbol]
+            )
+          end
+          def self.values
+          end
+        end
+      end
     end
   end
 end

data/rbi/cadenya/models/rotate_challenge_token_response.rbi

@@ -0,0 +1,30 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    class RotateChallengeTokenResponse < Cadenya::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Cadenya::RotateChallengeTokenResponse,
+            Cadenya::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :challenge_token
+
+      sig { params(challenge_token: String).void }
+      attr_writer :challenge_token
+
+      # Response containing the newly generated challenge token.
+      sig { params(challenge_token: String).returns(T.attached_class) }
+      def self.new(challenge_token: nil)
+      end
+
+      sig { override.returns({ challenge_token: String }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/cadenya/models/tool_set_adapter_mcp.rbi

@@ -28,6 +28,17 @@ module Cadenya
       sig { params(include_tools: Cadenya::ToolFilter::OrHash).void }
       attr_writer :include_tools
 
+      # Defines behavior for just-in-time capable tool set adapters (IE: MCP).
+      sig { returns(T.nilable(Cadenya::ToolSetAdapterMcp::JustInTime)) }
+      attr_reader :just_in_time
+
+      sig do
+        params(
+          just_in_time: Cadenya::ToolSetAdapterMcp::JustInTime::OrHash
+        ).void
+      end
+      attr_writer :just_in_time
+
       # Approval filters that will automatically set the approval requirement on tools
       # synced from an external source
       sig { returns(T.nilable(Cadenya::ApprovalRequirementFilter)) }
@@ -49,6 +60,7 @@ module Cadenya
           exclude_tools: Cadenya::ToolFilter::OrHash,
           headers: T::Hash[Symbol, String],
           include_tools: Cadenya::ToolFilter::OrHash,
+          just_in_time: Cadenya::ToolSetAdapterMcp::JustInTime::OrHash,
           tool_approvals: Cadenya::ApprovalRequirementFilter::OrHash,
           url: String
         ).returns(T.attached_class)
@@ -59,6 +71,8 @@ module Cadenya
         headers: nil,
         # Top-level filter with simple boolean logic (no nesting)
         include_tools: nil,
+        # Defines behavior for just-in-time capable tool set adapters (IE: MCP).
+        just_in_time: nil,
         # Approval filters that will automatically set the approval requirement on tools
         # synced from an external source
         tool_approvals: nil,
@@ -72,6 +86,7 @@ module Cadenya
             exclude_tools: Cadenya::ToolFilter,
             headers: T::Hash[Symbol, String],
             include_tools: Cadenya::ToolFilter,
+            just_in_time: Cadenya::ToolSetAdapterMcp::JustInTime,
             tool_approvals: Cadenya::ApprovalRequirementFilter,
             url: String
           }
@@ -79,6 +94,60 @@ module Cadenya
       end
       def to_hash
       end
+
+      class JustInTime < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::ToolSetAdapterMcp::JustInTime,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :enabled
+
+        sig { params(enabled: T::Boolean).void }
+        attr_writer :enabled
+
+        # If set, an objective will automatically be failed if tools cannot be loaded in
+        # the initial stages of an objective being created. Tools are loaded
+        # asynchronously, so this setting is useful for ensuring that an objective
+        # continued any further if tools are not available.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :fail_objective_on_tool_list_error
+
+        sig { params(fail_objective_on_tool_list_error: T::Boolean).void }
+        attr_writer :fail_objective_on_tool_list_error
+
+        # Defines behavior for just-in-time capable tool set adapters (IE: MCP).
+        sig do
+          params(
+            enabled: T::Boolean,
+            fail_objective_on_tool_list_error: T::Boolean
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          enabled: nil,
+          # If set, an objective will automatically be failed if tools cannot be loaded in
+          # the initial stages of an objective being created. Tools are loaded
+          # asynchronously, so this setting is useful for ensuring that an objective
+          # continued any further if tools are not available.
+          fail_objective_on_tool_list_error: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              enabled: T::Boolean,
+              fail_objective_on_tool_list_error: T::Boolean
+            }
+          )
+        end
+        def to_hash
+        end
+      end
     end
   end
 end

data/rbi/cadenya/models/tool_sets/tool_info.rbi

@@ -25,9 +25,20 @@ module Cadenya
         sig { params(tool_set: Cadenya::ResourceMetadata::OrHash).void }
         attr_writer :tool_set
 
+        # Content signature identifying the tool within its tool set: a hash of the
+        # sanitized llm_tool_name, description, and canonical parameters. Two tools with
+        # the same llm_tool_name but different parameters or description (as MCP servers
+        # may return per user) have distinct signatures.
+        sig { returns(T.nilable(String)) }
+        attr_reader :signature
+
+        sig { params(signature: String).void }
+        attr_writer :signature
+
         sig do
           params(
             created_by: Cadenya::Profile::OrHash,
+            signature: String,
             tool_set: Cadenya::ResourceMetadata::OrHash
           ).returns(T.attached_class)
         end
@@ -36,6 +47,11 @@ module Cadenya
           # account level. Profiles are account-scoped and can be granted access to multiple
           # workspaces.
           created_by: nil,
+          # Content signature identifying the tool within its tool set: a hash of the
+          # sanitized llm_tool_name, description, and canonical parameters. Two tools with
+          # the same llm_tool_name but different parameters or description (as MCP servers
+          # may return per user) have distinct signatures.
+          signature: nil,
           # Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
           tool_set: nil
         )
@@ -45,6 +61,7 @@ module Cadenya
           override.returns(
             {
               created_by: Cadenya::Profile,
+              signature: String,
               tool_set: Cadenya::ResourceMetadata
             }
           )