# Objectives

## List objectives

`objectives.list(workspace_id, **kwargs) -> CursorPagination<Objective>`

**get** `/v1/workspaces/{workspaceId}/objectives`

Lists all objectives in the workspace

### Parameters

- `workspace_id: String`

- `agent_id: String`

  Agent ID for filtering

- `agent_schedule_id: String`

  Filter to objectives produced by a specific AgentSchedule. Accepts
  canonical as_… form or external_id:<value> form.

- `cursor: String`

  Pagination cursor from previous response

- `include_info: bool`

  When set to true you may use more of your alloted API rate-limit

- `limit: Integer`

  Maximum number of results to return

- `parent_objective_id: String`

  Optional filters

- `profile_id: String`

- `sort_order: String`

  Sort order for results (asc or desc by creation time)

- `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

  Filter by state

  - `:STATE_UNSPECIFIED`

  - `:STATE_PENDING`

  - `:STATE_RUNNING`

  - `:STATE_WAITING`

  - `:STATE_FAILED`

  - `:STATE_CANCELLED`

  - `:STATE_FINALIZED`

### Returns

- `class Objective`

  - `data: ObjectiveData`

    - `agent: Agent`

      Agent resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: AgentSpec`

        Agent specification (user-provided configuration)

        - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

          Status of the agent

          - `:AGENT_STATUS_UNSPECIFIED`

          - `:AGENT_STATUS_DRAFT`

          - `:AGENT_STATUS_PUBLISHED`

          - `:AGENT_STATUS_ARCHIVED`

        - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

          Controls how variations are automatically selected when creating objectives
          Defaults to RANDOM when unspecified

          - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

          - `:VARIATION_SELECTION_MODE_RANDOM`

          - `:VARIATION_SELECTION_MODE_WEIGHTED`

        - `description: String`

          Description of the agent's purpose

        - `input_data_schema: Hash[Symbol, untyped]`

          InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
          prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
          the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

        - `output_definition: Hash[Symbol, untyped]`

          Optional output definition for objectives created for this agent.
          When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
          Use this option when you want structured data to be created by your objectives.

        - `webhook_events_url: String`

          The URL that Cadenya will send events for any objective assigned to the agent.

      - `info: AgentInfo`

        AgentInfo contains simple information about an agent for display or quick reference

        - `created_by: Profile`

          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.

          - `metadata: AccountResourceMetadata`

            AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `spec: ProfileSpec`

            Configuration for a profile.

            - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

              Whether this profile represents a human user, an API key, or a system
              principal.

              - `:PROFILE_TYPE_UNSPECIFIED`

              - `:PROFILE_TYPE_USER`

              - `:PROFILE_TYPE_API_KEY`

              - `:PROFILE_TYPE_SYSTEM`

            - `email: String`

              Email address of the profile. Required and unique within an account for
              user profiles.

            - `name: String`

              Display name (e.g., "Bobby Tables").

        - `variation_count: Integer`

    - `data: untyped`

      Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

    - `initial_message: String`

      The initial message sent to the agent. This becomes the first user message in the LLM chat history.

    - `memory_stack: Array[MemoryReference]`

      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_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `output: Hash[Symbol, untyped]`

      The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

    - `output_definition: Hash[Symbol, untyped]`

      Snapshot of the agent spec's output_definition at objective creation time.
      When present, the objective will run an extraction step after the LLM finishes.

    - `parent_objective_id: String`

      A parent objective means the objective was spawned off using a separate agent to complete an objective

    - `secrets: Array[ObjectiveDataSecret]`

      Secrets that can be used in the headers for tool calls using the secret interpolation format.

      - `name: String`

      - `value: String`

    - `source_schedule_id: String`

      ID of the AgentSchedule that produced this objective, when applicable.
      Populated when the objective is created from a schedule fire; empty when
      the objective was created via CreateObjective directly.

    - `system_prompt: String`

      system_prompt is read-only, derived from the selected variation's prompt

    - `variation: AgentVariation`

      AgentVariation resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `spec: AgentVariationSpec`

        AgentVariationSpec defines the operational configuration for a variation

        - `compaction_config: AgentVariationSpecCompactionConfig`

          CompactionConfig defines how context window compaction behaves for objectives using this variation.

          - `summarization: CompactionConfigSummarizationStrategy`

            SummarizationStrategy configures LLM-powered summarization of older conversation turns.

            - `instructions: String`

              Custom instructions that guide what the summarizer preserves.
              Replaces the default summarization prompt entirely.
              Example: "Preserve all code snippets, variable names, and technical decisions."

          - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

            ToolResultClearingStrategy configures clearing of older tool result content.

            - `preserve_recent_results: Integer`

              Number of most recent tool call results to keep intact.
              Older tool results have their content replaced with "[result cleared]"
              while preserving the assistant tool call message (function name, arguments).
              Default: 2

          - `trigger_threshold: Float`

            Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
            When input tokens reach this percentage of the model's limit, compaction triggers.
            Default: 0.75 (75%)

        - `constraints: AgentVariationSpecConstraints`

          Execution constraints

          - `max_sub_objectives: Integer`

            The maximum number of sub-objectives that can be created. 0 means no limit.

          - `max_tool_calls: Integer`

            The maximum number of tool calls that can be made. 0 means no limit.

        - `description: String`

          Human-readable description of what this variation does or when it should be used

        - `enable_episodic_memory: bool`

          Enable episodic memory for objectives using this variation.
          When true, the system automatically creates a document namespace for each objective
          using the objective's episodic_key as the external_id, allowing the agent to
          store and retrieve documents specific to that episode.

        - `episodic_memory_ttl: Integer`

          How long episodic memories should be retained.
          After this duration, episodic document namespaces can be automatically cleaned up.
          If not set, episodic memories are retained indefinitely.

        - `model_config: AgentVariationSpecModelConfig`

          ModelConfig defines the model configuration for a variation

          - `model_id: String`

            The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

          - `temperature: Float`

            Sampling temperature for model inference (0.0 to 1.0)
            Lower values produce more deterministic outputs, higher values increase randomness

        - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

          ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
          Max tools is the maximum number of tools that can be discovered per search.
          Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

          - `hints: Array[String]`

          - `max_tools: Integer`

          - `rerank_threshold: Float`

            Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
            which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
            the tool very closely match the query the tool search performed.

        - `prompt: String`

          The system prompt for this variation

        - `weight: Integer`

          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 on CreateObjectiveRequest.

      - `info: AgentVariationInfo`

        AgentVariationInfo provides read-only summary information about a variation

        - `assignments: Array[VariationAssignment]`

          All tools, tool sets, and sub-agents assigned to this variation.
          Populated on reads so clients can render a variation's full assignment
          list without calling the add/remove endpoints just to enumerate.

          - `id: String`

          - `agent: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

            - `id: String`

            - `name: String`

              Human-readable name of the referenced resource, populated by the server
              on reads for convenience. Absent on references to resources that do not
              have a name (e.g., objective tasks).

          - `tool: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `tool_set: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

        - `created_by: Profile`

          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.

        - `feedback_count: Integer`

          Total number of objective feedbacks received for this variation

        - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

          Read-only list of memory layer assignments for this variation,
          returned in ascending `position` (bottom → top). Capped at 10 entries.

          - `id: String`

            Assignment row id — handle for removing the assignment. Distinct
            from the referenced memory layer's id.

          - `memory_layer: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `position: Integer`

            Position in the variation's baseline stack. Lower values sit lower;
            the highest-position assignment is on top of the variation's
            baseline. Gaps are fine — only relative position matters. Positions
            must be unique within a variation; a request that would collide
            with an existing assignment's position is rejected with
            InvalidArgument.

        - `memory_layer_count: Integer`

          Count of memory layer assignments.

        - `model: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `score: Float`

          Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
          Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

        - `sub_agent_count: Integer`

          Number of sub-agents assigned to this variation

        - `tool_count: Integer`

          Number of individual tools assigned to this variation

        - `tool_set_count: Integer`

          Number of tool sets assigned to this variation

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: ObjectiveStatus`

    - `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

      - `:STATE_UNSPECIFIED`

      - `:STATE_PENDING`

      - `:STATE_RUNNING`

      - `:STATE_WAITING`

      - `:STATE_FAILED`

      - `:STATE_CANCELLED`

      - `:STATE_FINALIZED`

    - `message: String`

  - `info: ObjectiveInfo`

    ObjectiveInfo provides read-only aggregated statistics about an objective's execution

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `agent_variation: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `created_by: Profile`

      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.

    - `effective_memory_stack: Array[MemoryReference]`

      The effective memory stack at objective creation time, flattened
      from the variation's baseline plus ObjectiveData.memory_stack. Order
      is push order (last = top). Returned on reads so clients can see
      exactly what stack the objective is using without having to re-join
      variation state.

      - `memory_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `total_context_windows: Integer`

      Total number of context windows that this objective has generated

    - `total_events: Integer`

      Total number of events generated during this objective's execution

    - `total_input_tokens: Integer`

      Total input tokens consumed across all LLM completions across all context windows

    - `total_output_tokens: Integer`

      Total output tokens generated across all LLM completions across all context windows

    - `total_tool_calls: Integer`

      Total number of tool calls made during execution

  - `last_five_windows: Array[ObjectiveContextWindow]`

    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).

    - `data: ObjectiveContextWindowData`

      - `completion_tokens: Integer`

        A calculated value for how many completion tokens (output tokens) have been used in this context window

      - `objective_id: String`

        The objective's ID that this window belongs to

      - `previous_window_continue_instructions: String`

        The instructions for this window to continue from a previous window's chat history.

      - `prompt_tokens: Integer`

        A calculated value for how many prompt tokens (input tokens) have been used in this context window

      - `sequence: Integer`

        sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
        to calculate how many context windows an objective has.

    - `metadata: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `info: Info{ created_by, objective}`

      - `created_by: Profile`

        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.

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.list("workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "agent": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "status": "AGENT_STATUS_UNSPECIFIED",
            "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
            "description": "description",
            "inputDataSchema": {
              "foo": "bar"
            },
            "outputDefinition": {
              "foo": "bar"
            },
            "webhookEventsUrl": "webhookEventsUrl"
          },
          "info": {
            "createdBy": {
              "metadata": {
                "id": "id",
                "accountId": "accountId",
                "name": "name",
                "profileId": "profileId",
                "externalId": "externalId",
                "labels": {
                  "foo": "string"
                }
              },
              "spec": {
                "type": "PROFILE_TYPE_UNSPECIFIED",
                "email": "email",
                "name": "name"
              }
            },
            "variationCount": 0
          }
        },
        "data": {},
        "initialMessage": "initialMessage",
        "memoryStack": [
          {
            "memoryEntryId": "memoryEntryId",
            "memoryLayerId": "memoryLayerId"
          }
        ],
        "output": {
          "foo": "bar"
        },
        "outputDefinition": {
          "foo": "bar"
        },
        "parentObjectiveId": "parentObjectiveId",
        "secrets": [
          {
            "name": "name",
            "value": "value"
          }
        ],
        "sourceScheduleId": "sourceScheduleId",
        "systemPrompt": "systemPrompt",
        "variation": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "compactionConfig": {
              "summarization": {
                "instructions": "instructions"
              },
              "toolResultClearing": {
                "preserveRecentResults": 0
              },
              "triggerThreshold": 0
            },
            "constraints": {
              "maxSubObjectives": 0,
              "maxToolCalls": 0
            },
            "description": "description",
            "enableEpisodicMemory": true,
            "episodicMemoryTtl": 0,
            "modelConfig": {
              "modelId": "modelId",
              "temperature": 0
            },
            "progressiveDiscovery": {
              "hints": [
                "string"
              ],
              "maxTools": 0,
              "rerankThreshold": 0
            },
            "prompt": "prompt",
            "weight": 0
          },
          "info": {
            "assignments": [
              {
                "id": "id",
                "agent": {
                  "id": "id",
                  "name": "name"
                },
                "tool": {
                  "id": "id",
                  "name": "name"
                },
                "toolSet": {
                  "id": "id",
                  "name": "name"
                }
              }
            ],
            "createdBy": {
              "metadata": {
                "id": "id",
                "accountId": "accountId",
                "name": "name",
                "profileId": "profileId",
                "externalId": "externalId",
                "labels": {
                  "foo": "string"
                }
              },
              "spec": {
                "type": "PROFILE_TYPE_UNSPECIFIED",
                "email": "email",
                "name": "name"
              }
            },
            "feedbackCount": 0,
            "memoryLayerAssignments": [
              {
                "id": "id",
                "memoryLayer": {
                  "id": "id",
                  "name": "name"
                },
                "position": 0
              }
            ],
            "memoryLayerCount": 0,
            "model": {
              "id": "id",
              "accountId": "accountId",
              "createdAt": "2019-12-27T18:11:19.117Z",
              "name": "name",
              "profileId": "profileId",
              "workspaceId": "workspaceId",
              "bundleKey": "bundleKey",
              "externalId": "externalId",
              "labels": {
                "foo": "string"
              }
            },
            "score": 0,
            "subAgentCount": 0,
            "toolCount": 0,
            "toolSetCount": 0
          }
        }
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "status": {
        "state": "STATE_UNSPECIFIED",
        "message": "message"
      },
      "info": {
        "agent": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "agentVariation": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "effectiveMemoryStack": [
          {
            "memoryEntryId": "memoryEntryId",
            "memoryLayerId": "memoryLayerId"
          }
        ],
        "totalContextWindows": 0,
        "totalEvents": 0,
        "totalInputTokens": 0,
        "totalOutputTokens": 0,
        "totalToolCalls": 0
      },
      "lastFiveWindows": [
        {
          "data": {
            "completionTokens": 0,
            "objectiveId": "objectiveId",
            "previousWindowContinueInstructions": "previousWindowContinueInstructions",
            "promptTokens": 0,
            "sequence": 0
          },
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "info": {
            "createdBy": {
              "metadata": {
                "id": "id",
                "accountId": "accountId",
                "name": "name",
                "profileId": "profileId",
                "externalId": "externalId",
                "labels": {
                  "foo": "string"
                }
              },
              "spec": {
                "type": "PROFILE_TYPE_UNSPECIFIED",
                "email": "email",
                "name": "name"
              }
            },
            "objective": {
              "id": "id",
              "accountId": "accountId",
              "createdAt": "2019-12-27T18:11:19.117Z",
              "profileId": "profileId",
              "workspaceId": "workspaceId",
              "externalId": "externalId",
              "labels": {
                "foo": "string"
              }
            }
          }
        }
      ]
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Create a new objective

`objectives.create(workspace_id, **kwargs) -> Objective`

**post** `/v1/workspaces/{workspaceId}/objectives`

