@naturali/sdk 0.120.2 → 0.120.3

package/dist/index.cjs

@@ -3271,7 +3271,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) {
@@ -4077,6 +4078,7 @@ var Tools = class {
 	* Directly invokes a tool and returns its output. Supported for `http`, `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 `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `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) {
@@ -4194,7 +4196,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
@@ -1291,6 +1291,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-Naturali-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.
    *
    */
@@ -1298,7 +1300,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;
@@ -2785,7 +2787,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?: {
@@ -3745,9 +3747,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;
@@ -4681,19 +4688,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;
@@ -5981,6 +5988,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.
    *
    */
@@ -5988,7 +5997,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;
@@ -6049,6 +6058,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-Naturali-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.
    *
    */
@@ -6056,7 +6067,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;
@@ -6816,7 +6827,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
      */
@@ -9026,7 +9037,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;
@@ -9047,7 +9058,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;
   /**
@@ -9055,7 +9066,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;
   /**
@@ -11445,7 +11456,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>;
   };
@@ -12764,6 +12775,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 = {
@@ -14128,7 +14143,7 @@ type ListIngestionRulesResponse = ListIngestionRulesResponses[keyof ListIngestio
 type CreateIngestionRuleData = {
   body: {
     /**
-     * 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;
     /**
@@ -14288,6 +14303,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;
@@ -14360,7 +14378,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;
     /**
@@ -20433,7 +20451,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>;
@@ -20845,6 +20864,7 @@ declare class Tools {
    * Directly invokes a tool and returns its output. Supported for `http`, `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 `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `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>;
@@ -20909,7 +20929,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
@@ -1291,6 +1291,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-Naturali-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.
    *
    */
@@ -1298,7 +1300,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;
@@ -2785,7 +2787,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?: {
@@ -3745,9 +3747,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;
@@ -4681,19 +4688,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;
@@ -5981,6 +5988,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.
    *
    */
@@ -5988,7 +5997,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;
@@ -6049,6 +6058,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-Naturali-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.
    *
    */
@@ -6056,7 +6067,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;
@@ -6816,7 +6827,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
      */
@@ -9026,7 +9037,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;
@@ -9047,7 +9058,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;
   /**
@@ -9055,7 +9066,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;
   /**
@@ -11445,7 +11456,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>;
   };
@@ -12764,6 +12775,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 = {
@@ -14128,7 +14143,7 @@ type ListIngestionRulesResponse = ListIngestionRulesResponses[keyof ListIngestio
 type CreateIngestionRuleData = {
   body: {
     /**
-     * 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;
     /**
@@ -14288,6 +14303,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;
@@ -14360,7 +14378,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;
     /**
@@ -20433,7 +20451,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>;
@@ -20845,6 +20864,7 @@ declare class Tools {
    * Directly invokes a tool and returns its output. Supported for `http`, `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 `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `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>;
@@ -20909,7 +20929,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

@@ -3270,7 +3270,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) {
@@ -4076,6 +4077,7 @@ var Tools = class {
 	* Directly invokes a tool and returns its output. Supported for `http`, `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 `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `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) {
@@ -4193,7 +4195,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": "@naturali/sdk",
-  "version": "0.120.2",
+  "version": "0.120.3",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "sideEffects": false,
@@ -37,7 +37,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/api": "0.120.2"
+    "@naturali/api": "0.120.3"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",