@naturali/sdk 0.78.5 → 0.79.0

package/dist/index.cjs

@@ -3122,7 +3122,9 @@ var Orchestrations = class {
 	/**
 	* List orchestration runs
 	*
-	* Returns orchestration runs the caller can access, optionally filtered by orchestration.
+	* Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+	*
+	* Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.
 	*/
 	static listOrchestrationRuns(options) {
 		return (options.client ?? client).get({
@@ -3772,7 +3774,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 merged with the caller-supplied `input` before execution; preset keys take lower precedence.
+	* `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.
 	*
 	*/
 	static callTool(options) {

package/dist/index.d.cts

@@ -1125,7 +1125,9 @@ type CreateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.
+   * Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.
+   *
+   * Values accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -2398,6 +2400,12 @@ type EvalRun = {
   item_count?: number;
   completed_count?: number;
   errored_count?: number;
+  /**
+   * The caller-owned key/value metadata supplied when the run was started, returned verbatim. Null when the run was started without any (a trigger-started run included — see `trigger_id` for that provenance). The server writes nothing here.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   started_at?: Date | null;
   finished_at?: Date | null;
   created_at?: Date;
@@ -2435,7 +2443,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -3770,6 +3778,20 @@ type OrchestrationRun = {
   tool_context?: {
     [key: string]: string;
   } | null;
+  /**
+   * The caller-owned key/value metadata supplied at run creation, returned verbatim. Null when the run was started without any. The server writes nothing here and no key is reserved; the bag is never merged into `state`, so nothing in it reaches the graph.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
+  /**
+   * The run whose node started this one — set only on a child a `loop` or `sub_orchestration` node spawned, null for a run a caller started. A child is its own run with its own usage events, so this is what makes a delegated run's spend attributable to the run that ordered it.
+   */
+  parent_orchestration_run_id?: string | null;
+  /**
+   * The node within `parent_orchestration_run_id` that started this run. Null when `parent_orchestration_run_id` is null.
+   */
+  parent_node_id?: string | null;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -3781,9 +3803,17 @@ type OrchestrationRun = {
    */
   node_executions?: Array<NodeExecution>;
   /**
-   * Usage roll-up (token counts and cost_usd) summed across every metered generation the run produced. Present on the single-run read; omitted from run list responses.
+   * What the run cost: token counts and `cost_usd` summed across every metered generation it produced **and every run it started** through `loop` / `sub_orchestration` nodes, at any depth. Present on the single-run read; omitted from run list responses.
+   *
+   * A nested child is a run record of its own, so this figure spans several of them. Two consequences: summing `usage` across a list that mixes parents and children double-counts (filter with `nested=false`), and the per-event receipt at `/v1/projects/{project_id}/usage/receipt` stays scoped to one run — its line items carry a `node_id` from one graph only.
    */
   usage?: RunUsageTotals;
+  /**
+   * The same roll-up restricted to **this run's own nodes**, excluding every nested run it started. Equal to `usage` for a run with no children; below it for a run that delegates. Present on the single-run read; omitted from run list responses.
+   *
+   * This is the field to read to see where cost sits in a run tree — own versus subtree — without walking the children.
+   */
+  usage_own?: RunUsageTotals;
   required_action?: RequiredAction | null;
   started_at?: Date | null;
   completed_at?: Date | null;
@@ -3908,6 +3938,16 @@ type StartRunRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read.
+   *
+   * The bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own `input` and accumulated `state`) lives in its own top-level field and cannot be written from here.
+   *
+   * It is **not** merged into run state: no graph node sees it, and an `input_schema` never has to tolerate it — which is what makes it the place for an infrastructural label, rather than `input`. Keys are never transformed. It is not inherited by the child runs a `loop` or `sub_orchestration` node starts; each child carries whatever the graph gives it, which today is nothing.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
   /**
    * When true, block until the run reaches a terminal (succeeded/failed) or awaiting_input state and return the settled run. When false (default), return immediately with status "queued" and execute the run in the background.
    */
@@ -4419,6 +4459,12 @@ type Task = {
   payload?: {
     [key: string]: unknown;
   };
+  /**
+   * The caller-owned key/value metadata supplied when the task was created, returned verbatim. Null when the task was created without any. Unlike `payload` it is invisible to guards and to `payload_writes`, so it is the place for an attribution label rather than task data.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   /**
    * Server-owned. The result of the current state's last completed dispatch, overwritten on every dispatch. Read-only — exposed to transition guards and `on_complete`/`payload_writes` expressions as `task.last_result`, a namespace a caller cannot write.
    */
@@ -4498,6 +4544,16 @@ type CreateTaskRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own).
+   *
+   * The bag is caller-owned and no key is reserved: everything the engine decides about a task (`state`, `status`, `workflow_version`, `last_result`, `active_dispatch`, the automation fields) is a field of its own and cannot be written from here.
+   *
+   * Prefer this over `payload` for anything that is not task data: `payload` is read by every guard as `task.payload` and may be written by the workflow's declared `payload_writes`, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with `400 VALIDATION_FAILED` and no task is created.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
 };
 type UpdateTaskRequest = {
   title?: string;
@@ -4584,7 +4640,9 @@ type Tool = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.
+   * Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.
+   *
+   * Values accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -4650,7 +4708,9 @@ type UpdateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.
+   * Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.
+   *
+   * Values accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -4679,7 +4739,7 @@ type CallToolRequest = {
    */
   action?: string;
   /**
-   * Input parameters for the tool call. These are merged with the tool's `preset_parameters` before execution (caller-supplied values take precedence).
+   * Input parameters for the tool call. These are merged with the tool's `preset_parameters` before execution; a preset value wins over the same key sent here.
    *
    */
   input?: {
@@ -4795,7 +4855,7 @@ type Trigger = {
   project_id?: string;
   name?: string;
   description?: string | null;
-  type?: 'manual' | 'webhook' | 'schedule';
+  type?: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
   /**
    * Public ID of the target resource (orchestration, agent, tool, or eval)
@@ -4815,6 +4875,10 @@ type Trigger = {
    * 5-field cron expression (UTC). Present only for schedule triggers
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern. Present only for event triggers: `*`, `prefix.*`, or an exact event name
+   */
+  event_pattern?: string | null;
   active?: boolean;
   /**
    * Optional boundary policy that further restricts firings
@@ -4836,7 +4900,7 @@ type TriggerWithSecret = Trigger & {
 type CreateTriggerRequest = {
   name: string;
   description?: string;
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type: 'orchestration' | 'agent' | 'tool' | 'eval';
   target_id: string;
   /**
@@ -4850,6 +4914,10 @@ type CreateTriggerRequest = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string;
+  /**
+   * Internal-event subscription pattern. Required when type is event, rejected otherwise. `*` matches every event, `prefix.*` a namespace, or give an exact event name such as `documents.ingested`
+   */
+  event_pattern?: string;
   active?: boolean;
   policy_id?: string;
 };
@@ -4863,6 +4931,7 @@ type UpdateTriggerRequest = {
     [key: string]: unknown;
   } | null;
   cron?: string | null;
+  event_pattern?: string | null;
   active?: boolean;
   policy_id?: string | null;
 };
@@ -4881,7 +4950,7 @@ type TriggerFiring = {
   id?: string;
   trigger_id?: string;
   project_id?: string;
-  source?: 'manual' | 'webhook' | 'schedule';
+  source?: 'manual' | 'webhook' | 'schedule' | 'event';
   status?: 'pending' | 'running' | 'succeeded' | 'failed';
   input?: {
     [key: string]: unknown;
@@ -10398,6 +10467,14 @@ type StartEvalRunData = {
      * A terminal run of the same eval to compare against. The finished run's `aggregate_scores.baseline` reports per-scorer deltas over the item intersection. A run of a different eval is rejected with 400.
      */
     baseline_run_id?: string | null;
+    /**
+     * Caller-supplied key/value metadata attached to the run record for attribution — what this measurement was of (the commit or release candidate being scored, the CI job that asked for it). Round-trips verbatim on every read of the run, the list included.
+     *
+     * The bag is caller-owned and no key is reserved: everything the platform decides about a run (`status`, `agent_version`, `baseline_run_id`, `aggregate_scores`, `passed`, the counts) is a field of its own and cannot be written from here. Nothing in the scoring path reads it. A non-object is rejected with `400 VALIDATION_FAILED` and no run is created.
+     */
+    metadata?: {
+      [key: string]: unknown;
+    };
   };
   path: {
     /**
@@ -10603,7 +10680,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -13444,6 +13521,16 @@ type ListOrchestrationRunsData = {
      * Filter by orchestration public ID (orch_...)
      */
     orchestration_id?: string;
+    /**
+     * Filter to the runs one specific parent run's `loop` / `sub_orchestration` nodes started (run_...). This is how a caller holding a parent names the individual children behind its `usage`.
+     */
+    parent_orchestration_run_id?: string;
+    /**
+     * Filter by whether the run was started by another run. `false` returns only the runs a caller started (no parent), which is the set to sum `usage` over; `true` returns only the runs a `loop` / `sub_orchestration` node started, across every parent. Omit to return both.
+     *
+     * Contradicting `parent_orchestration_run_id` with `nested=false` is a `400`; any value other than `true` or `false` is a `400`.
+     */
+    nested?: boolean;
     /**
      * Maximum number of results to return
      */
@@ -13490,7 +13577,7 @@ type StartOrchestrationRunData = {
 };
 type StartOrchestrationRunErrors = {
   /**
-   * Validation error
+   * Validation error (e.g. a `tool_context` key that cannot become a header, or `metadata` that is not a JSON object). No run is created.
    */
   400: unknown;
   /**
@@ -15615,7 +15702,7 @@ type ListTriggersData = {
     project_id: string;
   };
   query?: {
-    type?: 'manual' | 'webhook' | 'schedule';
+    type?: 'manual' | 'webhook' | 'schedule' | 'event';
     target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
     /**
      * Maximum number of results to return
@@ -17978,7 +18065,9 @@ declare class Orchestrations {
   /**
    * List orchestration runs
    *
-   * Returns orchestration runs the caller can access, optionally filtered by orchestration.
+   * Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+   *
+   * Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.
    */
   static listOrchestrationRuns<ThrowOnError extends boolean = false>(options: Options<ListOrchestrationRunsData, ThrowOnError>): RequestResult<ListOrchestrationRunsResponses, ListOrchestrationRunsErrors, ThrowOnError>;
   /**
@@ -18304,7 +18393,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 merged with the caller-supplied `input` before execution; preset keys take lower precedence.
+   * `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.
    *
    */
   static callTool<ThrowOnError extends boolean = false>(options: Options<CallToolData, ThrowOnError>): RequestResult<CallToolResponses, CallToolErrors, ThrowOnError>;

package/dist/index.d.mts

@@ -1125,7 +1125,9 @@ type CreateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.
+   * Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.
+   *
+   * Values accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -2398,6 +2400,12 @@ type EvalRun = {
   item_count?: number;
   completed_count?: number;
   errored_count?: number;
+  /**
+   * The caller-owned key/value metadata supplied when the run was started, returned verbatim. Null when the run was started without any (a trigger-started run included — see `trigger_id` for that provenance). The server writes nothing here.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   started_at?: Date | null;
   finished_at?: Date | null;
   created_at?: Date;
@@ -2435,7 +2443,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -3770,6 +3778,20 @@ type OrchestrationRun = {
   tool_context?: {
     [key: string]: string;
   } | null;
+  /**
+   * The caller-owned key/value metadata supplied at run creation, returned verbatim. Null when the run was started without any. The server writes nothing here and no key is reserved; the bag is never merged into `state`, so nothing in it reaches the graph.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
+  /**
+   * The run whose node started this one — set only on a child a `loop` or `sub_orchestration` node spawned, null for a run a caller started. A child is its own run with its own usage events, so this is what makes a delegated run's spend attributable to the run that ordered it.
+   */
+  parent_orchestration_run_id?: string | null;
+  /**
+   * The node within `parent_orchestration_run_id` that started this run. Null when `parent_orchestration_run_id` is null.
+   */
+  parent_node_id?: string | null;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -3781,9 +3803,17 @@ type OrchestrationRun = {
    */
   node_executions?: Array<NodeExecution>;
   /**
-   * Usage roll-up (token counts and cost_usd) summed across every metered generation the run produced. Present on the single-run read; omitted from run list responses.
+   * What the run cost: token counts and `cost_usd` summed across every metered generation it produced **and every run it started** through `loop` / `sub_orchestration` nodes, at any depth. Present on the single-run read; omitted from run list responses.
+   *
+   * A nested child is a run record of its own, so this figure spans several of them. Two consequences: summing `usage` across a list that mixes parents and children double-counts (filter with `nested=false`), and the per-event receipt at `/v1/projects/{project_id}/usage/receipt` stays scoped to one run — its line items carry a `node_id` from one graph only.
    */
   usage?: RunUsageTotals;
+  /**
+   * The same roll-up restricted to **this run's own nodes**, excluding every nested run it started. Equal to `usage` for a run with no children; below it for a run that delegates. Present on the single-run read; omitted from run list responses.
+   *
+   * This is the field to read to see where cost sits in a run tree — own versus subtree — without walking the children.
+   */
+  usage_own?: RunUsageTotals;
   required_action?: RequiredAction | null;
   started_at?: Date | null;
   completed_at?: Date | null;
@@ -3908,6 +3938,16 @@ type StartRunRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read.
+   *
+   * The bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own `input` and accumulated `state`) lives in its own top-level field and cannot be written from here.
+   *
+   * It is **not** merged into run state: no graph node sees it, and an `input_schema` never has to tolerate it — which is what makes it the place for an infrastructural label, rather than `input`. Keys are never transformed. It is not inherited by the child runs a `loop` or `sub_orchestration` node starts; each child carries whatever the graph gives it, which today is nothing.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
   /**
    * When true, block until the run reaches a terminal (succeeded/failed) or awaiting_input state and return the settled run. When false (default), return immediately with status "queued" and execute the run in the background.
    */
@@ -4419,6 +4459,12 @@ type Task = {
   payload?: {
     [key: string]: unknown;
   };
+  /**
+   * The caller-owned key/value metadata supplied when the task was created, returned verbatim. Null when the task was created without any. Unlike `payload` it is invisible to guards and to `payload_writes`, so it is the place for an attribution label rather than task data.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   /**
    * Server-owned. The result of the current state's last completed dispatch, overwritten on every dispatch. Read-only — exposed to transition guards and `on_complete`/`payload_writes` expressions as `task.last_result`, a namespace a caller cannot write.
    */
@@ -4498,6 +4544,16 @@ type CreateTaskRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own).
+   *
+   * The bag is caller-owned and no key is reserved: everything the engine decides about a task (`state`, `status`, `workflow_version`, `last_result`, `active_dispatch`, the automation fields) is a field of its own and cannot be written from here.
+   *
+   * Prefer this over `payload` for anything that is not task data: `payload` is read by every guard as `task.payload` and may be written by the workflow's declared `payload_writes`, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with `400 VALIDATION_FAILED` and no task is created.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
 };
 type UpdateTaskRequest = {
   title?: string;
@@ -4584,7 +4640,9 @@ type Tool = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.
+   * Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.
+   *
+   * Values accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -4650,7 +4708,9 @@ type UpdateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.
+   * Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.
+   *
+   * Values accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -4679,7 +4739,7 @@ type CallToolRequest = {
    */
   action?: string;
   /**
-   * Input parameters for the tool call. These are merged with the tool's `preset_parameters` before execution (caller-supplied values take precedence).
+   * Input parameters for the tool call. These are merged with the tool's `preset_parameters` before execution; a preset value wins over the same key sent here.
    *
    */
   input?: {
@@ -4795,7 +4855,7 @@ type Trigger = {
   project_id?: string;
   name?: string;
   description?: string | null;
-  type?: 'manual' | 'webhook' | 'schedule';
+  type?: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
   /**
    * Public ID of the target resource (orchestration, agent, tool, or eval)
@@ -4815,6 +4875,10 @@ type Trigger = {
    * 5-field cron expression (UTC). Present only for schedule triggers
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern. Present only for event triggers: `*`, `prefix.*`, or an exact event name
+   */
+  event_pattern?: string | null;
   active?: boolean;
   /**
    * Optional boundary policy that further restricts firings
@@ -4836,7 +4900,7 @@ type TriggerWithSecret = Trigger & {
 type CreateTriggerRequest = {
   name: string;
   description?: string;
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type: 'orchestration' | 'agent' | 'tool' | 'eval';
   target_id: string;
   /**
@@ -4850,6 +4914,10 @@ type CreateTriggerRequest = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string;
+  /**
+   * Internal-event subscription pattern. Required when type is event, rejected otherwise. `*` matches every event, `prefix.*` a namespace, or give an exact event name such as `documents.ingested`
+   */
+  event_pattern?: string;
   active?: boolean;
   policy_id?: string;
 };
@@ -4863,6 +4931,7 @@ type UpdateTriggerRequest = {
     [key: string]: unknown;
   } | null;
   cron?: string | null;
+  event_pattern?: string | null;
   active?: boolean;
   policy_id?: string | null;
 };
@@ -4881,7 +4950,7 @@ type TriggerFiring = {
   id?: string;
   trigger_id?: string;
   project_id?: string;
-  source?: 'manual' | 'webhook' | 'schedule';
+  source?: 'manual' | 'webhook' | 'schedule' | 'event';
   status?: 'pending' | 'running' | 'succeeded' | 'failed';
   input?: {
     [key: string]: unknown;
@@ -10398,6 +10467,14 @@ type StartEvalRunData = {
      * A terminal run of the same eval to compare against. The finished run's `aggregate_scores.baseline` reports per-scorer deltas over the item intersection. A run of a different eval is rejected with 400.
      */
     baseline_run_id?: string | null;
+    /**
+     * Caller-supplied key/value metadata attached to the run record for attribution — what this measurement was of (the commit or release candidate being scored, the CI job that asked for it). Round-trips verbatim on every read of the run, the list included.
+     *
+     * The bag is caller-owned and no key is reserved: everything the platform decides about a run (`status`, `agent_version`, `baseline_run_id`, `aggregate_scores`, `passed`, the counts) is a field of its own and cannot be written from here. Nothing in the scoring path reads it. A non-object is rejected with `400 VALIDATION_FAILED` and no run is created.
+     */
+    metadata?: {
+      [key: string]: unknown;
+    };
   };
   path: {
     /**
@@ -10603,7 +10680,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -13444,6 +13521,16 @@ type ListOrchestrationRunsData = {
      * Filter by orchestration public ID (orch_...)
      */
     orchestration_id?: string;
+    /**
+     * Filter to the runs one specific parent run's `loop` / `sub_orchestration` nodes started (run_...). This is how a caller holding a parent names the individual children behind its `usage`.
+     */
+    parent_orchestration_run_id?: string;
+    /**
+     * Filter by whether the run was started by another run. `false` returns only the runs a caller started (no parent), which is the set to sum `usage` over; `true` returns only the runs a `loop` / `sub_orchestration` node started, across every parent. Omit to return both.
+     *
+     * Contradicting `parent_orchestration_run_id` with `nested=false` is a `400`; any value other than `true` or `false` is a `400`.
+     */
+    nested?: boolean;
     /**
      * Maximum number of results to return
      */
@@ -13490,7 +13577,7 @@ type StartOrchestrationRunData = {
 };
 type StartOrchestrationRunErrors = {
   /**
-   * Validation error
+   * Validation error (e.g. a `tool_context` key that cannot become a header, or `metadata` that is not a JSON object). No run is created.
    */
   400: unknown;
   /**
@@ -15615,7 +15702,7 @@ type ListTriggersData = {
     project_id: string;
   };
   query?: {
-    type?: 'manual' | 'webhook' | 'schedule';
+    type?: 'manual' | 'webhook' | 'schedule' | 'event';
     target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
     /**
      * Maximum number of results to return
@@ -17978,7 +18065,9 @@ declare class Orchestrations {
   /**
    * List orchestration runs
    *
-   * Returns orchestration runs the caller can access, optionally filtered by orchestration.
+   * Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+   *
+   * Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.
    */
   static listOrchestrationRuns<ThrowOnError extends boolean = false>(options: Options<ListOrchestrationRunsData, ThrowOnError>): RequestResult<ListOrchestrationRunsResponses, ListOrchestrationRunsErrors, ThrowOnError>;
   /**
@@ -18304,7 +18393,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 merged with the caller-supplied `input` before execution; preset keys take lower precedence.
+   * `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.
    *
    */
   static callTool<ThrowOnError extends boolean = false>(options: Options<CallToolData, ThrowOnError>): RequestResult<CallToolResponses, CallToolErrors, ThrowOnError>;

package/dist/index.mjs

@@ -3121,7 +3121,9 @@ var Orchestrations = class {
 	/**
 	* List orchestration runs
 	*
-	* Returns orchestration runs the caller can access, optionally filtered by orchestration.
+	* Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+	*
+	* Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.
 	*/
 	static listOrchestrationRuns(options) {
 		return (options.client ?? client).get({
@@ -3771,7 +3773,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 merged with the caller-supplied `input` before execution; preset keys take lower precedence.
+	* `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.
 	*
 	*/
 	static callTool(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.78.5",
+  "version": "0.79.0",
   "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.78.5"
+    "@naturali/api": "0.79.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",