Creates a new objective in the workspace

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `data: ObjectiveData`

  - `agent: Agent`

    Agent resource

    - `metadata: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: AgentSpec`

      Agent specification (user-provided configuration)

      - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

        Status of the agent

        - `:AGENT_STATUS_UNSPECIFIED`

        - `:AGENT_STATUS_DRAFT`

        - `:AGENT_STATUS_PUBLISHED`

        - `:AGENT_STATUS_ARCHIVED`

      - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

        Controls how variations are automatically selected when creating objectives
        Defaults to RANDOM when unspecified

        - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

        - `:VARIATION_SELECTION_MODE_RANDOM`

        - `:VARIATION_SELECTION_MODE_WEIGHTED`

      - `description: String`

        Description of the agent's purpose

      - `input_data_schema: Hash[Symbol, untyped]`

        InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
        prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
        the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

      - `output_definition: Hash[Symbol, untyped]`

        Optional output definition for objectives created for this agent.
        When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
        Use this option when you want structured data to be created by your objectives.

      - `webhook_events_url: String`

        The URL that Cadenya will send events for any objective assigned to the agent.

    - `info: AgentInfo`

      AgentInfo contains simple information about an agent for display or quick reference

      - `created_by: Profile`

        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.

        - `metadata: AccountResourceMetadata`

          AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

          - `id: String`

            Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

          - `account_id: String`

            Account this resource belongs to for multi-tenant isolation (prefixed ULID)

          - `name: String`

            Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
            Required for resources that users interact with directly

          - `profile_id: String`

          - `external_id: String`

            External ID for the resource (e.g., a workflow ID from an external system)

          - `labels: Hash[Symbol, String]`

            Arbitrary key-value pairs for categorization and filtering
            Examples: {"environment": "production", "team": "platform", "version": "v2"}

        - `spec: ProfileSpec`

          Configuration for a profile.

          - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

            Whether this profile represents a human user, an API key, or a system
            principal.

            - `:PROFILE_TYPE_UNSPECIFIED`

            - `:PROFILE_TYPE_USER`

            - `:PROFILE_TYPE_API_KEY`

            - `:PROFILE_TYPE_SYSTEM`

          - `email: String`

            Email address of the profile. Required and unique within an account for
            user profiles.

          - `name: String`

            Display name (e.g., "Bobby Tables").

      - `variation_count: Integer`

  - `data: untyped`

    Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

  - `initial_message: String`

    The initial message sent to the agent. This becomes the first user message in the LLM chat history.

  - `memory_stack: Array[MemoryReference]`

    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_entry_id: String`

      When set, pushes only this entry from memory_layer_id onto the stack —
      behaves as a single-entry layer (only this key resolves at this
      position). The entry must belong to memory_layer_id; mismatches are
      rejected with InvalidArgument.

    - `memory_layer_id: String`

  - `output: Hash[Symbol, untyped]`

    The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

  - `output_definition: Hash[Symbol, untyped]`

    Snapshot of the agent spec's output_definition at objective creation time.
    When present, the objective will run an extraction step after the LLM finishes.

  - `parent_objective_id: String`

    A parent objective means the objective was spawned off using a separate agent to complete an objective

  - `secrets: Array[ObjectiveDataSecret]`

    Secrets that can be used in the headers for tool calls using the secret interpolation format.

    - `name: String`

    - `value: String`

  - `source_schedule_id: String`

    ID of the AgentSchedule that produced this objective, when applicable.
    Populated when the objective is created from a schedule fire; empty when
    the objective was created via CreateObjective directly.

  - `system_prompt: String`

    system_prompt is read-only, derived from the selected variation's prompt

  - `variation: AgentVariation`

    AgentVariation resource

    - `metadata: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `spec: AgentVariationSpec`

      AgentVariationSpec defines the operational configuration for a variation

      - `compaction_config: AgentVariationSpecCompactionConfig`

        CompactionConfig defines how context window compaction behaves for objectives using this variation.

        - `summarization: CompactionConfigSummarizationStrategy`

          SummarizationStrategy configures LLM-powered summarization of older conversation turns.

          - `instructions: String`

            Custom instructions that guide what the summarizer preserves.
            Replaces the default summarization prompt entirely.
            Example: "Preserve all code snippets, variable names, and technical decisions."

        - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

          ToolResultClearingStrategy configures clearing of older tool result content.

          - `preserve_recent_results: Integer`

            Number of most recent tool call results to keep intact.
            Older tool results have their content replaced with "[result cleared]"
            while preserving the assistant tool call message (function name, arguments).
            Default: 2

        - `trigger_threshold: Float`

          Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
          When input tokens reach this percentage of the model's limit, compaction triggers.
          Default: 0.75 (75%)

      - `constraints: AgentVariationSpecConstraints`

        Execution constraints

        - `max_sub_objectives: Integer`

          The maximum number of sub-objectives that can be created. 0 means no limit.

        - `max_tool_calls: Integer`

          The maximum number of tool calls that can be made. 0 means no limit.

      - `description: String`

        Human-readable description of what this variation does or when it should be used

      - `enable_episodic_memory: bool`

        Enable episodic memory for objectives using this variation.
        When true, the system automatically creates a document namespace for each objective
        using the objective's episodic_key as the external_id, allowing the agent to
        store and retrieve documents specific to that episode.

      - `episodic_memory_ttl: Integer`

        How long episodic memories should be retained.
        After this duration, episodic document namespaces can be automatically cleaned up.
        If not set, episodic memories are retained indefinitely.

      - `model_config: AgentVariationSpecModelConfig`

        ModelConfig defines the model configuration for a variation

        - `model_id: String`

          The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

        - `temperature: Float`

          Sampling temperature for model inference (0.0 to 1.0)
          Lower values produce more deterministic outputs, higher values increase randomness

      - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

        ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
        Max tools is the maximum number of tools that can be discovered per search.
        Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

        - `hints: Array[String]`

        - `max_tools: Integer`

        - `rerank_threshold: Float`

          Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
          which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
          the tool very closely match the query the tool search performed.

      - `prompt: String`

        The system prompt for this variation

      - `weight: Integer`

        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 on CreateObjectiveRequest.

    - `info: AgentVariationInfo`

      AgentVariationInfo provides read-only summary information about a variation

      - `assignments: Array[VariationAssignment]`

        All tools, tool sets, and sub-agents assigned to this variation.
        Populated on reads so clients can render a variation's full assignment
        list without calling the add/remove endpoints just to enumerate.

        - `id: String`

        - `agent: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

          - `id: String`

          - `name: String`

            Human-readable name of the referenced resource, populated by the server
            on reads for convenience. Absent on references to resources that do not
            have a name (e.g., objective tasks).

        - `tool: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

        - `tool_set: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

      - `created_by: Profile`

        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.

      - `feedback_count: Integer`

        Total number of objective feedbacks received for this variation

      - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

        Read-only list of memory layer assignments for this variation,
        returned in ascending `position` (bottom → top). Capped at 10 entries.

        - `id: String`

          Assignment row id — handle for removing the assignment. Distinct
          from the referenced memory layer's id.

        - `memory_layer: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

        - `position: Integer`

          Position in the variation's baseline stack. Lower values sit lower;
          the highest-position assignment is on top of the variation's
          baseline. Gaps are fine — only relative position matters. Positions
          must be unique within a variation; a request that would collide
          with an existing assignment's position is rejected with
          InvalidArgument.

      - `memory_layer_count: Integer`

        Count of memory layer assignments.

      - `model: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `score: Float`

        Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
        Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

      - `sub_agent_count: Integer`

        Number of sub-agents assigned to this variation

      - `tool_count: Integer`

        Number of individual tools assigned to this variation

      - `tool_set_count: Integer`

        Number of tool sets assigned to this variation

- `metadata: CreateOperationMetadata`

  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.

  - `external_id: String`

    External ID for the operation (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

- `variation_id: String`

  Optional explicit variation selection. Overrides the agent's variation_selection_mode.

### Returns

- `class Objective`

  - `data: ObjectiveData`

    - `agent: Agent`

      Agent resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: AgentSpec`

        Agent specification (user-provided configuration)

        - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

          Status of the agent

          - `:AGENT_STATUS_UNSPECIFIED`

          - `:AGENT_STATUS_DRAFT`

          - `:AGENT_STATUS_PUBLISHED`

          - `:AGENT_STATUS_ARCHIVED`

        - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

          Controls how variations are automatically selected when creating objectives
          Defaults to RANDOM when unspecified

          - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

          - `:VARIATION_SELECTION_MODE_RANDOM`

          - `:VARIATION_SELECTION_MODE_WEIGHTED`

        - `description: String`

          Description of the agent's purpose

        - `input_data_schema: Hash[Symbol, untyped]`

          InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
          prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
          the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

        - `output_definition: Hash[Symbol, untyped]`

          Optional output definition for objectives created for this agent.
          When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
          Use this option when you want structured data to be created by your objectives.

        - `webhook_events_url: String`

          The URL that Cadenya will send events for any objective assigned to the agent.

      - `info: AgentInfo`

        AgentInfo contains simple information about an agent for display or quick reference

        - `created_by: Profile`

          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.

          - `metadata: AccountResourceMetadata`

            AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `spec: ProfileSpec`

            Configuration for a profile.

            - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

              Whether this profile represents a human user, an API key, or a system
              principal.

              - `:PROFILE_TYPE_UNSPECIFIED`

              - `:PROFILE_TYPE_USER`

              - `:PROFILE_TYPE_API_KEY`

              - `:PROFILE_TYPE_SYSTEM`

            - `email: String`

              Email address of the profile. Required and unique within an account for
              user profiles.

            - `name: String`

              Display name (e.g., "Bobby Tables").

        - `variation_count: Integer`

    - `data: untyped`

      Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

    - `initial_message: String`

      The initial message sent to the agent. This becomes the first user message in the LLM chat history.

    - `memory_stack: Array[MemoryReference]`

      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_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `output: Hash[Symbol, untyped]`

      The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

    - `output_definition: Hash[Symbol, untyped]`

      Snapshot of the agent spec's output_definition at objective creation time.
      When present, the objective will run an extraction step after the LLM finishes.

    - `parent_objective_id: String`

      A parent objective means the objective was spawned off using a separate agent to complete an objective

    - `secrets: Array[ObjectiveDataSecret]`

      Secrets that can be used in the headers for tool calls using the secret interpolation format.

      - `name: String`

      - `value: String`

    - `source_schedule_id: String`

      ID of the AgentSchedule that produced this objective, when applicable.
      Populated when the objective is created from a schedule fire; empty when
      the objective was created via CreateObjective directly.

    - `system_prompt: String`

      system_prompt is read-only, derived from the selected variation's prompt

    - `variation: AgentVariation`

      AgentVariation resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `spec: AgentVariationSpec`

        AgentVariationSpec defines the operational configuration for a variation

        - `compaction_config: AgentVariationSpecCompactionConfig`

          CompactionConfig defines how context window compaction behaves for objectives using this variation.

          - `summarization: CompactionConfigSummarizationStrategy`

            SummarizationStrategy configures LLM-powered summarization of older conversation turns.

            - `instructions: String`

              Custom instructions that guide what the summarizer preserves.
              Replaces the default summarization prompt entirely.
              Example: "Preserve all code snippets, variable names, and technical decisions."

          - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

            ToolResultClearingStrategy configures clearing of older tool result content.

            - `preserve_recent_results: Integer`

              Number of most recent tool call results to keep intact.
              Older tool results have their content replaced with "[result cleared]"
              while preserving the assistant tool call message (function name, arguments).
              Default: 2

          - `trigger_threshold: Float`

            Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
            When input tokens reach this percentage of the model's limit, compaction triggers.
            Default: 0.75 (75%)

        - `constraints: AgentVariationSpecConstraints`

          Execution constraints

          - `max_sub_objectives: Integer`

            The maximum number of sub-objectives that can be created. 0 means no limit.

          - `max_tool_calls: Integer`

            The maximum number of tool calls that can be made. 0 means no limit.

        - `description: String`

          Human-readable description of what this variation does or when it should be used

        - `enable_episodic_memory: bool`

          Enable episodic memory for objectives using this variation.
          When true, the system automatically creates a document namespace for each objective
          using the objective's episodic_key as the external_id, allowing the agent to
          store and retrieve documents specific to that episode.

        - `episodic_memory_ttl: Integer`

          How long episodic memories should be retained.
          After this duration, episodic document namespaces can be automatically cleaned up.
          If not set, episodic memories are retained indefinitely.

        - `model_config: AgentVariationSpecModelConfig`

          ModelConfig defines the model configuration for a variation

          - `model_id: String`

            The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

          - `temperature: Float`

            Sampling temperature for model inference (0.0 to 1.0)
            Lower values produce more deterministic outputs, higher values increase randomness

        - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

          ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
          Max tools is the maximum number of tools that can be discovered per search.
          Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

          - `hints: Array[String]`

          - `max_tools: Integer`

          - `rerank_threshold: Float`

            Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
            which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
            the tool very closely match the query the tool search performed.

        - `prompt: String`

          The system prompt for this variation

        - `weight: Integer`

          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 on CreateObjectiveRequest.

      - `info: AgentVariationInfo`

        AgentVariationInfo provides read-only summary information about a variation

        - `assignments: Array[VariationAssignment]`

          All tools, tool sets, and sub-agents assigned to this variation.
          Populated on reads so clients can render a variation's full assignment
          list without calling the add/remove endpoints just to enumerate.

          - `id: String`

          - `agent: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

            - `id: String`

            - `name: String`

              Human-readable name of the referenced resource, populated by the server
              on reads for convenience. Absent on references to resources that do not
              have a name (e.g., objective tasks).

          - `tool: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `tool_set: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

        - `created_by: Profile`

          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.

        - `feedback_count: Integer`

          Total number of objective feedbacks received for this variation

        - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

          Read-only list of memory layer assignments for this variation,
          returned in ascending `position` (bottom → top). Capped at 10 entries.

          - `id: String`

            Assignment row id — handle for removing the assignment. Distinct
            from the referenced memory layer's id.

          - `memory_layer: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `position: Integer`

            Position in the variation's baseline stack. Lower values sit lower;
            the highest-position assignment is on top of the variation's
            baseline. Gaps are fine — only relative position matters. Positions
            must be unique within a variation; a request that would collide
            with an existing assignment's position is rejected with
            InvalidArgument.

        - `memory_layer_count: Integer`

          Count of memory layer assignments.

        - `model: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `score: Float`

          Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
          Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

        - `sub_agent_count: Integer`

          Number of sub-agents assigned to this variation

        - `tool_count: Integer`

          Number of individual tools assigned to this variation

        - `tool_set_count: Integer`

          Number of tool sets assigned to this variation

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: ObjectiveStatus`

    - `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

      - `:STATE_UNSPECIFIED`

      - `:STATE_PENDING`

      - `:STATE_RUNNING`

      - `:STATE_WAITING`

      - `:STATE_FAILED`

      - `:STATE_CANCELLED`

      - `:STATE_FINALIZED`

    - `message: String`

  - `info: ObjectiveInfo`

    ObjectiveInfo provides read-only aggregated statistics about an objective's execution

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `agent_variation: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `created_by: Profile`

      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.

    - `effective_memory_stack: Array[MemoryReference]`

      The effective memory stack at objective creation time, flattened
      from the variation's baseline plus ObjectiveData.memory_stack. Order
      is push order (last = top). Returned on reads so clients can see
      exactly what stack the objective is using without having to re-join
      variation state.

      - `memory_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `total_context_windows: Integer`

      Total number of context windows that this objective has generated

    - `total_events: Integer`

      Total number of events generated during this objective's execution

    - `total_input_tokens: Integer`

      Total input tokens consumed across all LLM completions across all context windows

    - `total_output_tokens: Integer`

      Total output tokens generated across all LLM completions across all context windows

    - `total_tool_calls: Integer`

      Total number of tool calls made during execution

  - `last_five_windows: Array[ObjectiveContextWindow]`

    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).

    - `data: ObjectiveContextWindowData`

      - `completion_tokens: Integer`

        A calculated value for how many completion tokens (output tokens) have been used in this context window

      - `objective_id: String`

        The objective's ID that this window belongs to

      - `previous_window_continue_instructions: String`

        The instructions for this window to continue from a previous window's chat history.

      - `prompt_tokens: Integer`

        A calculated value for how many prompt tokens (input tokens) have been used in this context window

      - `sequence: Integer`

        sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
        to calculate how many context windows an objective has.

    - `metadata: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `info: Info{ created_by, objective}`

      - `created_by: Profile`

        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.

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective = cadenya.objectives.create("workspaceId", agent_id: "agentId", data: {})

puts(objective)
```

#### Response

```json
{
  "data": {
    "agent": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "status": "AGENT_STATUS_UNSPECIFIED",
        "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
        "description": "description",
        "inputDataSchema": {
          "foo": "bar"
        },
        "outputDefinition": {
          "foo": "bar"
        },
        "webhookEventsUrl": "webhookEventsUrl"
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "variationCount": 0
      }
    },
    "data": {},
    "initialMessage": "initialMessage",
    "memoryStack": [
      {
        "memoryEntryId": "memoryEntryId",
        "memoryLayerId": "memoryLayerId"
      }
    ],
    "output": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "parentObjectiveId": "parentObjectiveId",
    "secrets": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "sourceScheduleId": "sourceScheduleId",
    "systemPrompt": "systemPrompt",
    "variation": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "compactionConfig": {
          "summarization": {
            "instructions": "instructions"
          },
          "toolResultClearing": {
            "preserveRecentResults": 0
          },
          "triggerThreshold": 0
        },
        "constraints": {
          "maxSubObjectives": 0,
          "maxToolCalls": 0
        },
        "description": "description",
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 0,
        "modelConfig": {
          "modelId": "modelId",
          "temperature": 0
        },
        "progressiveDiscovery": {
          "hints": [
            "string"
          ],
          "maxTools": 0,
          "rerankThreshold": 0
        },
        "prompt": "prompt",
        "weight": 0
      },
      "info": {
        "assignments": [
          {
            "id": "id",
            "agent": {
              "id": "id",
              "name": "name"
            },
            "tool": {
              "id": "id",
              "name": "name"
            },
            "toolSet": {
              "id": "id",
              "name": "name"
            }
          }
        ],
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "feedbackCount": 0,
        "memoryLayerAssignments": [
          {
            "id": "id",
            "memoryLayer": {
              "id": "id",
              "name": "name"
            },
            "position": 0
          }
        ],
        "memoryLayerCount": 0,
        "model": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "score": 0,
        "subAgentCount": 0,
        "toolCount": 0,
        "toolSetCount": 0
      }
    }
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "status": {
    "state": "STATE_UNSPECIFIED",
    "message": "message"
  },
  "info": {
    "agent": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "agentVariation": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "effectiveMemoryStack": [
      {
        "memoryEntryId": "memoryEntryId",
        "memoryLayerId": "memoryLayerId"
      }
    ],
    "totalContextWindows": 0,
    "totalEvents": 0,
    "totalInputTokens": 0,
    "totalOutputTokens": 0,
    "totalToolCalls": 0
  },
  "lastFiveWindows": [
    {
      "data": {
        "completionTokens": 0,
        "objectiveId": "objectiveId",
        "previousWindowContinueInstructions": "previousWindowContinueInstructions",
        "promptTokens": 0,
        "sequence": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "objective": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        }
      }
    }
  ]
}
```

## Get an objective by ID

`objectives.retrieve(id, **kwargs) -> Objective`

**get** `/v1/workspaces/{workspaceId}/objectives/{id}`

Retrieves an objective by ID from the workspace

### Parameters

- `workspace_id: String`

- `id: String`

### Returns

- `class Objective`

  - `data: ObjectiveData`

    - `agent: Agent`

      Agent resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: AgentSpec`

        Agent specification (user-provided configuration)

        - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

          Status of the agent

          - `:AGENT_STATUS_UNSPECIFIED`

          - `:AGENT_STATUS_DRAFT`

          - `:AGENT_STATUS_PUBLISHED`

          - `:AGENT_STATUS_ARCHIVED`

        - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

          Controls how variations are automatically selected when creating objectives
          Defaults to RANDOM when unspecified

          - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

          - `:VARIATION_SELECTION_MODE_RANDOM`

          - `:VARIATION_SELECTION_MODE_WEIGHTED`

        - `description: String`

          Description of the agent's purpose

        - `input_data_schema: Hash[Symbol, untyped]`

          InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
          prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
          the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

        - `output_definition: Hash[Symbol, untyped]`

          Optional output definition for objectives created for this agent.
          When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
          Use this option when you want structured data to be created by your objectives.

        - `webhook_events_url: String`

          The URL that Cadenya will send events for any objective assigned to the agent.

      - `info: AgentInfo`

        AgentInfo contains simple information about an agent for display or quick reference

        - `created_by: Profile`

          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.

          - `metadata: AccountResourceMetadata`

            AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `spec: ProfileSpec`

            Configuration for a profile.

            - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

              Whether this profile represents a human user, an API key, or a system
              principal.

              - `:PROFILE_TYPE_UNSPECIFIED`

              - `:PROFILE_TYPE_USER`

              - `:PROFILE_TYPE_API_KEY`

              - `:PROFILE_TYPE_SYSTEM`

            - `email: String`

              Email address of the profile. Required and unique within an account for
              user profiles.

            - `name: String`

              Display name (e.g., "Bobby Tables").

        - `variation_count: Integer`

    - `data: untyped`

      Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

    - `initial_message: String`

      The initial message sent to the agent. This becomes the first user message in the LLM chat history.

    - `memory_stack: Array[MemoryReference]`

      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_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `output: Hash[Symbol, untyped]`

      The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

    - `output_definition: Hash[Symbol, untyped]`

      Snapshot of the agent spec's output_definition at objective creation time.
      When present, the objective will run an extraction step after the LLM finishes.

    - `parent_objective_id: String`

      A parent objective means the objective was spawned off using a separate agent to complete an objective

    - `secrets: Array[ObjectiveDataSecret]`

      Secrets that can be used in the headers for tool calls using the secret interpolation format.

      - `name: String`

      - `value: String`

    - `source_schedule_id: String`

      ID of the AgentSchedule that produced this objective, when applicable.
      Populated when the objective is created from a schedule fire; empty when
      the objective was created via CreateObjective directly.

    - `system_prompt: String`

      system_prompt is read-only, derived from the selected variation's prompt

    - `variation: AgentVariation`

      AgentVariation resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `spec: AgentVariationSpec`

        AgentVariationSpec defines the operational configuration for a variation

        - `compaction_config: AgentVariationSpecCompactionConfig`

          CompactionConfig defines how context window compaction behaves for objectives using this variation.

          - `summarization: CompactionConfigSummarizationStrategy`

            SummarizationStrategy configures LLM-powered summarization of older conversation turns.

            - `instructions: String`

              Custom instructions that guide what the summarizer preserves.
              Replaces the default summarization prompt entirely.
              Example: "Preserve all code snippets, variable names, and technical decisions."

          - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

            ToolResultClearingStrategy configures clearing of older tool result content.

            - `preserve_recent_results: Integer`

              Number of most recent tool call results to keep intact.
              Older tool results have their content replaced with "[result cleared]"
              while preserving the assistant tool call message (function name, arguments).
              Default: 2

          - `trigger_threshold: Float`

            Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
            When input tokens reach this percentage of the model's limit, compaction triggers.
            Default: 0.75 (75%)

        - `constraints: AgentVariationSpecConstraints`

          Execution constraints

          - `max_sub_objectives: Integer`

            The maximum number of sub-objectives that can be created. 0 means no limit.

          - `max_tool_calls: Integer`

            The maximum number of tool calls that can be made. 0 means no limit.

        - `description: String`

          Human-readable description of what this variation does or when it should be used

        - `enable_episodic_memory: bool`

          Enable episodic memory for objectives using this variation.
          When true, the system automatically creates a document namespace for each objective
          using the objective's episodic_key as the external_id, allowing the agent to
          store and retrieve documents specific to that episode.

        - `episodic_memory_ttl: Integer`

          How long episodic memories should be retained.
          After this duration, episodic document namespaces can be automatically cleaned up.
          If not set, episodic memories are retained indefinitely.

        - `model_config: AgentVariationSpecModelConfig`

          ModelConfig defines the model configuration for a variation

          - `model_id: String`

            The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

          - `temperature: Float`

            Sampling temperature for model inference (0.0 to 1.0)
            Lower values produce more deterministic outputs, higher values increase randomness

        - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

          ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
          Max tools is the maximum number of tools that can be discovered per search.
          Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

          - `hints: Array[String]`

          - `max_tools: Integer`

          - `rerank_threshold: Float`

            Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
            which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
            the tool very closely match the query the tool search performed.

        - `prompt: String`

          The system prompt for this variation

        - `weight: Integer`

          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 on CreateObjectiveRequest.

      - `info: AgentVariationInfo`

        AgentVariationInfo provides read-only summary information about a variation

        - `assignments: Array[VariationAssignment]`

          All tools, tool sets, and sub-agents assigned to this variation.
          Populated on reads so clients can render a variation's full assignment
          list without calling the add/remove endpoints just to enumerate.

          - `id: String`

          - `agent: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

            - `id: String`

            - `name: String`

              Human-readable name of the referenced resource, populated by the server
              on reads for convenience. Absent on references to resources that do not
              have a name (e.g., objective tasks).

          - `tool: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `tool_set: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

        - `created_by: Profile`

          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.

        - `feedback_count: Integer`

          Total number of objective feedbacks received for this variation

        - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

          Read-only list of memory layer assignments for this variation,
          returned in ascending `position` (bottom → top). Capped at 10 entries.

          - `id: String`

            Assignment row id — handle for removing the assignment. Distinct
            from the referenced memory layer's id.

          - `memory_layer: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `position: Integer`

            Position in the variation's baseline stack. Lower values sit lower;
            the highest-position assignment is on top of the variation's
            baseline. Gaps are fine — only relative position matters. Positions
            must be unique within a variation; a request that would collide
            with an existing assignment's position is rejected with
            InvalidArgument.

        - `memory_layer_count: Integer`

          Count of memory layer assignments.

        - `model: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `score: Float`

          Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
          Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

        - `sub_agent_count: Integer`

          Number of sub-agents assigned to this variation

        - `tool_count: Integer`

          Number of individual tools assigned to this variation

        - `tool_set_count: Integer`

          Number of tool sets assigned to this variation

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: ObjectiveStatus`

    - `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

      - `:STATE_UNSPECIFIED`

      - `:STATE_PENDING`

      - `:STATE_RUNNING`

      - `:STATE_WAITING`

      - `:STATE_FAILED`

      - `:STATE_CANCELLED`

      - `:STATE_FINALIZED`

    - `message: String`

  - `info: ObjectiveInfo`

    ObjectiveInfo provides read-only aggregated statistics about an objective's execution

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `agent_variation: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `created_by: Profile`

      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.

    - `effective_memory_stack: Array[MemoryReference]`

      The effective memory stack at objective creation time, flattened
      from the variation's baseline plus ObjectiveData.memory_stack. Order
      is push order (last = top). Returned on reads so clients can see
      exactly what stack the objective is using without having to re-join
      variation state.

      - `memory_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `total_context_windows: Integer`

      Total number of context windows that this objective has generated

    - `total_events: Integer`

      Total number of events generated during this objective's execution

    - `total_input_tokens: Integer`

      Total input tokens consumed across all LLM completions across all context windows

    - `total_output_tokens: Integer`

      Total output tokens generated across all LLM completions across all context windows

    - `total_tool_calls: Integer`

      Total number of tool calls made during execution

  - `last_five_windows: Array[ObjectiveContextWindow]`

    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).

    - `data: ObjectiveContextWindowData`

      - `completion_tokens: Integer`

        A calculated value for how many completion tokens (output tokens) have been used in this context window

      - `objective_id: String`

        The objective's ID that this window belongs to

      - `previous_window_continue_instructions: String`

        The instructions for this window to continue from a previous window's chat history.

      - `prompt_tokens: Integer`

        A calculated value for how many prompt tokens (input tokens) have been used in this context window

      - `sequence: Integer`

        sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
        to calculate how many context windows an objective has.

    - `metadata: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `info: Info{ created_by, objective}`

      - `created_by: Profile`

        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.

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective = cadenya.objectives.retrieve("id", workspace_id: "workspaceId")

