@cadenya/cadenya 0.102.0 → 0.104.0

package/resources/objectives/objectives.mjs

@@ -85,6 +85,16 @@ export class Objectives extends APIResource {
         const { workspaceId, ...query } = params;
         return this._client.getAPIList(path `/v1/workspaces/${workspaceId}/objectives/${objectiveID}/events`, (CursorPagination), { query, ...options });
     }
+    /**
+     * Returns the context-usage breakdown measured for the objective's most recent
+     * iteration: character lengths per context component (system prompt, memory
+     * appendices, tool definitions, messages by role) alongside the iteration's input
+     * token counts.
+     */
+    retrieveDiagnostics(objectiveID, params, options) {
+        const { workspaceId } = params;
+        return this._client.get(path `/v1/workspaces/${workspaceId}/objectives/${objectiveID}/diagnostics`, options);
+    }
     /**
      * Streams events for an objective in real-time using server-sent events (SSE)
      */

package/resources/objectives/objectives.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"objectives.mjs","sourceRoot":"","sources":["../../src/resources/objectives/objectives.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"objectives.mjs","sourceRoot":"","sources":["../../src/resources/objectives/objectives.ts"],"names":[],"mappings":"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"}

package/src/client.ts

@@ -130,6 +130,7 @@ import {
   AssistantMessage,
   AssistantToolCall,
   CallableTool,
+  ContextLengths,
   ContextWindowCompacted,
   MemoryRead,
   MemoryReference,
@@ -143,6 +144,7 @@ import {
   ObjectiveContextWindowsCursorPagination,
   ObjectiveContinueParams,
   ObjectiveCreateParams,
+  ObjectiveDiagnostics,
   ObjectiveError,
   ObjectiveEvent,
   ObjectiveEventData,
@@ -153,6 +155,8 @@ import {
   ObjectiveListContextWindowsParams,
   ObjectiveListEventsParams,
   ObjectiveListParams,
+  ObjectiveRetrieveDiagnosticsParams,
+  ObjectiveRetrieveDiagnosticsResponse,
   ObjectiveRetrieveParams,
   ObjectiveSecret,
   ObjectiveStreamEventsParams,
@@ -1102,6 +1106,7 @@ export declare namespace Cadenya {
     type AssistantMessage as AssistantMessage,
     type AssistantToolCall as AssistantToolCall,
     type CallableTool as CallableTool,
+    type ContextLengths as ContextLengths,
     type ContextWindowCompacted as ContextWindowCompacted,
     type MemoryRead as MemoryRead,
     type MemoryReference as MemoryReference,
@@ -1109,6 +1114,7 @@ export declare namespace Cadenya {
     type ObjectiveConfigSnapshot as ObjectiveConfigSnapshot,
     type ObjectiveContextWindow as ObjectiveContextWindow,
     type ObjectiveContextWindowData as ObjectiveContextWindowData,
+    type ObjectiveDiagnostics as ObjectiveDiagnostics,
     type ObjectiveError as ObjectiveError,
     type ObjectiveEvent as ObjectiveEvent,
     type ObjectiveEventData as ObjectiveEventData,
@@ -1126,6 +1132,7 @@ export declare namespace Cadenya {
     type ToolResult as ToolResult,
     type UserMessage as UserMessage,
     type ObjectiveCompactResponse as ObjectiveCompactResponse,
+    type ObjectiveRetrieveDiagnosticsResponse as ObjectiveRetrieveDiagnosticsResponse,
     type ObjectivesCursorPagination as ObjectivesCursorPagination,
     type ObjectiveContextWindowsCursorPagination as ObjectiveContextWindowsCursorPagination,
     type ObjectiveEventsCursorPagination as ObjectiveEventsCursorPagination,
@@ -1137,6 +1144,7 @@ export declare namespace Cadenya {
     type ObjectiveContinueParams as ObjectiveContinueParams,
     type ObjectiveListContextWindowsParams as ObjectiveListContextWindowsParams,
     type ObjectiveListEventsParams as ObjectiveListEventsParams,
+    type ObjectiveRetrieveDiagnosticsParams as ObjectiveRetrieveDiagnosticsParams,
     type ObjectiveStreamEventsParams as ObjectiveStreamEventsParams,
   };
 

package/src/resources/agents/agents.ts

@@ -246,15 +246,6 @@ export interface AgentSpec {
    */
   episodicMemoryTtl?: number;
 
-  /**
-   * 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.
-   */
-  inputDataSchema?: { [key: string]: unknown };
-
   /**
    * 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
@@ -263,6 +254,16 @@ export interface AgentSpec {
    */
   outputDefinition?: { [key: string]: unknown };
 
+  /**
+   * SystemPromptDataSchema enforces the shape of system_prompt_data when objectives
+   * are created. This is valuable when using liquid formatting in agent variation
+   * system prompt templates. The schema is also used when the agent is attached as a
+   * sub-agent, as it becomes 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.
+   */
+  systemPromptDataSchema?: { [key: string]: unknown };
+
   /**
    * The URL that Cadenya will send events for any objective assigned to the agent.
    */

package/src/resources/agents/schedules.ts

@@ -194,17 +194,18 @@ export interface AgentScheduleSpec {
   schedule: AgentScheduleSpecSchedule;
 
   /**
-   * Optional input data passed to the objective. If the agent has an
-   * input_data_schema, this must satisfy it.
+   * Optional explicit first user message passed to CreateObjective on each fire.
+   * Becomes the first user message in the objective's chat history. When unset, the
+   * fired objective defers to the selected variation's first_user_message_template.
    */
-  data?: unknown;
+  firstUserMessage?: string;
 
   /**
-   * Optional initial message passed to CreateObjective on each fire. Becomes the
-   * first user message in the objective's chat history. When unset, the fired
-   * objective defers to the selected variation's user_message_template.
+   * Optional data rendered into the variation's first_user_message_template when
+   * each fired objective is created. Separate from `system_prompt_data`, which
+   * renders the system prompt template.
    */
-  initialMessage?: string;
+  firstUserMessageData?: unknown;
 
   /**
    * What to do when the previous run is still in flight. Defaults to SKIP.
@@ -212,11 +213,11 @@ export interface AgentScheduleSpec {
   overlapPolicy?: 'OVERLAP_POLICY_UNSPECIFIED' | 'OVERLAP_POLICY_ALLOW' | 'OVERLAP_POLICY_SKIP';
 
   /**
-   * Optional data rendered into the variation's user_message_template when each
-   * fired objective is created. Separate from `data`, which renders the system
-   * prompt template.
+   * Optional data rendered into the variation's system_prompt_template when each
+   * fired objective is created. If the agent has a system_prompt_data_schema, this
+   * must satisfy it.
    */
-  userData?: unknown;
+  systemPromptData?: unknown;
 
   /**
    * Optional explicit variation. When unset, the agent's variation_selection_mode

package/src/resources/agents/variations.ts

@@ -262,6 +262,16 @@ export interface AgentVariationSpec {
    */
   description?: string;
 
+  /**
+   * Liquid template for the first user message of objectives using this variation.
+   * Rendered with CreateObjectiveRequest.first_user_message_data into
+   * Objective.first_user_message, the first user message in the LLM chat history.
+   * CreateObjectiveRequest.first_user_message, when set, overrides the rendered
+   * result. If neither this template nor first_user_message is present, objective
+   * creation is rejected with InvalidArgument.
+   */
+  firstUserMessageTemplate?: string;
+
   /**
    * ModelConfig defines the model configuration for a variation
    */
@@ -278,19 +288,11 @@ export interface AgentVariationSpec {
 
   /**
    * Liquid template for the system prompt of objectives using this variation.
-   * Rendered with CreateObjectiveRequest.data into Objective.system_prompt.
+   * Rendered with CreateObjectiveRequest.system_prompt_data into
+   * Objective.system_prompt.
    */
   systemPromptTemplate?: string;
 
-  /**
-   * Liquid template for the initial user message of objectives using this variation.
-   * Rendered with CreateObjectiveRequest.user_data and becomes the first user
-   * message in the LLM chat history. CreateObjectiveRequest.initial_message, when
-   * set, overrides the rendered result. If neither this template nor initial_message
-   * is present, objective creation is rejected with InvalidArgument.
-   */
-  userMessageTemplate?: string;
-
   /**
    * 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

package/src/resources/index.ts

@@ -80,6 +80,7 @@ export {
   type AssistantMessage,
   type AssistantToolCall,
   type CallableTool,
+  type ContextLengths,
   type ContextWindowCompacted,
   type MemoryRead,
   type MemoryReference,
@@ -87,6 +88,7 @@ export {
   type ObjectiveConfigSnapshot,
   type ObjectiveContextWindow,
   type ObjectiveContextWindowData,
+  type ObjectiveDiagnostics,
   type ObjectiveError,
   type ObjectiveEvent,
   type ObjectiveEventData,
@@ -104,6 +106,7 @@ export {
   type ToolResult,
   type UserMessage,
   type ObjectiveCompactResponse,
+  type ObjectiveRetrieveDiagnosticsResponse,
   type ObjectiveCreateParams,
   type ObjectiveRetrieveParams,
   type ObjectiveListParams,
@@ -112,6 +115,7 @@ export {
   type ObjectiveContinueParams,
   type ObjectiveListContextWindowsParams,
   type ObjectiveListEventsParams,
+  type ObjectiveRetrieveDiagnosticsParams,
   type ObjectiveStreamEventsParams,
   type ObjectivesCursorPagination,
   type ObjectiveContextWindowsCursorPagination,

package/src/resources/objectives/index.ts

@@ -14,6 +14,7 @@ export {
   type AssistantMessage,
   type AssistantToolCall,
   type CallableTool,
+  type ContextLengths,
   type ContextWindowCompacted,
   type MemoryRead,
   type MemoryReference,
@@ -21,6 +22,7 @@ export {
   type ObjectiveConfigSnapshot,
   type ObjectiveContextWindow,
   type ObjectiveContextWindowData,
+  type ObjectiveDiagnostics,
   type ObjectiveError,
   type ObjectiveEvent,
   type ObjectiveEventData,
@@ -38,6 +40,7 @@ export {
   type ToolResult,
   type UserMessage,
   type ObjectiveCompactResponse,
+  type ObjectiveRetrieveDiagnosticsResponse,
   type ObjectiveCreateParams,
   type ObjectiveRetrieveParams,
   type ObjectiveListParams,
@@ -46,6 +49,7 @@ export {
   type ObjectiveContinueParams,
   type ObjectiveListContextWindowsParams,
   type ObjectiveListEventsParams,
+  type ObjectiveRetrieveDiagnosticsParams,
   type ObjectiveStreamEventsParams,
   type ObjectivesCursorPagination,
   type ObjectiveContextWindowsCursorPagination,

package/src/resources/objectives/objectives.ts

@@ -170,6 +170,24 @@ export class Objectives extends APIResource {
     );
   }
 
+  /**
+   * Returns the context-usage breakdown measured for the objective's most recent
+   * iteration: character lengths per context component (system prompt, memory
+   * appendices, tool definitions, messages by role) alongside the iteration's input
+   * token counts.
+   */
+  retrieveDiagnostics(
+    objectiveID: string,
+    params: ObjectiveRetrieveDiagnosticsParams,
+    options?: RequestOptions,
+  ): APIPromise<ObjectiveRetrieveDiagnosticsResponse> {
+    const { workspaceId } = params;
+    return this._client.get(
+      path`/v1/workspaces/${workspaceId}/objectives/${objectiveID}/diagnostics`,
+      options,
+    );
+  }
+
   /**
    * Streams events for an objective in real-time using server-sent events (SSE)
    */
@@ -236,6 +254,59 @@ export interface CallableTool {
   tool?: Shared.ResourceMetadata;
 }
 
+/**
+ * ContextLengths is the measured character length of each distinct component of an
+ * iteration's assembled context window. Values are raw character lengths of the
+ * component as assembled into the request — token estimates are derived by the
+ * client against input_tokens (component share = component length / sum of all
+ * lengths).
+ *
+ * New components are added as new fields — wire-compatible; absent components read
+ * as 0.
+ */
+export interface ContextLengths {
+  /**
+   * Chat history messages with the assistant role.
+   */
+  assistantMessages: number;
+
+  /**
+   * The discoverable/available-tools appendix attached to the system prompt.
+   */
+  availableTools: number;
+
+  /**
+   * The episodic memory appendix attached to the system prompt.
+   */
+  episodicMemory: number;
+
+  /**
+   * The skills memory appendix attached to the system prompt.
+   */
+  skillsMemory: number;
+
+  /**
+   * The objective's base system prompt (rendered variation template).
+   */
+  systemPrompt: number;
+
+  /**
+   * Serialized tool definitions sent with the completion request (names,
+   * descriptions, and JSON-schema parameters).
+   */
+  toolDefinitions: number;
+
+  /**
+   * Tool results present in the chat history.
+   */
+  toolResults: number;
+
+  /**
+   * Chat history messages with the user role.
+   */
+  userMessages: number;
+}
+
 export interface ContextWindowCompacted {
   /**
    * Number of messages that were compacted
@@ -317,10 +388,10 @@ export interface Objective {
   configSnapshot: ObjectiveConfigSnapshot;
 
   /**
-   * The initial message sent to the agent. This becomes the first user message in
-   * the LLM chat history.
+   * The first user message in the LLM chat history, either provided explicitly at
+   * creation or rendered from the variation's first_user_message_template.
    */
-  initialMessage: string;
+  firstUserMessage: string;
 
   /**
    * Metadata for ephemeral operations and activities (e.g., objectives, executions,
@@ -346,14 +417,14 @@ export interface Objective {
   systemPrompt: string;
 
   /**
-   * Arbitrary data for the objective
+   * Episodic is used to configure the episodic memory for the objective
    */
-  data?: { [key: string]: unknown };
+  episodicMemory?: Objective.EpisodicMemory;
 
   /**
-   * Episodic is used to configure the episodic memory for the objective
+   * Arbitrary data rendered into the variation's first_user_message_template
    */
-  episodicMemory?: Objective.EpisodicMemory;
+  firstUserMessageData?: { [key: string]: unknown };
 
   /**
    * ObjectiveInfo provides read-only aggregated statistics about an objective's
@@ -403,9 +474,9 @@ export interface Objective {
   stateMessage?: string;
 
   /**
-   * Arbitrary data used to render the variation's user_message_template
+   * Arbitrary data rendered into the variation's system_prompt_template
    */
-  userData?: { [key: string]: unknown };
+  systemPromptData?: { [key: string]: unknown };
 }
 
 export namespace Objective {
@@ -515,6 +586,37 @@ export interface ObjectiveContextWindowData {
   sequence?: number;
 }
 
+/**
+ * ObjectiveDiagnostics is the context-usage breakdown measured for a single
+ * iteration at request-assembly time. It reports how much of the context window
+ * each component occupies so tool parameters, memory cascades, and prompts can be
+ * tuned against real token usage.
+ */
+export interface ObjectiveDiagnostics {
+  /**
+   * The portion of input_tokens served from the provider's prompt cache. Lets
+   * clients distinguish "big but cached" from "big and paid fresh every iteration".
+   */
+  cachedInputTokens: number;
+
+  /**
+   * ContextLengths is the measured character length of each distinct component of an
+   * iteration's assembled context window. Values are raw character lengths of the
+   * component as assembled into the request — token estimates are derived by the
+   * client against input_tokens (component share = component length / sum of all
+   * lengths).
+   *
+   * New components are added as new fields — wire-compatible; absent components read
+   * as 0.
+   */
+  contextLengths: ContextLengths;
+
+  /**
+   * Input tokens reported by the LLM provider for the iteration's completion.
+   */
+  inputTokens: number;
+}
+
 export interface ObjectiveError {
   message?: string;
 
@@ -899,14 +1001,25 @@ export interface ObjectiveCompactResponse {
   contextWindow?: ObjectiveContextWindowData;
 }
 
+export interface ObjectiveRetrieveDiagnosticsResponse {
+  /**
+   * ObjectiveDiagnostics is the context-usage breakdown measured for a single
+   * iteration at request-assembly time. It reports how much of the context window
+   * each component occupies so tool parameters, memory cascades, and prompts can be
+   * tuned against real token usage.
+   */
+  diagnostics: ObjectiveDiagnostics;
+}
+
 export interface ObjectiveCreateParams {
   agentId: string;
 
   /**
-   * Arbitrary data for the objective. May be used in liquid templates for prompts
-   * configured on the agent variation
+   * Arbitrary data rendered into the selected variation's system_prompt_template
+   * (liquid) to produce the objective's system prompt. If the agent has a
+   * system_prompt_data_schema, this must satisfy it.
    */
-  data: { [key: string]: unknown };
+  systemPromptData: { [key: string]: unknown };
 
   /**
    * Episodic is used to configure the episodic memory for the objective
@@ -914,13 +1027,20 @@ export interface ObjectiveCreateParams {
   episodicMemory?: ObjectiveCreateParams.EpisodicMemory;
 
   /**
-   * Optional override for the initial message sent to the agent. This becomes the
-   * first user message in the LLM chat history. When not set, the selected
-   * variation's user_message_template is rendered with user_data instead. If neither
-   * this field nor a user_message_template is present, the request is rejected with
+   * Optional explicit first user message for the LLM chat history. When not set, the
+   * selected variation's first_user_message_template is rendered with
+   * first_user_message_data instead. If neither this field nor a
+   * first_user_message_template is present, the request is rejected with
    * InvalidArgument.
    */
-  initialMessage?: string;
+  firstUserMessage?: string;
+
+  /**
+   * Arbitrary data rendered into the selected variation's
+   * first_user_message_template (liquid) to produce the first user message. Separate
+   * from `system_prompt_data`, which renders the system prompt template.
+   */
+  firstUserMessageData?: { [key: string]: unknown };
 
   /**
    * Memory layers/entries layered over the baseline cascade inherited from the
@@ -952,13 +1072,6 @@ export interface ObjectiveCreateParams {
    */
   secrets?: Array<ObjectiveCreateParams.Secret>;
 
-  /**
-   * Arbitrary data rendered into the selected variation's user_message_template
-   * (liquid) to produce the initial user message. Separate from `data`, which
-   * renders the system prompt template.
-   */
-  userData?: { [key: string]: unknown };
-
   /**
    * Optional explicit variation selection. Overrides the agent's
    * variation_selection_mode.
@@ -1114,6 +1227,10 @@ export interface ObjectiveListEventsParams extends CursorPaginationParams {
   windowId?: string;
 }
 
+export interface ObjectiveRetrieveDiagnosticsParams {
+  workspaceId: string;
+}
+
 export interface ObjectiveStreamEventsParams {
   workspaceId: string;
 }
@@ -1128,6 +1245,7 @@ export declare namespace Objectives {
     type AssistantMessage as AssistantMessage,
     type AssistantToolCall as AssistantToolCall,
     type CallableTool as CallableTool,
+    type ContextLengths as ContextLengths,
     type ContextWindowCompacted as ContextWindowCompacted,
     type MemoryRead as MemoryRead,
     type MemoryReference as MemoryReference,
@@ -1135,6 +1253,7 @@ export declare namespace Objectives {
     type ObjectiveConfigSnapshot as ObjectiveConfigSnapshot,
     type ObjectiveContextWindow as ObjectiveContextWindow,
     type ObjectiveContextWindowData as ObjectiveContextWindowData,
+    type ObjectiveDiagnostics as ObjectiveDiagnostics,
     type ObjectiveError as ObjectiveError,
     type ObjectiveEvent as ObjectiveEvent,
     type ObjectiveEventData as ObjectiveEventData,
@@ -1152,6 +1271,7 @@ export declare namespace Objectives {
     type ToolResult as ToolResult,
     type UserMessage as UserMessage,
     type ObjectiveCompactResponse as ObjectiveCompactResponse,
+    type ObjectiveRetrieveDiagnosticsResponse as ObjectiveRetrieveDiagnosticsResponse,
     type ObjectivesCursorPagination as ObjectivesCursorPagination,
     type ObjectiveContextWindowsCursorPagination as ObjectiveContextWindowsCursorPagination,
     type ObjectiveEventsCursorPagination as ObjectiveEventsCursorPagination,
@@ -1163,6 +1283,7 @@ export declare namespace Objectives {
     type ObjectiveContinueParams as ObjectiveContinueParams,
     type ObjectiveListContextWindowsParams as ObjectiveListContextWindowsParams,
     type ObjectiveListEventsParams as ObjectiveListEventsParams,
+    type ObjectiveRetrieveDiagnosticsParams as ObjectiveRetrieveDiagnosticsParams,
     type ObjectiveStreamEventsParams as ObjectiveStreamEventsParams,
   };
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.102.0'; // x-release-please-version
+export const VERSION = '0.104.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.102.0";
+export declare const VERSION = "0.104.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.102.0";
+export declare const VERSION = "0.104.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.102.0'; // x-release-please-version
+exports.VERSION = '0.104.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.102.0'; // x-release-please-version
+export const VERSION = '0.104.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map