@cadenya/cadenya 0.45.0 → 0.47.0

package/src/resources/agent-variations.ts

@@ -85,6 +85,21 @@ export class AgentVariations extends APIResource {
     });
   }
 
+  /**
+   * Attaches a memory layer to a variation at a given position in the variation's
+   * baseline memory stack.
+   */
+  addMemoryLayer(
+    agentVariationID: string,
+    body: AgentVariationAddMemoryLayerParams,
+    options?: RequestOptions,
+  ): APIPromise<VariationMemoryLayerAssignment> {
+    return this._client.post(path`/v1/agent_variations/${agentVariationID}/memory_layers`, {
+      body,
+      ...options,
+    });
+  }
+
   /**
    * Detaches an assignment from a variation, identified by the assignment ID
    * returned when it was added.
@@ -100,6 +115,37 @@ export class AgentVariations extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * Detaches a memory layer assignment from a variation, identified by the
+   * assignment id.
+   */
+  removeMemoryLayer(
+    id: string,
+    params: AgentVariationRemoveMemoryLayerParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { agentVariationId } = params;
+    return this._client.delete(path`/v1/agent_variations/${agentVariationId}/memory_layers/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Updates the position of a memory layer assignment on a variation.
+   */
+  updateMemoryLayer(
+    id: string,
+    params: AgentVariationUpdateMemoryLayerParams,
+    options?: RequestOptions,
+  ): APIPromise<VariationMemoryLayerAssignment> {
+    const { agentVariationId, ...body } = params;
+    return this._client.patch(path`/v1/agent_variations/${agentVariationId}/memory_layers/${id}`, {
+      body,
+      ...options,
+    });
+  }
 }
 
 export type AgentVariationsCursorPagination = CursorPagination<AgentVariation>;
@@ -147,6 +193,17 @@ export interface AgentVariationInfo {
    */
   feedbackCount?: number;
 
+  /**
+   * Read-only list of memory layer assignments for this variation, returned in
+   * ascending `position` (bottom → top). Capped at 10 entries.
+   */
+  memoryLayerAssignments?: Array<VariationMemoryLayerAssignment>;
+
+  /**
+   * Count of memory layer assignments.
+   */
+  memoryLayerCount?: number;
+
   /**
    * Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
    */
@@ -395,6 +452,41 @@ export interface VariationAssignment {
   toolSet?: Shared.BareMetadata;
 }
 
+/**
+ * VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a
+ * given position in the variation's baseline memory stack. A variation has at most
+ * one assignment per memory_layer_id.
+ *
+ * Variations only support whole-layer attachments — entry pinning is an
+ * objective-level capability.
+ */
+export interface VariationMemoryLayerAssignment {
+  /**
+   * Assignment row id — handle for removing the assignment. Distinct from the
+   * referenced memory layer's id.
+   */
+  id?: string;
+
+  /**
+   * 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.
+   */
+  memoryLayer?: Shared.BareMetadata;
+
+  /**
+   * 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.
+   */
+  position?: number;
+}
+
 export interface AgentVariationCreateParams {
   /**
    * CreateResourceMetadata contains the user-provided fields for creating a
@@ -469,10 +561,38 @@ export interface AgentVariationAddAssignmentParams {
   toolSetId?: string;
 }
 
+export interface AgentVariationAddMemoryLayerParams {
+  /**
+   * Layer to attach. Accepts memlyr\_… or external_id:… form.
+   */
+  memoryLayerId?: string;
+
+  /**
+   * Position in the stack. If omitted, server appends (max existing position + 1).
+   */
+  position?: number;
+}
+
 export interface AgentVariationRemoveAssignmentParams {
   agentVariationId: string;
 }
 
+export interface AgentVariationRemoveMemoryLayerParams {
+  agentVariationId: string;
+}
+
+export interface AgentVariationUpdateMemoryLayerParams {
+  /**
+   * Path param
+   */
+  agentVariationId: string;
+
+  /**
+   * Body param: New position. Only field currently updatable on an assignment.
+   */
+  position?: number;
+}
+
 export declare namespace AgentVariations {
   export {
     type AgentVariation as AgentVariation,
@@ -487,6 +607,7 @@ export declare namespace AgentVariations {
     type ToolSelectionAssignedTools as ToolSelectionAssignedTools,
     type ToolSelectionAutoDiscovery as ToolSelectionAutoDiscovery,
     type VariationAssignment as VariationAssignment,
+    type VariationMemoryLayerAssignment as VariationMemoryLayerAssignment,
     type AgentVariationsCursorPagination as AgentVariationsCursorPagination,
     type AgentVariationCreateParams as AgentVariationCreateParams,
     type AgentVariationRetrieveParams as AgentVariationRetrieveParams,
@@ -494,6 +615,9 @@ export declare namespace AgentVariations {
     type AgentVariationListParams as AgentVariationListParams,
     type AgentVariationDeleteParams as AgentVariationDeleteParams,
     type AgentVariationAddAssignmentParams as AgentVariationAddAssignmentParams,
+    type AgentVariationAddMemoryLayerParams as AgentVariationAddMemoryLayerParams,
     type AgentVariationRemoveAssignmentParams as AgentVariationRemoveAssignmentParams,
+    type AgentVariationRemoveMemoryLayerParams as AgentVariationRemoveMemoryLayerParams,
+    type AgentVariationUpdateMemoryLayerParams as AgentVariationUpdateMemoryLayerParams,
   };
 }

package/src/resources/agents/webhook-deliveries.ts

@@ -69,7 +69,8 @@ export interface WebhookDeliveryData {
     | 'OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE'
     | 'OBJECTIVE_EVENT_TYPE_TOOL_RESULT'
     | 'OBJECTIVE_EVENT_TYPE_TOOL_ERROR'
-    | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED';
+    | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED'
+    | 'OBJECTIVE_EVENT_TYPE_MEMORY_READ';
 
   /**
    * Response details (no response_body to avoid storing large payloads)
@@ -127,7 +128,8 @@ export interface WebhookDeliveryListParams extends CursorPaginationParams {
     | 'OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE'
     | 'OBJECTIVE_EVENT_TYPE_TOOL_RESULT'
     | 'OBJECTIVE_EVENT_TYPE_TOOL_ERROR'
-    | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED';
+    | 'OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED'
+    | 'OBJECTIVE_EVENT_TYPE_MEMORY_READ';
 
   /**
    * Optional filter by objective ID

package/src/resources/index.ts

@@ -33,13 +33,17 @@ export {
   type ToolSelectionAssignedTools,
   type ToolSelectionAutoDiscovery,
   type VariationAssignment,
+  type VariationMemoryLayerAssignment,
   type AgentVariationCreateParams,
   type AgentVariationRetrieveParams,
   type AgentVariationUpdateParams,
   type AgentVariationListParams,
   type AgentVariationDeleteParams,
   type AgentVariationAddAssignmentParams,
+  type AgentVariationAddMemoryLayerParams,
   type AgentVariationRemoveAssignmentParams,
+  type AgentVariationRemoveMemoryLayerParams,
+  type AgentVariationUpdateMemoryLayerParams,
   type AgentVariationsCursorPagination,
 } from './agent-variations';
 export {
@@ -77,6 +81,8 @@ export {
   type AssistantToolCall,
   type CallableTool,
   type ContextWindowCompacted,
+  type MemoryRead,
+  type MemoryReference,
   type Objective,
   type ObjectiveContextWindow,
   type ObjectiveContextWindowData,

package/src/resources/memory-layers/entries.ts

@@ -126,8 +126,6 @@ export interface MemoryEntryCreateSpec {
 
   description?: string;
 
-  title?: string;
-
   /**
    * ID of a COMPLETE Upload. The server reads the object from storage, copies its
    * bytes into the entry, and marks the upload consumed.
@@ -144,7 +142,7 @@ export interface MemoryEntryDetail {
   /**
    * The resolved body of the entry. For entries created or updated via an upload_id,
    * this is the ingested content, not the original upload handle. May be empty; an
-   * entry with only a key, title, and description is valid (e.g., a stub skill being
+   * entry with only a key and description is valid (e.g., a stub skill being
    * drafted, or an entry where the frontmatter alone is the payload).
    */
   content: string;
@@ -211,12 +209,6 @@ export interface MemoryEntrySpec {
    * advertise frontmatter.
    */
   description?: string;
-
-  /**
-   * Short human/LLM-readable title shown in the frontmatter manifest for skills
-   * entries. Ignored for layer types that do not advertise frontmatter.
-   */
-  title?: string;
 }
 
 /**
@@ -232,8 +224,6 @@ export interface MemoryEntryUpdateSpec {
 
   key?: string;
 
-  title?: string;
-
   uploadId?: string;
 }
 

package/src/resources/memory-layers/memory-layers.ts

@@ -90,8 +90,7 @@ export type MemoryLayersCursorPagination = CursorPagination<MemoryLayer>;
  * controls how its entries participate in the agent loop — see MemoryLayerType for
  * details.
  *
- * Memory stacks are LIFO: when an objective resolves a key, layers are walked from
- * the top of the stack downward, and the first matching entry wins.
+ * See "Memory stack composition" above for how layers compose at lookup time.
  */
 export interface MemoryLayer {
   /**

package/src/resources/objectives/index.ts

@@ -15,6 +15,8 @@ export {
   type AssistantToolCall,
   type CallableTool,
   type ContextWindowCompacted,
+  type MemoryRead,
+  type MemoryReference,
   type Objective,
   type ObjectiveContextWindow,
   type ObjectiveContextWindowData,

package/src/resources/objectives/objectives.ts

@@ -207,6 +207,51 @@ export interface ContextWindowCompacted {
   summary?: string;
 }
 
+/**
+ * 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.
+ */
+export interface MemoryRead {
+  /**
+   * The specific entry that was read.
+   */
+  memoryEntryId?: 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.
+   */
+  memoryLayerId?: 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.
+   */
+  message?: string;
+}
+
+/**
+ * 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.
+ */
+export interface MemoryReference {
+  /**
+   * 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.
+   */
+  memoryEntryId?: string;
+
+  memoryLayerId?: string;
+}
+
 export interface Objective {
   data: ObjectiveData;
 
@@ -316,6 +361,29 @@ export interface ObjectiveData {
    */
   initialMessage?: string;
 
+  /**
+   * Memory layers/entries to push onto this objective's memory stack on top of the
+   * baseline stack inherited from the selected variation.
+   *
+   * See "Memory stack composition" in memory.proto for lookup semantics.
+   *
+   * 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 via the runtime 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. Variations
+   *   themselves are capped at 10 memory layer assignments, so a variation that is
+   *   already "full" leaves no room for objective-level references.
+   */
+  memoryStack?: Array<MemoryReference>;
+
   /**
    * A parent objective means the objective was spawned off using a separate agent to
    * complete an objective
@@ -358,6 +426,13 @@ export interface ObjectiveEventData {
 
   error?: ObjectiveError;
 
+  /**
+   * 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.
+   */
+  memoryRead?: MemoryRead;
+
   subObjectiveCreated?: SubObjectiveCreated;
 
   toolApprovalRequested?: ToolApprovalRequested;
@@ -472,6 +547,14 @@ export interface ObjectiveInfo {
    */
   createdBy?: AccountAPI.Profile;
 
+  /**
+   * 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.
+   */
+  effectiveMemoryStack?: Array<MemoryReference>;
+
   /**
    * Total number of context windows that this objective has generated
    */
@@ -746,6 +829,8 @@ export declare namespace Objectives {
     type AssistantToolCall as AssistantToolCall,
     type CallableTool as CallableTool,
     type ContextWindowCompacted as ContextWindowCompacted,
+    type MemoryRead as MemoryRead,
+    type MemoryReference as MemoryReference,
     type Objective as Objective,
     type ObjectiveContextWindow as ObjectiveContextWindow,
     type ObjectiveContextWindowData as ObjectiveContextWindowData,

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.45.0'; // x-release-please-version
+export const VERSION = '0.47.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.45.0";
+export declare const VERSION = "0.47.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.45.0'; // x-release-please-version
+exports.VERSION = '0.47.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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