puts(objective)
```

#### Response

```json
{
  "data": {
    "agent": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "status": "AGENT_STATUS_UNSPECIFIED",
        "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
        "description": "description",
        "inputDataSchema": {
          "foo": "bar"
        },
        "outputDefinition": {
          "foo": "bar"
        },
        "webhookEventsUrl": "webhookEventsUrl"
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "variationCount": 0
      }
    },
    "data": {},
    "initialMessage": "initialMessage",
    "memoryStack": [
      {
        "memoryEntryId": "memoryEntryId",
        "memoryLayerId": "memoryLayerId"
      }
    ],
    "output": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "parentObjectiveId": "parentObjectiveId",
    "secrets": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "sourceScheduleId": "sourceScheduleId",
    "systemPrompt": "systemPrompt",
    "variation": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "compactionConfig": {
          "summarization": {
            "instructions": "instructions"
          },
          "toolResultClearing": {
            "preserveRecentResults": 0
          },
          "triggerThreshold": 0
        },
        "constraints": {
          "maxSubObjectives": 0,
          "maxToolCalls": 0
        },
        "description": "description",
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 0,
        "modelConfig": {
          "modelId": "modelId",
          "temperature": 0
        },
        "progressiveDiscovery": {
          "hints": [
            "string"
          ],
          "maxTools": 0,
          "rerankThreshold": 0
        },
        "prompt": "prompt",
        "weight": 0
      },
      "info": {
        "assignments": [
          {
            "id": "id",
            "agent": {
              "id": "id",
              "name": "name"
            },
            "tool": {
              "id": "id",
              "name": "name"
            },
            "toolSet": {
              "id": "id",
              "name": "name"
            }
          }
        ],
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "feedbackCount": 0,
        "memoryLayerAssignments": [
          {
            "id": "id",
            "memoryLayer": {
              "id": "id",
              "name": "name"
            },
            "position": 0
          }
        ],
        "memoryLayerCount": 0,
        "model": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "score": 0,
        "subAgentCount": 0,
        "toolCount": 0,
        "toolSetCount": 0
      }
    }
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "status": {
    "state": "STATE_UNSPECIFIED",
    "message": "message"
  },
  "info": {
    "agent": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "agentVariation": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "effectiveMemoryStack": [
      {
        "memoryEntryId": "memoryEntryId",
        "memoryLayerId": "memoryLayerId"
      }
    ],
    "totalContextWindows": 0,
    "totalEvents": 0,
    "totalInputTokens": 0,
    "totalOutputTokens": 0,
    "totalToolCalls": 0
  },
  "lastFiveWindows": [
    {
      "data": {
        "completionTokens": 0,
        "objectiveId": "objectiveId",
        "previousWindowContinueInstructions": "previousWindowContinueInstructions",
        "promptTokens": 0,
        "sequence": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "objective": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        }
      }
    }
  ]
}
```

## List objective events

`objectives.list_events(objective_id, **kwargs) -> CursorPagination<ObjectiveListEventsResponse>`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/events`

Lists all events for an objective

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `include_info: bool`

  When set to true you may use more of your alloted API rate-limit

- `limit: Integer`

  Maximum number of results to return

- `since_event_id: String`

  Optional string to fetch events since an ID

- `sort_order: String`

  Sort order for results (asc or desc by creation time)

- `window_id: String`

  Optional context window ID to filter events by

### Returns

- `class ObjectiveListEventsResponse`

  - `data: ObjectiveEventData`

    - `assistant_message: AssistantMessage`

      - `content: String`

      - `tool_calls: Array[AssistantToolCall]`

        - `arguments: String`

        - `function_name: String`

        - `tool: CallableTool`

          CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
          might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

          - `agent: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `created_at: Time`

              Timestamp when this resource was created

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

              ID of the actor (user or service account) that created this resource

            - `workspace_id: String`

              Workspace this resource belongs to for organizational grouping (prefixed ULID)

            - `bundle_key: String`

              Optional bundle ownership key. When set, indicates the resource is
              managed by a configuration bundle identified by this key. Used by
              BulkWorkspaceResources.Apply to track which resources belong to which
              bundle for reconciliation / soft-delete on re-apply.

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `cadenya_provided_tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

          - `tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `cancelled: Cancelled{ message}`

      ObjectiveCancelled is the terminal event written when an objective is
      cancelled. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `message: String`

        Optional human-readable note recorded at cancel time. Today the workflow
        sets "Cancelled" but this field leaves room for richer reasons (e.g.
        "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted").

    - `context_window_compacted: ContextWindowCompacted`

      - `messages_compacted: Integer`

        Number of messages that were compacted

      - `new_context_window: ObjectiveContextWindowData`

        The new context window created by this compaction

        - `completion_tokens: Integer`

          A calculated value for how many completion tokens (output tokens) have been used in this context window

        - `objective_id: String`

          The objective's ID that this window belongs to

        - `previous_window_continue_instructions: String`

          The instructions for this window to continue from a previous window's chat history.

        - `prompt_tokens: Integer`

          A calculated value for how many prompt tokens (input tokens) have been used in this context window

        - `sequence: Integer`

          sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
          to calculate how many context windows an objective has.

      - `strategies: Array[String]`

        The strategies that were applied during this compaction

      - `summary: String`

        The summary generated by the summarization strategy, if used.

    - `error: ObjectiveError`

      - `message: String`

      - `type: String`

    - `finalized: Finalized{ output}`

      ObjectiveFinalized is the terminal event written when an objective is
      finalized. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `output: untyped`

        If the objective was created with an output schema, and the agent
        successfully completed the objective, this field will contain the
        structured output of the objective.

    - `memory_read: MemoryRead`

      MemoryRead is emitted each time the agent resolves a key against the
      memory stack and loads an entry. Lookups that miss (key not found in
      any layer) do not emit this event.

      - `memory_entry_id: String`

        The specific entry that was read.

      - `memory_layer_id: String`

        The layer the entry resolved to. The top-most layer that contained
        the key — other layers beneath it that also contained the key are
        shadowed and not referenced here.

      - `message: String`

        Human-readable description of the read, set by the runtime. For
        example: "Loaded skill", "Resolved context key". Not machine-parsed;
        intended for UI display alongside the other events in an objective's
        timeline.

    - `sub_agent_spawned: SubAgentSpawned`

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

        - `id: String`

          Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

        - `account_id: String`

          Account this operation belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this operation was created
          ULID includes timestamp information, but this explicit field enables easier querying

        - `profile_id: String`

          ID of the actor (user or service account) that created this operation

        - `workspace_id: String`

          Workspace this operation belongs to for organizational grouping (prefixed ULID)

        - `external_id: String`

          External ID for the operation (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

      - `task: String`

    - `sub_agent_updated: SubAgentUpdated`

      - `agent: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `message: String`

      - `objective: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

      - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

        - `:STATUS_UNSPECIFIED`

        - `:STATUS_PENDING`

        - `:STATUS_RUNNING`

        - `:STATUS_COMPLETED`

        - `:STATUS_FAILED`

        - `:STATUS_CANCELLED`

    - `tool_approval_requested: ToolApprovalRequested`

      - `tool_call_id: String`

        The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

    - `tool_approved: ToolApproved`

      - `tool_call_id: String`

        The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

    - `tool_called: ToolCalled`

      - `tool_call_id: String`

        The ID of the objective tool call record that was executed.

    - `tool_denied: ToolDenied`

      - `memo: String`

        The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

      - `tool_call_id: String`

        The ID of the objective tool call record that was denied via the DenyToolCall RPC.

    - `tool_error: ToolError`

      - `message: String`

      - `tool_call_id: String`

        The ID of the objective tool call record that encountered an error during execution.

    - `tool_result: ToolResult`

      - `content: String`

      - `tool_call_id: String`

    - `type: String`

    - `user_message: UserMessage`

      - `content: String`

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `context_window_id: String`

  - `info: ObjectiveEventInfo`

    - `created_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.list_events("objectiveId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "assistantMessage": {
          "content": "content",
          "toolCalls": [
            {
              "arguments": "arguments",
              "functionName": "functionName",
              "tool": {
                "agent": {
                  "id": "id",
                  "accountId": "accountId",
                  "createdAt": "2019-12-27T18:11:19.117Z",
                  "name": "name",
                  "profileId": "profileId",
                  "workspaceId": "workspaceId",
                  "bundleKey": "bundleKey",
                  "externalId": "externalId",
                  "labels": {
                    "foo": "string"
                  }
                },
                "cadenyaProvidedTool": {
                  "id": "id",
                  "accountId": "accountId",
                  "createdAt": "2019-12-27T18:11:19.117Z",
                  "name": "name",
                  "profileId": "profileId",
                  "workspaceId": "workspaceId",
                  "bundleKey": "bundleKey",
                  "externalId": "externalId",
                  "labels": {
                    "foo": "string"
                  }
                },
                "tool": {
                  "id": "id",
                  "accountId": "accountId",
                  "createdAt": "2019-12-27T18:11:19.117Z",
                  "name": "name",
                  "profileId": "profileId",
                  "workspaceId": "workspaceId",
                  "bundleKey": "bundleKey",
                  "externalId": "externalId",
                  "labels": {
                    "foo": "string"
                  }
                }
              }
            }
          ]
        },
        "cancelled": {
          "message": "message"
        },
        "contextWindowCompacted": {
          "messagesCompacted": 0,
          "newContextWindow": {
            "completionTokens": 0,
            "objectiveId": "objectiveId",
            "previousWindowContinueInstructions": "previousWindowContinueInstructions",
            "promptTokens": 0,
            "sequence": 0
          },
          "strategies": [
            "string"
          ],
          "summary": "summary"
        },
        "error": {
          "message": "message",
          "type": "type"
        },
        "finalized": {
          "output": {}
        },
        "memoryRead": {
          "memoryEntryId": "memoryEntryId",
          "memoryLayerId": "memoryLayerId",
          "message": "message"
        },
        "subAgentSpawned": {
          "agent": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "objective": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "task": "task"
        },
        "subAgentUpdated": {
          "agent": {
            "id": "id",
            "name": "name"
          },
          "message": "message",
          "objective": {
            "id": "id",
            "name": "name"
          },
          "status": "STATUS_UNSPECIFIED"
        },
        "toolApprovalRequested": {
          "toolCallId": "toolCallId"
        },
        "toolApproved": {
          "toolCallId": "toolCallId"
        },
        "toolCalled": {
          "toolCallId": "toolCallId"
        },
        "toolDenied": {
          "memo": "memo",
          "toolCallId": "toolCallId"
        },
        "toolError": {
          "message": "message",
          "toolCallId": "toolCallId"
        },
        "toolResult": {
          "content": "content",
          "toolCallId": "toolCallId"
        },
        "type": "type",
        "userMessage": {
          "content": "content"
        }
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "contextWindowId": "contextWindowId",
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "objective": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Continue an objective

`objectives.continue(objective_id, **kwargs) -> ObjectiveContinueResponse`

