@cadenya/cadenya 0.67.0 → 0.68.0

package/src/client.ts

@@ -937,98 +937,59 @@ export class Cadenya {
   static toFile = Uploads.toFile;
 
   /**
-   * AccountService manages account-level operations.
-   *  Accounts are the top-level organizational unit in the system.
-   *  All operations are scoped to the authenticated account determined by the JWT token.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Account-level operations
+   * Manage the authenticated account. Accounts are the top-level organizational
+   *  unit and contain one or more workspaces.
    */
   account: API.AccountResource = new API.AccountResource(this);
   /**
-   * AgentService manages AI agents at the WORKSPACE level.
-   *  Agents are workspace-scoped resources that define AI behavior and tool access.
-   *  All operations are implicitly scoped to the workspace determined by the JWT token.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   * Manage AI agents within a workspace. Agents define AI behavior and tool access.
    */
   agents: API.Agents = new API.Agents(this);
   objectives: API.Objectives = new API.Objectives(this);
   /**
-   * MemoryService manages memory layers and their entries at the WORKSPACE level.
-   *  Layers are named containers that can be composed into an objective's memory
-   *  stack; entries are the keyed values within a layer.
-   *
-   *  All operations are implicitly scoped to the workspace determined by the JWT
-   *  token. System-managed layers (e.g., episodic layers created by the runtime)
-   *  cannot be mutated through this API.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   * Manage memory layers and their entries. Layers are named containers that can
+   *  be composed into an objective's memory stack; entries are the keyed values
+   *  within a layer. System-managed layers (e.g., episodic layers created by the
+   *  runtime) cannot be mutated through this API.
    */
   memoryLayers: API.MemoryLayers = new API.MemoryLayers(this);
   /**
-   * UploadService issues short-lived presigned URLs for direct client-to-object-
-   *  storage uploads at the WORKSPACE level. Created uploads can be referenced by
-   *  id when creating or updating resources that accept binary content (e.g.,
-   *  MemoryEntry).
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   * Issue short-lived presigned URLs for direct client-to-object-storage
+   *  uploads. Created uploads can be referenced by id when creating or updating
+   *  resources that accept binary content (e.g., MemoryEntry).
    */
   uploads: API.Uploads = new API.Uploads(this);
   /**
-   * ModelService manages LLM models at the WORKSPACE level.
-   *  Models represent available LLM providers and families (e.g., "anthropic/claude-sonnet-4.6").
-   *  Models are seeded into workspaces and can be enabled or disabled.
-   *  All operations are implicitly scoped to the workspace determined by the JWT token.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   * Manage LLM models available to a workspace. Models represent provider and
+   *  family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
+   *  with the supported models and you can enable or disable each one.
    */
   models: API.Models = new API.Models(this);
   search: API.Search = new API.Search(this);
   /**
-   * ToolService manages tool sets and tools at the WORKSPACE level.
-   *  Tool sets group related tools, and tools define specific capabilities for agents.
-   *  All operations are implicitly scoped to the workspace determined by the JWT token.
-   *
-   *  Note: When a ToolSet has managed=true, only API Key actors can modify its tools.
-   *  Profile actors (humans) are restricted from modifying managed tool sets.
+   * Manage tool sets and the tools they contain. Tool sets group related tools,
+   *  and tools define specific capabilities available to agents.
    *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   *  When a tool set is managed, only API key actors can modify its tools; human
+   *  (profile) actors cannot.
    */
   toolSets: API.ToolSets = new API.ToolSets(this);
   /**
-   * APIKeyService manages workspace-scoped API Keys.
-   *  Each API key belongs to a single workspace, ensuring isolation between environments.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   * Issue, rotate, and revoke API keys for a workspace. Each API key belongs to
+   *  exactly one workspace, ensuring isolation between environments.
    */
   apiKeys: API.APIKeys = new API.APIKeys(this);
   workspaceSecrets: API.WorkspaceSecrets = new API.WorkspaceSecrets(this);
   /**
-   * WorkspaceService manages workspaces at the ACCOUNT level.
-   *  This service is responsible for creating and listing workspaces within an account.
-   *  Workspaces provide organizational grouping for resources within an account.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Account-level operations (manages workspaces themselves, not resources within workspaces)
+   * Manage workspaces within an account. Workspaces provide organizational
+   *  grouping and isolation for resources such as agents, tools, and API keys.
    */
   workspaces: API.Workspaces = new API.Workspaces(this);
   webhooks: API.Webhooks = new API.Webhooks(this);
   /**
-   * BulkWorkspaceResources is the workspace-scoped service that applies
-   *  a declarative bundle of workspace resources (tool sets, memory
-   *  layers, agents, variations, assignments, schedules) in one async
-   *  operation. See docs/superpowers/specs/2026-05-02-bulk-workspace-resources-design.md
-   *  for the full design.
-   *
-   *  Authentication: Bearer token (JWT)
-   *  Scope: Workspace-level operations
+   * Apply a declarative bundle of workspace resources — tool sets, memory
+   *  layers, agents, variations, assignments, and schedules — in a single
+   *  asynchronous operation.
    */
   bulkWorkspaceResources: API.BulkWorkspaceResources = new API.BulkWorkspaceResources(this);
 }

