@cadenya/cadenya 1.5.0 → 1.6.0

package/src/types.ts

@@ -272,7 +272,21 @@ export interface AccountSpec {
 }
 
 /**
- * Attach a single tool, tool set, or sub-agent to a variation. Exactly one
+ * Activate an inactive pool.
+ */
+export interface ActivateAgentPoolRequest {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * AgentPool ID. Accepts the canonical `apool_…` form or the `external_id:<value>` form.
+   */
+  id?: string;
+}
+
+/**
+ * Attach a single tool, tool set, sub-agent, or agent pool to a variation. Exactly one
  *  of the target fields must be set; the assignment kind is inferred from the
  *  populated field. Adding an existing target returns AlreadyExists.
  *  All targets must be in the variation's workspace and eligible for assignment.
@@ -280,7 +294,8 @@ export interface AccountSpec {
 export type AddAgentVariationAssignmentRequest =
   | AddAgentVariationAssignmentRequest_ToolId
   | AddAgentVariationAssignmentRequest_ToolSetId
-  | AddAgentVariationAssignmentRequest_SubAgentId;
+  | AddAgentVariationAssignmentRequest_SubAgentId
+  | AddAgentVariationAssignmentRequest_AgentPoolId;
 
 /**
  * Attach a memory layer to a variation. Use UpdateAgentVariationMemoryLayer or
@@ -375,6 +390,103 @@ export interface AgentInfo {
   createdBy?: Profile;
 }
 
+/**
+ * Output only. Pools are created INACTIVE. Use :activate, :deactivate,
+ *  :archive, and :unarchive to transition states. Unarchive returns INACTIVE.
+ */
+export type AgentPoolState = 'AGENT_POOL_STATE_UNSPECIFIED' | 'AGENT_POOL_STATE_ACTIVE' | 'AGENT_POOL_STATE_INACTIVE' | 'AGENT_POOL_STATE_ARCHIVED';
+
+/**
+ * A workspace-scoped group of agents. When assigned to a variation, the pool
+ *  exposes one callable target that routes a request to a member agent.
+ *  Pool membership references agents; variation assignments reference the pool.
+ */
+export interface AgentPool {
+  metadata: ResourceMetadata;
+  spec: AgentPoolSpec;
+  info?: AgentPoolInfo;
+  /**
+   * Output only. Pools are created INACTIVE. Use :activate, :deactivate,
+   *  :archive, and :unarchive to transition states. Unarchive returns INACTIVE.
+   */
+  state: AgentPoolState;
+}
+
+/**
+ * A member of a pool, identified by its agent ID. This is distinct from a
+ *  VariationAssignment, which attaches the entire pool to a variation.
+ */
+export interface AgentPoolAssignment {
+  /**
+   * Canonical ID of an agent in the pool's workspace.
+   */
+  agentId: string;
+}
+
+/**
+ * AgentPoolInfo represents the information of an agent pool.
+ */
+export interface AgentPoolInfo {
+  /**
+   * Number of member agents in spec.assignments.
+   */
+  assignedAgents: number;
+  createdBy: Profile;
+}
+
+/**
+ * AgentPoolSpec describes the pool's purpose, membership, input schema, and routing instructions.
+ */
+export interface AgentPoolSpec {
+  /**
+   * Describes when a calling agent should use this pool.
+   */
+  description: string;
+  /**
+   * JSON Schema defining the input arguments for this pool's callable tool.
+   *  When the pool is assigned to an agent variation, this schema tells the LLM
+   *  what arguments to supply. The supplied arguments provide the context used
+   *  to route the request to an agent in the pool.
+   */
+  state?: Record<string, unknown>;
+  /**
+   * Complete set of member agents, all in the pool's workspace. At least one
+   *  member is required. Order has no meaning; duplicate agent IDs are invalid.
+   */
+  assignments: Array<AgentPoolAssignment>;
+  /**
+   * Instructions for routing requests to an agent in the pool.
+   *  If empty, defaults to "Which agent is best suited to handle this request?".
+   */
+  instructions?: string;
+}
+
+/**
+ * Partial input for UpdateAgentPool. The server applies update_mask, then
+ *  validates the resulting AgentPoolSpec before persisting any changes.
+ */
+export interface AgentPoolUpdateSpec {
+  /**
+   * Omit to leave unchanged, unless the mask selects this field or all of spec.
+   */
+  description?: string;
+  /**
+   * JSON Schema for the pool's callable input arguments. Update through
+   *  spec.state in the update mask.
+   */
+  state?: Record<string, unknown>;
+  /**
+   * Replacement membership. A selected empty list is invalid because a pool
+   *  must retain at least one member. Unselected fields remain unchanged.
+   */
+  assignments?: Array<AgentPoolAssignment>;
+  /**
+   * Routing instructions to update through spec.instructions in the update
+   *  mask. Selecting this field with an empty value restores the default question.
+   */
+  instructions?: string;
+}
+
 /**
  * The current lifecycle state of the schedule. Output only. Schedules are
  *  created STATE_ACTIVE; use the :pause, :resume, and :archive actions to
@@ -600,23 +712,27 @@ export interface AgentVariationInfo {
   /**
    * Number of distinct callable tools available through this variation's
    *  assignments after normalization. Expands tool sets and deduplicates tools
-   *  also assigned directly. Each sub-agent contributes one callable tool;
-   *  its own assignments are not expanded. Counts the full normalized set,
-   *  regardless of which tools progressive discovery has loaded.
+   *  also assigned directly. Each sub-agent or pool contributes one callable
+   *  tool; sub-agent assignments and pool members are not expanded. Counts the
+   *  full normalized set, regardless of which tools progressive discovery has loaded.
    */
   effectiveToolCount: number;
   /**
    * Current display metadata for targets explicitly referenced by
    *  spec.assignments and spec.memory_layer_assignments, keyed by canonical
-   *  resource ID. Includes tools, tool sets, sub-agents, and memory layers in
-   *  one map; each value's id equals its key. Does not expand tools within
-   *  assigned tool sets or assignments within sub-agents.
+   *  resource ID. Includes tools, tool sets, sub-agents, agent pools,
+   *  and memory layers in one map; each value's id equals its key. Does not expand
+   *  tools within assigned tool sets, assignments within sub-agents, or pool members.
    *  Populated whenever info is returned; empty when there are no assignments.
    *  Missing or inaccessible targets are omitted, and names may be absent.
    *  Clients use spec for assignment type/order and fall back to the ID when
    *  display metadata is unavailable. This map never accepts assignment writes.
    */
   assignmentMetadata: Record<string, BareMetadata>;