**post** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/continue`

Continues an objective that has completed

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `enqueue: bool`

  When set to true, the message will be enqueued for when the agent loop is available to process it.

- `message: String`

  The message to continue an objective that has completed (or you are enqueing)

- `secrets: Array[Secret{ name, value}]`

  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)

  - `name: String`

  - `value: String`

### Returns

- `class ObjectiveContinueResponse`

  - `data: ObjectiveEventData`

    - `assistant_message: AssistantMessage`

      - `content: String`

      - `tool_calls: Array[AssistantToolCall]`

        - `arguments: String`

        - `function_name: String`

        - `tool: CallableTool`

          CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
          might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

          - `agent: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `created_at: Time`

              Timestamp when this resource was created

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

              ID of the actor (user or service account) that created this resource

            - `workspace_id: String`

              Workspace this resource belongs to for organizational grouping (prefixed ULID)

            - `bundle_key: String`

              Optional bundle ownership key. When set, indicates the resource is
              managed by a configuration bundle identified by this key. Used by
              BulkWorkspaceResources.Apply to track which resources belong to which
              bundle for reconciliation / soft-delete on re-apply.

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `cadenya_provided_tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

          - `tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `cancelled: Cancelled{ message}`

      ObjectiveCancelled is the terminal event written when an objective is
      cancelled. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `message: String`

        Optional human-readable note recorded at cancel time. Today the workflow
        sets "Cancelled" but this field leaves room for richer reasons (e.g.
        "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted").

    - `context_window_compacted: ContextWindowCompacted`

      - `messages_compacted: Integer`

        Number of messages that were compacted

      - `new_context_window: ObjectiveContextWindowData`

        The new context window created by this compaction

        - `completion_tokens: Integer`

          A calculated value for how many completion tokens (output tokens) have been used in this context window

        - `objective_id: String`

          The objective's ID that this window belongs to

        - `previous_window_continue_instructions: String`

          The instructions for this window to continue from a previous window's chat history.

        - `prompt_tokens: Integer`

          A calculated value for how many prompt tokens (input tokens) have been used in this context window

        - `sequence: Integer`

          sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
          to calculate how many context windows an objective has.

      - `strategies: Array[String]`

        The strategies that were applied during this compaction

      - `summary: String`

        The summary generated by the summarization strategy, if used.

    - `error: ObjectiveError`

      - `message: String`

      - `type: String`

    - `finalized: Finalized{ output}`

      ObjectiveFinalized is the terminal event written when an objective is
      finalized. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `output: untyped`

        If the objective was created with an output schema, and the agent
        successfully completed the objective, this field will contain the
        structured output of the objective.

    - `memory_read: MemoryRead`

      MemoryRead is emitted each time the agent resolves a key against the
      memory stack and loads an entry. Lookups that miss (key not found in
      any layer) do not emit this event.

      - `memory_entry_id: String`

        The specific entry that was read.

      - `memory_layer_id: String`

        The layer the entry resolved to. The top-most layer that contained
        the key — other layers beneath it that also contained the key are
        shadowed and not referenced here.

      - `message: String`

        Human-readable description of the read, set by the runtime. For
        example: "Loaded skill", "Resolved context key". Not machine-parsed;
        intended for UI display alongside the other events in an objective's
        timeline.

    - `sub_agent_spawned: SubAgentSpawned`

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

        - `id: String`

          Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

        - `account_id: String`

          Account this operation belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this operation was created
          ULID includes timestamp information, but this explicit field enables easier querying

        - `profile_id: String`

          ID of the actor (user or service account) that created this operation

        - `workspace_id: String`

          Workspace this operation belongs to for organizational grouping (prefixed ULID)

        - `external_id: String`

          External ID for the operation (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

      - `task: String`

    - `sub_agent_updated: SubAgentUpdated`

      - `agent: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `message: String`

      - `objective: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

      - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

        - `:STATUS_UNSPECIFIED`

        - `:STATUS_PENDING`

        - `:STATUS_RUNNING`

        - `:STATUS_COMPLETED`

        - `:STATUS_FAILED`

        - `:STATUS_CANCELLED`

    - `tool_approval_requested: ToolApprovalRequested`

      - `tool_call_id: String`

        The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

    - `tool_approved: ToolApproved`

      - `tool_call_id: String`

        The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

    - `tool_called: ToolCalled`

      - `tool_call_id: String`

        The ID of the objective tool call record that was executed.

    - `tool_denied: ToolDenied`

      - `memo: String`

        The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

      - `tool_call_id: String`

        The ID of the objective tool call record that was denied via the DenyToolCall RPC.

    - `tool_error: ToolError`

      - `message: String`

      - `tool_call_id: String`

        The ID of the objective tool call record that encountered an error during execution.

    - `tool_result: ToolResult`

      - `content: String`

      - `tool_call_id: String`

    - `type: String`

    - `user_message: UserMessage`

      - `content: String`

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `context_window_id: String`

  - `info: ObjectiveEventInfo`

    - `created_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

response = cadenya.objectives.continue("objectiveId", workspace_id: "workspaceId")

puts(response)
```

#### Response

```json
{
  "data": {
    "assistantMessage": {
      "content": "content",
      "toolCalls": [
        {
          "arguments": "arguments",
          "functionName": "functionName",
          "tool": {
            "agent": {
              "id": "id",
              "accountId": "accountId",
              "createdAt": "2019-12-27T18:11:19.117Z",
              "name": "name",
              "profileId": "profileId",
              "workspaceId": "workspaceId",
              "bundleKey": "bundleKey",
              "externalId": "externalId",
              "labels": {
                "foo": "string"
              }
            },
            "cadenyaProvidedTool": {
              "id": "id",
              "accountId": "accountId",
              "createdAt": "2019-12-27T18:11:19.117Z",
              "name": "name",
              "profileId": "profileId",
              "workspaceId": "workspaceId",
              "bundleKey": "bundleKey",
              "externalId": "externalId",
              "labels": {
                "foo": "string"
              }
            },
            "tool": {
              "id": "id",
              "accountId": "accountId",
              "createdAt": "2019-12-27T18:11:19.117Z",
              "name": "name",
              "profileId": "profileId",
              "workspaceId": "workspaceId",
              "bundleKey": "bundleKey",
              "externalId": "externalId",
              "labels": {
                "foo": "string"
              }
            }
          }
        }
      ]
    },
    "cancelled": {
      "message": "message"
    },
    "contextWindowCompacted": {
      "messagesCompacted": 0,
      "newContextWindow": {
        "completionTokens": 0,
        "objectiveId": "objectiveId",
        "previousWindowContinueInstructions": "previousWindowContinueInstructions",
        "promptTokens": 0,
        "sequence": 0
      },
      "strategies": [
        "string"
      ],
      "summary": "summary"
    },
    "error": {
      "message": "message",
      "type": "type"
    },
    "finalized": {
      "output": {}
    },
    "memoryRead": {
      "memoryEntryId": "memoryEntryId",
      "memoryLayerId": "memoryLayerId",
      "message": "message"
    },
    "subAgentSpawned": {
      "agent": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "objective": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "task": "task"
    },
    "subAgentUpdated": {
      "agent": {
        "id": "id",
        "name": "name"
      },
      "message": "message",
      "objective": {
        "id": "id",
        "name": "name"
      },
      "status": "STATUS_UNSPECIFIED"
    },
    "toolApprovalRequested": {
      "toolCallId": "toolCallId"
    },
    "toolApproved": {
      "toolCallId": "toolCallId"
    },
    "toolCalled": {
      "toolCallId": "toolCallId"
    },
    "toolDenied": {
      "memo": "memo",
      "toolCallId": "toolCallId"
    },
    "toolError": {
      "message": "message",
      "toolCallId": "toolCallId"
    },
    "toolResult": {
      "content": "content",
      "toolCallId": "toolCallId"
    },
    "type": "type",
    "userMessage": {
      "content": "content"
    }
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "contextWindowId": "contextWindowId",
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "objective": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    }
  }
}
```

## Cancel an objective

`objectives.cancel(objective_id, **kwargs) -> Objective`

**post** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/cancel`

Cancels a running or pending objective. The objective's state will be set to STATE_CANCELLED.

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `reason: String`

  Optional reason for cancellation

### Returns

- `class Objective`

  - `data: ObjectiveData`

    - `agent: Agent`

      Agent resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: AgentSpec`

        Agent specification (user-provided configuration)

        - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

          Status of the agent

          - `:AGENT_STATUS_UNSPECIFIED`

          - `:AGENT_STATUS_DRAFT`

          - `:AGENT_STATUS_PUBLISHED`

          - `:AGENT_STATUS_ARCHIVED`

        - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

          Controls how variations are automatically selected when creating objectives
          Defaults to RANDOM when unspecified

          - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

          - `:VARIATION_SELECTION_MODE_RANDOM`

          - `:VARIATION_SELECTION_MODE_WEIGHTED`

        - `description: String`

          Description of the agent's purpose

        - `input_data_schema: Hash[Symbol, untyped]`

          InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
          prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
          the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

        - `output_definition: Hash[Symbol, untyped]`

          Optional output definition for objectives created for this agent.
          When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
          Use this option when you want structured data to be created by your objectives.

        - `webhook_events_url: String`

          The URL that Cadenya will send events for any objective assigned to the agent.

      - `info: AgentInfo`

        AgentInfo contains simple information about an agent for display or quick reference

        - `created_by: Profile`

          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.

          - `metadata: AccountResourceMetadata`

            AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `spec: ProfileSpec`

            Configuration for a profile.

            - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

              Whether this profile represents a human user, an API key, or a system
              principal.

              - `:PROFILE_TYPE_UNSPECIFIED`

              - `:PROFILE_TYPE_USER`

              - `:PROFILE_TYPE_API_KEY`

              - `:PROFILE_TYPE_SYSTEM`

            - `email: String`

              Email address of the profile. Required and unique within an account for
              user profiles.

            - `name: String`

              Display name (e.g., "Bobby Tables").

        - `variation_count: Integer`

    - `data: untyped`

      Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

    - `initial_message: String`

      The initial message sent to the agent. This becomes the first user message in the LLM chat history.

    - `memory_stack: Array[MemoryReference]`

      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_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `output: Hash[Symbol, untyped]`

      The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

    - `output_definition: Hash[Symbol, untyped]`

      Snapshot of the agent spec's output_definition at objective creation time.
      When present, the objective will run an extraction step after the LLM finishes.

    - `parent_objective_id: String`

      A parent objective means the objective was spawned off using a separate agent to complete an objective

    - `secrets: Array[ObjectiveDataSecret]`

      Secrets that can be used in the headers for tool calls using the secret interpolation format.

      - `name: String`

      - `value: String`

    - `source_schedule_id: String`

      ID of the AgentSchedule that produced this objective, when applicable.
      Populated when the objective is created from a schedule fire; empty when
      the objective was created via CreateObjective directly.

    - `system_prompt: String`

      system_prompt is read-only, derived from the selected variation's prompt

    - `variation: AgentVariation`

      AgentVariation resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `spec: AgentVariationSpec`

        AgentVariationSpec defines the operational configuration for a variation

        - `compaction_config: AgentVariationSpecCompactionConfig`

          CompactionConfig defines how context window compaction behaves for objectives using this variation.

          - `summarization: CompactionConfigSummarizationStrategy`

            SummarizationStrategy configures LLM-powered summarization of older conversation turns.

            - `instructions: String`

              Custom instructions that guide what the summarizer preserves.
              Replaces the default summarization prompt entirely.
              Example: "Preserve all code snippets, variable names, and technical decisions."

          - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

            ToolResultClearingStrategy configures clearing of older tool result content.

            - `preserve_recent_results: Integer`

              Number of most recent tool call results to keep intact.
              Older tool results have their content replaced with "[result cleared]"
              while preserving the assistant tool call message (function name, arguments).
              Default: 2

          - `trigger_threshold: Float`

            Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
            When input tokens reach this percentage of the model's limit, compaction triggers.
            Default: 0.75 (75%)

        - `constraints: AgentVariationSpecConstraints`

          Execution constraints

          - `max_sub_objectives: Integer`

            The maximum number of sub-objectives that can be created. 0 means no limit.

          - `max_tool_calls: Integer`

            The maximum number of tool calls that can be made. 0 means no limit.

        - `description: String`

          Human-readable description of what this variation does or when it should be used

        - `enable_episodic_memory: bool`

          Enable episodic memory for objectives using this variation.
          When true, the system automatically creates a document namespace for each objective
          using the objective's episodic_key as the external_id, allowing the agent to
          store and retrieve documents specific to that episode.

        - `episodic_memory_ttl: Integer`

          How long episodic memories should be retained.
          After this duration, episodic document namespaces can be automatically cleaned up.
          If not set, episodic memories are retained indefinitely.

        - `model_config: AgentVariationSpecModelConfig`

          ModelConfig defines the model configuration for a variation

          - `model_id: String`

            The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

          - `temperature: Float`

            Sampling temperature for model inference (0.0 to 1.0)
            Lower values produce more deterministic outputs, higher values increase randomness

        - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

          ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
          Max tools is the maximum number of tools that can be discovered per search.
          Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

          - `hints: Array[String]`

          - `max_tools: Integer`

          - `rerank_threshold: Float`

            Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
            which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
            the tool very closely match the query the tool search performed.

        - `prompt: String`

          The system prompt for this variation

        - `weight: Integer`

          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 on CreateObjectiveRequest.

      - `info: AgentVariationInfo`

        AgentVariationInfo provides read-only summary information about a variation

        - `assignments: Array[VariationAssignment]`

          All tools, tool sets, and sub-agents assigned to this variation.
          Populated on reads so clients can render a variation's full assignment
          list without calling the add/remove endpoints just to enumerate.

          - `id: String`

          - `agent: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

            - `id: String`

            - `name: String`

              Human-readable name of the referenced resource, populated by the server
              on reads for convenience. Absent on references to resources that do not
              have a name (e.g., objective tasks).

          - `tool: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `tool_set: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

        - `created_by: Profile`

          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.

        - `feedback_count: Integer`

          Total number of objective feedbacks received for this variation

        - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

          Read-only list of memory layer assignments for this variation,
          returned in ascending `position` (bottom → top). Capped at 10 entries.

          - `id: String`

            Assignment row id — handle for removing the assignment. Distinct
            from the referenced memory layer's id.

          - `memory_layer: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `position: Integer`

            Position in the variation's baseline stack. Lower values sit lower;
            the highest-position assignment is on top of the variation's
            baseline. Gaps are fine — only relative position matters. Positions
            must be unique within a variation; a request that would collide
            with an existing assignment's position is rejected with
            InvalidArgument.

        - `memory_layer_count: Integer`

          Count of memory layer assignments.

        - `model: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `score: Float`

          Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
          Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

        - `sub_agent_count: Integer`

          Number of sub-agents assigned to this variation

        - `tool_count: Integer`

          Number of individual tools assigned to this variation

        - `tool_set_count: Integer`

          Number of tool sets assigned to this variation

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: ObjectiveStatus`

    - `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

      - `:STATE_UNSPECIFIED`

      - `:STATE_PENDING`

      - `:STATE_RUNNING`

      - `:STATE_WAITING`

      - `:STATE_FAILED`

      - `:STATE_CANCELLED`

      - `:STATE_FINALIZED`

    - `message: String`

  - `info: ObjectiveInfo`

    ObjectiveInfo provides read-only aggregated statistics about an objective's execution

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `agent_variation: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `created_by: Profile`

      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.

    - `effective_memory_stack: Array[MemoryReference]`

      The effective memory stack at objective creation time, flattened
      from the variation's baseline plus ObjectiveData.memory_stack. Order
      is push order (last = top). Returned on reads so clients can see
      exactly what stack the objective is using without having to re-join
      variation state.

      - `memory_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `total_context_windows: Integer`

      Total number of context windows that this objective has generated

    - `total_events: Integer`

      Total number of events generated during this objective's execution

    - `total_input_tokens: Integer`

      Total input tokens consumed across all LLM completions across all context windows

    - `total_output_tokens: Integer`

      Total output tokens generated across all LLM completions across all context windows

    - `total_tool_calls: Integer`

      Total number of tool calls made during execution

  - `last_five_windows: Array[ObjectiveContextWindow]`

    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).

    - `data: ObjectiveContextWindowData`

      - `completion_tokens: Integer`

        A calculated value for how many completion tokens (output tokens) have been used in this context window

      - `objective_id: String`

        The objective's ID that this window belongs to

      - `previous_window_continue_instructions: String`

        The instructions for this window to continue from a previous window's chat history.

      - `prompt_tokens: Integer`

        A calculated value for how many prompt tokens (input tokens) have been used in this context window

      - `sequence: Integer`

        sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
        to calculate how many context windows an objective has.

    - `metadata: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `info: Info{ created_by, objective}`

      - `created_by: Profile`

        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.

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective = cadenya.objectives.cancel("objectiveId", workspace_id: "workspaceId")

puts(objective)
```

#### Response

```json
{
  "data": {
    "agent": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "status": "AGENT_STATUS_UNSPECIFIED",
        "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
        "description": "description",
        "inputDataSchema": {
          "foo": "bar"
        },
        "outputDefinition": {
          "foo": "bar"
        },
        "webhookEventsUrl": "webhookEventsUrl"
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "variationCount": 0
      }
    },
    "data": {},
    "initialMessage": "initialMessage",
    "memoryStack": [
      {
        "memoryEntryId": "memoryEntryId",
        "memoryLayerId": "memoryLayerId"
      }
    ],
    "output": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "parentObjectiveId": "parentObjectiveId",
    "secrets": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "sourceScheduleId": "sourceScheduleId",
    "systemPrompt": "systemPrompt",
    "variation": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "compactionConfig": {
          "summarization": {
            "instructions": "instructions"
          },
          "toolResultClearing": {
            "preserveRecentResults": 0
          },
          "triggerThreshold": 0
        },
        "constraints": {
          "maxSubObjectives": 0,
          "maxToolCalls": 0
        },
        "description": "description",
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 0,
        "modelConfig": {
          "modelId": "modelId",
          "temperature": 0
        },
        "progressiveDiscovery": {
          "hints": [
            "string"
          ],
          "maxTools": 0,
          "rerankThreshold": 0
        },
        "prompt": "prompt",
        "weight": 0
      },
      "info": {
        "assignments": [
          {
            "id": "id",
            "agent": {
              "id": "id",
              "name": "name"
            },
            "tool": {
              "id": "id",
              "name": "name"
            },
            "toolSet": {
              "id": "id",
              "name": "name"
            }
          }
        ],
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "feedbackCount": 0,
        "memoryLayerAssignments": [
          {
            "id": "id",
            "memoryLayer": {
              "id": "id",
              "name": "name"
            },
            "position": 0
          }
        ],
        "memoryLayerCount": 0,
        "model": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "score": 0,
        "subAgentCount": 0,
        "toolCount": 0,
        "toolSetCount": 0
      }
    }
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "status": {
    "state": "STATE_UNSPECIFIED",
    "message": "message"
  },
  "info": {
    "agent": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "agentVariation": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "effectiveMemoryStack": [
      {
        "memoryEntryId": "memoryEntryId",
        "memoryLayerId": "memoryLayerId"
      }
    ],
    "totalContextWindows": 0,
    "totalEvents": 0,
    "totalInputTokens": 0,
    "totalOutputTokens": 0,
    "totalToolCalls": 0
  },
  "lastFiveWindows": [
    {
      "data": {
        "completionTokens": 0,
        "objectiveId": "objectiveId",
        "previousWindowContinueInstructions": "previousWindowContinueInstructions",
        "promptTokens": 0,
        "sequence": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "objective": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        }
      }
    }
  ]
}
```

## Compact an objective

`objectives.compact(objective_id, **kwargs) -> ObjectiveCompactResponse`

**post** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/compact`

Triggers compaction on a running objective. Optionally override the variation's compaction config.

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `compaction_config: AgentVariationSpecCompactionConfig`

  CompactionConfig defines how context window compaction behaves for objectives using this variation.

  - `summarization: CompactionConfigSummarizationStrategy`

    SummarizationStrategy configures LLM-powered summarization of older conversation turns.

    - `instructions: String`

      Custom instructions that guide what the summarizer preserves.
      Replaces the default summarization prompt entirely.
      Example: "Preserve all code snippets, variable names, and technical decisions."

  - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

    ToolResultClearingStrategy configures clearing of older tool result content.

    - `preserve_recent_results: Integer`

      Number of most recent tool call results to keep intact.
      Older tool results have their content replaced with "[result cleared]"
      while preserving the assistant tool call message (function name, arguments).
      Default: 2

  - `trigger_threshold: Float`

    Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
    When input tokens reach this percentage of the model's limit, compaction triggers.
    Default: 0.75 (75%)

### Returns

- `class ObjectiveCompactResponse`

  Compact objective response

  - `context_window: ObjectiveContextWindowData`

    The new context window created by the compaction

    - `completion_tokens: Integer`

      A calculated value for how many completion tokens (output tokens) have been used in this context window

    - `objective_id: String`

      The objective's ID that this window belongs to

    - `previous_window_continue_instructions: String`

      The instructions for this window to continue from a previous window's chat history.

    - `prompt_tokens: Integer`

      A calculated value for how many prompt tokens (input tokens) have been used in this context window

    - `sequence: Integer`

      sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
      to calculate how many context windows an objective has.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