package/src/resources/account.ts

@@ -7,12 +7,8 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 /**
- * AccountService manages account-level operations.
- *  Accounts are the top-level organizational unit in the system.
- *  All operations are scoped to the authenticated account determined by the JWT token.
- *
- *  Authentication: Bearer token (JWT)
- *  Scope: Account-level operations
+ * Manage the authenticated account. Accounts are the top-level organizational
+ *  unit and contain one or more workspaces.
  */
 export class AccountResource extends APIResource {
   /**
@@ -32,11 +28,12 @@ export class AccountResource extends APIResource {
 }
 
 /**
- * Account is an account resource.
+ * An account, the top-level organizational unit. Contains workspaces and
+ * account-wide settings such as the webhook signing secret.
  */
 export interface Account {
   /**
-   * AccountInfo contains information about the account.
+   * Server-populated information about the account.
    */
   info: Account.Info;
 
@@ -47,14 +44,14 @@ export interface Account {
   metadata: Shared.AccountResourceMetadata;
 
   /**
-   * AccountSpec contains the specification for an account.
+   * Configuration for an account.
    */
   spec: AccountSpec;
 }
 
 export namespace Account {
   /**
-   * AccountInfo contains information about the account.
+   * Server-populated information about the account.
    */
   export interface Info {
     /**
@@ -67,7 +64,7 @@ export namespace Account {
 }
 
 /**
- * AccountSpec contains the specification for an account.
+ * Configuration for an account.
  */
 export interface AccountSpec {
   billingEmail?: string;
@@ -80,9 +77,9 @@ export interface AccountSpec {
 }
 
 /**
- * Profile represents a human user at the account level. Profiles are
- * account-scoped resources that can be associated with multiple workspaces through
- * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+ * 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.
  */
 export interface Profile {
   /**
@@ -92,35 +89,34 @@ export interface Profile {
   metadata: Shared.AccountResourceMetadata;
 
   /**
-   * ProfileSpec contains the profile-specific fields
+   * Configuration for a profile.
    */
   spec: ProfileSpec;
 }
 
 /**
- * ProfileSpec contains the profile-specific fields
+ * Configuration for a profile.
  */
 export interface ProfileSpec {
   /**
-   * Type is the type of profile. User's are humans, API keys are computers. You know
-   * the deal.
+   * Whether this profile represents a human user, an API key, or a system principal.
    */
   type: 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM';
 
   /**
-   * Email address of the user (required, unique per account)
+   * Email address of the profile. Required and unique within an account for user
+   * profiles.
    */
   email?: string;
 
   /**
-   * Display name for the user (e.g., "Bobby Tables")
+   * Display name (e.g., "Bobby Tables").
    */
   name?: string;
 }
 
 /**
- * RotateWebhookEventsHmacSecretResponse is a response to a
- * RotateWebhookEventsHmacSecretRequest.
+ * Response containing the newly generated webhook signing secret.
  */
 export interface RotateWebhookSigningKeyResponse {
   webhookEventsHmacSecret?: string;

package/src/resources/agents/agents.ts

@@ -63,12 +63,7 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * AgentService manages AI agents at the WORKSPACE level.
- *  Agents are workspace-scoped resources that define AI behavior and tool access.
- *  All operations are implicitly scoped to the workspace determined by the JWT token.
- *
- *  Authentication: Bearer token (JWT)
- *  Scope: Workspace-level operations
+ * Manage AI agents within a workspace. Agents define AI behavior and tool access.
  */
 export class Agents extends APIResource {
   feedback: FeedbackAPI.Feedback = new FeedbackAPI.Feedback(this._client);
@@ -156,9 +151,9 @@ export interface Agent {
  */
 export interface AgentInfo {
   /**
-   * Profile represents a human user at the account level. Profiles are
-   * account-scoped resources that can be associated with multiple workspaces through
-   * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+   * 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.
    */
   createdBy?: AccountAPI.Profile;
 
@@ -253,14 +248,14 @@ export namespace AgentCreateParams {
 
 export interface AgentRetrieveParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 }
 
 export interface AgentUpdateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -290,7 +285,8 @@ export interface AgentListParams extends CursorPaginationParams {
   bundleKey?: string;
 
   /**
-   * When set to true you may use more of your alloted API rate-limit
+   * When true, the `info` field on each returned agent is populated. Requests with
+   * this flag count more against your rate limit.
    */
   includeInfo?: boolean;
 
@@ -329,7 +325,7 @@ export interface AgentListParams extends CursorPaginationParams {
 
 export interface AgentDeleteParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 }

package/src/resources/agents/feedback.ts

@@ -8,12 +8,7 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * AgentService manages AI agents at the WORKSPACE level.
- *  Agents are workspace-scoped resources that define AI behavior and tool access.
- *  All operations are implicitly scoped to the workspace determined by the JWT token.
- *
- *  Authentication: Bearer token (JWT)
- *  Scope: Workspace-level operations
+ * Manage AI agents within a workspace. Agents define AI behavior and tool access.
  */
 export class Feedback extends APIResource {
   /**
@@ -37,7 +32,7 @@ export class Feedback extends APIResource {
 
 export interface FeedbackListParams extends CursorPaginationParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param
    */
   workspaceId: string;
 

package/src/resources/agents/schedules.ts

@@ -10,12 +10,8 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 /**
- * AgentScheduleService manages recurring schedules attached to agents.
- *  Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule.
- *  All operations are implicitly scoped to the workspace determined by the JWT token.
- *
- *  Authentication: Bearer token (JWT)
- *  Scope: Workspace-level operations
+ * Manage recurring schedules attached to agents. Schedules trigger objectives
+ *  on a cadence defined by AgentScheduleSpec.Schedule.
  */
 export class Schedules extends APIResource {
   /**
@@ -104,9 +100,9 @@ export interface AgentSchedule {
  */
 export interface AgentScheduleInfo {
   /**
-   * Profile represents a human user at the account level. Profiles are
-   * account-scoped resources that can be associated with multiple workspaces through
-   * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+   * 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.
    */
   createdBy?: AccountAPI.Profile;
 
@@ -260,7 +256,7 @@ export interface ScheduleRange {
 
 export interface ScheduleCreateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -280,26 +276,26 @@ export interface ScheduleCreateParams {
 
 export interface ScheduleRetrieveParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 }
 
 export interface ScheduleUpdateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
@@ -324,7 +320,7 @@ export interface ScheduleUpdateParams {
 
 export interface ScheduleListParams extends CursorPaginationParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -334,7 +330,8 @@ export interface ScheduleListParams extends CursorPaginationParams {
   bundleKey?: string;
 
   /**
-   * Query param: When set to true you may use more of your alloted API rate-limit.
+   * Query param: When true, the `info` field on each returned schedule is populated.
+   * Requests with this flag count more against your rate limit.
    */
   includeInfo?: boolean;
 
@@ -356,13 +353,13 @@ export interface ScheduleListParams extends CursorPaginationParams {
 
 export interface ScheduleDeleteParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 }

package/src/resources/agents/variations.ts

@@ -9,6 +9,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * Manage variations of an agent and their tool, sub-agent, and memory layer assignments.
+ */
 export class Variations extends APIResource {
   /**
    * Creates a new variation for an agent
@@ -189,9 +192,9 @@ export interface AgentVariationInfo {
   assignments?: Array<VariationAssignment>;
 
   /**
-   * Profile represents a human user at the account level. Profiles are
-   * account-scoped resources that can be associated with multiple workspaces through
-   * the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).
+   * 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.
    */
   createdBy?: AccountAPI.Profile;
 
@@ -402,15 +405,14 @@ export interface CompactionConfigToolResultClearingStrategy {
 }
 
 /**
- * VariationAssignment is a read-only reference to a single tool, tool set, or
- * sub-agent attached to a variation. Clients read the full set of assignments via
+ * A read-only reference to a single tool, tool set, or sub-agent attached to a
+ * variation. Read the full set of assignments via
  * `AgentVariationInfo.assignments`; mutations go through the dedicated add/remove
- * assignment endpoints under
- * /v1/agents/{agent_id}/variations/{variation_id}/assignments.
+ * assignment endpoints.
  *
- * The `id` identifies the assignment row itself (not the referenced resource) and
- * is the handle used to remove the assignment. It is returned by the add endpoint
- * and present on every entry in AgentVariationInfo.assignments.
+ * The `id` identifies the assignment itself (not the referenced resource) and is
+ * the handle used to remove the assignment. It is returned by the add endpoint and
+ * present on every entry in `AgentVariationInfo.assignments`.
  */
 export interface VariationAssignment {
   id?: string;
@@ -483,7 +485,7 @@ export interface VariationMemoryLayerAssignment {
 
 export interface VariationCreateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -504,26 +506,26 @@ export interface VariationCreateParams {
 
 export interface VariationRetrieveParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 }
 
 export interface VariationUpdateParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
@@ -549,7 +551,7 @@ export interface VariationUpdateParams {
 
 export interface VariationListParams extends CursorPaginationParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
@@ -559,7 +561,8 @@ export interface VariationListParams extends CursorPaginationParams {
   bundleKey?: string;
 
   /**
-   * Query param: When set to true you may use more of your alloted API rate-limit
+   * Query param: When true, the `info` field on each returned variation is
+   * populated. Requests with this flag count more against your rate limit.
    */
   includeInfo?: boolean;
 
@@ -571,26 +574,26 @@ export interface VariationListParams extends CursorPaginationParams {
 
 export interface VariationDeleteParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 }
 
 export interface VariationAddAssignmentParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
@@ -612,19 +615,19 @@ export interface VariationAddAssignmentParams {
 
 export interface VariationAddMemoryLayerParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
   /**
-   * Body param: Layer to attach. Accepts canonical memlyr\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Body param: Layer to attach. Accepts the canonical `memlyr_…` form or the
+   * `external_id:<value>` form.
    */
   memoryLayerId?: string;
 
@@ -637,57 +640,57 @@ export interface VariationAddMemoryLayerParams {
 
 export interface VariationRemoveAssignmentParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 
   /**
-   * Variation ID (from path). Accepts canonical av\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>`
+   * form.
    */
   variationId: string;
 }
 
 export interface VariationRemoveMemoryLayerParams {
   /**
-   * Workspace ID (from path).
+   * Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Agent ID (from path). Accepts canonical agent\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>`
+   * form.
    */
   agentId: string;
 
   /**
-   * Variation ID (from path). Accepts canonical av\_… form or external_id:<value>
-   * form (see common.proto "Path-parameter ID resolution").
+   * Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>`
+   * form.
    */
   variationId: string;
 }
 
 export interface VariationUpdateMemoryLayerParams {
   /**
-   * Path param: Workspace ID (from path).
+   * Path param: Workspace ID.
    */
   workspaceId: string;
 
   /**
-   * Path param: Agent ID (from path). Accepts canonical agent\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Agent ID. Accepts the canonical `agent_…` form or the
+   * `external_id:<value>` form.
    */
   agentId: string;
 
   /**
-   * Path param: Variation ID (from path). Accepts canonical av\_… form or
-   * external_id:<value> form (see common.proto "Path-parameter ID resolution").
+   * Path param: Variation ID. Accepts the canonical `av_…` form or the
+   * `external_id:<value>` form.
    */
   variationId: string;