+  /**
+   * Number of agent pools assigned to this variation.
+   */
+  agentPoolCount: number;
 }
 
 /**
@@ -637,7 +753,7 @@ export interface AgentVariationSpec {
    * ProgressiveDiscovery is an optional config that, when set, will load a Cadenya provided tool that
    *  can search for tools in the assigned tool sets or tools.
    * 
-   *  Note: Sub-agents are always loaded as a tool regardless of this value.
+   *  Note: Sub-agents and agent pools are always loaded as tools regardless of this value.
    */
   progressiveDiscovery?: AgentVariationSpec_ProgressiveDiscovery;
   /**
@@ -667,7 +783,7 @@ export interface AgentVariationSpec {
    */
   firstUserMessageTemplate?: string;
   /**
-   * Complete set of assigned tools, tool sets, and sub-agents. Order has no
+   * Complete set of assigned tools, tool sets, sub-agents, and agent pools. Order has no
    *  meaning. Duplicate (target kind, canonical target ID) pairs are collapsed.
    *  On create, omitted or empty means no assignments. On update, selecting
    *  spec.assignments in update_mask replaces the entire set; empty clears it.
@@ -819,6 +935,20 @@ export interface ApproveToolCallRequest {
   toolCallId?: string;
 }
 
+/**
+ * Archive an active or inactive pool, preserving membership and assignments.
+ */
+export interface ArchiveAgentPoolRequest {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * AgentPool ID. Accepts the canonical `apool_…` form or the `external_id:<value>` form.
+   */
+  id?: string;
+}
+
 /**
  * Archive agent request
  */