response = cadenya.objectives.compact("objectiveId", workspace_id: "workspaceId")

puts(response)
```

#### Response

```json
{
  "contextWindow": {
    "completionTokens": 0,
    "objectiveId": "objectiveId",
    "previousWindowContinueInstructions": "previousWindowContinueInstructions",
    "promptTokens": 0,
    "sequence": 0
  }
}
```

## List objective context windows

`objectives.list_context_windows(objective_id, **kwargs) -> CursorPagination<ObjectiveContextWindow>`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/context_windows`

Read-only list of the last five windows of execution for this objective, ordered by most recent first

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `include_info: bool`

  When set to true you may use more of your alloted API rate-limit

- `limit: Integer`

  Maximum number of results to return

### Returns

- `class ObjectiveContextWindow`

  ObjectiveContextWindow is a window of chat completions that is grouped together to prevent context-window overflows. Context windows also allow
  agents to compact their windows and carry on into a new one.

  - `data: ObjectiveContextWindowData`

    - `completion_tokens: Integer`

      A calculated value for how many completion tokens (output tokens) have been used in this context window

    - `objective_id: String`

      The objective's ID that this window belongs to

    - `previous_window_continue_instructions: String`

      The instructions for this window to continue from a previous window's chat history.

    - `prompt_tokens: Integer`

      A calculated value for how many prompt tokens (input tokens) have been used in this context window

    - `sequence: Integer`

      sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
      to calculate how many context windows an objective has.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info: Info{ created_by, objective}`

    - `created_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.list_context_windows("objectiveId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "completionTokens": 0,
        "objectiveId": "objectiveId",
        "previousWindowContinueInstructions": "previousWindowContinueInstructions",
        "promptTokens": 0,
        "sequence": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "objective": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Domain Types

### Assistant Message

- `class AssistantMessage`

  - `content: String`

  - `tool_calls: Array[AssistantToolCall]`

    - `arguments: String`

    - `function_name: String`

    - `tool: CallableTool`

      CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
      might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `cadenya_provided_tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

### Assistant Tool Call

- `class AssistantToolCall`

  - `arguments: String`

  - `function_name: String`

  - `tool: CallableTool`

    CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
    might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `cadenya_provided_tool: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `tool: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

### Callable Tool

- `class CallableTool`

  CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
  might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

  - `agent: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `cadenya_provided_tool: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

  - `tool: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

### Context Window Compacted

- `class ContextWindowCompacted`

  - `messages_compacted: Integer`

    Number of messages that were compacted

  - `new_context_window: ObjectiveContextWindowData`

    The new context window created by this compaction

    - `completion_tokens: Integer`

      A calculated value for how many completion tokens (output tokens) have been used in this context window

    - `objective_id: String`

      The objective's ID that this window belongs to

    - `previous_window_continue_instructions: String`

      The instructions for this window to continue from a previous window's chat history.

    - `prompt_tokens: Integer`

      A calculated value for how many prompt tokens (input tokens) have been used in this context window

    - `sequence: Integer`

      sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
      to calculate how many context windows an objective has.

  - `strategies: Array[String]`

    The strategies that were applied during this compaction

  - `summary: String`

    The summary generated by the summarization strategy, if used.

### Memory Read

- `class MemoryRead`

  MemoryRead is emitted each time the agent resolves a key against the
  memory stack and loads an entry. Lookups that miss (key not found in
  any layer) do not emit this event.

  - `memory_entry_id: String`

    The specific entry that was read.

  - `memory_layer_id: String`

    The layer the entry resolved to. The top-most layer that contained
    the key — other layers beneath it that also contained the key are
    shadowed and not referenced here.

  - `message: String`

    Human-readable description of the read, set by the runtime. For
    example: "Loaded skill", "Resolved context key". Not machine-parsed;
    intended for UI display alongside the other events in an objective's
    timeline.

### Memory Reference

- `class MemoryReference`

  MemoryReference identifies a memory layer or a specific entry within
  one, for composition into a memory stack. Used on objectives (where
  entry pinning is permitted).

  memory_layer_id accepts both the canonical form (memlyr_…) and the
  external-id form (external_id:my-custom-id). The same applies to
  memory_entry_id when set.

  - `memory_entry_id: String`

    When set, pushes only this entry from memory_layer_id onto the stack —
    behaves as a single-entry layer (only this key resolves at this
    position). The entry must belong to memory_layer_id; mismatches are
    rejected with InvalidArgument.

  - `memory_layer_id: String`

### Objective

- `class Objective`

  - `data: ObjectiveData`

    - `agent: Agent`

      Agent resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: AgentSpec`

        Agent specification (user-provided configuration)

        - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

          Status of the agent

          - `:AGENT_STATUS_UNSPECIFIED`

          - `:AGENT_STATUS_DRAFT`

          - `:AGENT_STATUS_PUBLISHED`

          - `:AGENT_STATUS_ARCHIVED`

        - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

          Controls how variations are automatically selected when creating objectives
          Defaults to RANDOM when unspecified

          - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

          - `:VARIATION_SELECTION_MODE_RANDOM`

          - `:VARIATION_SELECTION_MODE_WEIGHTED`

        - `description: String`

          Description of the agent's purpose

        - `input_data_schema: Hash[Symbol, untyped]`

          InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
          prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
          the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

        - `output_definition: Hash[Symbol, untyped]`

          Optional output definition for objectives created for this agent.
          When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
          Use this option when you want structured data to be created by your objectives.

        - `webhook_events_url: String`

          The URL that Cadenya will send events for any objective assigned to the agent.

      - `info: AgentInfo`

        AgentInfo contains simple information about an agent for display or quick reference

        - `created_by: Profile`

          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.

          - `metadata: AccountResourceMetadata`

            AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `spec: ProfileSpec`

            Configuration for a profile.

            - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

              Whether this profile represents a human user, an API key, or a system
              principal.

              - `:PROFILE_TYPE_UNSPECIFIED`

              - `:PROFILE_TYPE_USER`

              - `:PROFILE_TYPE_API_KEY`

              - `:PROFILE_TYPE_SYSTEM`

            - `email: String`

              Email address of the profile. Required and unique within an account for
              user profiles.

            - `name: String`

              Display name (e.g., "Bobby Tables").

        - `variation_count: Integer`

    - `data: untyped`

      Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

    - `initial_message: String`

      The initial message sent to the agent. This becomes the first user message in the LLM chat history.

    - `memory_stack: Array[MemoryReference]`

      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_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `output: Hash[Symbol, untyped]`

      The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

    - `output_definition: Hash[Symbol, untyped]`

      Snapshot of the agent spec's output_definition at objective creation time.
      When present, the objective will run an extraction step after the LLM finishes.

    - `parent_objective_id: String`

      A parent objective means the objective was spawned off using a separate agent to complete an objective

    - `secrets: Array[ObjectiveDataSecret]`

      Secrets that can be used in the headers for tool calls using the secret interpolation format.

      - `name: String`

      - `value: String`

    - `source_schedule_id: String`

      ID of the AgentSchedule that produced this objective, when applicable.
      Populated when the objective is created from a schedule fire; empty when
      the objective was created via CreateObjective directly.

    - `system_prompt: String`

      system_prompt is read-only, derived from the selected variation's prompt

    - `variation: AgentVariation`

      AgentVariation resource

      - `metadata: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `spec: AgentVariationSpec`

        AgentVariationSpec defines the operational configuration for a variation

        - `compaction_config: AgentVariationSpecCompactionConfig`

          CompactionConfig defines how context window compaction behaves for objectives using this variation.

          - `summarization: CompactionConfigSummarizationStrategy`

            SummarizationStrategy configures LLM-powered summarization of older conversation turns.

            - `instructions: String`

              Custom instructions that guide what the summarizer preserves.
              Replaces the default summarization prompt entirely.
              Example: "Preserve all code snippets, variable names, and technical decisions."

          - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

            ToolResultClearingStrategy configures clearing of older tool result content.

            - `preserve_recent_results: Integer`

              Number of most recent tool call results to keep intact.
              Older tool results have their content replaced with "[result cleared]"
              while preserving the assistant tool call message (function name, arguments).
              Default: 2

          - `trigger_threshold: Float`

            Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
            When input tokens reach this percentage of the model's limit, compaction triggers.
            Default: 0.75 (75%)

        - `constraints: AgentVariationSpecConstraints`

          Execution constraints

          - `max_sub_objectives: Integer`

            The maximum number of sub-objectives that can be created. 0 means no limit.

          - `max_tool_calls: Integer`

            The maximum number of tool calls that can be made. 0 means no limit.

        - `description: String`

          Human-readable description of what this variation does or when it should be used

        - `enable_episodic_memory: bool`

          Enable episodic memory for objectives using this variation.
          When true, the system automatically creates a document namespace for each objective
          using the objective's episodic_key as the external_id, allowing the agent to
          store and retrieve documents specific to that episode.

        - `episodic_memory_ttl: Integer`

          How long episodic memories should be retained.
          After this duration, episodic document namespaces can be automatically cleaned up.
          If not set, episodic memories are retained indefinitely.

        - `model_config: AgentVariationSpecModelConfig`

          ModelConfig defines the model configuration for a variation

          - `model_id: String`

            The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

          - `temperature: Float`

            Sampling temperature for model inference (0.0 to 1.0)
            Lower values produce more deterministic outputs, higher values increase randomness

        - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

          ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
          Max tools is the maximum number of tools that can be discovered per search.
          Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

          - `hints: Array[String]`

          - `max_tools: Integer`

          - `rerank_threshold: Float`

            Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
            which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
            the tool very closely match the query the tool search performed.

        - `prompt: String`

          The system prompt for this variation

        - `weight: Integer`

          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 on CreateObjectiveRequest.

      - `info: AgentVariationInfo`

        AgentVariationInfo provides read-only summary information about a variation

        - `assignments: Array[VariationAssignment]`

          All tools, tool sets, and sub-agents assigned to this variation.
          Populated on reads so clients can render a variation's full assignment
          list without calling the add/remove endpoints just to enumerate.

          - `id: String`

          - `agent: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

            - `id: String`

            - `name: String`

              Human-readable name of the referenced resource, populated by the server
              on reads for convenience. Absent on references to resources that do not
              have a name (e.g., objective tasks).

          - `tool: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `tool_set: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

        - `created_by: Profile`

          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.

        - `feedback_count: Integer`

          Total number of objective feedbacks received for this variation

        - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

          Read-only list of memory layer assignments for this variation,
          returned in ascending `position` (bottom → top). Capped at 10 entries.

          - `id: String`

            Assignment row id — handle for removing the assignment. Distinct
            from the referenced memory layer's id.

          - `memory_layer: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `position: Integer`

            Position in the variation's baseline stack. Lower values sit lower;
            the highest-position assignment is on top of the variation's
            baseline. Gaps are fine — only relative position matters. Positions
            must be unique within a variation; a request that would collide
            with an existing assignment's position is rejected with
            InvalidArgument.

        - `memory_layer_count: Integer`

          Count of memory layer assignments.

        - `model: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `score: Float`

          Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
          Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

        - `sub_agent_count: Integer`

          Number of sub-agents assigned to this variation

        - `tool_count: Integer`

          Number of individual tools assigned to this variation

        - `tool_set_count: Integer`

          Number of tool sets assigned to this variation

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: ObjectiveStatus`

    - `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

      - `:STATE_UNSPECIFIED`

      - `:STATE_PENDING`

      - `:STATE_RUNNING`

      - `:STATE_WAITING`

      - `:STATE_FAILED`

      - `:STATE_CANCELLED`

      - `:STATE_FINALIZED`

    - `message: String`

  - `info: ObjectiveInfo`

    ObjectiveInfo provides read-only aggregated statistics about an objective's execution

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `agent_variation: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `created_by: Profile`

      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.

    - `effective_memory_stack: Array[MemoryReference]`

      The effective memory stack at objective creation time, flattened
      from the variation's baseline plus ObjectiveData.memory_stack. Order
      is push order (last = top). Returned on reads so clients can see
      exactly what stack the objective is using without having to re-join
      variation state.

      - `memory_entry_id: String`

        When set, pushes only this entry from memory_layer_id onto the stack —
        behaves as a single-entry layer (only this key resolves at this
        position). The entry must belong to memory_layer_id; mismatches are
        rejected with InvalidArgument.

      - `memory_layer_id: String`

    - `total_context_windows: Integer`

      Total number of context windows that this objective has generated

    - `total_events: Integer`

      Total number of events generated during this objective's execution

    - `total_input_tokens: Integer`

      Total input tokens consumed across all LLM completions across all context windows

    - `total_output_tokens: Integer`

      Total output tokens generated across all LLM completions across all context windows

    - `total_tool_calls: Integer`

      Total number of tool calls made during execution

  - `last_five_windows: Array[ObjectiveContextWindow]`

    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).

    - `data: ObjectiveContextWindowData`

      - `completion_tokens: Integer`

        A calculated value for how many completion tokens (output tokens) have been used in this context window

      - `objective_id: String`

        The objective's ID that this window belongs to

      - `previous_window_continue_instructions: String`

        The instructions for this window to continue from a previous window's chat history.

      - `prompt_tokens: Integer`

        A calculated value for how many prompt tokens (input tokens) have been used in this context window

      - `sequence: Integer`

        sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
        to calculate how many context windows an objective has.

    - `metadata: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `info: Info{ created_by, objective}`

      - `created_by: Profile`

        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.

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Objective Context Window

- `class ObjectiveContextWindow`

  ObjectiveContextWindow is a window of chat completions that is grouped together to prevent context-window overflows. Context windows also allow
  agents to compact their windows and carry on into a new one.

  - `data: ObjectiveContextWindowData`

    - `completion_tokens: Integer`

      A calculated value for how many completion tokens (output tokens) have been used in this context window

    - `objective_id: String`

      The objective's ID that this window belongs to

    - `previous_window_continue_instructions: String`

      The instructions for this window to continue from a previous window's chat history.

    - `prompt_tokens: Integer`

      A calculated value for how many prompt tokens (input tokens) have been used in this context window

    - `sequence: Integer`

      sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
      to calculate how many context windows an objective has.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info: Info{ created_by, objective}`

    - `created_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Objective Context Window Data

- `class ObjectiveContextWindowData`

  - `completion_tokens: Integer`

    A calculated value for how many completion tokens (output tokens) have been used in this context window

  - `objective_id: String`

    The objective's ID that this window belongs to

  - `previous_window_continue_instructions: String`

    The instructions for this window to continue from a previous window's chat history.

  - `prompt_tokens: Integer`

    A calculated value for how many prompt tokens (input tokens) have been used in this context window

  - `sequence: Integer`

    sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
    to calculate how many context windows an objective has.

### Objective Data

- `class ObjectiveData`

  - `agent: Agent`

    Agent resource

    - `metadata: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: AgentSpec`

      Agent specification (user-provided configuration)

      - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

        Status of the agent

        - `:AGENT_STATUS_UNSPECIFIED`

        - `:AGENT_STATUS_DRAFT`

        - `:AGENT_STATUS_PUBLISHED`

        - `:AGENT_STATUS_ARCHIVED`

      - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

        Controls how variations are automatically selected when creating objectives
        Defaults to RANDOM when unspecified

        - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

        - `:VARIATION_SELECTION_MODE_RANDOM`

        - `:VARIATION_SELECTION_MODE_WEIGHTED`

      - `description: String`

        Description of the agent's purpose

      - `input_data_schema: Hash[Symbol, untyped]`

        InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation
        prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool's input parameter schema. If omitted,
        the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.

      - `output_definition: Hash[Symbol, untyped]`

        Optional output definition for objectives created for this agent.
        When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
        Use this option when you want structured data to be created by your objectives.

      - `webhook_events_url: String`

        The URL that Cadenya will send events for any objective assigned to the agent.

    - `info: AgentInfo`

      AgentInfo contains simple information about an agent for display or quick reference

      - `created_by: Profile`

        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.

        - `metadata: AccountResourceMetadata`

          AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

          - `id: String`

            Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

          - `account_id: String`

            Account this resource belongs to for multi-tenant isolation (prefixed ULID)

          - `name: String`

            Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
            Required for resources that users interact with directly

          - `profile_id: String`

          - `external_id: String`

            External ID for the resource (e.g., a workflow ID from an external system)

          - `labels: Hash[Symbol, String]`

            Arbitrary key-value pairs for categorization and filtering
            Examples: {"environment": "production", "team": "platform", "version": "v2"}

        - `spec: ProfileSpec`

          Configuration for a profile.

          - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

            Whether this profile represents a human user, an API key, or a system
            principal.

            - `:PROFILE_TYPE_UNSPECIFIED`

            - `:PROFILE_TYPE_USER`

            - `:PROFILE_TYPE_API_KEY`

            - `:PROFILE_TYPE_SYSTEM`

          - `email: String`

            Email address of the profile. Required and unique within an account for
            user profiles.

          - `name: String`

            Display name (e.g., "Bobby Tables").

      - `variation_count: Integer`

  - `data: untyped`

    Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.

  - `initial_message: String`

    The initial message sent to the agent. This becomes the first user message in the LLM chat history.

  - `memory_stack: Array[MemoryReference]`

    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_entry_id: String`

      When set, pushes only this entry from memory_layer_id onto the stack —
      behaves as a single-entry layer (only this key resolves at this
      position). The entry must belong to memory_layer_id; mismatches are
      rejected with InvalidArgument.

    - `memory_layer_id: String`

  - `output: Hash[Symbol, untyped]`

    The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.

  - `output_definition: Hash[Symbol, untyped]`

    Snapshot of the agent spec's output_definition at objective creation time.
    When present, the objective will run an extraction step after the LLM finishes.

  - `parent_objective_id: String`

    A parent objective means the objective was spawned off using a separate agent to complete an objective

  - `secrets: Array[ObjectiveDataSecret]`

    Secrets that can be used in the headers for tool calls using the secret interpolation format.

    - `name: String`

    - `value: String`

  - `source_schedule_id: String`

    ID of the AgentSchedule that produced this objective, when applicable.
    Populated when the objective is created from a schedule fire; empty when
    the objective was created via CreateObjective directly.

  - `system_prompt: String`

    system_prompt is read-only, derived from the selected variation's prompt

  - `variation: AgentVariation`

    AgentVariation resource

    - `metadata: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `spec: AgentVariationSpec`

      AgentVariationSpec defines the operational configuration for a variation

      - `compaction_config: AgentVariationSpecCompactionConfig`

        CompactionConfig defines how context window compaction behaves for objectives using this variation.

        - `summarization: CompactionConfigSummarizationStrategy`

          SummarizationStrategy configures LLM-powered summarization of older conversation turns.

          - `instructions: String`

            Custom instructions that guide what the summarizer preserves.
            Replaces the default summarization prompt entirely.
            Example: "Preserve all code snippets, variable names, and technical decisions."

        - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

          ToolResultClearingStrategy configures clearing of older tool result content.

          - `preserve_recent_results: Integer`

            Number of most recent tool call results to keep intact.
            Older tool results have their content replaced with "[result cleared]"
            while preserving the assistant tool call message (function name, arguments).
            Default: 2

        - `trigger_threshold: Float`

          Trigger threshold as a percentage of the model's context window (0.0 to 1.0).
          When input tokens reach this percentage of the model's limit, compaction triggers.
          Default: 0.75 (75%)

      - `constraints: AgentVariationSpecConstraints`

        Execution constraints

        - `max_sub_objectives: Integer`

          The maximum number of sub-objectives that can be created. 0 means no limit.

        - `max_tool_calls: Integer`

          The maximum number of tool calls that can be made. 0 means no limit.

      - `description: String`

        Human-readable description of what this variation does or when it should be used

      - `enable_episodic_memory: bool`

        Enable episodic memory for objectives using this variation.
        When true, the system automatically creates a document namespace for each objective
        using the objective's episodic_key as the external_id, allowing the agent to
        store and retrieve documents specific to that episode.

      - `episodic_memory_ttl: Integer`

        How long episodic memories should be retained.
        After this duration, episodic document namespaces can be automatically cleaned up.
        If not set, episodic memories are retained indefinitely.

      - `model_config: AgentVariationSpecModelConfig`

        ModelConfig defines the model configuration for a variation

        - `model_id: String`

          The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

        - `temperature: Float`

          Sampling temperature for model inference (0.0 to 1.0)
          Lower values produce more deterministic outputs, higher values increase randomness

      - `progressive_discovery: AgentVariationSpecProgressiveDiscovery`

        ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it.
        Max tools is the maximum number of tools that can be discovered per search.
        Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.

        - `hints: Array[String]`

        - `max_tools: Integer`

        - `rerank_threshold: Float`

          Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process
          which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example,
          the tool very closely match the query the tool search performed.

      - `prompt: String`

        The system prompt for this variation

      - `weight: Integer`

        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 on CreateObjectiveRequest.

    - `info: AgentVariationInfo`

      AgentVariationInfo provides read-only summary information about a variation

      - `assignments: Array[VariationAssignment]`

        All tools, tool sets, and sub-agents assigned to this variation.
        Populated on reads so clients can render a variation's full assignment
        list without calling the add/remove endpoints just to enumerate.

        - `id: String`

        - `agent: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

          - `id: String`

          - `name: String`

            Human-readable name of the referenced resource, populated by the server
            on reads for convenience. Absent on references to resources that do not
            have a name (e.g., objective tasks).

        - `tool: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

        - `tool_set: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

      - `created_by: Profile`

        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.

      - `feedback_count: Integer`

        Total number of objective feedbacks received for this variation

      - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

        Read-only list of memory layer assignments for this variation,
        returned in ascending `position` (bottom → top). Capped at 10 entries.

        - `id: String`

          Assignment row id — handle for removing the assignment. Distinct
          from the referenced memory layer's id.

        - `memory_layer: BareMetadata`

          BareMetadata contains the minimal metadata for a resource: the ID and an
          optional human-readable name. These are used for reference fields where the
          full metadata (account scoping, timestamps, labels, external IDs) is not
          needed — e.g., the tool references inside an agent variation spec or the
          tools assigned to an objective. Both fields are server-populated; clients
          provide IDs through sibling fields rather than by constructing a
          BareMetadata themselves.

        - `position: Integer`

          Position in the variation's baseline stack. Lower values sit lower;
          the highest-position assignment is on top of the variation's
          baseline. Gaps are fine — only relative position matters. Positions
          must be unique within a variation; a request that would collide
          with an existing assignment's position is rejected with
          InvalidArgument.

      - `memory_layer_count: Integer`

        Count of memory layer assignments.

      - `model: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `score: Float`

        Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
        Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

      - `sub_agent_count: Integer`

        Number of sub-agents assigned to this variation

      - `tool_count: Integer`

        Number of individual tools assigned to this variation

      - `tool_set_count: Integer`

        Number of tool sets assigned to this variation

### Objective Data Secret

- `class ObjectiveDataSecret`

  - `name: String`

  - `value: String`

### Objective Error

- `class ObjectiveError`

  - `message: String`

  - `type: String`

### Objective Event Data

- `class ObjectiveEventData`

  - `assistant_message: AssistantMessage`

    - `content: String`

    - `tool_calls: Array[AssistantToolCall]`

      - `arguments: String`

      - `function_name: String`

      - `tool: CallableTool`

        CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
        might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

        - `agent: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

          - `id: String`

            Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

          - `account_id: String`

            Account this resource belongs to for multi-tenant isolation (prefixed ULID)

          - `created_at: Time`

            Timestamp when this resource was created

          - `name: String`

            Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
            Required for resources that users interact with directly

          - `profile_id: String`

            ID of the actor (user or service account) that created this resource

          - `workspace_id: String`

            Workspace this resource belongs to for organizational grouping (prefixed ULID)

          - `bundle_key: String`

            Optional bundle ownership key. When set, indicates the resource is
            managed by a configuration bundle identified by this key. Used by
            BulkWorkspaceResources.Apply to track which resources belong to which
            bundle for reconciliation / soft-delete on re-apply.

          - `external_id: String`

            External ID for the resource (e.g., a workflow ID from an external system)

          - `labels: Hash[Symbol, String]`

            Arbitrary key-value pairs for categorization and filtering
            Examples: {"environment": "production", "team": "platform", "version": "v2"}

        - `cadenya_provided_tool: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `tool: ResourceMetadata`

          Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

  - `cancelled: Cancelled{ message}`

    ObjectiveCancelled is the terminal event written when an objective is
    cancelled. After this event, the objective is super-terminal: no further
    iterations, compaction, or continuation are permitted.

    - `message: String`

      Optional human-readable note recorded at cancel time. Today the workflow
      sets "Cancelled" but this field leaves room for richer reasons (e.g.
      "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted").

  - `context_window_compacted: ContextWindowCompacted`

    - `messages_compacted: Integer`

      Number of messages that were compacted

    - `new_context_window: ObjectiveContextWindowData`

      The new context window created by this compaction

      - `completion_tokens: Integer`

        A calculated value for how many completion tokens (output tokens) have been used in this context window

      - `objective_id: String`

        The objective's ID that this window belongs to

      - `previous_window_continue_instructions: String`

        The instructions for this window to continue from a previous window's chat history.

      - `prompt_tokens: Integer`

        A calculated value for how many prompt tokens (input tokens) have been used in this context window

      - `sequence: Integer`

        sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
        to calculate how many context windows an objective has.

    - `strategies: Array[String]`

      The strategies that were applied during this compaction

    - `summary: String`

      The summary generated by the summarization strategy, if used.

  - `error: ObjectiveError`

    - `message: String`

    - `type: String`

  - `finalized: Finalized{ output}`

    ObjectiveFinalized is the terminal event written when an objective is
    finalized. After this event, the objective is super-terminal: no further
    iterations, compaction, or continuation are permitted.

    - `output: untyped`

      If the objective was created with an output schema, and the agent
      successfully completed the objective, this field will contain the
      structured output of the objective.

  - `memory_read: MemoryRead`

    MemoryRead is emitted each time the agent resolves a key against the
    memory stack and loads an entry. Lookups that miss (key not found in
    any layer) do not emit this event.

    - `memory_entry_id: String`

      The specific entry that was read.

    - `memory_layer_id: String`

      The layer the entry resolved to. The top-most layer that contained
      the key — other layers beneath it that also contained the key are
      shadowed and not referenced here.

    - `message: String`

      Human-readable description of the read, set by the runtime. For
      example: "Loaded skill", "Resolved context key". Not machine-parsed;
      intended for UI display alongside the other events in an objective's
      timeline.

  - `sub_agent_spawned: SubAgentSpawned`

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

      - `id: String`

        Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

      - `account_id: String`

        Account this operation belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this operation was created
        ULID includes timestamp information, but this explicit field enables easier querying

      - `profile_id: String`

        ID of the actor (user or service account) that created this operation

      - `workspace_id: String`

        Workspace this operation belongs to for organizational grouping (prefixed ULID)

      - `external_id: String`

        External ID for the operation (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

    - `task: String`

  - `sub_agent_updated: SubAgentUpdated`

    - `agent: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

      - `id: String`

      - `name: String`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `message: String`

    - `objective: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

    - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

      - `:STATUS_UNSPECIFIED`

      - `:STATUS_PENDING`

      - `:STATUS_RUNNING`

      - `:STATUS_COMPLETED`

      - `:STATUS_FAILED`

      - `:STATUS_CANCELLED`

  - `tool_approval_requested: ToolApprovalRequested`

    - `tool_call_id: String`

      The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

  - `tool_approved: ToolApproved`

    - `tool_call_id: String`

      The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

  - `tool_called: ToolCalled`

    - `tool_call_id: String`

      The ID of the objective tool call record that was executed.

  - `tool_denied: ToolDenied`

    - `memo: String`

      The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

    - `tool_call_id: String`

      The ID of the objective tool call record that was denied via the DenyToolCall RPC.

  - `tool_error: ToolError`

    - `message: String`

    - `tool_call_id: String`

      The ID of the objective tool call record that encountered an error during execution.

  - `tool_result: ToolResult`

    - `content: String`

    - `tool_call_id: String`

  - `type: String`

  - `user_message: UserMessage`

    - `content: String`

### Objective Event Info

- `class ObjectiveEventInfo`

  - `created_by: Profile`

    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.

    - `metadata: AccountResourceMetadata`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

  - `objective: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Objective Event Webhook Data

