@soat/sdk 0.32.0 → 0.33.1

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({
@@ -4312,9 +4314,7 @@ const bindResource = (SdkClass, client) => {
 	} });
 };
 /**
-* Stripe-style SOAT client.
-*
-* Create an instance once and reuse it throughout your application:
+* Stripe-style SOAT client. Create an instance once and reuse it:
 *
 * ```ts
 * import { SoatClient } from '@soat/sdk';
@@ -4327,14 +4327,13 @@ const bindResource = (SdkClass, client) => {
 * });
 * ```
 *
-* The instance exposes one property per API resource. Each property mirrors
-* the corresponding static class from the generated SDK, so all method
-* signatures, types, and return values are identical — the only difference
-* is that you never need to supply `client` yourself.
+* One property per API resource, each mirroring the corresponding static class
+* from the generated SDK — identical signatures, types and return values, only
+* without having to supply `client`.
 *
-* The list is exhaustive by construction: `NoUnregisteredResource` at the
-* bottom of this file fails `pnpm typecheck` when a spec adds a resource this
-* class does not expose.
+* The list is exhaustive by construction: `NoUnregisteredResource` at the bottom
+* of this file fails `pnpm typecheck` when a spec adds a resource this class
+* does not expose.
 */
 var SoatClient = class {
 	activity;

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;
@@ -5367,6 +5383,8 @@ type Tool = {
   context_keys?: Array<string> | null;
   /**
    * 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;
@@ -5449,6 +5467,8 @@ type CreateToolRequest = {
   context_keys?: Array<string> | null;
   /**
    * 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;
@@ -5513,6 +5533,8 @@ type UpdateToolRequest = {
   context_keys?: Array<string> | null;
   /**
    * 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;
@@ -7379,6 +7401,20 @@ type ListAiProvidersResponses = {
       name?: string;
       provider?: 'openai' | 'anthropic' | 'google' | 'xai' | 'groq' | 'ollama' | 'azure' | 'bedrock' | 'vertex' | 'gateway' | 'custom';
       default_model?: string;
+      /**
+       * Secret ID containing API credentials, or null when the record links none.
+       */
+      secret_id?: string | null;
+      /**
+       * Custom base URL for the provider. Absent when the record sets none.
+       */
+      base_url?: string;
+      /**
+       * Additional provider-specific configuration. Absent when the record sets none.
+       */
+      config?: {
+        [key: string]: unknown;
+      };
       project_id?: string;
       created_at?: Date;
       updated_at?: Date;
@@ -13330,6 +13366,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 +18220,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>;
   /**
@@ -18877,9 +18925,7 @@ interface SoatClientOptions {
   headers?: Record<string, string>;
 }
 /**
- * Stripe-style SOAT client.
- *
- * Create an instance once and reuse it throughout your application:
+ * Stripe-style SOAT client. Create an instance once and reuse it:
  *
  * ```ts
  * import { SoatClient } from '@soat/sdk';
@@ -18892,14 +18938,13 @@ interface SoatClientOptions {
  * });
  * ```
  *
- * The instance exposes one property per API resource. Each property mirrors
- * the corresponding static class from the generated SDK, so all method
- * signatures, types, and return values are identical — the only difference
- * is that you never need to supply `client` yourself.
+ * One property per API resource, each mirroring the corresponding static class
+ * from the generated SDK — identical signatures, types and return values, only
+ * without having to supply `client`.
  *
- * The list is exhaustive by construction: `NoUnregisteredResource` at the
- * bottom of this file fails `pnpm typecheck` when a spec adds a resource this
- * class does not expose.
+ * The list is exhaustive by construction: `NoUnregisteredResource` at the bottom
+ * of this file fails `pnpm typecheck` when a spec adds a resource this class
+ * does not expose.
  */
 declare class SoatClient {
   readonly activity: typeof Activity;

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;
@@ -5367,6 +5383,8 @@ type Tool = {
   context_keys?: Array<string> | null;
   /**
    * 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;
@@ -5449,6 +5467,8 @@ type CreateToolRequest = {
   context_keys?: Array<string> | null;
   /**
    * 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;
@@ -5513,6 +5533,8 @@ type UpdateToolRequest = {
   context_keys?: Array<string> | null;
   /**
    * 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;
@@ -7379,6 +7401,20 @@ type ListAiProvidersResponses = {
       name?: string;
       provider?: 'openai' | 'anthropic' | 'google' | 'xai' | 'groq' | 'ollama' | 'azure' | 'bedrock' | 'vertex' | 'gateway' | 'custom';
       default_model?: string;
+      /**
+       * Secret ID containing API credentials, or null when the record links none.
+       */
+      secret_id?: string | null;
+      /**
+       * Custom base URL for the provider. Absent when the record sets none.
+       */
+      base_url?: string;
+      /**
+       * Additional provider-specific configuration. Absent when the record sets none.
+       */
+      config?: {
+        [key: string]: unknown;
+      };
       project_id?: string;
       created_at?: Date;
       updated_at?: Date;
@@ -13330,6 +13366,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 +18220,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>;
   /**
@@ -18877,9 +18925,7 @@ interface SoatClientOptions {
   headers?: Record<string, string>;
 }
 /**
- * Stripe-style SOAT client.
- *
- * Create an instance once and reuse it throughout your application:
+ * Stripe-style SOAT client. Create an instance once and reuse it:
  *
  * ```ts
  * import { SoatClient } from '@soat/sdk';
@@ -18892,14 +18938,13 @@ interface SoatClientOptions {
  * });
  * ```
  *
- * The instance exposes one property per API resource. Each property mirrors
- * the corresponding static class from the generated SDK, so all method
- * signatures, types, and return values are identical — the only difference
- * is that you never need to supply `client` yourself.
+ * One property per API resource, each mirroring the corresponding static class
+ * from the generated SDK — identical signatures, types and return values, only
+ * without having to supply `client`.
  *
- * The list is exhaustive by construction: `NoUnregisteredResource` at the
- * bottom of this file fails `pnpm typecheck` when a spec adds a resource this
- * class does not expose.
+ * The list is exhaustive by construction: `NoUnregisteredResource` at the bottom
+ * of this file fails `pnpm typecheck` when a spec adds a resource this class
+ * does not expose.
  */
 declare class SoatClient {
   readonly activity: typeof Activity;

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({
@@ -4311,9 +4313,7 @@ const bindResource = (SdkClass, client) => {
 	} });
 };
 /**
-* Stripe-style SOAT client.
-*
-* Create an instance once and reuse it throughout your application:
+* Stripe-style SOAT client. Create an instance once and reuse it:
 *
 * ```ts
 * import { SoatClient } from '@soat/sdk';
@@ -4326,14 +4326,13 @@ const bindResource = (SdkClass, client) => {
 * });
 * ```
 *
-* The instance exposes one property per API resource. Each property mirrors
-* the corresponding static class from the generated SDK, so all method
-* signatures, types, and return values are identical — the only difference
-* is that you never need to supply `client` yourself.
+* One property per API resource, each mirroring the corresponding static class
+* from the generated SDK — identical signatures, types and return values, only
+* without having to supply `client`.
 *
-* The list is exhaustive by construction: `NoUnregisteredResource` at the
-* bottom of this file fails `pnpm typecheck` when a spec adds a resource this
-* class does not expose.
+* The list is exhaustive by construction: `NoUnregisteredResource` at the bottom
+* of this file fails `pnpm typecheck` when a spec adds a resource this class
+* does not expose.
 */
 var SoatClient = class {
 	activity;

package/package.json

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