@@ -924,7 +1054,8 @@ export interface BedrockConfig {
 export type CallableTool =
   | CallableTool_Tool
   | CallableTool_Agent
-  | CallableTool_CadenyaProvidedTool;
+  | CallableTool_CadenyaProvidedTool
+  | CallableTool_AgentPool;
 
 export interface CancelObjectiveRequest {
   workspaceId?: string;
@@ -1220,6 +1351,18 @@ export interface CreateAccountResourceMetadata {
   labels?: Record<string, string>;
 }
 
+/**
+ * Create a pool in INACTIVE state. Validate and persist membership atomically.
+ */
+export interface CreateAgentPoolRequest {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  metadata: CreateResourceMetadata;
+  spec: AgentPoolSpec;
+}
+
 /**
  * Create agent request
  */
@@ -1580,6 +1723,20 @@ export interface CredentialHeaders {
   headers?: Record<string, string>;
 }
 
+/**
+ * Deactivate an active pool.
+ */
+export interface DeactivateAgentPoolRequest {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * AgentPool ID. Accepts the canonical `apool_…` form or the `external_id:<value>` form.
+   */
+  id?: string;
+}
+
 /**
  * Delete tenant widget sessions response.
  */
@@ -1707,6 +1864,14 @@ export interface ListAgentFeedbackResponse {
   pagination?: Page;
 }
 
+/**
+ * List agent pools response
+ */
+export interface ListAgentPoolsResponse {
+  items: Array<AgentPool>;
+  pagination?: Page;
+}
+
 /**
  * List agent schedules response.
  */
@@ -3165,7 +3330,8 @@ export interface Reasoning {
 export type RemoveAgentVariationAssignmentRequest =
   | RemoveAgentVariationAssignmentRequest_ToolId
   | RemoveAgentVariationAssignmentRequest_ToolSetId
-  | RemoveAgentVariationAssignmentRequest_SubAgentId;
+  | RemoveAgentVariationAssignmentRequest_SubAgentId
+  | RemoveAgentVariationAssignmentRequest_AgentPoolId;
 
 /**
  * Remove by memory layer ID. An unassigned layer returns NotFound.
@@ -4349,6 +4515,20 @@ export type ToolSpec_Config =
   | ToolSpec_Config_Openapi
   | ToolSpec_Config_Bare;
 
+/**
+ * Restore an archived pool to INACTIVE; activate it separately to route requests.
+ */
+export interface UnarchiveAgentPoolRequest {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * AgentPool ID. Accepts the canonical `apool_…` form or the `external_id:<value>` form.
+   */
+  id?: string;
+}
+
 /**
  * Unarchive agent request
  */
@@ -4469,6 +4649,32 @@ export interface UpdateAccountResourceMetadata {
   labels?: Record<string, string>;
 }
 
+/**
+ * Update agent pool request
+ */
+export interface UpdateAgentPoolRequest {
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * AgentPool ID. Accepts the canonical `apool_…` form or the `external_id:<value>` form.
+   */
+  id?: string;
+  metadata?: UpdateResourceMetadata;
+  spec?: AgentPoolUpdateSpec;
+  /**
+   * Fields to update. Only metadata and spec are mutable; top-level state and info
+   *  paths are invalid. spec.assignments replaces the entire membership list.
+   *  A spec mask replaces the full spec; * replaces all mutable fields.
+   *  Without a mask, infer paths from non-empty fields. Empty or omitted
+   *  membership then leaves the existing list unchanged. Element/index paths
+   *  are invalid. Validate the merged pool atomically: an empty description
+   *  or membership (including an explicitly masked empty list) is invalid.
+   */
+  updateMask?: string;
+}
+
 /**
  * Update agent request
  */
@@ -4827,14 +5033,15 @@ export interface UserMessage {
 }
 
 /**
- * A tool, tool set, or sub-agent assigned to a variation, identified only by
+ * A tool, tool set, sub-agent, or agent pool assigned to a variation, identified only by
  *  the target resource ID. The same shape is accepted in a spec and returned
  *  on reads. Assignment junction records are an internal implementation detail.
  */
 export type VariationAssignment =
   | VariationAssignment_ToolId
   | VariationAssignment_ToolSetId
-  | VariationAssignment_SubAgentId;
+  | VariationAssignment_SubAgentId
+  | VariationAssignment_AgentPoolId;
 
 /**
  * A whole memory layer in a variation's baseline memory cascade. Identified
@@ -5288,6 +5495,14 @@ export interface VariationAssignment_SubAgentId {
   subAgentId: string;
 }
 
+export interface VariationAssignment_AgentPoolId {
+  type: 'agentPoolId';
+  /**
+   * Canonical agent pool ID. Attaches the pool as a single callable target.
+   */
+  agentPoolId: string;
+}
+
 export interface ObjectiveToolCallResult_ContentBlock_Text {
   type: 'text';
   text: ObjectiveToolCallResult_TextBlock;
@@ -5638,6 +5853,14 @@ export interface CallableTool_CadenyaProvidedTool {
   cadenyaProvidedTool: ResourceMetadata;
 }
 
+export interface CallableTool_AgentPool {
+  type: 'agentPool';
+  /**
+   * Agent pool responsible for routing this call to a member agent.
+   */
+  agentPool: ResourceMetadata;
+}
+
 export interface MemoryEntryCreateSpec_Content {
   type: 'content';
   /**
@@ -5733,6 +5956,26 @@ export interface AddAgentVariationAssignmentRequest_SubAgentId {
   variationId?: string;
 }
 
+export interface AddAgentVariationAssignmentRequest_AgentPoolId {
+  type: 'agentPoolId';
+  /**
+   * Canonical agent pool ID in the variation's workspace.
+   */
+  agentPoolId: string;
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.
+   */
+  agentId?: string;
+  /**
+   * Variation ID. Accepts the canonical `agentvar_…` form or the `external_id:<value>` form.
+   */
+  variationId?: string;
+}
+
 export interface RemoveAgentVariationAssignmentRequest_ToolId {
   type: 'toolId';
   toolId: string;
@@ -5784,6 +6027,26 @@ export interface RemoveAgentVariationAssignmentRequest_SubAgentId {
   variationId?: string;
 }
 
+export interface RemoveAgentVariationAssignmentRequest_AgentPoolId {
+  type: 'agentPoolId';
+  /**
+   * Canonical agent pool ID in the variation's workspace.
+   */
+  agentPoolId: string;
+  /**
+   * Workspace ID.
+   */
+  workspaceId?: string;
+  /**
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.
+   */
+  agentId?: string;
+  /**
+   * Variation ID. Accepts the canonical `agentvar_…` form or the `external_id:<value>` form.
+   */
+  variationId?: string;
+}
+
 export interface AIProviderCredential_ApiKey {
   type: 'apiKey';
   /**
@@ -5898,6 +6161,8 @@ export interface WidgetSessionErrorInfo {
   metadata?: Record<string, string>;
 }
 
+export type AgentPoolServiceListAgentPoolsState = 'AGENT_POOL_STATE_UNSPECIFIED' | 'AGENT_POOL_STATE_ACTIVE' | 'AGENT_POOL_STATE_INACTIVE' | 'AGENT_POOL_STATE_ARCHIVED';
+
 export type AgentServiceListAgentsState = 'STATE_UNSPECIFIED' | 'STATE_DRAFT' | 'STATE_PUBLISHED' | 'STATE_ARCHIVED';
 
 export type AgentServiceListAgentsVariationSelectionMode = 'VARIATION_SELECTION_MODE_UNSPECIFIED' | 'VARIATION_SELECTION_MODE_RANDOM' | 'VARIATION_SELECTION_MODE_WEIGHTED';
@@ -5947,7 +6212,7 @@ export interface APIKeySpecParam {
   permissions?: Array<string>;
 }
 
-export type AddAgentVariationAssignmentRequestParam = AddAgentVariationAssignmentRequest_ToolIdParam | AddAgentVariationAssignmentRequest_ToolSetIdParam | AddAgentVariationAssignmentRequest_SubAgentIdParam;
+export type AddAgentVariationAssignmentRequestParam = AddAgentVariationAssignmentRequest_ToolIdParam | AddAgentVariationAssignmentRequest_ToolSetIdParam | AddAgentVariationAssignmentRequest_SubAgentIdParam | AddAgentVariationAssignmentRequest_AgentPoolIdParam;
 
 export interface CreateAgentVariationRequestParam {
   metadata: CreateResourceMetadata;
@@ -5971,7 +6236,7 @@ export interface ObjectiveEpisodicConfigParam {
   key: string;
 }
 
-export type RemoveAgentVariationAssignmentRequestParam = RemoveAgentVariationAssignmentRequest_ToolIdParam | RemoveAgentVariationAssignmentRequest_ToolSetIdParam | RemoveAgentVariationAssignmentRequest_SubAgentIdParam;
+export type RemoveAgentVariationAssignmentRequestParam = RemoveAgentVariationAssignmentRequest_ToolIdParam | RemoveAgentVariationAssignmentRequest_ToolSetIdParam | RemoveAgentVariationAssignmentRequest_SubAgentIdParam | RemoveAgentVariationAssignmentRequest_AgentPoolIdParam;
 
 export interface WidgetSessionSpecParam {
   /**
@@ -6027,6 +6292,14 @@ export interface AddAgentVariationAssignmentRequest_SubAgentIdParam {
   subAgentId: string;
 }
 
+export interface AddAgentVariationAssignmentRequest_AgentPoolIdParam {
+  type: 'agentPoolId';
+  /**
+   * Canonical agent pool ID in the variation's workspace.
+   */
+  agentPoolId: string;
+}
+
 export interface RemoveAgentVariationAssignmentRequest_ToolIdParam {
   type: 'toolId';
   toolId: string;
@@ -6042,6 +6315,14 @@ export interface RemoveAgentVariationAssignmentRequest_SubAgentIdParam {
   subAgentId: string;
 }
 
+export interface RemoveAgentVariationAssignmentRequest_AgentPoolIdParam {
+  type: 'agentPoolId';
+  /**
+   * Canonical agent pool ID in the variation's workspace.
+   */
+  agentPoolId: string;
+}
+
 
 // ---- request wire projections (strip readOnly at runtime) ----
 
@@ -6067,6 +6348,7 @@ export function wireAddAgentVariationAssignmentRequest(value: AddAgentVariationA
     case "toolId": return wireAddAgentVariationAssignmentRequest_ToolId((value as never));
     case "toolSetId": return wireAddAgentVariationAssignmentRequest_ToolSetId((value as never));
     case "subAgentId": return wireAddAgentVariationAssignmentRequest_SubAgentId((value as never));
+    case "agentPoolId": return wireAddAgentVariationAssignmentRequest_AgentPoolId((value as never));
     default: return value;
   }
 }
@@ -6100,6 +6382,7 @@ export function wireRemoveAgentVariationAssignmentRequest(value: RemoveAgentVari
     case "toolId": return wireRemoveAgentVariationAssignmentRequest_ToolId((value as never));
     case "toolSetId": return wireRemoveAgentVariationAssignmentRequest_ToolSetId((value as never));
     case "subAgentId": return wireRemoveAgentVariationAssignmentRequest_SubAgentId((value as never));
+    case "agentPoolId": return wireRemoveAgentVariationAssignmentRequest_AgentPoolId((value as never));
     default: return value;
   }
 }
@@ -6139,6 +6422,14 @@ export function wireAddAgentVariationAssignmentRequest_SubAgentId(value: AddAgen
   return out;
 }
 
+export function wireAddAgentVariationAssignmentRequest_AgentPoolId(value: AddAgentVariationAssignmentRequest_AgentPoolIdParam | null | undefined): unknown {
+  if (value == null || typeof value !== 'object') return value;
+  const out: Record<string, unknown> = {};
+  if (value.type !== undefined) out["type"] = value.type;
+  if (value.agentPoolId !== undefined) out["agentPoolId"] = value.agentPoolId;
+  return out;
+}
+
 export function wireRemoveAgentVariationAssignmentRequest_ToolId(value: RemoveAgentVariationAssignmentRequest_ToolIdParam | null | undefined): unknown {
   if (value == null || typeof value !== 'object') return value;
   const out: Record<string, unknown> = {};
@@ -6163,3 +6454,11 @@ export function wireRemoveAgentVariationAssignmentRequest_SubAgentId(value: Remo
   return out;
 }
 
+export function wireRemoveAgentVariationAssignmentRequest_AgentPoolId(value: RemoveAgentVariationAssignmentRequest_AgentPoolIdParam | null | undefined): unknown {
+  if (value == null || typeof value !== 'object') return value;
+  const out: Record<string, unknown> = {};
+  if (value.type !== undefined) out["type"] = value.type;
+  if (value.agentPoolId !== undefined) out["agentPoolId"] = value.agentPoolId;
+  return out;
+}
+