- `class ObjectiveEventWebhookData`

  The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload.

  - `data: Data{ agent, agent_variation, objective, objective_event}`

    The webhook data payload with flat top-level keys for agent, variation, objective, and event.

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `agent_variation: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

      - `id: String`

        Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

      - `account_id: String`

        Account this operation belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this operation was created
        ULID includes timestamp information, but this explicit field enables easier querying

      - `profile_id: String`

        ID of the actor (user or service account) that created this operation

      - `workspace_id: String`

        Workspace this operation belongs to for organizational grouping (prefixed ULID)

      - `external_id: String`

        External ID for the operation (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

    - `objective_event: ObjectiveEvent{ data, metadata, context_window_id, info}`

      - `data: ObjectiveEventData`

        - `assistant_message: AssistantMessage`

          - `content: String`

          - `tool_calls: Array[AssistantToolCall]`

            - `arguments: String`

            - `function_name: String`

            - `tool: CallableTool`

              CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
              might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

              - `agent: ResourceMetadata`

                Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

              - `cadenya_provided_tool: ResourceMetadata`

                Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

              - `tool: ResourceMetadata`

                Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `cancelled: Cancelled{ message}`

          ObjectiveCancelled is the terminal event written when an objective is
          cancelled. After this event, the objective is super-terminal: no further
          iterations, compaction, or continuation are permitted.

          - `message: String`

            Optional human-readable note recorded at cancel time. Today the workflow
            sets "Cancelled" but this field leaves room for richer reasons (e.g.
            "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted").

        - `context_window_compacted: ContextWindowCompacted`

          - `messages_compacted: Integer`

            Number of messages that were compacted

          - `new_context_window: ObjectiveContextWindowData`

            The new context window created by this compaction

            - `completion_tokens: Integer`

              A calculated value for how many completion tokens (output tokens) have been used in this context window

            - `objective_id: String`

              The objective's ID that this window belongs to

            - `previous_window_continue_instructions: String`

              The instructions for this window to continue from a previous window's chat history.

            - `prompt_tokens: Integer`

              A calculated value for how many prompt tokens (input tokens) have been used in this context window

            - `sequence: Integer`

              sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
              to calculate how many context windows an objective has.

          - `strategies: Array[String]`

            The strategies that were applied during this compaction

          - `summary: String`

            The summary generated by the summarization strategy, if used.

        - `error: ObjectiveError`

          - `message: String`

          - `type: String`

        - `finalized: Finalized{ output}`

          ObjectiveFinalized is the terminal event written when an objective is
          finalized. After this event, the objective is super-terminal: no further
          iterations, compaction, or continuation are permitted.

          - `output: untyped`

            If the objective was created with an output schema, and the agent
            successfully completed the objective, this field will contain the
            structured output of the objective.

        - `memory_read: MemoryRead`

          MemoryRead is emitted each time the agent resolves a key against the
          memory stack and loads an entry. Lookups that miss (key not found in
          any layer) do not emit this event.

          - `memory_entry_id: String`

            The specific entry that was read.

          - `memory_layer_id: String`

            The layer the entry resolved to. The top-most layer that contained
            the key — other layers beneath it that also contained the key are
            shadowed and not referenced here.

          - `message: String`

            Human-readable description of the read, set by the runtime. For
            example: "Loaded skill", "Resolved context key". Not machine-parsed;
            intended for UI display alongside the other events in an objective's
            timeline.

        - `sub_agent_spawned: SubAgentSpawned`

          - `agent: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

          - `objective: OperationMetadata`

            Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

          - `task: String`

        - `sub_agent_updated: SubAgentUpdated`

          - `agent: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

            - `id: String`

            - `name: String`

              Human-readable name of the referenced resource, populated by the server
              on reads for convenience. Absent on references to resources that do not
              have a name (e.g., objective tasks).

          - `message: String`

          - `objective: BareMetadata`

            BareMetadata contains the minimal metadata for a resource: the ID and an
            optional human-readable name. These are used for reference fields where the
            full metadata (account scoping, timestamps, labels, external IDs) is not
            needed — e.g., the tool references inside an agent variation spec or the
            tools assigned to an objective. Both fields are server-populated; clients
            provide IDs through sibling fields rather than by constructing a
            BareMetadata themselves.

          - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

            - `:STATUS_UNSPECIFIED`

            - `:STATUS_PENDING`

            - `:STATUS_RUNNING`

            - `:STATUS_COMPLETED`

            - `:STATUS_FAILED`

            - `:STATUS_CANCELLED`

        - `tool_approval_requested: ToolApprovalRequested`

          - `tool_call_id: String`

            The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

        - `tool_approved: ToolApproved`

          - `tool_call_id: String`

            The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

        - `tool_called: ToolCalled`

          - `tool_call_id: String`

            The ID of the objective tool call record that was executed.

        - `tool_denied: ToolDenied`

          - `memo: String`

            The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

          - `tool_call_id: String`

            The ID of the objective tool call record that was denied via the DenyToolCall RPC.

        - `tool_error: ToolError`

          - `message: String`

          - `tool_call_id: String`

            The ID of the objective tool call record that encountered an error during execution.

        - `tool_result: ToolResult`

          - `content: String`

          - `tool_call_id: String`

        - `type: String`

        - `user_message: UserMessage`

          - `content: String`

      - `metadata: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

      - `context_window_id: String`

      - `info: ObjectiveEventInfo`

        - `created_by: Profile`

          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.

          - `metadata: AccountResourceMetadata`

            AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `spec: ProfileSpec`

            Configuration for a profile.

            - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

              Whether this profile represents a human user, an API key, or a system
              principal.

              - `:PROFILE_TYPE_UNSPECIFIED`

              - `:PROFILE_TYPE_USER`

              - `:PROFILE_TYPE_API_KEY`

              - `:PROFILE_TYPE_SYSTEM`

            - `email: String`

              Email address of the profile. Required and unique within an account for
              user profiles.

            - `name: String`

              Display name (e.g., "Bobby Tables").

        - `objective: OperationMetadata`

          Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `timestamp: Time`

  - `type: String`

    The event type, prefixed with objective_event. (e.g., objective_event.tool_result)

### Objective Info

- `class ObjectiveInfo`

  ObjectiveInfo provides read-only aggregated statistics about an objective's execution

  - `agent: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `agent_variation: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

  - `created_by: Profile`

    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.

    - `metadata: AccountResourceMetadata`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

  - `effective_memory_stack: Array[MemoryReference]`

    The effective memory stack at objective creation time, flattened
    from the variation's baseline plus ObjectiveData.memory_stack. Order
    is push order (last = top). Returned on reads so clients can see
    exactly what stack the objective is using without having to re-join
    variation state.

    - `memory_entry_id: String`

      When set, pushes only this entry from memory_layer_id onto the stack —
      behaves as a single-entry layer (only this key resolves at this
      position). The entry must belong to memory_layer_id; mismatches are
      rejected with InvalidArgument.

    - `memory_layer_id: String`

  - `total_context_windows: Integer`

    Total number of context windows that this objective has generated

  - `total_events: Integer`

    Total number of events generated during this objective's execution

  - `total_input_tokens: Integer`

    Total input tokens consumed across all LLM completions across all context windows

  - `total_output_tokens: Integer`

    Total output tokens generated across all LLM completions across all context windows

  - `total_tool_calls: Integer`

    Total number of tool calls made during execution

### Objective Status

- `class ObjectiveStatus`

  - `state: :STATE_UNSPECIFIED | :STATE_PENDING | :STATE_RUNNING | 4 more`

    - `:STATE_UNSPECIFIED`

    - `:STATE_PENDING`

    - `:STATE_RUNNING`

    - `:STATE_WAITING`

    - `:STATE_FAILED`

    - `:STATE_CANCELLED`

    - `:STATE_FINALIZED`

  - `message: String`

### Sub Agent Spawned

- `class SubAgentSpawned`

  - `agent: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `objective: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `task: String`

### Sub Agent Updated

- `class SubAgentUpdated`

  - `agent: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `message: String`

  - `objective: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

  - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

    - `:STATUS_UNSPECIFIED`

    - `:STATUS_PENDING`

    - `:STATUS_RUNNING`

    - `:STATUS_COMPLETED`

    - `:STATUS_FAILED`

    - `:STATUS_CANCELLED`

### Tool Approval Requested

- `class ToolApprovalRequested`

  - `tool_call_id: String`

    The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

### Tool Approved

- `class ToolApproved`

  - `tool_call_id: String`

    The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

### Tool Called

- `class ToolCalled`

  - `tool_call_id: String`

    The ID of the objective tool call record that was executed.

### Tool Denied

- `class ToolDenied`

  - `memo: String`

    The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

  - `tool_call_id: String`

    The ID of the objective tool call record that was denied via the DenyToolCall RPC.

### Tool Error

- `class ToolError`

  - `message: String`

  - `tool_call_id: String`

    The ID of the objective tool call record that encountered an error during execution.

### Tool Result

- `class ToolResult`

  - `content: String`

  - `tool_call_id: String`

### User Message

- `class UserMessage`

  - `content: String`

### Objective List Events Response

