@soat/sdk 0.44.0 → 0.45.0

package/dist/index.cjs

@@ -1069,7 +1069,11 @@ var ApiKeys = class {
 	/**
 	* List API keys
 	*
-	* Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.
+	* Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns the caller's own
+	* keys scoped to that project, or every key scoped to it when the credential
+	* holds `api-keys:ListApiKeys` on the project. Confinement to a project is not
+	* authority over it, and a key's metadata names its owner, prefix and attached
+	* policies.
 	*
 	*/
 	static listApiKeys(options) {
@@ -2881,7 +2885,8 @@ var Orchestrations = class {
 	/**
 	* Get orchestration queue stats
 	*
-	* Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. A project-scoped caller sees only their own projects under `per_project`.
+	* Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`.
+	* Every figure is scoped to what the caller may see. A project-scoped caller gets `per_project` for their own projects only, `queue_depth` and `claimed_tasks` summed over those same projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.
 	*
 	*/
 	static getQueueStats(options) {
@@ -3747,6 +3752,7 @@ var Tools = class {
 	* Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input.
 	* For `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` ("not available on this tool") before any outbound request is made.
 	* `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.
+	* Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with `422 TOOL_DISPATCH_FAILED`, whose `meta` carries the `tool_id` and the `outcome`. A `pipeline` tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.
 	*
 	*/
 	static callTool(options) {
@@ -3864,7 +3870,8 @@ var Triggers = class {
 	/**
 	* Update a trigger
 	*
-	* Updates an existing trigger's configuration. The type is immutable.
+	* 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.
+	*
 	*/
 	static updateTrigger(options) {
 		return (options.client ?? client).patch({

package/dist/index.d.cts

@@ -340,7 +340,7 @@ type ActivityEntry = {
   /**
    * How the entry was produced
    */
-  kind?: 'action_executed' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
+  kind?: 'action_executed' | 'approval_created' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
   severity?: 'info' | 'warning' | 'critical';
   /**
    * One-line, human-readable description
@@ -2172,7 +2172,7 @@ type FormationTemplate = {
     [key: string]: ResourceDeclaration;
   };
   /**
-   * Map of output names to values. Values may use `{ "ref": "logicalId" }` to reference physical IDs of created resources, or `{ "param": "ParamName" }` and `{ "sub": "text ${ParamName}" }` to embed parameter values.
+   * Map of output names to values. Values may use `{ "ref": "logicalId" }` to reference physical IDs of created resources, or `{ "param": "ParamName" }` and `{ "sub": "text ${ParamName}" }` to embed parameter values. `{ "ref_attr": "LogicalId.attribute" }` resolves a named attribute of a created resource, except one carrying credential material — a trigger's or webhook's `secret` is refused with 400 VALIDATION_FAILED, since a formation is readable by anyone holding `formations:GetFormation`. Read those from the resource's own secret route instead.
    *
    */
   outputs?: {
@@ -3239,9 +3239,14 @@ type Formation = {
    * Human-readable formation name
    */
   name?: string;
+  /**
+   * The template as deployed. Credential-bearing properties — a `secret` resource's `value`, and any property a custom resource type declares `write_only` — read back as `{ "no_echo": true }` rather than the value that was supplied.
+   *
+   */
   template?: FormationTemplate;
   /**
-   * Resolved output values after stack deployment
+   * Resolved output values after stack deployment. An output that resolved a credential attribute on a formation deployed before those were refused is omitted.
+   *
    */
   outputs?: {
     [key: string]: string;
@@ -4281,19 +4286,19 @@ type QueueStats = {
    */
   driver?: 'postgres' | 'sqs';
   /**
-   * Tasks waiting to be claimed now (unclaimed and past their `available_at`). Backoff-delayed tasks are excluded.
+   * Tasks waiting to be claimed now (unclaimed and past their `available_at`). Backoff-delayed tasks are excluded. Summed over the caller's own projects when the caller is project-scoped.
    */
   queue_depth?: number;
   /**
-   * Tasks currently claimed with a valid (unexpired) lease.
+   * Tasks currently claimed with a valid (unexpired) lease. Summed over the caller's own projects when the caller is project-scoped.
    */
   claimed_tasks?: number;
   /**
-   * Age in seconds of the oldest claimable-now task, or `null` when none are waiting.
+   * Age in seconds of the oldest claimable-now task, or `null` when none are waiting. Also `null` for a project-scoped caller: the figure is deployment-wide.
    */
   oldest_queued_age_seconds?: number | null;
   /**
-   * Claim-latency percentiles (time from a task becoming available to being claimed) over a rolling in-process window. `p50`/`p95` are `null` when no claim happened in the window.
+   * Claim-latency percentiles (time from a task becoming available to being claimed) over a rolling in-process window. `p50`/`p95` are `null` when no claim happened in the window, and for a project-scoped caller: the window is deployment-wide.
    */
   claim_latency_ms?: {
     p50?: number | null;
@@ -5526,6 +5531,8 @@ type Tool = {
    *
    * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
    *
+   * A credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{"no_echo": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.
+   *
    * `headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in a prefixed context header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.
    *
    */
@@ -5533,7 +5540,7 @@ type Tool = {
     [key: string]: unknown;
   } | null;
   /**
-   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.
+   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.
    */
   mcp?: {
     [key: string]: unknown;
@@ -5610,6 +5617,8 @@ type CreateToolRequest = {
    *
    * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
    *
+   * A credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{"no_echo": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.
+   *
    * `headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.
    *
    */
@@ -5617,7 +5626,7 @@ type CreateToolRequest = {
     [key: string]: unknown;
   };
   /**
-   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.
+   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.
    */
   mcp?: {
     [key: string]: unknown;
@@ -5676,6 +5685,8 @@ type UpdateToolRequest = {
    *
    * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
    *
+   * A credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{"no_echo": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.
+   *
    * `headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.
    *
    */
@@ -5683,7 +5694,7 @@ type UpdateToolRequest = {
     [key: string]: unknown;
   } | null;
   /**
-   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.
+   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.
    */
   mcp?: {
     [key: string]: unknown;
@@ -6662,7 +6673,7 @@ type ListActivityData = {
     /**
      * Filter by activity kind
      */
-    kind?: 'action_executed' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
+    kind?: 'action_executed' | 'approval_created' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
     /**
      * Filter by severity
      */
@@ -8279,7 +8290,7 @@ type GetApprovalResponse = GetApprovalResponses[keyof GetApprovalResponses];
 type ApproveApprovalData = {
   body?: {
     /**
-     * Edited arguments to execute instead of the proposed ones
+     * Edited arguments to execute instead of the proposed ones. Editing composes a new call, so it additionally requires permission to make that call: `tools:CallTool` on the tool, and for a `builtin` proposal the action's own IAM action.
      */
     arguments?: {
       [key: string]: unknown;
@@ -8296,7 +8307,7 @@ type ApproveApprovalData = {
 };
 type ApproveApprovalErrors = {
   /**
-   * Edited arguments are not a JSON object
+   * Edited arguments are not a JSON object, or do not satisfy the tool's parameters schema
    */
   400: unknown;
   /**
@@ -8304,7 +8315,7 @@ type ApproveApprovalErrors = {
    */
   401: unknown;
   /**
-   * Forbidden
+   * Forbidden — including an edit by a caller who may resolve the item but not make the call it proposes
    */
   403: unknown;
   /**
@@ -9887,7 +9898,7 @@ type CreateEmbeddingsData = {
      */
     input?: string;
     /**
-     * Batch of texts to embed.
+     * Batch of texts to embed. At most 256 per request — each input is one call to the embedding model, so a larger batch is refused (`VALIDATION_FAILED`) rather than queued. Split it across requests.
      */
     inputs?: Array<string>;
   };
@@ -11112,6 +11123,10 @@ type UploadFileErrors = {
    * The project's `storage_bytes` quota is exceeded (`QUOTA_STORAGE_EXCEEDED`). Delete stored content, or raise the quota — no window reset clears a stored total, so no `Retry-After` is sent.
    */
   409: ErrorResponse;
+  /**
+   * The upload is over this deployment's byte ceiling (`UPLOAD_TOO_LARGE`; `FILE_UPLOAD_MAX_BYTES`, 25 MB by default). The request is refused while the body is still streaming, so nothing was stored.
+   */
+  413: ErrorResponse;
 };
 type UploadFileError = UploadFileErrors[keyof UploadFileErrors];
 type UploadFileResponses = {
@@ -11209,6 +11224,10 @@ type UploadFileWithTokenErrors = {
    * Upload token expired
    */
   410: ErrorResponse;
+  /**
+   * The upload is over this deployment's byte ceiling (`UPLOAD_TOO_LARGE`; `FILE_UPLOAD_MAX_BYTES`, 25 MB by default). The request is refused while the body is still streaming, so nothing was stored.
+   */
+  413: ErrorResponse;
 };
 type UploadFileWithTokenError = UploadFileWithTokenErrors[keyof UploadFileWithTokenErrors];
 type UploadFileWithTokenResponses = {
@@ -12421,7 +12440,7 @@ type CreateIngestionRuleData = {
      */
     project_id?: string;
     /**
-     * MIME type glob matched against a file's content_type
+     * MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters — a MIME glob needs one on each side of the slash at most.
      */
     content_type_glob: string;
     /**
@@ -12568,6 +12587,9 @@ type GetIngestionRuleResponses = {
 type GetIngestionRuleResponse = GetIngestionRuleResponses[keyof GetIngestionRuleResponses];
 type UpdateIngestionRuleData = {
   body: {
+    /**
+     * MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters.
+     */
     content_type_glob?: string;
     tool_id?: string | null;
     agent_id?: string | null;
@@ -12640,7 +12662,7 @@ type SearchKnowledgeData = {
      */
     min_score?: number;
     /**
-     * Maximum number of results to return (default 10)
+     * Maximum number of results to return (default 10). A value above 100 is clamped to 100 — the ceiling bounds the vector scan this one request performs, so a larger `limit` returns everything there is up to that many rows rather than being refused.
      */
     limit?: number;
     /**
@@ -17752,7 +17774,11 @@ declare class ApiKeys {
   /**
    * List API keys
    *
-   * Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.
+   * Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns the caller's own
+   * keys scoped to that project, or every key scoped to it when the credential
+   * holds `api-keys:ListApiKeys` on the project. Confinement to a project is not
+   * authority over it, and a key's metadata names its owner, prefix and attached
+   * policies.
    *
    */
   static listApiKeys<ThrowOnError extends boolean = false>(options?: Options<ListApiKeysData, ThrowOnError>): RequestResult<ListApiKeysResponses, ListApiKeysErrors, ThrowOnError>;
@@ -18686,7 +18712,8 @@ declare class Orchestrations {
   /**
    * Get orchestration queue stats
    *
-   * Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. A project-scoped caller sees only their own projects under `per_project`.
+   * Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`.
+   * Every figure is scoped to what the caller may see. A project-scoped caller gets `per_project` for their own projects only, `queue_depth` and `claimed_tasks` summed over those same projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.
    *
    */
   static getQueueStats<ThrowOnError extends boolean = false>(options?: Options<GetQueueStatsData, ThrowOnError>): RequestResult<GetQueueStatsResponses, GetQueueStatsErrors, ThrowOnError>;
@@ -19117,6 +19144,7 @@ declare class Tools {
    * Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input.
    * For `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` ("not available on this tool") before any outbound request is made.
    * `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.
+   * Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with `422 TOOL_DISPATCH_FAILED`, whose `meta` carries the `tool_id` and the `outcome`. A `pipeline` tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.
    *
    */
   static callTool<ThrowOnError extends boolean = false>(options: Options<CallToolData, ThrowOnError>): RequestResult<CallToolResponses, CallToolErrors, ThrowOnError>;
@@ -19181,7 +19209,8 @@ declare class Triggers {
   /**
    * Update a trigger
    *
-   * Updates an existing trigger's configuration. The type is immutable.
+   * 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.
+   *
    */
   static updateTrigger<ThrowOnError extends boolean = false>(options: Options<UpdateTriggerData, ThrowOnError>): RequestResult<UpdateTriggerResponses, UpdateTriggerErrors, ThrowOnError>;
   /**

package/dist/index.d.mts

@@ -340,7 +340,7 @@ type ActivityEntry = {
   /**
    * How the entry was produced
    */
-  kind?: 'action_executed' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
+  kind?: 'action_executed' | 'approval_created' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
   severity?: 'info' | 'warning' | 'critical';
   /**
    * One-line, human-readable description
@@ -2172,7 +2172,7 @@ type FormationTemplate = {
     [key: string]: ResourceDeclaration;
   };
   /**
-   * Map of output names to values. Values may use `{ "ref": "logicalId" }` to reference physical IDs of created resources, or `{ "param": "ParamName" }` and `{ "sub": "text ${ParamName}" }` to embed parameter values.
+   * Map of output names to values. Values may use `{ "ref": "logicalId" }` to reference physical IDs of created resources, or `{ "param": "ParamName" }` and `{ "sub": "text ${ParamName}" }` to embed parameter values. `{ "ref_attr": "LogicalId.attribute" }` resolves a named attribute of a created resource, except one carrying credential material — a trigger's or webhook's `secret` is refused with 400 VALIDATION_FAILED, since a formation is readable by anyone holding `formations:GetFormation`. Read those from the resource's own secret route instead.
    *
    */
   outputs?: {
@@ -3239,9 +3239,14 @@ type Formation = {
    * Human-readable formation name
    */
   name?: string;
+  /**
+   * The template as deployed. Credential-bearing properties — a `secret` resource's `value`, and any property a custom resource type declares `write_only` — read back as `{ "no_echo": true }` rather than the value that was supplied.
+   *
+   */
   template?: FormationTemplate;
   /**
-   * Resolved output values after stack deployment
+   * Resolved output values after stack deployment. An output that resolved a credential attribute on a formation deployed before those were refused is omitted.
+   *
    */
   outputs?: {
     [key: string]: string;
@@ -4281,19 +4286,19 @@ type QueueStats = {
    */
   driver?: 'postgres' | 'sqs';
   /**
-   * Tasks waiting to be claimed now (unclaimed and past their `available_at`). Backoff-delayed tasks are excluded.
+   * Tasks waiting to be claimed now (unclaimed and past their `available_at`). Backoff-delayed tasks are excluded. Summed over the caller's own projects when the caller is project-scoped.
    */
   queue_depth?: number;
   /**
-   * Tasks currently claimed with a valid (unexpired) lease.
+   * Tasks currently claimed with a valid (unexpired) lease. Summed over the caller's own projects when the caller is project-scoped.
    */
   claimed_tasks?: number;
   /**
-   * Age in seconds of the oldest claimable-now task, or `null` when none are waiting.
+   * Age in seconds of the oldest claimable-now task, or `null` when none are waiting. Also `null` for a project-scoped caller: the figure is deployment-wide.
    */
   oldest_queued_age_seconds?: number | null;
   /**
-   * Claim-latency percentiles (time from a task becoming available to being claimed) over a rolling in-process window. `p50`/`p95` are `null` when no claim happened in the window.
+   * Claim-latency percentiles (time from a task becoming available to being claimed) over a rolling in-process window. `p50`/`p95` are `null` when no claim happened in the window, and for a project-scoped caller: the window is deployment-wide.
    */
   claim_latency_ms?: {
     p50?: number | null;
@@ -5526,6 +5531,8 @@ type Tool = {
    *
    * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
    *
+   * A credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{"no_echo": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.
+   *
    * `headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in a prefixed context header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.
    *
    */
@@ -5533,7 +5540,7 @@ type Tool = {
     [key: string]: unknown;
   } | null;
   /**
-   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.
+   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.
    */
   mcp?: {
     [key: string]: unknown;
@@ -5610,6 +5617,8 @@ type CreateToolRequest = {
    *
    * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
    *
+   * A credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{"no_echo": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.
+   *
    * `headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.
    *
    */
@@ -5617,7 +5626,7 @@ type CreateToolRequest = {
     [key: string]: unknown;
   };
   /**
-   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.
+   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.
    */
   mcp?: {
     [key: string]: unknown;
@@ -5676,6 +5685,8 @@ type UpdateToolRequest = {
    *
    * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
    *
+   * A credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{"no_echo": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.
+   *
    * `headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.
    *
    */
@@ -5683,7 +5694,7 @@ type UpdateToolRequest = {
     [key: string]: unknown;
   } | null;
   /**
-   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.
+   * MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.
    */
   mcp?: {
     [key: string]: unknown;
@@ -6662,7 +6673,7 @@ type ListActivityData = {
     /**
      * Filter by activity kind
      */
-    kind?: 'action_executed' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
+    kind?: 'action_executed' | 'approval_created' | 'approval_resolved' | 'exception_created' | 'schedule_fired';
     /**
      * Filter by severity
      */
@@ -8279,7 +8290,7 @@ type GetApprovalResponse = GetApprovalResponses[keyof GetApprovalResponses];
 type ApproveApprovalData = {
   body?: {
     /**
-     * Edited arguments to execute instead of the proposed ones
+     * Edited arguments to execute instead of the proposed ones. Editing composes a new call, so it additionally requires permission to make that call: `tools:CallTool` on the tool, and for a `builtin` proposal the action's own IAM action.
      */
     arguments?: {
       [key: string]: unknown;
@@ -8296,7 +8307,7 @@ type ApproveApprovalData = {
 };
 type ApproveApprovalErrors = {
   /**
-   * Edited arguments are not a JSON object
+   * Edited arguments are not a JSON object, or do not satisfy the tool's parameters schema
    */
   400: unknown;
   /**
@@ -8304,7 +8315,7 @@ type ApproveApprovalErrors = {
    */
   401: unknown;
   /**
-   * Forbidden
+   * Forbidden — including an edit by a caller who may resolve the item but not make the call it proposes
    */
   403: unknown;
   /**
@@ -9887,7 +9898,7 @@ type CreateEmbeddingsData = {
      */
     input?: string;
     /**
-     * Batch of texts to embed.
+     * Batch of texts to embed. At most 256 per request — each input is one call to the embedding model, so a larger batch is refused (`VALIDATION_FAILED`) rather than queued. Split it across requests.
      */
     inputs?: Array<string>;
   };
@@ -11112,6 +11123,10 @@ type UploadFileErrors = {
    * The project's `storage_bytes` quota is exceeded (`QUOTA_STORAGE_EXCEEDED`). Delete stored content, or raise the quota — no window reset clears a stored total, so no `Retry-After` is sent.
    */
   409: ErrorResponse;
+  /**
+   * The upload is over this deployment's byte ceiling (`UPLOAD_TOO_LARGE`; `FILE_UPLOAD_MAX_BYTES`, 25 MB by default). The request is refused while the body is still streaming, so nothing was stored.
+   */
+  413: ErrorResponse;
 };
 type UploadFileError = UploadFileErrors[keyof UploadFileErrors];
 type UploadFileResponses = {
@@ -11209,6 +11224,10 @@ type UploadFileWithTokenErrors = {
    * Upload token expired
    */
   410: ErrorResponse;
+  /**
+   * The upload is over this deployment's byte ceiling (`UPLOAD_TOO_LARGE`; `FILE_UPLOAD_MAX_BYTES`, 25 MB by default). The request is refused while the body is still streaming, so nothing was stored.
+   */
+  413: ErrorResponse;
 };
 type UploadFileWithTokenError = UploadFileWithTokenErrors[keyof UploadFileWithTokenErrors];
 type UploadFileWithTokenResponses = {
@@ -12421,7 +12440,7 @@ type CreateIngestionRuleData = {
      */
     project_id?: string;
     /**
-     * MIME type glob matched against a file's content_type
+     * MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters — a MIME glob needs one on each side of the slash at most.
      */
     content_type_glob: string;
     /**
@@ -12568,6 +12587,9 @@ type GetIngestionRuleResponses = {
 type GetIngestionRuleResponse = GetIngestionRuleResponses[keyof GetIngestionRuleResponses];
 type UpdateIngestionRuleData = {
   body: {
+    /**
+     * MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters.
+     */
     content_type_glob?: string;
     tool_id?: string | null;
     agent_id?: string | null;
@@ -12640,7 +12662,7 @@ type SearchKnowledgeData = {
      */
     min_score?: number;
     /**
-     * Maximum number of results to return (default 10)
+     * Maximum number of results to return (default 10). A value above 100 is clamped to 100 — the ceiling bounds the vector scan this one request performs, so a larger `limit` returns everything there is up to that many rows rather than being refused.
      */
     limit?: number;
     /**
@@ -17752,7 +17774,11 @@ declare class ApiKeys {
   /**
    * List API keys
    *
-   * Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.
+   * Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns the caller's own
+   * keys scoped to that project, or every key scoped to it when the credential
+   * holds `api-keys:ListApiKeys` on the project. Confinement to a project is not
+   * authority over it, and a key's metadata names its owner, prefix and attached
+   * policies.
    *
    */
   static listApiKeys<ThrowOnError extends boolean = false>(options?: Options<ListApiKeysData, ThrowOnError>): RequestResult<ListApiKeysResponses, ListApiKeysErrors, ThrowOnError>;
@@ -18686,7 +18712,8 @@ declare class Orchestrations {
   /**
    * Get orchestration queue stats
    *
-   * Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. A project-scoped caller sees only their own projects under `per_project`.
+   * Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`.
+   * Every figure is scoped to what the caller may see. A project-scoped caller gets `per_project` for their own projects only, `queue_depth` and `claimed_tasks` summed over those same projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.
    *
    */
   static getQueueStats<ThrowOnError extends boolean = false>(options?: Options<GetQueueStatsData, ThrowOnError>): RequestResult<GetQueueStatsResponses, GetQueueStatsErrors, ThrowOnError>;
@@ -19117,6 +19144,7 @@ declare class Tools {
    * Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input.
    * For `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` ("not available on this tool") before any outbound request is made.
    * `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.
+   * Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with `422 TOOL_DISPATCH_FAILED`, whose `meta` carries the `tool_id` and the `outcome`. A `pipeline` tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.
    *
    */
   static callTool<ThrowOnError extends boolean = false>(options: Options<CallToolData, ThrowOnError>): RequestResult<CallToolResponses, CallToolErrors, ThrowOnError>;
@@ -19181,7 +19209,8 @@ declare class Triggers {
   /**
    * Update a trigger
    *
-   * Updates an existing trigger's configuration. The type is immutable.
+   * 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.
+   *
    */
   static updateTrigger<ThrowOnError extends boolean = false>(options: Options<UpdateTriggerData, ThrowOnError>): RequestResult<UpdateTriggerResponses, UpdateTriggerErrors, ThrowOnError>;
   /**

package/dist/index.mjs

@@ -1068,7 +1068,11 @@ var ApiKeys = class {
 	/**
 	* List API keys
 	*
-	* Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.
+	* Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns the caller's own
+	* keys scoped to that project, or every key scoped to it when the credential
+	* holds `api-keys:ListApiKeys` on the project. Confinement to a project is not
+	* authority over it, and a key's metadata names its owner, prefix and attached
+	* policies.
 	*
 	*/
 	static listApiKeys(options) {
@@ -2880,7 +2884,8 @@ var Orchestrations = class {
 	/**
 	* Get orchestration queue stats
 	*
-	* Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. A project-scoped caller sees only their own projects under `per_project`.
+	* Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`.
+	* Every figure is scoped to what the caller may see. A project-scoped caller gets `per_project` for their own projects only, `queue_depth` and `claimed_tasks` summed over those same projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.
 	*
 	*/
 	static getQueueStats(options) {
@@ -3746,6 +3751,7 @@ var Tools = class {
 	* Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input.
 	* For `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` ("not available on this tool") before any outbound request is made.
 	* `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.
+	* Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with `422 TOOL_DISPATCH_FAILED`, whose `meta` carries the `tool_id` and the `outcome`. A `pipeline` tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.
 	*
 	*/
 	static callTool(options) {
@@ -3863,7 +3869,8 @@ var Triggers = class {
 	/**
 	* Update a trigger
 	*
-	* Updates an existing trigger's configuration. The type is immutable.
+	* 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.
+	*
 	*/
 	static updateTrigger(options) {
 		return (options.client ?? client).patch({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/sdk",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "TypeScript SDK for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",