@soat/sdk 0.99.3 → 0.101.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -764,7 +764,7 @@ var Agents = class {
764
764
  /**
765
765
  * Create an agent
766
766
  *
767
- * Creates a new agent bound to an AI provider.
767
+ * Creates a new agent bound to an AI provider. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
768
768
  */
769
769
  static createAgent(options) {
770
770
  return (options.client ?? client).post({
@@ -803,7 +803,7 @@ var Agents = class {
803
803
  /**
804
804
  * Partially update an agent
805
805
  *
806
- * Partially updates an existing agent. Identical to PUT — both perform partial updates.
806
+ * Partially updates an existing agent. Identical to PUT — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
807
807
  */
808
808
  static patchAgent(options) {
809
809
  return (options.client ?? client).patch({
@@ -818,7 +818,7 @@ var Agents = class {
818
818
  /**
819
819
  * Update an agent
820
820
  *
821
- * Updates an existing agent. Identical to PATCH — both perform partial updates.
821
+ * Updates an existing agent. Identical to PATCH — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
822
822
  */
823
823
  static updateAgent(options) {
824
824
  return (options.client ?? client).put({
@@ -972,8 +972,14 @@ var AiProviders = class {
972
972
  *
973
973
  * Creates a new LLM provider configuration.
974
974
  *
975
- * A `bedrock` or `vertex` record must carry a credential of its own — a
976
- * linked `secret_id`, or an `apiKey` in `config`. Without one the provider
975
+ * A provider's credential is its linked `secret_id`; `config.apiKey` is
976
+ * refused with `400 VALIDATION_FAILED`.
977
+ *
978
+ * A record with both `base_url` and `secret_id` sends the secret to that
979
+ * URL, so creating one also needs `secrets:UseSecret` on the secret, else
980
+ * `403`.
981
+ *
982
+ * A `bedrock` or `vertex` record must link one. Without it the provider
977
983
  * SDK signs with the server's own credentials (the AWS default credential
978
984
  * chain, Google Application Default Credentials), which is refused with
979
985
  * `400 VALIDATION_FAILED` unless the deployment allows it.
@@ -1017,7 +1023,7 @@ var AiProviders = class {
1017
1023
  /**
1018
1024
  * Update an AI provider
1019
1025
  *
1020
- * Updates an AI provider configuration
1026
+ * Updates an AI provider configuration. Setting `base_url` or `secret_id` so the record holds both also needs `secrets:UseSecret` on the secret, else `403`.
1021
1027
  */
1022
1028
  static updateAiProvider(options) {
1023
1029
  return (options.client ?? client).patch({
@@ -1100,7 +1106,7 @@ var ApiKeys = class {
1100
1106
  /**
1101
1107
  * Create an API key
1102
1108
  *
1103
- * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
1109
+ * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped token** (an OAuth access token, a trigger run-as token or a run token), it returns `403 API_KEY_SCOPED_TOKEN`: such a token never creates a key. - When the request is authenticated with a **project-scoped API key**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
1104
1110
  *
1105
1111
  */
1106
1112
  static createApiKey(options) {
@@ -1138,7 +1144,7 @@ var ApiKeys = class {
1138
1144
  /**
1139
1145
  * Update an API key
1140
1146
  *
1141
- * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise).
1147
+ * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise). A project-scoped token (OAuth, trigger or run) never updates a key (`403 API_KEY_SCOPED_TOKEN`).
1142
1148
  */
1143
1149
  static updateApiKey(options) {
1144
1150
  return (options.client ?? client).put({
@@ -3703,7 +3709,7 @@ var Playbooks = class {
3703
3709
  *
3704
3710
  * Creates a playbook at version 1. The definition is refused with `400 PLAYBOOK_VALIDATION_FAILED` when it holds a duplicate node or input, an input reading a missing node or field, an `execute` node without an executor or another kind with one, transformations on a non-final node, or a cycle; `meta.problems` lists every one. A duplicate `name` in the project is `409 NAME_CONFLICT`.
3705
3711
  *
3706
- * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
3712
+ * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). An executor cannot be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), nor a transformation's tool a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
3707
3713
  */
3708
3714
  static createPlaybook(options) {
3709
3715
  return (options.client ?? client).post({
@@ -3720,7 +3726,7 @@ var Playbooks = class {
3720
3726
  *
3721
3727
  * Answers what a create or update would be told about a definition, without writing: `valid`, and every graph problem it holds. A definition whose shape cannot be read is `400 VALIDATION_FAILED`, as on a write.
3722
3728
  *
3723
- * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
3729
+ * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`) and not be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), and each transformation's tool must not be a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
3724
3730
  */
3725
3731
  static validatePlaybook(options) {
3726
3732
  return (options.client ?? client).post({
@@ -3759,7 +3765,7 @@ var Playbooks = class {
3759
3765
  *
3760
3766
  * Updates any of `name`, `description` and `definition`. Only a change to `definition` archives a new version; a rename or a rewrite of the definition the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
3761
3767
  *
3762
- * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
3768
+ * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `EXECUTOR_TOOL_UNSUPPORTED` for a `client` tool executor, `TRANSFORMATION_TOOL_UNSUPPORTED` for a `client` or `mcp` transformation tool, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
3763
3769
  */
3764
3770
  static updatePlaybook(options) {
3765
3771
  return (options.client ?? client).patch({
@@ -4150,7 +4156,7 @@ var Projects = class {
4150
4156
  *
4151
4157
  * Deletes a project. Requires admin role. Fails with `409` if the project has any dependent resource, unless `force=true` is passed, in which case those resources are deleted along with the project.
4152
4158
  *
4153
- * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared.
4159
+ * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, priced usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared. A deleted formation and a usage event with no cost go with the project.
4154
4160
  *
4155
4161
  */
4156
4162
  static deleteProject(options) {
@@ -4173,7 +4179,7 @@ var Projects = class {
4173
4179
  /**
4174
4180
  * Update a project
4175
4181
  *
4176
- * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
4182
+ * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires projects:UpdateProject on the project, which a project-scoped policy can grant. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
4177
4183
  */
4178
4184
  static updateProject(options) {
4179
4185
  return (options.client ?? client).patch({
@@ -5024,7 +5030,7 @@ var Triggers = class {
5024
5030
  /**
5025
5031
  * Create a trigger
5026
5032
  *
5027
- * Creates a new trigger for a project
5033
+ * Creates a new trigger for a project. A `{{secret:...}}` reference in `tool_context` also needs `secrets:UseSecret` on that secret, else `403`.
5028
5034
  */
5029
5035
  static createTrigger(options) {
5030
5036
  return (options.client ?? client).post({
@@ -5072,7 +5078,7 @@ var Triggers = class {
5072
5078
  /**
5073
5079
  * Update a trigger
5074
5080
  *
5075
- * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.
5081
+ * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had. A `{{secret:...}}` reference in a written `tool_context`, or in the stored one when the target changes, also needs `secrets:UseSecret` on that secret, else `403`.
5076
5082
  *
5077
5083
  */
5078
5084
  static updateTrigger(options) {
package/dist/index.d.cts CHANGED
@@ -6036,9 +6036,9 @@ type NodeExecution = {
6036
6036
  */
6037
6037
  type RequiredAction = {
6038
6038
  /**
6039
- * Discriminator identifying the kind of pause. Open enum — new pause kinds may be added in minor releases; clients must tolerate unknown values.
6039
+ * Discriminator identifying the kind of pause. Open enum — new pause kinds may be added in minor releases; clients must tolerate unknown values. `child_run` is a `loop` or `sub_orchestration` node whose child runs, listed in `context.orchestration_run_ids`, have not settled; their settle resumes it, and it accepts no human input.
6040
6040
  */
6041
- type: 'human_input' | 'webhook_receive' | 'approval' | 'paused';
6041
+ type: 'human_input' | 'webhook_receive' | 'approval' | 'paused' | 'child_run';
6042
6042
  /**
6043
6043
  * The node the run is parked at. Absent for a `paused` action, which no node produced.
6044
6044
  */
@@ -6338,7 +6338,7 @@ type UpdatePlaybookRequest = {
6338
6338
  };
6339
6339
  type ValidatePlaybookRequest = {
6340
6340
  /**
6341
- * Also check the references against this project: the upstreams (`UNKNOWN_UPSTREAM`, and the `MISSING_NODE` and `UNKNOWN_FIELD` of what an upstream node pulls) and the executors (`EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`).
6341
+ * Also check the references against this project: the upstreams (`UNKNOWN_UPSTREAM`, and the `MISSING_NODE` and `UNKNOWN_FIELD` of what an upstream node pulls) and the executors (`EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`, `EXECUTOR_TOOL_UNSUPPORTED`, `TRANSFORMATION_TOOL_UNSUPPORTED`).
6342
6342
  */
6343
6343
  project_id?: string;
6344
6344
  /**
@@ -6353,7 +6353,7 @@ type ValidatePlaybookRequest = {
6353
6353
  type PlaybookValidationResult = {
6354
6354
  valid: boolean;
6355
6355
  /**
6356
- * Every reason the definition cannot be stored: `DUPLICATE_NODE`, `DUPLICATE_INPUT`, `MISSING_NODE`, `UNKNOWN_FIELD`, `EXECUTOR_REQUIRED`, `EXECUTOR_FORBIDDEN`, `TRANSFORMATIONS_NOT_FINAL`, `DUPLICATE_TRANSFORMATION`, `CYCLE`, and, with `project_id`, `UNKNOWN_UPSTREAM`, `UPSTREAM_CYCLE`, `EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE`. The same items a refused write lists under `meta.problems`.
6356
+ * Every reason the definition cannot be stored: `DUPLICATE_NODE`, `DUPLICATE_INPUT`, `MISSING_NODE`, `UNKNOWN_FIELD`, `EXECUTOR_REQUIRED`, `EXECUTOR_FORBIDDEN`, `TRANSFORMATIONS_NOT_FINAL`, `DUPLICATE_TRANSFORMATION`, `CYCLE`, and, with `project_id`, `UNKNOWN_UPSTREAM`, `UPSTREAM_CYCLE`, `EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`, `EXECUTOR_TOOL_UNSUPPORTED` or `TRANSFORMATION_TOOL_UNSUPPORTED`. The same items a refused write lists under `meta.problems`.
6357
6357
  */
6358
6358
  problems: Array<ValidationProblem>;
6359
6359
  };
@@ -10527,7 +10527,7 @@ type ListAiProvidersResponses = {
10527
10527
  */
10528
10528
  base_url?: string;
10529
10529
  /**
10530
- * Additional provider-specific configuration. Absent when the record sets none. A `config.apiKey` reads as `{"no_echo": true}`.
10530
+ * Additional provider-specific configuration. Absent when the record sets none. Never carries a credential.
10531
10531
  */
10532
10532
  config?: {
10533
10533
  [key: string]: unknown;
@@ -10558,7 +10558,7 @@ type CreateAiProviderData = {
10558
10558
  */
10559
10559
  default_model: string;
10560
10560
  /**
10561
- * Secret ID containing API credentials. Required for `bedrock` and `vertex` unless `config.apiKey` carries one.
10561
+ * Secret ID containing API credentials. Required for `bedrock` and `vertex`.
10562
10562
  */
10563
10563
  secret_id?: string;
10564
10564
  /**
@@ -10566,7 +10566,7 @@ type CreateAiProviderData = {
10566
10566
  */
10567
10567
  base_url?: string;
10568
10568
  /**
10569
- * Additional provider-specific configuration. `config.apiKey`, when set, must be a string; every read returns it as `{"no_echo": true}`.
10569
+ * Additional provider-specific configuration. `apiKey` is refused: the credential goes in the linked secret.
10570
10570
  */
10571
10571
  config?: {
10572
10572
  [key: string]: unknown;
@@ -10725,7 +10725,7 @@ type GetAiProviderResponses = {
10725
10725
  secret_id?: string | null;
10726
10726
  base_url?: string;
10727
10727
  /**
10728
- * Additional provider-specific configuration. A `config.apiKey` reads as `{"no_echo": true}`.
10728
+ * Additional provider-specific configuration. Never carries a credential.
10729
10729
  */
10730
10730
  config?: {
10731
10731
  [key: string]: unknown;
@@ -10746,7 +10746,7 @@ type UpdateAiProviderData = {
10746
10746
  secret_id?: string | null;
10747
10747
  base_url?: string;
10748
10748
  /**
10749
- * Replaces the whole configuration, so a `config.apiKey` the record keeps is sent again as a string; the masked `{"no_echo": true}` a read returns is refused.
10749
+ * Replaces the whole configuration. `apiKey` is refused: the credential goes in the linked secret.
10750
10750
  */
10751
10751
  config?: {
10752
10752
  [key: string]: unknown;
@@ -11028,7 +11028,7 @@ type CreateApiKeyErrors = {
11028
11028
  */
11029
11029
  401: ErrorResponse;
11030
11030
  /**
11031
- * Forbidden (a project-scoped credential named a different project, or asked for an unscoped key; or a key narrowed by `policy_ids` asked for a key outside its boundary)
11031
+ * Forbidden (a project-scoped token; a project-scoped key named a different project, or asked for an unscoped key; or a key narrowed by `policy_ids` asked for a key outside its boundary)
11032
11032
  */
11033
11033
  403: ErrorResponse;
11034
11034
  /**
@@ -11173,7 +11173,7 @@ type UpdateApiKeyErrors = {
11173
11173
  */
11174
11174
  401: ErrorResponse;
11175
11175
  /**
11176
- * Forbidden (not the key owner or admin, the credential is scoped to a different project, or a key narrowed by `policy_ids` asked for policies outside its boundary)
11176
+ * Forbidden (a project-scoped token, not the key owner or admin, the credential is scoped to a different project, or a key narrowed by `policy_ids` asked for policies outside its boundary)
11177
11177
  */
11178
11178
  403: ErrorResponse;
11179
11179
  /**
@@ -13730,7 +13730,7 @@ type UpdateDocumentErrors = {
13730
13730
  */
13731
13731
  404: ErrorResponse;
13732
13732
  /**
13733
- * The document has moved past the version this write read (`VERSION_CONFLICT`, with `meta.current_version`), or `path` is held by another file in the project (`NAME_CONFLICT`). Nothing is written.
13733
+ * The document has moved past the version this write read (`VERSION_CONFLICT`, with `meta.current_version`), `path` is held by another file in the project (`NAME_CONFLICT`), or new `content` would exceed the project's `storage_bytes` quota (`QUOTA_STORAGE_EXCEEDED`, no `Retry-After`). Nothing is written.
13734
13734
  */
13735
13735
  409: ErrorResponse;
13736
13736
  /**
@@ -14147,7 +14147,7 @@ type RestoreDocumentVersionErrors = {
14147
14147
  */
14148
14148
  404: ErrorResponse;
14149
14149
  /**
14150
- * Another write took the document's version first (`VERSION_CONFLICT`, with `meta.current_version`), or the restored `path` is held by another file in the project (`NAME_CONFLICT`). Nothing is written.
14150
+ * Another write took the document's version first (`VERSION_CONFLICT`, with `meta.current_version`), the restored `path` is held by another file in the project (`NAME_CONFLICT`), or the restored content would exceed the project's `storage_bytes` quota (`QUOTA_STORAGE_EXCEEDED`, no `Retry-After`). Nothing is written.
14151
14151
  */
14152
14152
  409: ErrorResponse;
14153
14153
  /**
@@ -18477,7 +18477,7 @@ type UpdateMemoryErrors = {
18477
18477
  */
18478
18478
  404: ErrorResponse;
18479
18479
  /**
18480
- * The resource has moved past the version this write read (`VERSION_CONFLICT`): a stated `expected_version` or `If-Match` no longer matches, or a concurrent write took the version first. `meta.current_version` names the version in force. Nothing is written.
18480
+ * The memory has moved past the version this write read (`VERSION_CONFLICT`, with `meta.current_version`), or new `content` would exceed the project's `storage_bytes` quota (`QUOTA_STORAGE_EXCEEDED`, no `Retry-After`). Nothing is written.
18481
18481
  */
18482
18482
  409: ErrorResponse;
18483
18483
  /**
@@ -28745,7 +28745,7 @@ export declare class Agents {
28745
28745
  /**
28746
28746
  * Create an agent
28747
28747
  *
28748
- * Creates a new agent bound to an AI provider.
28748
+ * Creates a new agent bound to an AI provider. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
28749
28749
  */
28750
28750
  static createAgent<ThrowOnError extends boolean = false>(options: Options<CreateAgentData, ThrowOnError>): RequestResult<CreateAgentResponses, CreateAgentErrors, ThrowOnError>;
28751
28751
  /**
@@ -28765,13 +28765,13 @@ export declare class Agents {
28765
28765
  /**
28766
28766
  * Partially update an agent
28767
28767
  *
28768
- * Partially updates an existing agent. Identical to PUT — both perform partial updates.
28768
+ * Partially updates an existing agent. Identical to PUT — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
28769
28769
  */
28770
28770
  static patchAgent<ThrowOnError extends boolean = false>(options: Options<PatchAgentData, ThrowOnError>): RequestResult<PatchAgentResponses, PatchAgentErrors, ThrowOnError>;
28771
28771
  /**
28772
28772
  * Update an agent
28773
28773
  *
28774
- * Updates an existing agent. Identical to PATCH — both perform partial updates.
28774
+ * Updates an existing agent. Identical to PATCH — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
28775
28775
  */
28776
28776
  static updateAgent<ThrowOnError extends boolean = false>(options: Options<UpdateAgentData, ThrowOnError>): RequestResult<UpdateAgentResponses, UpdateAgentErrors, ThrowOnError>;
28777
28777
  /**
@@ -28855,8 +28855,14 @@ export declare class AiProviders {
28855
28855
  *
28856
28856
  * Creates a new LLM provider configuration.
28857
28857
  *
28858
- * A `bedrock` or `vertex` record must carry a credential of its own — a
28859
- * linked `secret_id`, or an `apiKey` in `config`. Without one the provider
28858
+ * A provider's credential is its linked `secret_id`; `config.apiKey` is
28859
+ * refused with `400 VALIDATION_FAILED`.
28860
+ *
28861
+ * A record with both `base_url` and `secret_id` sends the secret to that
28862
+ * URL, so creating one also needs `secrets:UseSecret` on the secret, else
28863
+ * `403`.
28864
+ *
28865
+ * A `bedrock` or `vertex` record must link one. Without it the provider
28860
28866
  * SDK signs with the server's own credentials (the AWS default credential
28861
28867
  * chain, Google Application Default Credentials), which is refused with
28862
28868
  * `400 VALIDATION_FAILED` unless the deployment allows it.
@@ -28881,7 +28887,7 @@ export declare class AiProviders {
28881
28887
  /**
28882
28888
  * Update an AI provider
28883
28889
  *
28884
- * Updates an AI provider configuration
28890
+ * Updates an AI provider configuration. Setting `base_url` or `secret_id` so the record holds both also needs `secrets:UseSecret` on the secret, else `403`.
28885
28891
  */
28886
28892
  static updateAiProvider<ThrowOnError extends boolean = false>(options: Options<UpdateAiProviderData, ThrowOnError>): RequestResult<UpdateAiProviderResponses, UpdateAiProviderErrors, ThrowOnError>;
28887
28893
  /**
@@ -28927,7 +28933,7 @@ export declare class ApiKeys {
28927
28933
  /**
28928
28934
  * Create an API key
28929
28935
  *
28930
- * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
28936
+ * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped token** (an OAuth access token, a trigger run-as token or a run token), it returns `403 API_KEY_SCOPED_TOKEN`: such a token never creates a key. - When the request is authenticated with a **project-scoped API key**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
28931
28937
  *
28932
28938
  */
28933
28939
  static createApiKey<ThrowOnError extends boolean = false>(options: Options<CreateApiKeyData, ThrowOnError>): RequestResult<CreateApiKeyResponses, CreateApiKeyErrors, ThrowOnError>;
@@ -28946,7 +28952,7 @@ export declare class ApiKeys {
28946
28952
  /**
28947
28953
  * Update an API key
28948
28954
  *
28949
- * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise).
28955
+ * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise). A project-scoped token (OAuth, trigger or run) never updates a key (`403 API_KEY_SCOPED_TOKEN`).
28950
28956
  */
28951
28957
  static updateApiKey<ThrowOnError extends boolean = false>(options: Options<UpdateApiKeyData, ThrowOnError>): RequestResult<UpdateApiKeyResponses, UpdateApiKeyErrors, ThrowOnError>;
28952
28958
  }
@@ -30266,7 +30272,7 @@ export declare class Playbooks {
30266
30272
  *
30267
30273
  * Creates a playbook at version 1. The definition is refused with `400 PLAYBOOK_VALIDATION_FAILED` when it holds a duplicate node or input, an input reading a missing node or field, an `execute` node without an executor or another kind with one, transformations on a non-final node, or a cycle; `meta.problems` lists every one. A duplicate `name` in the project is `409 NAME_CONFLICT`.
30268
30274
  *
30269
- * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
30275
+ * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). An executor cannot be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), nor a transformation's tool a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
30270
30276
  */
30271
30277
  static createPlaybook<ThrowOnError extends boolean = false>(options: Options<CreatePlaybookData, ThrowOnError>): RequestResult<CreatePlaybookResponses, CreatePlaybookErrors, ThrowOnError>;
30272
30278
  /**
@@ -30274,7 +30280,7 @@ export declare class Playbooks {
30274
30280
  *
30275
30281
  * Answers what a create or update would be told about a definition, without writing: `valid`, and every graph problem it holds. A definition whose shape cannot be read is `400 VALIDATION_FAILED`, as on a write.
30276
30282
  *
30277
- * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
30283
+ * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`) and not be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), and each transformation's tool must not be a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
30278
30284
  */
30279
30285
  static validatePlaybook<ThrowOnError extends boolean = false>(options: Options<ValidatePlaybookData, ThrowOnError>): RequestResult<ValidatePlaybookResponses, ValidatePlaybookErrors, ThrowOnError>;
30280
30286
  /**
@@ -30294,7 +30300,7 @@ export declare class Playbooks {
30294
30300
  *
30295
30301
  * Updates any of `name`, `description` and `definition`. Only a change to `definition` archives a new version; a rename or a rewrite of the definition the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
30296
30302
  *
30297
- * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
30303
+ * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `EXECUTOR_TOOL_UNSUPPORTED` for a `client` tool executor, `TRANSFORMATION_TOOL_UNSUPPORTED` for a `client` or `mcp` transformation tool, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
30298
30304
  */
30299
30305
  static updatePlaybook<ThrowOnError extends boolean = false>(options: Options<UpdatePlaybookData, ThrowOnError>): RequestResult<UpdatePlaybookResponses, UpdatePlaybookErrors, ThrowOnError>;
30300
30306
  /**
@@ -30492,7 +30498,7 @@ export declare class Projects {
30492
30498
  *
30493
30499
  * Deletes a project. Requires admin role. Fails with `409` if the project has any dependent resource, unless `force=true` is passed, in which case those resources are deleted along with the project.
30494
30500
  *
30495
- * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared.
30501
+ * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, priced usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared. A deleted formation and a usage event with no cost go with the project.
30496
30502
  *
30497
30503
  */
30498
30504
  static deleteProject<ThrowOnError extends boolean = false>(options: Options<DeleteProjectData, ThrowOnError>): RequestResult<DeleteProjectResponses, DeleteProjectErrors, ThrowOnError>;
@@ -30505,7 +30511,7 @@ export declare class Projects {
30505
30511
  /**
30506
30512
  * Update a project
30507
30513
  *
30508
- * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
30514
+ * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires projects:UpdateProject on the project, which a project-scoped policy can grant. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
30509
30515
  */
30510
30516
  static updateProject<ThrowOnError extends boolean = false>(options: Options<UpdateProjectData, ThrowOnError>): RequestResult<UpdateProjectResponses, UpdateProjectErrors, ThrowOnError>;
30511
30517
  /**
@@ -30933,7 +30939,7 @@ export declare class Triggers {
30933
30939
  /**
30934
30940
  * Create a trigger
30935
30941
  *
30936
- * Creates a new trigger for a project
30942
+ * Creates a new trigger for a project. A `{{secret:...}}` reference in `tool_context` also needs `secrets:UseSecret` on that secret, else `403`.
30937
30943
  */
30938
30944
  static createTrigger<ThrowOnError extends boolean = false>(options: Options<CreateTriggerData, ThrowOnError>): RequestResult<CreateTriggerResponses, CreateTriggerErrors, ThrowOnError>;
30939
30945
  /**
@@ -30957,7 +30963,7 @@ export declare class Triggers {
30957
30963
  /**
30958
30964
  * Update a trigger
30959
30965
  *
30960
- * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.
30966
+ * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had. A `{{secret:...}}` reference in a written `tool_context`, or in the stored one when the target changes, also needs `secrets:UseSecret` on that secret, else `403`.
30961
30967
  *
30962
30968
  */
30963
30969
  static updateTrigger<ThrowOnError extends boolean = false>(options: Options<UpdateTriggerData, ThrowOnError>): RequestResult<UpdateTriggerResponses, UpdateTriggerErrors, ThrowOnError>;
package/dist/index.d.mts CHANGED
@@ -6036,9 +6036,9 @@ type NodeExecution = {
6036
6036
  */
6037
6037
  type RequiredAction = {
6038
6038
  /**
6039
- * Discriminator identifying the kind of pause. Open enum — new pause kinds may be added in minor releases; clients must tolerate unknown values.
6039
+ * Discriminator identifying the kind of pause. Open enum — new pause kinds may be added in minor releases; clients must tolerate unknown values. `child_run` is a `loop` or `sub_orchestration` node whose child runs, listed in `context.orchestration_run_ids`, have not settled; their settle resumes it, and it accepts no human input.
6040
6040
  */
6041
- type: 'human_input' | 'webhook_receive' | 'approval' | 'paused';
6041
+ type: 'human_input' | 'webhook_receive' | 'approval' | 'paused' | 'child_run';
6042
6042
  /**
6043
6043
  * The node the run is parked at. Absent for a `paused` action, which no node produced.
6044
6044
  */
@@ -6338,7 +6338,7 @@ type UpdatePlaybookRequest = {
6338
6338
  };
6339
6339
  type ValidatePlaybookRequest = {
6340
6340
  /**
6341
- * Also check the references against this project: the upstreams (`UNKNOWN_UPSTREAM`, and the `MISSING_NODE` and `UNKNOWN_FIELD` of what an upstream node pulls) and the executors (`EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`).
6341
+ * Also check the references against this project: the upstreams (`UNKNOWN_UPSTREAM`, and the `MISSING_NODE` and `UNKNOWN_FIELD` of what an upstream node pulls) and the executors (`EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`, `EXECUTOR_TOOL_UNSUPPORTED`, `TRANSFORMATION_TOOL_UNSUPPORTED`).
6342
6342
  */
6343
6343
  project_id?: string;
6344
6344
  /**
@@ -6353,7 +6353,7 @@ type ValidatePlaybookRequest = {
6353
6353
  type PlaybookValidationResult = {
6354
6354
  valid: boolean;
6355
6355
  /**
6356
- * Every reason the definition cannot be stored: `DUPLICATE_NODE`, `DUPLICATE_INPUT`, `MISSING_NODE`, `UNKNOWN_FIELD`, `EXECUTOR_REQUIRED`, `EXECUTOR_FORBIDDEN`, `TRANSFORMATIONS_NOT_FINAL`, `DUPLICATE_TRANSFORMATION`, `CYCLE`, and, with `project_id`, `UNKNOWN_UPSTREAM`, `UPSTREAM_CYCLE`, `EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE`. The same items a refused write lists under `meta.problems`.
6356
+ * Every reason the definition cannot be stored: `DUPLICATE_NODE`, `DUPLICATE_INPUT`, `MISSING_NODE`, `UNKNOWN_FIELD`, `EXECUTOR_REQUIRED`, `EXECUTOR_FORBIDDEN`, `TRANSFORMATIONS_NOT_FINAL`, `DUPLICATE_TRANSFORMATION`, `CYCLE`, and, with `project_id`, `UNKNOWN_UPSTREAM`, `UPSTREAM_CYCLE`, `EXECUTOR_NOT_FOUND`, `EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`, `EXECUTOR_TOOL_UNSUPPORTED` or `TRANSFORMATION_TOOL_UNSUPPORTED`. The same items a refused write lists under `meta.problems`.
6357
6357
  */
6358
6358
  problems: Array<ValidationProblem>;
6359
6359
  };
@@ -10527,7 +10527,7 @@ type ListAiProvidersResponses = {
10527
10527
  */
10528
10528
  base_url?: string;
10529
10529
  /**
10530
- * Additional provider-specific configuration. Absent when the record sets none. A `config.apiKey` reads as `{"no_echo": true}`.
10530
+ * Additional provider-specific configuration. Absent when the record sets none. Never carries a credential.
10531
10531
  */
10532
10532
  config?: {
10533
10533
  [key: string]: unknown;
@@ -10558,7 +10558,7 @@ type CreateAiProviderData = {
10558
10558
  */
10559
10559
  default_model: string;
10560
10560
  /**
10561
- * Secret ID containing API credentials. Required for `bedrock` and `vertex` unless `config.apiKey` carries one.
10561
+ * Secret ID containing API credentials. Required for `bedrock` and `vertex`.
10562
10562
  */
10563
10563
  secret_id?: string;
10564
10564
  /**
@@ -10566,7 +10566,7 @@ type CreateAiProviderData = {
10566
10566
  */
10567
10567
  base_url?: string;
10568
10568
  /**
10569
- * Additional provider-specific configuration. `config.apiKey`, when set, must be a string; every read returns it as `{"no_echo": true}`.
10569
+ * Additional provider-specific configuration. `apiKey` is refused: the credential goes in the linked secret.
10570
10570
  */
10571
10571
  config?: {
10572
10572
  [key: string]: unknown;
@@ -10725,7 +10725,7 @@ type GetAiProviderResponses = {
10725
10725
  secret_id?: string | null;
10726
10726
  base_url?: string;
10727
10727
  /**
10728
- * Additional provider-specific configuration. A `config.apiKey` reads as `{"no_echo": true}`.
10728
+ * Additional provider-specific configuration. Never carries a credential.
10729
10729
  */
10730
10730
  config?: {
10731
10731
  [key: string]: unknown;
@@ -10746,7 +10746,7 @@ type UpdateAiProviderData = {
10746
10746
  secret_id?: string | null;
10747
10747
  base_url?: string;
10748
10748
  /**
10749
- * Replaces the whole configuration, so a `config.apiKey` the record keeps is sent again as a string; the masked `{"no_echo": true}` a read returns is refused.
10749
+ * Replaces the whole configuration. `apiKey` is refused: the credential goes in the linked secret.
10750
10750
  */
10751
10751
  config?: {
10752
10752
  [key: string]: unknown;
@@ -11028,7 +11028,7 @@ type CreateApiKeyErrors = {
11028
11028
  */
11029
11029
  401: ErrorResponse;
11030
11030
  /**
11031
- * Forbidden (a project-scoped credential named a different project, or asked for an unscoped key; or a key narrowed by `policy_ids` asked for a key outside its boundary)
11031
+ * Forbidden (a project-scoped token; a project-scoped key named a different project, or asked for an unscoped key; or a key narrowed by `policy_ids` asked for a key outside its boundary)
11032
11032
  */
11033
11033
  403: ErrorResponse;
11034
11034
  /**
@@ -11173,7 +11173,7 @@ type UpdateApiKeyErrors = {
11173
11173
  */
11174
11174
  401: ErrorResponse;
11175
11175
  /**
11176
- * Forbidden (not the key owner or admin, the credential is scoped to a different project, or a key narrowed by `policy_ids` asked for policies outside its boundary)
11176
+ * Forbidden (a project-scoped token, not the key owner or admin, the credential is scoped to a different project, or a key narrowed by `policy_ids` asked for policies outside its boundary)
11177
11177
  */
11178
11178
  403: ErrorResponse;
11179
11179
  /**
@@ -13730,7 +13730,7 @@ type UpdateDocumentErrors = {
13730
13730
  */
13731
13731
  404: ErrorResponse;
13732
13732
  /**
13733
- * The document has moved past the version this write read (`VERSION_CONFLICT`, with `meta.current_version`), or `path` is held by another file in the project (`NAME_CONFLICT`). Nothing is written.
13733
+ * The document has moved past the version this write read (`VERSION_CONFLICT`, with `meta.current_version`), `path` is held by another file in the project (`NAME_CONFLICT`), or new `content` would exceed the project's `storage_bytes` quota (`QUOTA_STORAGE_EXCEEDED`, no `Retry-After`). Nothing is written.
13734
13734
  */
13735
13735
  409: ErrorResponse;
13736
13736
  /**
@@ -14147,7 +14147,7 @@ type RestoreDocumentVersionErrors = {
14147
14147
  */
14148
14148
  404: ErrorResponse;
14149
14149
  /**
14150
- * Another write took the document's version first (`VERSION_CONFLICT`, with `meta.current_version`), or the restored `path` is held by another file in the project (`NAME_CONFLICT`). Nothing is written.
14150
+ * Another write took the document's version first (`VERSION_CONFLICT`, with `meta.current_version`), the restored `path` is held by another file in the project (`NAME_CONFLICT`), or the restored content would exceed the project's `storage_bytes` quota (`QUOTA_STORAGE_EXCEEDED`, no `Retry-After`). Nothing is written.
14151
14151
  */
14152
14152
  409: ErrorResponse;
14153
14153
  /**
@@ -18477,7 +18477,7 @@ type UpdateMemoryErrors = {
18477
18477
  */
18478
18478
  404: ErrorResponse;
18479
18479
  /**
18480
- * The resource has moved past the version this write read (`VERSION_CONFLICT`): a stated `expected_version` or `If-Match` no longer matches, or a concurrent write took the version first. `meta.current_version` names the version in force. Nothing is written.
18480
+ * The memory has moved past the version this write read (`VERSION_CONFLICT`, with `meta.current_version`), or new `content` would exceed the project's `storage_bytes` quota (`QUOTA_STORAGE_EXCEEDED`, no `Retry-After`). Nothing is written.
18481
18481
  */
18482
18482
  409: ErrorResponse;
18483
18483
  /**
@@ -28745,7 +28745,7 @@ export declare class Agents {
28745
28745
  /**
28746
28746
  * Create an agent
28747
28747
  *
28748
- * Creates a new agent bound to an AI provider.
28748
+ * Creates a new agent bound to an AI provider. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
28749
28749
  */
28750
28750
  static createAgent<ThrowOnError extends boolean = false>(options: Options<CreateAgentData, ThrowOnError>): RequestResult<CreateAgentResponses, CreateAgentErrors, ThrowOnError>;
28751
28751
  /**
@@ -28765,13 +28765,13 @@ export declare class Agents {
28765
28765
  /**
28766
28766
  * Partially update an agent
28767
28767
  *
28768
- * Partially updates an existing agent. Identical to PUT — both perform partial updates.
28768
+ * Partially updates an existing agent. Identical to PUT — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
28769
28769
  */
28770
28770
  static patchAgent<ThrowOnError extends boolean = false>(options: Options<PatchAgentData, ThrowOnError>): RequestResult<PatchAgentResponses, PatchAgentErrors, ThrowOnError>;
28771
28771
  /**
28772
28772
  * Update an agent
28773
28773
  *
28774
- * Updates an existing agent. Identical to PATCH — both perform partial updates.
28774
+ * Updates an existing agent. Identical to PATCH — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
28775
28775
  */
28776
28776
  static updateAgent<ThrowOnError extends boolean = false>(options: Options<UpdateAgentData, ThrowOnError>): RequestResult<UpdateAgentResponses, UpdateAgentErrors, ThrowOnError>;
28777
28777
  /**
@@ -28855,8 +28855,14 @@ export declare class AiProviders {
28855
28855
  *
28856
28856
  * Creates a new LLM provider configuration.
28857
28857
  *
28858
- * A `bedrock` or `vertex` record must carry a credential of its own — a
28859
- * linked `secret_id`, or an `apiKey` in `config`. Without one the provider
28858
+ * A provider's credential is its linked `secret_id`; `config.apiKey` is
28859
+ * refused with `400 VALIDATION_FAILED`.
28860
+ *
28861
+ * A record with both `base_url` and `secret_id` sends the secret to that
28862
+ * URL, so creating one also needs `secrets:UseSecret` on the secret, else
28863
+ * `403`.
28864
+ *
28865
+ * A `bedrock` or `vertex` record must link one. Without it the provider
28860
28866
  * SDK signs with the server's own credentials (the AWS default credential
28861
28867
  * chain, Google Application Default Credentials), which is refused with
28862
28868
  * `400 VALIDATION_FAILED` unless the deployment allows it.
@@ -28881,7 +28887,7 @@ export declare class AiProviders {
28881
28887
  /**
28882
28888
  * Update an AI provider
28883
28889
  *
28884
- * Updates an AI provider configuration
28890
+ * Updates an AI provider configuration. Setting `base_url` or `secret_id` so the record holds both also needs `secrets:UseSecret` on the secret, else `403`.
28885
28891
  */
28886
28892
  static updateAiProvider<ThrowOnError extends boolean = false>(options: Options<UpdateAiProviderData, ThrowOnError>): RequestResult<UpdateAiProviderResponses, UpdateAiProviderErrors, ThrowOnError>;
28887
28893
  /**
@@ -28927,7 +28933,7 @@ export declare class ApiKeys {
28927
28933
  /**
28928
28934
  * Create an API key
28929
28935
  *
28930
- * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
28936
+ * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped token** (an OAuth access token, a trigger run-as token or a run token), it returns `403 API_KEY_SCOPED_TOKEN`: such a token never creates a key. - When the request is authenticated with a **project-scoped API key**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
28931
28937
  *
28932
28938
  */
28933
28939
  static createApiKey<ThrowOnError extends boolean = false>(options: Options<CreateApiKeyData, ThrowOnError>): RequestResult<CreateApiKeyResponses, CreateApiKeyErrors, ThrowOnError>;
@@ -28946,7 +28952,7 @@ export declare class ApiKeys {
28946
28952
  /**
28947
28953
  * Update an API key
28948
28954
  *
28949
- * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise).
28955
+ * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise). A project-scoped token (OAuth, trigger or run) never updates a key (`403 API_KEY_SCOPED_TOKEN`).
28950
28956
  */
28951
28957
  static updateApiKey<ThrowOnError extends boolean = false>(options: Options<UpdateApiKeyData, ThrowOnError>): RequestResult<UpdateApiKeyResponses, UpdateApiKeyErrors, ThrowOnError>;
28952
28958
  }
@@ -30266,7 +30272,7 @@ export declare class Playbooks {
30266
30272
  *
30267
30273
  * Creates a playbook at version 1. The definition is refused with `400 PLAYBOOK_VALIDATION_FAILED` when it holds a duplicate node or input, an input reading a missing node or field, an `execute` node without an executor or another kind with one, transformations on a non-final node, or a cycle; `meta.problems` lists every one. A duplicate `name` in the project is `409 NAME_CONFLICT`.
30268
30274
  *
30269
- * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
30275
+ * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). An executor cannot be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), nor a transformation's tool a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
30270
30276
  */
30271
30277
  static createPlaybook<ThrowOnError extends boolean = false>(options: Options<CreatePlaybookData, ThrowOnError>): RequestResult<CreatePlaybookResponses, CreatePlaybookErrors, ThrowOnError>;
30272
30278
  /**
@@ -30274,7 +30280,7 @@ export declare class Playbooks {
30274
30280
  *
30275
30281
  * Answers what a create or update would be told about a definition, without writing: `valid`, and every graph problem it holds. A definition whose shape cannot be read is `400 VALIDATION_FAILED`, as on a write.
30276
30282
  *
30277
- * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
30283
+ * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`) and not be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), and each transformation's tool must not be a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
30278
30284
  */
30279
30285
  static validatePlaybook<ThrowOnError extends boolean = false>(options: Options<ValidatePlaybookData, ThrowOnError>): RequestResult<ValidatePlaybookResponses, ValidatePlaybookErrors, ThrowOnError>;
30280
30286
  /**
@@ -30294,7 +30300,7 @@ export declare class Playbooks {
30294
30300
  *
30295
30301
  * Updates any of `name`, `description` and `definition`. Only a change to `definition` archives a new version; a rename or a rewrite of the definition the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
30296
30302
  *
30297
- * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
30303
+ * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `EXECUTOR_TOOL_UNSUPPORTED` for a `client` tool executor, `TRANSFORMATION_TOOL_UNSUPPORTED` for a `client` or `mcp` transformation tool, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
30298
30304
  */
30299
30305
  static updatePlaybook<ThrowOnError extends boolean = false>(options: Options<UpdatePlaybookData, ThrowOnError>): RequestResult<UpdatePlaybookResponses, UpdatePlaybookErrors, ThrowOnError>;
30300
30306
  /**
@@ -30492,7 +30498,7 @@ export declare class Projects {
30492
30498
  *
30493
30499
  * Deletes a project. Requires admin role. Fails with `409` if the project has any dependent resource, unless `force=true` is passed, in which case those resources are deleted along with the project.
30494
30500
  *
30495
- * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared.
30501
+ * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, priced usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared. A deleted formation and a usage event with no cost go with the project.
30496
30502
  *
30497
30503
  */
30498
30504
  static deleteProject<ThrowOnError extends boolean = false>(options: Options<DeleteProjectData, ThrowOnError>): RequestResult<DeleteProjectResponses, DeleteProjectErrors, ThrowOnError>;
@@ -30505,7 +30511,7 @@ export declare class Projects {
30505
30511
  /**
30506
30512
  * Update a project
30507
30513
  *
30508
- * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
30514
+ * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires projects:UpdateProject on the project, which a project-scoped policy can grant. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
30509
30515
  */
30510
30516
  static updateProject<ThrowOnError extends boolean = false>(options: Options<UpdateProjectData, ThrowOnError>): RequestResult<UpdateProjectResponses, UpdateProjectErrors, ThrowOnError>;
30511
30517
  /**
@@ -30933,7 +30939,7 @@ export declare class Triggers {
30933
30939
  /**
30934
30940
  * Create a trigger
30935
30941
  *
30936
- * Creates a new trigger for a project
30942
+ * Creates a new trigger for a project. A `{{secret:...}}` reference in `tool_context` also needs `secrets:UseSecret` on that secret, else `403`.
30937
30943
  */
30938
30944
  static createTrigger<ThrowOnError extends boolean = false>(options: Options<CreateTriggerData, ThrowOnError>): RequestResult<CreateTriggerResponses, CreateTriggerErrors, ThrowOnError>;
30939
30945
  /**
@@ -30957,7 +30963,7 @@ export declare class Triggers {
30957
30963
  /**
30958
30964
  * Update a trigger
30959
30965
  *
30960
- * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.
30966
+ * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had. A `{{secret:...}}` reference in a written `tool_context`, or in the stored one when the target changes, also needs `secrets:UseSecret` on that secret, else `403`.
30961
30967
  *
30962
30968
  */
30963
30969
  static updateTrigger<ThrowOnError extends boolean = false>(options: Options<UpdateTriggerData, ThrowOnError>): RequestResult<UpdateTriggerResponses, UpdateTriggerErrors, ThrowOnError>;
package/dist/index.mjs CHANGED
@@ -763,7 +763,7 @@ var Agents = class {
763
763
  /**
764
764
  * Create an agent
765
765
  *
766
- * Creates a new agent bound to an AI provider.
766
+ * Creates a new agent bound to an AI provider. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
767
767
  */
768
768
  static createAgent(options) {
769
769
  return (options.client ?? client).post({
@@ -802,7 +802,7 @@ var Agents = class {
802
802
  /**
803
803
  * Partially update an agent
804
804
  *
805
- * Partially updates an existing agent. Identical to PUT — both perform partial updates.
805
+ * Partially updates an existing agent. Identical to PUT — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
806
806
  */
807
807
  static patchAgent(options) {
808
808
  return (options.client ?? client).patch({
@@ -817,7 +817,7 @@ var Agents = class {
817
817
  /**
818
818
  * Update an agent
819
819
  *
820
- * Updates an existing agent. Identical to PATCH — both perform partial updates.
820
+ * Updates an existing agent. Identical to PATCH — both perform partial updates. A `{{secret:...}}` reference in an inline `tool_bindings[].tool` also needs `secrets:UseSecret` on that secret, else `403`.
821
821
  */
822
822
  static updateAgent(options) {
823
823
  return (options.client ?? client).put({
@@ -971,8 +971,14 @@ var AiProviders = class {
971
971
  *
972
972
  * Creates a new LLM provider configuration.
973
973
  *
974
- * A `bedrock` or `vertex` record must carry a credential of its own — a
975
- * linked `secret_id`, or an `apiKey` in `config`. Without one the provider
974
+ * A provider's credential is its linked `secret_id`; `config.apiKey` is
975
+ * refused with `400 VALIDATION_FAILED`.
976
+ *
977
+ * A record with both `base_url` and `secret_id` sends the secret to that
978
+ * URL, so creating one also needs `secrets:UseSecret` on the secret, else
979
+ * `403`.
980
+ *
981
+ * A `bedrock` or `vertex` record must link one. Without it the provider
976
982
  * SDK signs with the server's own credentials (the AWS default credential
977
983
  * chain, Google Application Default Credentials), which is refused with
978
984
  * `400 VALIDATION_FAILED` unless the deployment allows it.
@@ -1016,7 +1022,7 @@ var AiProviders = class {
1016
1022
  /**
1017
1023
  * Update an AI provider
1018
1024
  *
1019
- * Updates an AI provider configuration
1025
+ * Updates an AI provider configuration. Setting `base_url` or `secret_id` so the record holds both also needs `secrets:UseSecret` on the secret, else `403`.
1020
1026
  */
1021
1027
  static updateAiProvider(options) {
1022
1028
  return (options.client ?? client).patch({
@@ -1099,7 +1105,7 @@ var ApiKeys = class {
1099
1105
  /**
1100
1106
  * Create an API key
1101
1107
  *
1102
- * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
1108
+ * Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped token** (an OAuth access token, a trigger run-as token or a run token), it returns `403 API_KEY_SCOPED_TOKEN`: such a token never creates a key. - When the request is authenticated with a **project-scoped API key**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential. - When the request is authenticated with an **API key narrowed by `policy_ids`**, the new key stays inside that boundary: omitting `policy_ids` inherits the caller's own, a non-empty subset of them is accepted, and an empty list or any other policy returns `403 API_KEY_POLICY_BOUNDARY`.
1103
1109
  *
1104
1110
  */
1105
1111
  static createApiKey(options) {
@@ -1137,7 +1143,7 @@ var ApiKeys = class {
1137
1143
  /**
1138
1144
  * Update an API key
1139
1145
  *
1140
- * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise).
1146
+ * Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it. An API key narrowed by `policy_ids` can only set `policy_ids` to a non-empty subset of its own (`403 API_KEY_POLICY_BOUNDARY` otherwise). A project-scoped token (OAuth, trigger or run) never updates a key (`403 API_KEY_SCOPED_TOKEN`).
1141
1147
  */
1142
1148
  static updateApiKey(options) {
1143
1149
  return (options.client ?? client).put({
@@ -3702,7 +3708,7 @@ var Playbooks = class {
3702
3708
  *
3703
3709
  * Creates a playbook at version 1. The definition is refused with `400 PLAYBOOK_VALIDATION_FAILED` when it holds a duplicate node or input, an input reading a missing node or field, an `execute` node without an executor or another kind with one, transformations on a non-final node, or a cycle; `meta.problems` lists every one. A duplicate `name` in the project is `409 NAME_CONFLICT`.
3704
3710
  *
3705
- * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
3711
+ * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). An executor cannot be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), nor a transformation's tool a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
3706
3712
  */
3707
3713
  static createPlaybook(options) {
3708
3714
  return (options.client ?? client).post({
@@ -3719,7 +3725,7 @@ var Playbooks = class {
3719
3725
  *
3720
3726
  * Answers what a create or update would be told about a definition, without writing: `valid`, and every graph problem it holds. A definition whose shape cannot be read is `400 VALIDATION_FAILED`, as on a write.
3721
3727
  *
3722
- * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
3728
+ * With `project_id`, the references are checked too, as a write there would check them: the upstreams against that project's playbooks, and each executor the caller may start must exist (`EXECUTOR_NOT_FOUND`) and name an action its `mcp` tool allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`) and not be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), and each transformation's tool must not be a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). The caller needs both `playbooks:ValidatePlaybook` and `playbooks:ListPlaybooks` on the project. Without it, only the definition's own graph is checked.
3723
3729
  */
3724
3730
  static validatePlaybook(options) {
3725
3731
  return (options.client ?? client).post({
@@ -3758,7 +3764,7 @@ var Playbooks = class {
3758
3764
  *
3759
3765
  * Updates any of `name`, `description` and `definition`. Only a change to `definition` archives a new version; a rename or a rewrite of the definition the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
3760
3766
  *
3761
- * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
3767
+ * A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `EXECUTOR_TOOL_UNSUPPORTED` for a `client` tool executor, `TRANSFORMATION_TOOL_UNSUPPORTED` for a `client` or `mcp` transformation tool, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
3762
3768
  */
3763
3769
  static updatePlaybook(options) {
3764
3770
  return (options.client ?? client).patch({
@@ -4149,7 +4155,7 @@ var Projects = class {
4149
4155
  *
4150
4156
  * Deletes a project. Requires admin role. Fails with `409` if the project has any dependent resource, unless `force=true` is passed, in which case those resources are deleted along with the project.
4151
4157
  *
4152
- * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared.
4158
+ * Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memory stores, secrets, files, guardrails, quotas, priced usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared. A deleted formation and a usage event with no cost go with the project.
4153
4159
  *
4154
4160
  */
4155
4161
  static deleteProject(options) {
@@ -4172,7 +4178,7 @@ var Projects = class {
4172
4178
  /**
4173
4179
  * Update a project
4174
4180
  *
4175
- * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
4181
+ * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires projects:UpdateProject on the project, which a project-scoped policy can grant. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
4176
4182
  */
4177
4183
  static updateProject(options) {
4178
4184
  return (options.client ?? client).patch({
@@ -5023,7 +5029,7 @@ var Triggers = class {
5023
5029
  /**
5024
5030
  * Create a trigger
5025
5031
  *
5026
- * Creates a new trigger for a project
5032
+ * Creates a new trigger for a project. A `{{secret:...}}` reference in `tool_context` also needs `secrets:UseSecret` on that secret, else `403`.
5027
5033
  */
5028
5034
  static createTrigger(options) {
5029
5035
  return (options.client ?? client).post({
@@ -5071,7 +5077,7 @@ var Triggers = class {
5071
5077
  /**
5072
5078
  * Update a trigger
5073
5079
  *
5074
- * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.
5080
+ * Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had. A `{{secret:...}}` reference in a written `tool_context`, or in the stored one when the target changes, also needs `secrets:UseSecret` on that secret, else `403`.
5075
5081
  *
5076
5082
  */
5077
5083
  static updateTrigger(options) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@soat/sdk",
3
- "version": "0.99.3",
3
+ "version": "0.101.0",
4
4
  "description": "TypeScript SDK for SOAT — open-source infrastructure for production-ready AI agents.",
5
5
  "keywords": [
6
6
  "ai-agents",