- `class ObjectiveListEventsResponse`

  - `data: ObjectiveEventData`

    - `assistant_message: AssistantMessage`

      - `content: String`

      - `tool_calls: Array[AssistantToolCall]`

        - `arguments: String`

        - `function_name: String`

        - `tool: CallableTool`

          CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
          might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

          - `agent: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `created_at: Time`

              Timestamp when this resource was created

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

              ID of the actor (user or service account) that created this resource

            - `workspace_id: String`

              Workspace this resource belongs to for organizational grouping (prefixed ULID)

            - `bundle_key: String`

              Optional bundle ownership key. When set, indicates the resource is
              managed by a configuration bundle identified by this key. Used by
              BulkWorkspaceResources.Apply to track which resources belong to which
              bundle for reconciliation / soft-delete on re-apply.

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `cadenya_provided_tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

          - `tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `cancelled: Cancelled{ message}`

      ObjectiveCancelled is the terminal event written when an objective is
      cancelled. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `message: String`

        Optional human-readable note recorded at cancel time. Today the workflow
        sets "Cancelled" but this field leaves room for richer reasons (e.g.
        "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted").

    - `context_window_compacted: ContextWindowCompacted`

      - `messages_compacted: Integer`

        Number of messages that were compacted

      - `new_context_window: ObjectiveContextWindowData`

        The new context window created by this compaction

        - `completion_tokens: Integer`

          A calculated value for how many completion tokens (output tokens) have been used in this context window

        - `objective_id: String`

          The objective's ID that this window belongs to

        - `previous_window_continue_instructions: String`

          The instructions for this window to continue from a previous window's chat history.

        - `prompt_tokens: Integer`

          A calculated value for how many prompt tokens (input tokens) have been used in this context window

        - `sequence: Integer`

          sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
          to calculate how many context windows an objective has.

      - `strategies: Array[String]`

        The strategies that were applied during this compaction

      - `summary: String`

        The summary generated by the summarization strategy, if used.

    - `error: ObjectiveError`

      - `message: String`

      - `type: String`

    - `finalized: Finalized{ output}`

      ObjectiveFinalized is the terminal event written when an objective is
      finalized. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `output: untyped`

        If the objective was created with an output schema, and the agent
        successfully completed the objective, this field will contain the
        structured output of the objective.

    - `memory_read: MemoryRead`

      MemoryRead is emitted each time the agent resolves a key against the
      memory stack and loads an entry. Lookups that miss (key not found in
      any layer) do not emit this event.

      - `memory_entry_id: String`

        The specific entry that was read.

      - `memory_layer_id: String`

        The layer the entry resolved to. The top-most layer that contained
        the key — other layers beneath it that also contained the key are
        shadowed and not referenced here.

      - `message: String`

        Human-readable description of the read, set by the runtime. For
        example: "Loaded skill", "Resolved context key". Not machine-parsed;
        intended for UI display alongside the other events in an objective's
        timeline.

    - `sub_agent_spawned: SubAgentSpawned`

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

        - `id: String`

          Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

        - `account_id: String`

          Account this operation belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this operation was created
          ULID includes timestamp information, but this explicit field enables easier querying

        - `profile_id: String`

          ID of the actor (user or service account) that created this operation

        - `workspace_id: String`

          Workspace this operation belongs to for organizational grouping (prefixed ULID)

        - `external_id: String`

          External ID for the operation (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

      - `task: String`

    - `sub_agent_updated: SubAgentUpdated`

      - `agent: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `message: String`

      - `objective: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

      - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

        - `:STATUS_UNSPECIFIED`

        - `:STATUS_PENDING`

        - `:STATUS_RUNNING`

        - `:STATUS_COMPLETED`

        - `:STATUS_FAILED`

        - `:STATUS_CANCELLED`

    - `tool_approval_requested: ToolApprovalRequested`

      - `tool_call_id: String`

        The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

    - `tool_approved: ToolApproved`

      - `tool_call_id: String`

        The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

    - `tool_called: ToolCalled`

      - `tool_call_id: String`

        The ID of the objective tool call record that was executed.

    - `tool_denied: ToolDenied`

      - `memo: String`

        The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

      - `tool_call_id: String`

        The ID of the objective tool call record that was denied via the DenyToolCall RPC.

    - `tool_error: ToolError`

      - `message: String`

      - `tool_call_id: String`

        The ID of the objective tool call record that encountered an error during execution.

    - `tool_result: ToolResult`

      - `content: String`

      - `tool_call_id: String`

    - `type: String`

    - `user_message: UserMessage`

      - `content: String`

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `context_window_id: String`

  - `info: ObjectiveEventInfo`

    - `created_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Objective Continue Response

- `class ObjectiveContinueResponse`

  - `data: ObjectiveEventData`

    - `assistant_message: AssistantMessage`

      - `content: String`

      - `tool_calls: Array[AssistantToolCall]`

        - `arguments: String`

        - `function_name: String`

        - `tool: CallableTool`

          CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
          might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

          - `agent: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

            - `id: String`

              Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

            - `account_id: String`

              Account this resource belongs to for multi-tenant isolation (prefixed ULID)

            - `created_at: Time`

              Timestamp when this resource was created

            - `name: String`

              Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
              Required for resources that users interact with directly

            - `profile_id: String`

              ID of the actor (user or service account) that created this resource

            - `workspace_id: String`

              Workspace this resource belongs to for organizational grouping (prefixed ULID)

            - `bundle_key: String`

              Optional bundle ownership key. When set, indicates the resource is
              managed by a configuration bundle identified by this key. Used by
              BulkWorkspaceResources.Apply to track which resources belong to which
              bundle for reconciliation / soft-delete on re-apply.

            - `external_id: String`

              External ID for the resource (e.g., a workflow ID from an external system)

            - `labels: Hash[Symbol, String]`

              Arbitrary key-value pairs for categorization and filtering
              Examples: {"environment": "production", "team": "platform", "version": "v2"}

          - `cadenya_provided_tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

          - `tool: ResourceMetadata`

            Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `cancelled: Cancelled{ message}`

      ObjectiveCancelled is the terminal event written when an objective is
      cancelled. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `message: String`

        Optional human-readable note recorded at cancel time. Today the workflow
        sets "Cancelled" but this field leaves room for richer reasons (e.g.
        "Cancelled by user", "Cancelled by schedule sweep", "Credit balance exhausted").

    - `context_window_compacted: ContextWindowCompacted`

      - `messages_compacted: Integer`

        Number of messages that were compacted

      - `new_context_window: ObjectiveContextWindowData`

        The new context window created by this compaction

        - `completion_tokens: Integer`

          A calculated value for how many completion tokens (output tokens) have been used in this context window

        - `objective_id: String`

          The objective's ID that this window belongs to

        - `previous_window_continue_instructions: String`

          The instructions for this window to continue from a previous window's chat history.

        - `prompt_tokens: Integer`

          A calculated value for how many prompt tokens (input tokens) have been used in this context window

        - `sequence: Integer`

          sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
          to calculate how many context windows an objective has.

      - `strategies: Array[String]`

        The strategies that were applied during this compaction

      - `summary: String`

        The summary generated by the summarization strategy, if used.

    - `error: ObjectiveError`

      - `message: String`

      - `type: String`

    - `finalized: Finalized{ output}`

      ObjectiveFinalized is the terminal event written when an objective is
      finalized. After this event, the objective is super-terminal: no further
      iterations, compaction, or continuation are permitted.

      - `output: untyped`

        If the objective was created with an output schema, and the agent
        successfully completed the objective, this field will contain the
        structured output of the objective.

    - `memory_read: MemoryRead`

      MemoryRead is emitted each time the agent resolves a key against the
      memory stack and loads an entry. Lookups that miss (key not found in
      any layer) do not emit this event.

      - `memory_entry_id: String`

        The specific entry that was read.

      - `memory_layer_id: String`

        The layer the entry resolved to. The top-most layer that contained
        the key — other layers beneath it that also contained the key are
        shadowed and not referenced here.

      - `message: String`

        Human-readable description of the read, set by the runtime. For
        example: "Loaded skill", "Resolved context key". Not machine-parsed;
        intended for UI display alongside the other events in an objective's
        timeline.

    - `sub_agent_spawned: SubAgentSpawned`

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `objective: OperationMetadata`

        Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

        - `id: String`

          Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

        - `account_id: String`

          Account this operation belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this operation was created
          ULID includes timestamp information, but this explicit field enables easier querying

        - `profile_id: String`

          ID of the actor (user or service account) that created this operation

        - `workspace_id: String`

          Workspace this operation belongs to for organizational grouping (prefixed ULID)

        - `external_id: String`

          External ID for the operation (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

      - `task: String`

    - `sub_agent_updated: SubAgentUpdated`

      - `agent: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `message: String`

      - `objective: BareMetadata`

        BareMetadata contains the minimal metadata for a resource: the ID and an
        optional human-readable name. These are used for reference fields where the
        full metadata (account scoping, timestamps, labels, external IDs) is not
        needed — e.g., the tool references inside an agent variation spec or the
        tools assigned to an objective. Both fields are server-populated; clients
        provide IDs through sibling fields rather than by constructing a
        BareMetadata themselves.

      - `status: :STATUS_UNSPECIFIED | :STATUS_PENDING | :STATUS_RUNNING | 3 more`

        - `:STATUS_UNSPECIFIED`

        - `:STATUS_PENDING`

        - `:STATUS_RUNNING`

        - `:STATUS_COMPLETED`

        - `:STATUS_FAILED`

        - `:STATUS_CANCELLED`

    - `tool_approval_requested: ToolApprovalRequested`

      - `tool_call_id: String`

        The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

    - `tool_approved: ToolApproved`

      - `tool_call_id: String`

        The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

    - `tool_called: ToolCalled`

      - `tool_call_id: String`

        The ID of the objective tool call record that was executed.

    - `tool_denied: ToolDenied`

      - `memo: String`

        The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

      - `tool_call_id: String`

        The ID of the objective tool call record that was denied via the DenyToolCall RPC.

    - `tool_error: ToolError`

      - `message: String`

      - `tool_call_id: String`

        The ID of the objective tool call record that encountered an error during execution.

    - `tool_result: ToolResult`

      - `content: String`

      - `tool_call_id: String`

    - `type: String`

    - `user_message: UserMessage`

      - `content: String`

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `context_window_id: String`

  - `info: ObjectiveEventInfo`

    - `created_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Objective Compact Response

- `class ObjectiveCompactResponse`

  Compact objective response

  - `context_window: ObjectiveContextWindowData`

    The new context window created by the compaction

    - `completion_tokens: Integer`

      A calculated value for how many completion tokens (output tokens) have been used in this context window

    - `objective_id: String`

      The objective's ID that this window belongs to

    - `previous_window_continue_instructions: String`

      The instructions for this window to continue from a previous window's chat history.

    - `prompt_tokens: Integer`

      A calculated value for how many prompt tokens (input tokens) have been used in this context window

    - `sequence: Integer`

      sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order
      to calculate how many context windows an objective has.

# Tools

## List objective tools

`objectives.tools.list(objective_id, **kwargs) -> CursorPagination<ObjectiveTool>`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tools`

Lists all tools that were assigned to an objective

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `limit: Integer`

  Maximum number of results to return

### Returns

- `class ObjectiveTool`

  ObjectiveTool represents a tool that was assigned to an objective.

  - `metadata: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `snapshot: Tool`

    Snapshot of the tool at the time it was assigned to the objective. Because tools can change over time, snapshots
    are used to ensure tools don't change unexpectedly during an objective's lifecycle.

    - `metadata: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ToolSpec`

      - `config: ToolSpecConfig`

        Config defines the adapter to use for the tool.
        This is used to determine how the tool is called.
        For example, if the tool is an HTTP tool, the adapter will be Http.
        If the tool is an inline tool, the adapter will be Inline.

        - `http: ConfigHTTP`

          - `request_method: :HTTP_METHOD_UNSPECIFIED | :GET | :POST | 3 more`

            - `:HTTP_METHOD_UNSPECIFIED`

            - `:GET`

            - `:POST`

            - `:PUT`

            - `:PATCH`

            - `:DELETE`

          - `headers: Hash[Symbol, String]`

          - `path: String`

          - `query: String`

          - `request_body_content_type: String`

          - `request_body_template: String`

            These are only used when the request method is a POST, PUT, or PATCH

          - `tool_name: String`

            The tool name (commonly an "operation id" in OpenAPI specs) to call on the HTTP adapter. This is used to match the tool spec to the correct endpoint on the HTTP adapter.
            it will be derived from the name of the tool if not provided.

        - `mcp: ConfigMcp`

          - `tool_description: String`

          - `tool_name: String`

          - `tool_title: String`

        - `openapi: ConfigOpenAPI`

          - `method_: String`

          - `operation_id: String`

          - `path: String`

      - `description: String`

      - `parameters: Hash[Symbol, untyped]`

      - `status: :TOOL_STATUS_UNSPECIFIED | :TOOL_STATUS_AVAILABLE | :TOOL_STATUS_OMITTED | :TOOL_STATUS_ARCHIVED`

        - `:TOOL_STATUS_UNSPECIFIED`

        - `:TOOL_STATUS_AVAILABLE`

        - `:TOOL_STATUS_OMITTED`

        - `:TOOL_STATUS_ARCHIVED`

      - `requires_approval: bool`

    - `info: ToolInfo`

      - `created_by: Profile`

        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.

        - `metadata: AccountResourceMetadata`

          AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

          - `id: String`

            Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

          - `account_id: String`

            Account this resource belongs to for multi-tenant isolation (prefixed ULID)

          - `name: String`

            Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
            Required for resources that users interact with directly

          - `profile_id: String`

          - `external_id: String`

            External ID for the resource (e.g., a workflow ID from an external system)

          - `labels: Hash[Symbol, String]`

            Arbitrary key-value pairs for categorization and filtering
            Examples: {"environment": "production", "team": "platform", "version": "v2"}

        - `spec: ProfileSpec`

          Configuration for a profile.

          - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

            Whether this profile represents a human user, an API key, or a system
            principal.

            - `:PROFILE_TYPE_UNSPECIFIED`

            - `:PROFILE_TYPE_USER`

            - `:PROFILE_TYPE_API_KEY`

            - `:PROFILE_TYPE_SYSTEM`

          - `email: String`

            Email address of the profile. Required and unique within an account for
            user profiles.

          - `name: String`

            Display name (e.g., "Bobby Tables").

      - `tool_set: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.tools.list("objectiveId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "name": "name"
      },
      "snapshot": {
        "metadata": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "spec": {
          "config": {
            "http": {
              "requestMethod": "HTTP_METHOD_UNSPECIFIED",
              "headers": {
                "foo": "string"
              },
              "path": "path",
              "query": "query",
              "requestBodyContentType": "requestBodyContentType",
              "requestBodyTemplate": "requestBodyTemplate",
              "toolName": "toolName"
            },
            "mcp": {
              "toolDescription": "toolDescription",
              "toolName": "toolName",
              "toolTitle": "toolTitle"
            },
            "openapi": {
              "method": "method",
              "operationId": "operationId",
              "path": "path"
            }
          },
          "description": "description",
          "parameters": {
            "foo": "bar"
          },
          "status": "TOOL_STATUS_UNSPECIFIED",
          "requiresApproval": true
        },
        "info": {
          "createdBy": {
            "metadata": {
              "id": "id",
              "accountId": "accountId",
              "name": "name",
              "profileId": "profileId",
              "externalId": "externalId",
              "labels": {
                "foo": "string"
              }
            },
            "spec": {
              "type": "PROFILE_TYPE_UNSPECIFIED",
              "email": "email",
              "name": "name"
            }
          },
          "toolSet": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Domain Types

### Objective Tool

- `class ObjectiveTool`

  ObjectiveTool represents a tool that was assigned to an objective.

  - `metadata: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `snapshot: Tool`

    Snapshot of the tool at the time it was assigned to the objective. Because tools can change over time, snapshots
    are used to ensure tools don't change unexpectedly during an objective's lifecycle.

    - `metadata: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ToolSpec`

      - `config: ToolSpecConfig`

        Config defines the adapter to use for the tool.
        This is used to determine how the tool is called.
        For example, if the tool is an HTTP tool, the adapter will be Http.
        If the tool is an inline tool, the adapter will be Inline.

        - `http: ConfigHTTP`

          - `request_method: :HTTP_METHOD_UNSPECIFIED | :GET | :POST | 3 more`

            - `:HTTP_METHOD_UNSPECIFIED`

            - `:GET`

            - `:POST`

            - `:PUT`

            - `:PATCH`

            - `:DELETE`

          - `headers: Hash[Symbol, String]`

          - `path: String`

          - `query: String`

          - `request_body_content_type: String`

          - `request_body_template: String`

            These are only used when the request method is a POST, PUT, or PATCH

          - `tool_name: String`

            The tool name (commonly an "operation id" in OpenAPI specs) to call on the HTTP adapter. This is used to match the tool spec to the correct endpoint on the HTTP adapter.
            it will be derived from the name of the tool if not provided.

        - `mcp: ConfigMcp`

          - `tool_description: String`

          - `tool_name: String`

          - `tool_title: String`

        - `openapi: ConfigOpenAPI`

          - `method_: String`

          - `operation_id: String`

          - `path: String`

      - `description: String`

      - `parameters: Hash[Symbol, untyped]`

      - `status: :TOOL_STATUS_UNSPECIFIED | :TOOL_STATUS_AVAILABLE | :TOOL_STATUS_OMITTED | :TOOL_STATUS_ARCHIVED`

        - `:TOOL_STATUS_UNSPECIFIED`

        - `:TOOL_STATUS_AVAILABLE`

        - `:TOOL_STATUS_OMITTED`

        - `:TOOL_STATUS_ARCHIVED`

      - `requires_approval: bool`

    - `info: ToolInfo`

      - `created_by: Profile`

        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.

        - `metadata: AccountResourceMetadata`

          AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

          - `id: String`

            Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

          - `account_id: String`

            Account this resource belongs to for multi-tenant isolation (prefixed ULID)

          - `name: String`

            Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
            Required for resources that users interact with directly

          - `profile_id: String`

          - `external_id: String`

            External ID for the resource (e.g., a workflow ID from an external system)

          - `labels: Hash[Symbol, String]`

            Arbitrary key-value pairs for categorization and filtering
            Examples: {"environment": "production", "team": "platform", "version": "v2"}

        - `spec: ProfileSpec`

          Configuration for a profile.

          - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

            Whether this profile represents a human user, an API key, or a system
            principal.

            - `:PROFILE_TYPE_UNSPECIFIED`

            - `:PROFILE_TYPE_USER`

            - `:PROFILE_TYPE_API_KEY`

            - `:PROFILE_TYPE_SYSTEM`

          - `email: String`

            Email address of the profile. Required and unique within an account for
            user profiles.

          - `name: String`

            Display name (e.g., "Bobby Tables").

      - `tool_set: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

# Tool Calls

## List objective tool calls

`objectives.tool_calls.list(objective_id, **kwargs) -> CursorPagination<ObjectiveToolCall>`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls`

Lists all tool calls for an objective

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `include_info: bool`

  When set to true you may use more of your alloted API rate-limit

- `limit: Integer`

  Maximum number of results to return

- `status: :TOOL_CALL_STATUS_UNSPECIFIED | :TOOL_CALL_STATUS_AUTO_APPROVED | :TOOL_CALL_STATUS_WAITING_FOR_APPROVAL | 2 more`

  Filter by tool call status

  - `:TOOL_CALL_STATUS_UNSPECIFIED`

  - `:TOOL_CALL_STATUS_AUTO_APPROVED`

  - `:TOOL_CALL_STATUS_WAITING_FOR_APPROVAL`

  - `:TOOL_CALL_STATUS_APPROVED`

  - `:TOOL_CALL_STATUS_DENIED`

### Returns

- `class ObjectiveToolCall`

  ObjectiveToolCall is a record of a tool call made during an objective's execution.
  Tool calls are mutable — their status changes as they are approved, denied, or executed.

  - `data: ObjectiveToolCallData`

    - `callable: CallableTool`

      CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
      might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `cadenya_provided_tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `arguments: Hash[Symbol, untyped]`

      The arguments passed to the tool

    - `memo: String`

      A memo supplied by the reviewer when denying the tool call

    - `result: String`

      The result content returned by the tool after execution

    - `status_changed_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: :TOOL_CALL_STATUS_UNSPECIFIED | :TOOL_CALL_STATUS_AUTO_APPROVED | :TOOL_CALL_STATUS_WAITING_FOR_APPROVAL | 2 more`

    Current status of the tool call

    - `:TOOL_CALL_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_STATUS_AUTO_APPROVED`

    - `:TOOL_CALL_STATUS_WAITING_FOR_APPROVAL`

    - `:TOOL_CALL_STATUS_APPROVED`

    - `:TOOL_CALL_STATUS_DENIED`

  - `execution_status: :TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED | :TOOL_CALL_EXECUTION_STATUS_PENDING | :TOOL_CALL_EXECUTION_STATUS_RUNNING | 2 more`

    - `:TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_EXECUTION_STATUS_PENDING`

    - `:TOOL_CALL_EXECUTION_STATUS_RUNNING`

    - `:TOOL_CALL_EXECUTION_STATUS_COMPLETED`

    - `:TOOL_CALL_EXECUTION_STATUS_ERRORED`

  - `info: ObjectiveToolCallInfo`

    - `created_by: Profile`

      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.

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.tool_calls.list("objectiveId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "callable": {
          "agent": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "cadenyaProvidedTool": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "tool": {
            "id": "id",
            "accountId": "accountId",
            "createdAt": "2019-12-27T18:11:19.117Z",
            "name": "name",
            "profileId": "profileId",
            "workspaceId": "workspaceId",
            "bundleKey": "bundleKey",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          }
        },
        "arguments": {
          "foo": "bar"
        },
        "memo": "memo",
        "result": "result",
        "statusChangedBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        }
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "status": "TOOL_CALL_STATUS_UNSPECIFIED",
      "executionStatus": "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED",
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "objective": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Approve a tool call

`objectives.tool_calls.approve(tool_call_id, **kwargs) -> ObjectiveToolCall`

**put** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}/approve`

When an agent attempts to use a tool that requires approval, use this endpoint to mark it as approved.

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `tool_call_id: String`

### Returns

- `class ObjectiveToolCall`

  ObjectiveToolCall is a record of a tool call made during an objective's execution.
  Tool calls are mutable — their status changes as they are approved, denied, or executed.

  - `data: ObjectiveToolCallData`

    - `callable: CallableTool`

      CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
      might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `cadenya_provided_tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `arguments: Hash[Symbol, untyped]`

      The arguments passed to the tool

    - `memo: String`

      A memo supplied by the reviewer when denying the tool call

    - `result: String`

      The result content returned by the tool after execution

    - `status_changed_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: :TOOL_CALL_STATUS_UNSPECIFIED | :TOOL_CALL_STATUS_AUTO_APPROVED | :TOOL_CALL_STATUS_WAITING_FOR_APPROVAL | 2 more`

    Current status of the tool call

    - `:TOOL_CALL_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_STATUS_AUTO_APPROVED`

    - `:TOOL_CALL_STATUS_WAITING_FOR_APPROVAL`

    - `:TOOL_CALL_STATUS_APPROVED`

    - `:TOOL_CALL_STATUS_DENIED`

  - `execution_status: :TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED | :TOOL_CALL_EXECUTION_STATUS_PENDING | :TOOL_CALL_EXECUTION_STATUS_RUNNING | 2 more`

    - `:TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_EXECUTION_STATUS_PENDING`

    - `:TOOL_CALL_EXECUTION_STATUS_RUNNING`

    - `:TOOL_CALL_EXECUTION_STATUS_COMPLETED`

    - `:TOOL_CALL_EXECUTION_STATUS_ERRORED`

  - `info: ObjectiveToolCallInfo`

    - `created_by: Profile`

      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.

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective_tool_call = cadenya.objectives.tool_calls.approve(
  "toolCallId",
  workspace_id: "workspaceId",
  objective_id: "objectiveId"
)

puts(objective_tool_call)
```

#### Response

```json
{
  "data": {
    "callable": {
      "agent": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "cadenyaProvidedTool": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "tool": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      }
    },
    "arguments": {
      "foo": "bar"
    },
    "memo": "memo",
    "result": "result",
    "statusChangedBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    }
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "status": "TOOL_CALL_STATUS_UNSPECIFIED",
  "executionStatus": "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED",
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "objective": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    }
  }
}
```

## Deny a tool call

`objectives.tool_calls.deny(tool_call_id, **kwargs) -> ObjectiveToolCall`

**put** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}/deny`

When an agent attempts to use a tool that requires approval, use this endpoint to mark it as denied. Use a memo to steer the LLM to a different decision or usage of the tool.

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `tool_call_id: String`

- `memo: String`

  A memo to associate to the tool call denial. Use a memo to steer the LLM to a different decision or usage of the tool.

### Returns

- `class ObjectiveToolCall`

  ObjectiveToolCall is a record of a tool call made during an objective's execution.
  Tool calls are mutable — their status changes as they are approved, denied, or executed.

  - `data: ObjectiveToolCallData`

    - `callable: CallableTool`

      CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
      might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `cadenya_provided_tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `arguments: Hash[Symbol, untyped]`

      The arguments passed to the tool

    - `memo: String`

      A memo supplied by the reviewer when denying the tool call

    - `result: String`

      The result content returned by the tool after execution

    - `status_changed_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: :TOOL_CALL_STATUS_UNSPECIFIED | :TOOL_CALL_STATUS_AUTO_APPROVED | :TOOL_CALL_STATUS_WAITING_FOR_APPROVAL | 2 more`

    Current status of the tool call

    - `:TOOL_CALL_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_STATUS_AUTO_APPROVED`

    - `:TOOL_CALL_STATUS_WAITING_FOR_APPROVAL`

    - `:TOOL_CALL_STATUS_APPROVED`

    - `:TOOL_CALL_STATUS_DENIED`

  - `execution_status: :TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED | :TOOL_CALL_EXECUTION_STATUS_PENDING | :TOOL_CALL_EXECUTION_STATUS_RUNNING | 2 more`

    - `:TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_EXECUTION_STATUS_PENDING`

    - `:TOOL_CALL_EXECUTION_STATUS_RUNNING`

    - `:TOOL_CALL_EXECUTION_STATUS_COMPLETED`

    - `:TOOL_CALL_EXECUTION_STATUS_ERRORED`

  - `info: ObjectiveToolCallInfo`

    - `created_by: Profile`

      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.

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective_tool_call = cadenya.objectives.tool_calls.deny("toolCallId", workspace_id: "workspaceId", objective_id: "objectiveId")

