@soat/sdk 0.31.0 → 0.33.0

package/dist/index.cjs

@@ -2938,7 +2938,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({
@@ -3655,7 +3657,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

@@ -4593,6 +4593,14 @@ type OrchestrationRun = {
   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.
    */
@@ -4604,9 +4612,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 `/api/v1/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;
@@ -5366,7 +5382,9 @@ 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.
+   *
+   * 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;
@@ -5448,7 +5466,9 @@ 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.
+   *
+   * 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;
@@ -5512,7 +5532,9 @@ 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.
+   *
+   * 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;
@@ -5541,7 +5563,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?: {
@@ -6046,7 +6068,7 @@ type UsageReceipt = {
     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. The event records no attempt number, so a retried node's attempts share one `node_id`, 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).
+     * 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;
@@ -13330,6 +13352,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
      */
@@ -18174,7 +18206,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>;
   /**
@@ -18526,7 +18560,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

@@ -4593,6 +4593,14 @@ type OrchestrationRun = {
   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.
    */
@@ -4604,9 +4612,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 `/api/v1/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;
@@ -5366,7 +5382,9 @@ 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.
+   *
+   * 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;
@@ -5448,7 +5466,9 @@ 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.
+   *
+   * 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;
@@ -5512,7 +5532,9 @@ 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.
+   *
+   * 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;
@@ -5541,7 +5563,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?: {
@@ -6046,7 +6068,7 @@ type UsageReceipt = {
     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. The event records no attempt number, so a retried node's attempts share one `node_id`, 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).
+     * 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;
@@ -13330,6 +13352,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
      */
@@ -18174,7 +18206,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>;
   /**
@@ -18526,7 +18560,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

@@ -2937,7 +2937,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({
@@ -3654,7 +3656,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.31.0",
+  "version": "0.33.0",
   "description": "TypeScript SDK for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",