@soat/sdk 0.30.1 → 0.32.0

package/dist/index.cjs

@@ -3655,7 +3655,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 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

@@ -1879,6 +1879,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;
@@ -1916,7 +1922,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
    */
@@ -2684,7 +2690,7 @@ type WebhookResourceProperties = {
   events: Array<string>;
 };
 /**
- * Binds a starter (manual, webhook, or schedule) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
+ * Binds a starter (manual, webhook, schedule, or event) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
  */
 type TriggerResourceProperties = {
   /**
@@ -2698,7 +2704,7 @@ type TriggerResourceProperties = {
   /**
    * Starter type. Immutable after creation
    */
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   /**
    * The kind of resource this trigger activates
    */
@@ -2721,6 +2727,10 @@ type TriggerResourceProperties = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern (`*`, `prefix.*`, or an exact event name). Required when type is event, rejected otherwise
+   */
+  event_pattern?: string | null;
   /**
    * Whether the trigger fires (default true)
    */
@@ -3095,9 +3105,12 @@ type GuardrailResourceProperties = {
 };
 type ResourceDeclaration = {
   /**
-   * Resource type
+   * Resource type. The built-in types are `ai_provider`, `tool`, `agent`, `actor`, `api_key`, `chat`, `conversation`, `dataset`, `dataset_item`, `document`, `file`, `guardrail`, `ingestion_rule`, `memory`, `memory_entry`, `model_route`, `eval`, `orchestration`, `policy`, `project_price`, `quota`, `secret`, `session`, `webhook`, `trigger` and `workflow`.
+   *
+   * This is deliberately not an enum: a deployment operator can register additional resource types backed by their own handler, and those are declared here exactly like a built-in one. The set a given deployment accepts is authoritative in the server, which rejects an unregistered type with `VALIDATION_FAILED` and lists what it does support.
+   *
    */
-  type: 'ai_provider' | 'tool' | 'agent' | 'actor' | 'api_key' | 'chat' | 'conversation' | 'dataset' | 'dataset_item' | 'document' | 'file' | 'guardrail' | 'ingestion_rule' | 'memory' | 'memory_entry' | 'model_route' | 'eval' | 'orchestration' | 'policy' | 'project_price' | 'quota' | 'secret' | 'session' | 'webhook' | 'trigger' | 'workflow';
+  type: string;
   /**
    * Resource properties, as authored in the template and echoed back verbatim. The allowed fields, required fields, and field types for each resource `type` are defined by the corresponding `<Type>ResourceProperties` schema in this document (e.g. `model_route` → `ModelRouteResourceProperties`), which the server enforces at validate/deploy time. The declaration itself is free-form here because property values may be substitution expressions rather than final values: `{ "ref": "logicalId" }` references another resource's physical ID, `{ "param": "ParamName" }` substitutes a parameter value, and `{ "sub": "text ${ParamName}" }` interpolates parameters into a string.
    *
@@ -4574,6 +4587,12 @@ 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;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -4712,6 +4731,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.
    */
@@ -5155,6 +5184,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.
    */
@@ -5235,6 +5270,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;
@@ -5321,7 +5366,7 @@ type Tool = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every builtin 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.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -5403,7 +5448,7 @@ type CreateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every builtin 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.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -5467,7 +5512,7 @@ type UpdateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every builtin 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.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -5496,7 +5541,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?: {
@@ -5612,7 +5657,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)
@@ -5632,6 +5677,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
@@ -5657,7 +5706,7 @@ type CreateTriggerRequest = {
   project_id?: string;
   name: string;
   description?: string;
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type: 'orchestration' | 'agent' | 'tool' | 'eval';
   target_id: string;
   /**
@@ -5671,6 +5720,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;
 };
@@ -5684,6 +5737,7 @@ type UpdateTriggerRequest = {
     [key: string]: unknown;
   } | null;
   cron?: string | null;
+  event_pattern?: string | null;
   active?: boolean;
   policy_id?: string | null;
 };
@@ -5702,7 +5756,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;
@@ -5991,6 +6045,11 @@ type UsageReceipt = {
     meter_type?: string;
     provider?: string;
     model?: string;
+    /**
+     * Orchestration node that produced the event. On a run receipt every line carries it — an `agent` node's `llm_tokens` line and the `compute_execution` line of each node execution alike — so grouping the lines by `node_id` gives the per-node cost the receipt total alone hides. A retried node contributes one line per attempt, all under the same `node_id` — the event records no attempt number — which is the intended reading for spend: a retry is real money. Null when no node produced the event (a standalone generation, a run-level meter).
+     *
+     */
+    node_id?: string | null;
     cost_usd?: number | null;
     components?: Array<UsageComponent>;
   }>;
@@ -10226,6 +10285,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: {
     /**
@@ -10414,7 +10481,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
      */
@@ -13304,7 +13371,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;
   /**
@@ -15447,7 +15514,7 @@ type ListTriggersData = {
   path?: never;
   query?: {
     project_id?: string;
-    type?: 'manual' | 'webhook' | 'schedule';
+    type?: 'manual' | 'webhook' | 'schedule' | 'event';
     target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
     /**
      * Maximum number of results to return
@@ -18459,7 +18526,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 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

@@ -1879,6 +1879,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;
@@ -1916,7 +1922,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
    */
@@ -2684,7 +2690,7 @@ type WebhookResourceProperties = {
   events: Array<string>;
 };
 /**
- * Binds a starter (manual, webhook, or schedule) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
+ * Binds a starter (manual, webhook, schedule, or event) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
  */
 type TriggerResourceProperties = {
   /**
@@ -2698,7 +2704,7 @@ type TriggerResourceProperties = {
   /**
    * Starter type. Immutable after creation
    */
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   /**
    * The kind of resource this trigger activates
    */
@@ -2721,6 +2727,10 @@ type TriggerResourceProperties = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern (`*`, `prefix.*`, or an exact event name). Required when type is event, rejected otherwise
+   */
+  event_pattern?: string | null;
   /**
    * Whether the trigger fires (default true)
    */
@@ -3095,9 +3105,12 @@ type GuardrailResourceProperties = {
 };
 type ResourceDeclaration = {
   /**
-   * Resource type
+   * Resource type. The built-in types are `ai_provider`, `tool`, `agent`, `actor`, `api_key`, `chat`, `conversation`, `dataset`, `dataset_item`, `document`, `file`, `guardrail`, `ingestion_rule`, `memory`, `memory_entry`, `model_route`, `eval`, `orchestration`, `policy`, `project_price`, `quota`, `secret`, `session`, `webhook`, `trigger` and `workflow`.
+   *
+   * This is deliberately not an enum: a deployment operator can register additional resource types backed by their own handler, and those are declared here exactly like a built-in one. The set a given deployment accepts is authoritative in the server, which rejects an unregistered type with `VALIDATION_FAILED` and lists what it does support.
+   *
    */
-  type: 'ai_provider' | 'tool' | 'agent' | 'actor' | 'api_key' | 'chat' | 'conversation' | 'dataset' | 'dataset_item' | 'document' | 'file' | 'guardrail' | 'ingestion_rule' | 'memory' | 'memory_entry' | 'model_route' | 'eval' | 'orchestration' | 'policy' | 'project_price' | 'quota' | 'secret' | 'session' | 'webhook' | 'trigger' | 'workflow';
+  type: string;
   /**
    * Resource properties, as authored in the template and echoed back verbatim. The allowed fields, required fields, and field types for each resource `type` are defined by the corresponding `<Type>ResourceProperties` schema in this document (e.g. `model_route` → `ModelRouteResourceProperties`), which the server enforces at validate/deploy time. The declaration itself is free-form here because property values may be substitution expressions rather than final values: `{ "ref": "logicalId" }` references another resource's physical ID, `{ "param": "ParamName" }` substitutes a parameter value, and `{ "sub": "text ${ParamName}" }` interpolates parameters into a string.
    *
@@ -4574,6 +4587,12 @@ 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;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -4712,6 +4731,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.
    */
@@ -5155,6 +5184,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.
    */
@@ -5235,6 +5270,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;
@@ -5321,7 +5366,7 @@ type Tool = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every builtin 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.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -5403,7 +5448,7 @@ type CreateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every builtin 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.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -5467,7 +5512,7 @@ type UpdateToolRequest = {
    */
   context_keys?: Array<string> | null;
   /**
-   * Fixed parameters merged into every builtin 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.
    */
   preset_parameters?: {
     [key: string]: unknown;
@@ -5496,7 +5541,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?: {
@@ -5612,7 +5657,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)
@@ -5632,6 +5677,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
@@ -5657,7 +5706,7 @@ type CreateTriggerRequest = {
   project_id?: string;
   name: string;
   description?: string;
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type: 'orchestration' | 'agent' | 'tool' | 'eval';
   target_id: string;
   /**
@@ -5671,6 +5720,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;
 };
@@ -5684,6 +5737,7 @@ type UpdateTriggerRequest = {
     [key: string]: unknown;
   } | null;
   cron?: string | null;
+  event_pattern?: string | null;
   active?: boolean;
   policy_id?: string | null;
 };
@@ -5702,7 +5756,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;
@@ -5991,6 +6045,11 @@ type UsageReceipt = {
     meter_type?: string;
     provider?: string;
     model?: string;
+    /**
+     * Orchestration node that produced the event. On a run receipt every line carries it — an `agent` node's `llm_tokens` line and the `compute_execution` line of each node execution alike — so grouping the lines by `node_id` gives the per-node cost the receipt total alone hides. A retried node contributes one line per attempt, all under the same `node_id` — the event records no attempt number — which is the intended reading for spend: a retry is real money. Null when no node produced the event (a standalone generation, a run-level meter).
+     *
+     */
+    node_id?: string | null;
     cost_usd?: number | null;
     components?: Array<UsageComponent>;
   }>;
@@ -10226,6 +10285,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: {
     /**
@@ -10414,7 +10481,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
      */
@@ -13304,7 +13371,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;
   /**
@@ -15447,7 +15514,7 @@ type ListTriggersData = {
   path?: never;
   query?: {
     project_id?: string;
-    type?: 'manual' | 'webhook' | 'schedule';
+    type?: 'manual' | 'webhook' | 'schedule' | 'event';
     target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
     /**
      * Maximum number of results to return
@@ -18459,7 +18526,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 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

@@ -3654,7 +3654,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 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": "@soat/sdk",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "TypeScript SDK for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",