puts(objective_tool_call)
```

#### Response

```json
{
  "data": {
    "callable": {
      "agent": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "cadenyaProvidedTool": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "tool": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      }
    },
    "arguments": {
      "foo": "bar"
    },
    "memo": "memo",
    "result": "result",
    "statusChangedBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    }
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "status": "TOOL_CALL_STATUS_UNSPECIFIED",
  "executionStatus": "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED",
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "objective": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    }
  }
}
```

## Domain Types

### Objective Tool Call

- `class ObjectiveToolCall`

  ObjectiveToolCall is a record of a tool call made during an objective's execution.
  Tool calls are mutable — their status changes as they are approved, denied, or executed.

  - `data: ObjectiveToolCallData`

    - `callable: CallableTool`

      CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
      might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

      - `agent: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `created_at: Time`

          Timestamp when this resource was created

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

          ID of the actor (user or service account) that created this resource

        - `workspace_id: String`

          Workspace this resource belongs to for organizational grouping (prefixed ULID)

        - `bundle_key: String`

          Optional bundle ownership key. When set, indicates the resource is
          managed by a configuration bundle identified by this key. Used by
          BulkWorkspaceResources.Apply to track which resources belong to which
          bundle for reconciliation / soft-delete on re-apply.

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `cadenya_provided_tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `tool: ResourceMetadata`

        Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `arguments: Hash[Symbol, untyped]`

      The arguments passed to the tool

    - `memo: String`

      A memo supplied by the reviewer when denying the tool call

    - `result: String`

      The result content returned by the tool after execution

    - `status_changed_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `status: :TOOL_CALL_STATUS_UNSPECIFIED | :TOOL_CALL_STATUS_AUTO_APPROVED | :TOOL_CALL_STATUS_WAITING_FOR_APPROVAL | 2 more`

    Current status of the tool call

    - `:TOOL_CALL_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_STATUS_AUTO_APPROVED`

    - `:TOOL_CALL_STATUS_WAITING_FOR_APPROVAL`

    - `:TOOL_CALL_STATUS_APPROVED`

    - `:TOOL_CALL_STATUS_DENIED`

  - `execution_status: :TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED | :TOOL_CALL_EXECUTION_STATUS_PENDING | :TOOL_CALL_EXECUTION_STATUS_RUNNING | 2 more`

    - `:TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED`

    - `:TOOL_CALL_EXECUTION_STATUS_PENDING`

    - `:TOOL_CALL_EXECUTION_STATUS_RUNNING`

    - `:TOOL_CALL_EXECUTION_STATUS_COMPLETED`

    - `:TOOL_CALL_EXECUTION_STATUS_ERRORED`

  - `info: ObjectiveToolCallInfo`

    - `created_by: Profile`

      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.

    - `objective: OperationMetadata`

      Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

### Objective Tool Call Data

- `class ObjectiveToolCallData`

  - `callable: CallableTool`

    CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective
    might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

    - `agent: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `created_at: Time`

        Timestamp when this resource was created

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

        ID of the actor (user or service account) that created this resource

      - `workspace_id: String`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `bundle_key: String`

        Optional bundle ownership key. When set, indicates the resource is
        managed by a configuration bundle identified by this key. Used by
        BulkWorkspaceResources.Apply to track which resources belong to which
        bundle for reconciliation / soft-delete on re-apply.

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `cadenya_provided_tool: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `tool: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

  - `arguments: Hash[Symbol, untyped]`

    The arguments passed to the tool

  - `memo: String`

    A memo supplied by the reviewer when denying the tool call

  - `result: String`

    The result content returned by the tool after execution

  - `status_changed_by: Profile`

    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.

    - `metadata: AccountResourceMetadata`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

### Objective Tool Call Info

- `class ObjectiveToolCallInfo`

  - `created_by: Profile`

    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.

    - `metadata: AccountResourceMetadata`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

  - `objective: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

# Tasks

## List objective tasks

`objectives.tasks.list(objective_id, **kwargs) -> CursorPagination<ObjectiveTask>`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tasks`

Lists all tasks for an objective

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `limit: Integer`

  Maximum number of results to return

- `sort_order: String`

  Sort order for results

### Returns

- `class ObjectiveTask`

  ObjectiveTask represents a task within an objective, typically created and managed by an AI agent
  to track progress toward completing the objective.

  - `data: ObjectiveTaskData`

    - `completed: bool`

      Whether the task has been completed

    - `number: Integer`

      The sequential number of this task within the objective (auto-assigned, 1-based)

    - `task: String`

      Description of the task to be completed

    - `completed_at: Time`

      Timestamp when the task was marked as completed

  - `metadata: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.tasks.list("objectiveId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "completed": true,
        "number": 0,
        "task": "task",
        "completedAt": "2019-12-27T18:11:19.117Z"
      },
      "metadata": {
        "id": "id",
        "name": "name"
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Get an objective task by ID

`objectives.tasks.retrieve(id, **kwargs) -> ObjectiveTask`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tasks/{id}`

Retrieves a task by ID from an objective

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `id: String`

### Returns

- `class ObjectiveTask`

  ObjectiveTask represents a task within an objective, typically created and managed by an AI agent
  to track progress toward completing the objective.

  - `data: ObjectiveTaskData`

    - `completed: bool`

      Whether the task has been completed

    - `number: Integer`

      The sequential number of this task within the objective (auto-assigned, 1-based)

    - `task: String`

      Description of the task to be completed

    - `completed_at: Time`

      Timestamp when the task was marked as completed

  - `metadata: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective_task = cadenya.objectives.tasks.retrieve("id", workspace_id: "workspaceId", objective_id: "objectiveId")

puts(objective_task)
```

#### Response

```json
{
  "data": {
    "completed": true,
    "number": 0,
    "task": "task",
    "completedAt": "2019-12-27T18:11:19.117Z"
  },
  "metadata": {
    "id": "id",
    "name": "name"
  }
}
```

## Domain Types

### Objective Task

- `class ObjectiveTask`

  ObjectiveTask represents a task within an objective, typically created and managed by an AI agent
  to track progress toward completing the objective.

  - `data: ObjectiveTaskData`

    - `completed: bool`

      Whether the task has been completed

    - `number: Integer`

      The sequential number of this task within the objective (auto-assigned, 1-based)

    - `task: String`

      Description of the task to be completed

    - `completed_at: Time`

      Timestamp when the task was marked as completed

  - `metadata: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

### Objective Task Data

- `class ObjectiveTaskData`

  - `completed: bool`

    Whether the task has been completed

  - `number: Integer`

    The sequential number of this task within the objective (auto-assigned, 1-based)

  - `task: String`

    Description of the task to be completed

  - `completed_at: Time`

    Timestamp when the task was marked as completed

# Feedback

## Submit feedback for an objective

`objectives.feedback.create(objective_id, **kwargs) -> ObjectiveFeedback`

**post** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback`

Submits feedback for an objective's execution. Feedback scores are used by the agent variation scoring system to evaluate and rank variation performance.

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `data: ObjectiveFeedbackData`

  - `comment: String`

    Optional human-readable comment explaining the feedback

  - `score: Float`

    A score between -1.0 and 1.0 representing the quality of the objective's execution.
    -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

- `metadata: CreateOperationMetadata`

  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.

  - `external_id: String`

    External ID for the operation (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Returns

- `class ObjectiveFeedback`

  ObjectiveFeedback represents feedback submitted for an objective's execution.
  Feedback is used to score agent variations and improve agent performance over time.

  - `data: ObjectiveFeedbackData`

    - `comment: String`

      Optional human-readable comment explaining the feedback

    - `score: Float`

      A score between -1.0 and 1.0 representing the quality of the objective's execution.
      -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info: ObjectiveFeedbackInfo`

    - `agent_variation: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

      - `id: String`

      - `name: String`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `objective: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

    - `submitted_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective_feedback = cadenya.objectives.feedback.create("objectiveId", workspace_id: "workspaceId", data: {}, metadata: {})

puts(objective_feedback)
```

#### Response

```json
{
  "data": {
    "comment": "comment",
    "score": 0
  },
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "info": {
    "agentVariation": {
      "id": "id",
      "name": "name"
    },
    "objective": {
      "id": "id",
      "name": "name"
    },
    "submittedBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    }
  }
}
```

## List feedback for an objective

`objectives.feedback.list(objective_id, **kwargs) -> CursorPagination<ObjectiveFeedback>`

**get** `/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback`

Lists all feedback submitted for an objective

### Parameters

- `workspace_id: String`

- `objective_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `limit: Integer`

  Maximum number of results to return

### Returns

- `class ObjectiveFeedback`

  ObjectiveFeedback represents feedback submitted for an objective's execution.
  Feedback is used to score agent variations and improve agent performance over time.

  - `data: ObjectiveFeedbackData`

    - `comment: String`

      Optional human-readable comment explaining the feedback

    - `score: Float`

      A score between -1.0 and 1.0 representing the quality of the objective's execution.
      -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info: ObjectiveFeedbackInfo`

    - `agent_variation: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

      - `id: String`

      - `name: String`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `objective: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

    - `submitted_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.objectives.feedback.list("objectiveId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "comment": "comment",
        "score": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "agentVariation": {
          "id": "id",
          "name": "name"
        },
        "objective": {
          "id": "id",
          "name": "name"
        },
        "submittedBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Domain Types

### Objective Feedback

- `class ObjectiveFeedback`

  ObjectiveFeedback represents feedback submitted for an objective's execution.
  Feedback is used to score agent variations and improve agent performance over time.

  - `data: ObjectiveFeedbackData`

    - `comment: String`

      Optional human-readable comment explaining the feedback

    - `score: Float`

      A score between -1.0 and 1.0 representing the quality of the objective's execution.
      -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info: ObjectiveFeedbackInfo`

    - `agent_variation: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

      - `id: String`

      - `name: String`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `objective: BareMetadata`

      BareMetadata contains the minimal metadata for a resource: the ID and an
      optional human-readable name. These are used for reference fields where the
      full metadata (account scoping, timestamps, labels, external IDs) is not
      needed — e.g., the tool references inside an agent variation spec or the
      tools assigned to an objective. Both fields are server-populated; clients
      provide IDs through sibling fields rather than by constructing a
      BareMetadata themselves.

    - `submitted_by: Profile`

      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.

      - `metadata: AccountResourceMetadata`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

### Objective Feedback Data

- `class ObjectiveFeedbackData`

  - `comment: String`

    Optional human-readable comment explaining the feedback

  - `score: Float`

    A score between -1.0 and 1.0 representing the quality of the objective's execution.
    -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

### Objective Feedback Info

- `class ObjectiveFeedbackInfo`

  - `agent_variation: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `objective: BareMetadata`

    BareMetadata contains the minimal metadata for a resource: the ID and an
    optional human-readable name. These are used for reference fields where the
    full metadata (account scoping, timestamps, labels, external IDs) is not
    needed — e.g., the tool references inside an agent variation spec or the
    tools assigned to an objective. Both fields are server-populated; clients
    provide IDs through sibling fields rather than by constructing a
    BareMetadata themselves.

  - `submitted_by: Profile`

    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.

    - `metadata: AccountResourceMetadata`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").