@soat/sdk 0.36.0 → 0.37.0

package/dist/index.cjs

@@ -1044,7 +1044,7 @@ var AiProviders = class {
 	/**
 	* Upsert per-provider price overrides
 	*
-	* Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+	* Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future once the (model, component) has a price row — past prices are immutable, so corrections ship as new future-dated rows. A first price for a (model, component) nothing prices yet may be dated now or earlier, so a new provider is never live and unpriced.
 	*
 	*/
 	static updateAiProviderPrices(options) {
@@ -2317,6 +2317,8 @@ var Formations = class {
 	*
 	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.
 	*
+	* A deploy that replaced a resource and could not delete the superseded one answers `status: "active"` with `error.code: "FORMATION_REPLACE_CLEANUP_FAILED"` — the desired state is realised, and `error.meta.failures` names every resource still live. The next deploy retries the disposal.
+	*
 	*/
 	static updateFormation(options) {
 		return (options.client ?? client).put({
@@ -3162,7 +3164,7 @@ var Projects = class {
 	/**
 	* Update a project
 	*
-	* Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
+	* Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
 	*/
 	static updateProject(options) {
 		return (options.client ?? client).patch({
@@ -3189,7 +3191,7 @@ var Projects = class {
 	/**
 	* Upsert a project's price rows
 	*
-	* Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+	* Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable, so corrections ship as new future-dated rows. A first price, with no row for the project or the global default, may be dated now or earlier.
 	*
 	*/
 	static updateProjectPrices(options) {
@@ -3963,7 +3965,7 @@ var Usage = class {
 	/**
 	* Upsert price-book rows
 	*
-	* Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows.
+	* Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows. A first price, with no row in this scope or any broader one, may be dated now or earlier.
 	*
 	*/
 	static upsertPriceBook(options) {

package/dist/index.d.cts

@@ -462,11 +462,11 @@ type Agent = {
    */
   max_steps?: number | null;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
+   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `has_tool_call` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
    */
   tool_choice?: unknown;
   /**
-   * Conditions that end the agent's work early, on top of `max_steps` — turn-scoped (`hasToolCall`) or chain-scoped (`maxChainGenerations`). See the create request body for the accepted shapes.
+   * Conditions that end the agent's work early, on top of `max_steps` — turn-scoped (`has_tool_call`) or chain-scoped (`max_chain_generations`). See the create request body for the accepted shapes.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -682,17 +682,17 @@ type CreateAgentRequest = {
   tool_bindings?: Array<ToolBinding>;
   max_steps?: number;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
+   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `has_tool_call` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
    */
   tool_choice?: unknown;
   /**
    * Conditions that end the agent's work early, on top of `max_steps`. Two scopes:
    *
-   * `{"type": "hasToolCall", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
+   * `{"type": "has_tool_call", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
    *
-   * `{"type": "maxChainGenerations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
+   * `{"type": "max_chain_generations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
    *
-   * An unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
+   * An unknown `type`, a `has_tool_call` without a `tool_name`, a `max_chain_generations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -787,17 +787,17 @@ type UpdateAgentRequest = {
   tool_bindings?: Array<ToolBinding> | null;
   max_steps?: number | null;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
+   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `has_tool_call` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
    */
   tool_choice?: unknown;
   /**
    * Conditions that end the agent's work early, on top of `max_steps`. Two scopes:
    *
-   * `{"type": "hasToolCall", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
+   * `{"type": "has_tool_call", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
    *
-   * `{"type": "maxChainGenerations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
+   * `{"type": "max_chain_generations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
    *
-   * An unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
+   * An unknown `type`, a `has_tool_call` without a `tool_name`, a `max_chain_generations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -2249,19 +2249,19 @@ type AgentResourceProperties = {
    */
   tool_choice?: unknown;
   /**
-   * Conditions that stop the agent's work early — turn-scoped (`hasToolCall`) or chain-scoped (`maxChainGenerations`).
+   * Conditions that stop the agent's work early — turn-scoped (`has_tool_call`) or chain-scoped (`max_chain_generations`).
    */
   stop_conditions?: Array<{
     /**
-     * Condition type — `hasToolCall` or `maxChainGenerations`
+     * Condition type — `has_tool_call` or `max_chain_generations`
      */
     type?: string;
     /**
-     * Tool name to match when type is `hasToolCall`
+     * Tool name to match when type is `has_tool_call`
      */
     tool_name?: string | null;
     /**
-     * Generations the continuation chain may reach when type is `maxChainGenerations`
+     * Generations the continuation chain may reach when type is `max_chain_generations`
      */
     max_generations?: number | null;
   }> | null;
@@ -2526,7 +2526,7 @@ type ToolResourceProperties = {
    */
   denied_actions?: Array<string> | null;
   /**
-   * Optional allowlist of `tool_context` keys forwarded to this tool as prefixed context headers. `null` or omitted forwards every key; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded, and a key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list.
+   * Optional allowlist of `tool_context` keys forwarded to this tool as prefixed context headers. `null` or omitted forwards every key; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded, and a key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list.
    */
   context_keys?: Array<string> | null;
   /**
@@ -3270,6 +3270,8 @@ type Formation = {
   /**
    * Why the formation is `failed` or `delete_failed`, in the same `{ code, message, meta }` shape as an error response. Null in every other status, and cleared by the next successful deploy. This is the reason a `2xx` deploy response can report `status: "failed"` without a second call to `list-formation-events`.
    *
+   * One case carries an error while the formation is `active`: `FORMATION_REPLACE_CLEANUP_FAILED`, when a deploy replaced a resource and the superseded one could not be deleted. The desired state is realised, so the deploy succeeded — but the old resource is still live, and `meta.failures` names it. It stays on the formation as pending cleanup and is retried on the next deploy or teardown, which clears the error once it is gone.
+   *
    */
   error?: FormationError | null;
   /**
@@ -3340,7 +3342,7 @@ type UnauthorizedFormationAction = {
  */
 type FormationError = {
   /**
-   * The failing operation's error code (`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`, `FORMATION_DELETE_FAILED`, …), or `UNKNOWN` when the underlying failure carried no code.
+   * The failing operation's error code (`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`, `FORMATION_DELETE_FAILED`, `FORMATION_REPLACE_CLEANUP_FAILED`, …), or `UNKNOWN` when the underlying failure carried no code.
    */
   code: string;
   /**
@@ -3348,7 +3350,7 @@ type FormationError = {
    */
   message: string;
   /**
-   * Context for the failure. A failed apply names the resource that broke it (`logical_id`, `resource_type`); a failed teardown lists every blocker under `failures`.
+   * Context for the failure. A failed apply names the resource that broke it (`logical_id`, `resource_type`); a failed teardown lists every blocker under `failures`, and so does a succeeded deploy that could not dispose of a replaced resource — there each entry adds the `physical_resource_id` still live.
    */
   meta?: {
     [key: string]: unknown;
@@ -4412,7 +4414,7 @@ type OrchestrationNode = {
    */
   parallelism?: number;
   /**
-   * For loop and sub_orchestration nodes — allowlist of the run's `tool_context` keys the child run inherits. When `null` (the default), the child inherits the parent's whole bag — the behavior of every graph authored before this field existed. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; `[]` hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with `INVALID_TOOL_CONTEXT_KEY`. The server-derived identity keys (`sessionId`, `actorId`, `actorExternalId`) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
+   * For loop and sub_orchestration nodes — allowlist of the run's `tool_context` keys the child run inherits. When `null` (the default), the child inherits the parent's whole bag — the behavior of every graph authored before this field existed. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; `[]` hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with `INVALID_TOOL_CONTEXT_KEY`. The server-derived identity keys (`session_id`, `actor_id`, `actor_external_id`) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
    */
   context_keys?: Array<string> | null;
   /**
@@ -4702,6 +4704,10 @@ type OrchestrationRun = {
    * The node within `parent_orchestration_run_id` that started this run. Null when `parent_orchestration_run_id` is null.
    */
   parent_node_id?: string | null;
+  /**
+   * `loop` / `sub_orchestration` edges between this run and the run a caller started: `0` for a caller-started run, one more than its parent's for a child. Starting a child past the effective bound — the smaller of the deployment's `MAX_ORCHESTRATION_RUN_DEPTH` (default 10) and the project's `max_run_depth` — is refused with `ORCHESTRATION_RUN_DEPTH_LIMIT`, which fails the run that tried to descend. That bounds a graph whose `sub_orchestration` node names itself, directly or through a cycle of two graphs, which the intra-graph cycle check cannot see.
+   */
+  run_depth?: number;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -4843,7 +4849,7 @@ type StartRunRequest = {
    *
    * The bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.
    *
-   * The reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped at generation time — a caller cannot address them from here.
+   * The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here.
    */
   tool_context?: {
     [key: string]: string;
@@ -4914,9 +4920,13 @@ type ProjectRecord = {
    */
   max_concurrent_runs?: number | null;
   /**
-   * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` means no project ceiling (the default), leaving the deployment-wide one. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `maxChainGenerations` stop condition.
+   * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` means no project ceiling (the default), leaving the deployment-wide one. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `max_chain_generations` stop condition.
    */
   max_chain_generations?: number | null;
+  /**
+   * `loop` / `sub_orchestration` nesting levels a run tree in this project may reach before the engine refuses to start the next child. `null` means no project bound (the default), leaving the deployment-wide one. The effective bound is the smaller of the two.
+   */
+  max_run_depth?: number | null;
   /**
    * Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. `null` means no default, so every consumer must bind explicitly.
    */
@@ -5389,7 +5399,7 @@ type CreateTaskRequest = {
   /**
    * Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call made by this task's automation dispatches — the agent generations a state's `on_enter` starts, and the agent nodes of any orchestration run it starts. The header name is `X-Soat-Context-` plus the key verbatim; no character is re-cased.
    * Creation is the task's first move, so this is the bag the entry state's `on_enter` runs with. Each transition may replace it (see `TransitionTaskRequest.tool_context`).
-   * The reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
+   * The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
    * Write-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state.
    */
   tool_context?: {
@@ -5422,7 +5432,7 @@ type TransitionTaskRequest = {
   /**
    * Caller context for the automation dispatches the task makes from here on, forwarded as `X-Soat-Context-<key>` headers on their tool calls.
    * Supplying it **replaces** the task's stored bag wholesale; omitting it keeps the current one, so the context follows whoever last moved the task and survives every move that does not speak about it — including an approval gate, a retry, and an automation hop. Send an empty object to clear it without closing the task.
-   * The reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
+   * The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
    * Write-only: never returned by a task read, and cleared when the transition closes the task.
    */
   tool_context?: {
@@ -5487,7 +5497,7 @@ type Tool = {
    */
   denied_actions?: Array<string> | null;
   /**
-   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null`, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
+   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null`, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
    */
   context_keys?: Array<string> | null;
   /**
@@ -5571,7 +5581,7 @@ type CreateToolRequest = {
    */
   denied_actions?: Array<string>;
   /**
-   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
+   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
    */
   context_keys?: Array<string> | null;
   /**
@@ -5637,7 +5647,7 @@ type UpdateToolRequest = {
    */
   denied_actions?: Array<string> | null;
   /**
-   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
+   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
    */
   context_keys?: Array<string> | null;
   /**
@@ -5680,7 +5690,7 @@ type CallToolRequest = {
   };
   /**
    * Key/value context for this call, forwarded to the tool as `X-Soat-Context-<key>` request headers and resolving any `{{context:<key>}}` token in the tool's `execute.headers`, `mcp.headers` or `preset_parameters`. Narrowed by the tool's `context_keys` allowlist when it sets one.
-   * This route has no session, so it stamps no server-derived identity: the reserved keys `sessionId`, `actorId` and `actorExternalId` are dropped from this bag (in any casing) rather than forwarded, so a downstream tool can still trust that a context header naming one is server-derived. Every other key becomes an HTTP header name and must match that grammar, or the call fails with `INVALID_TOOL_CONTEXT_KEY`.
+   * This route has no session, so it stamps no server-derived identity: the reserved keys `session_id`, `actor_id` and `actor_external_id` are dropped from this bag (in any casing) rather than forwarded, so a downstream tool can still trust that a context header naming one is server-derived. Every other key becomes an HTTP header name and must match that grammar, or the call fails with `INVALID_TOOL_CONTEXT_KEY`.
    *
    */
   tool_context?: {
@@ -7077,7 +7087,7 @@ type DeleteAgentErrors = {
    */
   404: ErrorResponse;
   /**
-   * Agent has dependent generations or traces (pass `force=true` to delete anyway). `error.meta` carries `generationCount` and `traceCount` so a caller can tell which one is nonzero.
+   * Agent has dependent generations or traces (pass `force=true` to delete anyway). `error.meta` carries `generation_count` and `trace_count` so a caller can tell which one is nonzero.
    *
    */
   409: ErrorResponse;
@@ -10545,7 +10555,7 @@ type StartEvalRunData = {
      *
      * Stored on the run and re-read per item, since a queued run (the default) is driven by a worker with no request behind it. **Write-only**: no read of the run returns it, unlike `metadata` — a run is a report other people read, and a credential in it is not theirs to see. Cleared once the run reaches a terminal state.
      *
-     * An eval generation has no session, so the reserved keys `sessionId`, `actorId` and `actorExternalId` are dropped (in any casing) rather than forwarded. Every other key becomes an HTTP header name and must match that grammar, or the request is rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.
+     * An eval generation has no session, so the reserved keys `session_id`, `actor_id` and `actor_external_id` are dropped (in any casing) rather than forwarded. Every other key becomes an HTTP header name and must match that grammar, or the request is rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.
      */
     tool_context?: {
       [key: string]: string;
@@ -14141,9 +14151,13 @@ type UpdateProjectData = {
      */
     max_concurrent_runs?: number | null;
     /**
-     * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` clears the project's ceiling, leaving the deployment-wide `MAX_CONTINUATION_CHAIN_GENERATIONS`; otherwise an integer >= 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `maxChainGenerations` stop condition, so an agent author can be stricter than this number but never exceed it.
+     * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` clears the project's ceiling, leaving the deployment-wide `MAX_CONTINUATION_CHAIN_GENERATIONS`; otherwise an integer >= 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `max_chain_generations` stop condition, so an agent author can be stricter than this number but never exceed it.
      */
     max_chain_generations?: number | null;
+    /**
+     * `loop` / `sub_orchestration` nesting levels a run tree in this project may reach before the engine refuses to start the next child. `null` clears the project's bound, leaving the deployment-wide `MAX_ORCHESTRATION_RUN_DEPTH` (default 10); otherwise an integer >= 1. The effective bound is the smaller of the two, so this can only be stricter than the deployment's — which is what makes it a bound a graph author cannot opt out of. A refused child fails its parent run with `ORCHESTRATION_RUN_DEPTH_LIMIT`.
+     */
+    max_run_depth?: number | null;
     /**
      * Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. The route must belong to this project (`400` otherwise). `null` clears the default, which is refused with `409` while any consumer inherits it — repointing it to another route is always allowed and immediately changes which targets those consumers use.
      */
@@ -17488,7 +17502,7 @@ declare class AiProviders {
   /**
    * Upsert per-provider price overrides
    *
-   * Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+   * Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future once the (model, component) has a price row — past prices are immutable, so corrections ship as new future-dated rows. A first price for a (model, component) nothing prices yet may be dated now or earlier, so a new provider is never live and unpriced.
    *
    */
   static updateAiProviderPrices<ThrowOnError extends boolean = false>(options: Options<UpdateAiProviderPricesData, ThrowOnError>): RequestResult<UpdateAiProviderPricesResponses, UpdateAiProviderPricesErrors, ThrowOnError>;
@@ -18142,6 +18156,8 @@ declare class Formations {
    *
    * A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.
    *
+   * A deploy that replaced a resource and could not delete the superseded one answers `status: "active"` with `error.code: "FORMATION_REPLACE_CLEANUP_FAILED"` — the desired state is realised, and `error.meta.failures` names every resource still live. The next deploy retries the disposal.
+   *
    */
   static updateFormation<ThrowOnError extends boolean = false>(options: Options<UpdateFormationData, ThrowOnError>): RequestResult<UpdateFormationResponses, UpdateFormationErrors, ThrowOnError>;
   /**
@@ -18573,7 +18589,7 @@ declare class Projects {
   /**
    * Update a project
    *
-   * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
+   * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
    */
   static updateProject<ThrowOnError extends boolean = false>(options: Options<UpdateProjectData, ThrowOnError>): RequestResult<UpdateProjectResponses, UpdateProjectErrors, ThrowOnError>;
   /**
@@ -18586,7 +18602,7 @@ declare class Projects {
   /**
    * Upsert a project's price rows
    *
-   * Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+   * Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable, so corrections ship as new future-dated rows. A first price, with no row for the project or the global default, may be dated now or earlier.
    *
    */
   static updateProjectPrices<ThrowOnError extends boolean = false>(options: Options<UpdateProjectPricesData, ThrowOnError>): RequestResult<UpdateProjectPricesResponses, UpdateProjectPricesErrors, ThrowOnError>;
@@ -18978,7 +18994,7 @@ declare class Usage {
   /**
    * Upsert price-book rows
    *
-   * Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows.
+   * Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows. A first price, with no row in this scope or any broader one, may be dated now or earlier.
    *
    */
   static upsertPriceBook<ThrowOnError extends boolean = false>(options: Options<UpsertPriceBookData, ThrowOnError>): RequestResult<UpsertPriceBookResponses, UpsertPriceBookErrors, ThrowOnError>;

package/dist/index.d.mts

@@ -462,11 +462,11 @@ type Agent = {
    */
   max_steps?: number | null;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
+   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `has_tool_call` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
    */
   tool_choice?: unknown;
   /**
-   * Conditions that end the agent's work early, on top of `max_steps` — turn-scoped (`hasToolCall`) or chain-scoped (`maxChainGenerations`). See the create request body for the accepted shapes.
+   * Conditions that end the agent's work early, on top of `max_steps` — turn-scoped (`has_tool_call`) or chain-scoped (`max_chain_generations`). See the create request body for the accepted shapes.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -682,17 +682,17 @@ type CreateAgentRequest = {
   tool_bindings?: Array<ToolBinding>;
   max_steps?: number;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
+   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `has_tool_call` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
    */
   tool_choice?: unknown;
   /**
    * Conditions that end the agent's work early, on top of `max_steps`. Two scopes:
    *
-   * `{"type": "hasToolCall", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
+   * `{"type": "has_tool_call", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
    *
-   * `{"type": "maxChainGenerations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
+   * `{"type": "max_chain_generations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
    *
-   * An unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
+   * An unknown `type`, a `has_tool_call` without a `tool_name`, a `max_chain_generations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -787,17 +787,17 @@ type UpdateAgentRequest = {
   tool_bindings?: Array<ToolBinding> | null;
   max_steps?: number | null;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
+   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`). A forcing value (`"required"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `has_tool_call` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.
    */
   tool_choice?: unknown;
   /**
    * Conditions that end the agent's work early, on top of `max_steps`. Two scopes:
    *
-   * `{"type": "hasToolCall", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
+   * `{"type": "has_tool_call", "tool_name": "<resolved tool name>"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.
    *
-   * `{"type": "maxChainGenerations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
+   * `{"type": "max_chain_generations", "max_generations": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.
    *
-   * An unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
+   * An unknown `type`, a `has_tool_call` without a `tool_name`, a `max_chain_generations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -2249,19 +2249,19 @@ type AgentResourceProperties = {
    */
   tool_choice?: unknown;
   /**
-   * Conditions that stop the agent's work early — turn-scoped (`hasToolCall`) or chain-scoped (`maxChainGenerations`).
+   * Conditions that stop the agent's work early — turn-scoped (`has_tool_call`) or chain-scoped (`max_chain_generations`).
    */
   stop_conditions?: Array<{
     /**
-     * Condition type — `hasToolCall` or `maxChainGenerations`
+     * Condition type — `has_tool_call` or `max_chain_generations`
      */
     type?: string;
     /**
-     * Tool name to match when type is `hasToolCall`
+     * Tool name to match when type is `has_tool_call`
      */
     tool_name?: string | null;
     /**
-     * Generations the continuation chain may reach when type is `maxChainGenerations`
+     * Generations the continuation chain may reach when type is `max_chain_generations`
      */
     max_generations?: number | null;
   }> | null;
@@ -2526,7 +2526,7 @@ type ToolResourceProperties = {
    */
   denied_actions?: Array<string> | null;
   /**
-   * Optional allowlist of `tool_context` keys forwarded to this tool as prefixed context headers. `null` or omitted forwards every key; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded, and a key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list.
+   * Optional allowlist of `tool_context` keys forwarded to this tool as prefixed context headers. `null` or omitted forwards every key; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded, and a key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list.
    */
   context_keys?: Array<string> | null;
   /**
@@ -3270,6 +3270,8 @@ type Formation = {
   /**
    * Why the formation is `failed` or `delete_failed`, in the same `{ code, message, meta }` shape as an error response. Null in every other status, and cleared by the next successful deploy. This is the reason a `2xx` deploy response can report `status: "failed"` without a second call to `list-formation-events`.
    *
+   * One case carries an error while the formation is `active`: `FORMATION_REPLACE_CLEANUP_FAILED`, when a deploy replaced a resource and the superseded one could not be deleted. The desired state is realised, so the deploy succeeded — but the old resource is still live, and `meta.failures` names it. It stays on the formation as pending cleanup and is retried on the next deploy or teardown, which clears the error once it is gone.
+   *
    */
   error?: FormationError | null;
   /**
@@ -3340,7 +3342,7 @@ type UnauthorizedFormationAction = {
  */
 type FormationError = {
   /**
-   * The failing operation's error code (`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`, `FORMATION_DELETE_FAILED`, …), or `UNKNOWN` when the underlying failure carried no code.
+   * The failing operation's error code (`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`, `FORMATION_DELETE_FAILED`, `FORMATION_REPLACE_CLEANUP_FAILED`, …), or `UNKNOWN` when the underlying failure carried no code.
    */
   code: string;
   /**
@@ -3348,7 +3350,7 @@ type FormationError = {
    */
   message: string;
   /**
-   * Context for the failure. A failed apply names the resource that broke it (`logical_id`, `resource_type`); a failed teardown lists every blocker under `failures`.
+   * Context for the failure. A failed apply names the resource that broke it (`logical_id`, `resource_type`); a failed teardown lists every blocker under `failures`, and so does a succeeded deploy that could not dispose of a replaced resource — there each entry adds the `physical_resource_id` still live.
    */
   meta?: {
     [key: string]: unknown;
@@ -4412,7 +4414,7 @@ type OrchestrationNode = {
    */
   parallelism?: number;
   /**
-   * For loop and sub_orchestration nodes — allowlist of the run's `tool_context` keys the child run inherits. When `null` (the default), the child inherits the parent's whole bag — the behavior of every graph authored before this field existed. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; `[]` hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with `INVALID_TOOL_CONTEXT_KEY`. The server-derived identity keys (`sessionId`, `actorId`, `actorExternalId`) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
+   * For loop and sub_orchestration nodes — allowlist of the run's `tool_context` keys the child run inherits. When `null` (the default), the child inherits the parent's whole bag — the behavior of every graph authored before this field existed. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; `[]` hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with `INVALID_TOOL_CONTEXT_KEY`. The server-derived identity keys (`session_id`, `actor_id`, `actor_external_id`) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
    */
   context_keys?: Array<string> | null;
   /**
@@ -4702,6 +4704,10 @@ type OrchestrationRun = {
    * The node within `parent_orchestration_run_id` that started this run. Null when `parent_orchestration_run_id` is null.
    */
   parent_node_id?: string | null;
+  /**
+   * `loop` / `sub_orchestration` edges between this run and the run a caller started: `0` for a caller-started run, one more than its parent's for a child. Starting a child past the effective bound — the smaller of the deployment's `MAX_ORCHESTRATION_RUN_DEPTH` (default 10) and the project's `max_run_depth` — is refused with `ORCHESTRATION_RUN_DEPTH_LIMIT`, which fails the run that tried to descend. That bounds a graph whose `sub_orchestration` node names itself, directly or through a cycle of two graphs, which the intra-graph cycle check cannot see.
+   */
+  run_depth?: number;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -4843,7 +4849,7 @@ type StartRunRequest = {
    *
    * The bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.
    *
-   * The reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped at generation time — a caller cannot address them from here.
+   * The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here.
    */
   tool_context?: {
     [key: string]: string;
@@ -4914,9 +4920,13 @@ type ProjectRecord = {
    */
   max_concurrent_runs?: number | null;
   /**
-   * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` means no project ceiling (the default), leaving the deployment-wide one. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `maxChainGenerations` stop condition.
+   * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` means no project ceiling (the default), leaving the deployment-wide one. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `max_chain_generations` stop condition.
    */
   max_chain_generations?: number | null;
+  /**
+   * `loop` / `sub_orchestration` nesting levels a run tree in this project may reach before the engine refuses to start the next child. `null` means no project bound (the default), leaving the deployment-wide one. The effective bound is the smaller of the two.
+   */
+  max_run_depth?: number | null;
   /**
    * Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. `null` means no default, so every consumer must bind explicitly.
    */
@@ -5389,7 +5399,7 @@ type CreateTaskRequest = {
   /**
    * Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call made by this task's automation dispatches — the agent generations a state's `on_enter` starts, and the agent nodes of any orchestration run it starts. The header name is `X-Soat-Context-` plus the key verbatim; no character is re-cased.
    * Creation is the task's first move, so this is the bag the entry state's `on_enter` runs with. Each transition may replace it (see `TransitionTaskRequest.tool_context`).
-   * The reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
+   * The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
    * Write-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state.
    */
   tool_context?: {
@@ -5422,7 +5432,7 @@ type TransitionTaskRequest = {
   /**
    * Caller context for the automation dispatches the task makes from here on, forwarded as `X-Soat-Context-<key>` headers on their tool calls.
    * Supplying it **replaces** the task's stored bag wholesale; omitting it keeps the current one, so the context follows whoever last moved the task and survives every move that does not speak about it — including an approval gate, a retry, and an automation hop. Send an empty object to clear it without closing the task.
-   * The reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
+   * The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).
    * Write-only: never returned by a task read, and cleared when the transition closes the task.
    */
   tool_context?: {
@@ -5487,7 +5497,7 @@ type Tool = {
    */
   denied_actions?: Array<string> | null;
   /**
-   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null`, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
+   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null`, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
    */
   context_keys?: Array<string> | null;
   /**
@@ -5571,7 +5581,7 @@ type CreateToolRequest = {
    */
   denied_actions?: Array<string>;
   /**
-   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
+   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
    */
   context_keys?: Array<string> | null;
   /**
@@ -5637,7 +5647,7 @@ type UpdateToolRequest = {
    */
   denied_actions?: Array<string> | null;
   /**
-   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`sessionId`, `actorId`, `actorExternalId`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
+   * Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
    */
   context_keys?: Array<string> | null;
   /**
@@ -5680,7 +5690,7 @@ type CallToolRequest = {
   };
   /**
    * Key/value context for this call, forwarded to the tool as `X-Soat-Context-<key>` request headers and resolving any `{{context:<key>}}` token in the tool's `execute.headers`, `mcp.headers` or `preset_parameters`. Narrowed by the tool's `context_keys` allowlist when it sets one.
-   * This route has no session, so it stamps no server-derived identity: the reserved keys `sessionId`, `actorId` and `actorExternalId` are dropped from this bag (in any casing) rather than forwarded, so a downstream tool can still trust that a context header naming one is server-derived. Every other key becomes an HTTP header name and must match that grammar, or the call fails with `INVALID_TOOL_CONTEXT_KEY`.
+   * This route has no session, so it stamps no server-derived identity: the reserved keys `session_id`, `actor_id` and `actor_external_id` are dropped from this bag (in any casing) rather than forwarded, so a downstream tool can still trust that a context header naming one is server-derived. Every other key becomes an HTTP header name and must match that grammar, or the call fails with `INVALID_TOOL_CONTEXT_KEY`.
    *
    */
   tool_context?: {
@@ -7077,7 +7087,7 @@ type DeleteAgentErrors = {
    */
   404: ErrorResponse;
   /**
-   * Agent has dependent generations or traces (pass `force=true` to delete anyway). `error.meta` carries `generationCount` and `traceCount` so a caller can tell which one is nonzero.
+   * Agent has dependent generations or traces (pass `force=true` to delete anyway). `error.meta` carries `generation_count` and `trace_count` so a caller can tell which one is nonzero.
    *
    */
   409: ErrorResponse;
@@ -10545,7 +10555,7 @@ type StartEvalRunData = {
      *
      * Stored on the run and re-read per item, since a queued run (the default) is driven by a worker with no request behind it. **Write-only**: no read of the run returns it, unlike `metadata` — a run is a report other people read, and a credential in it is not theirs to see. Cleared once the run reaches a terminal state.
      *
-     * An eval generation has no session, so the reserved keys `sessionId`, `actorId` and `actorExternalId` are dropped (in any casing) rather than forwarded. Every other key becomes an HTTP header name and must match that grammar, or the request is rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.
+     * An eval generation has no session, so the reserved keys `session_id`, `actor_id` and `actor_external_id` are dropped (in any casing) rather than forwarded. Every other key becomes an HTTP header name and must match that grammar, or the request is rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.
      */
     tool_context?: {
       [key: string]: string;
@@ -14141,9 +14151,13 @@ type UpdateProjectData = {
      */
     max_concurrent_runs?: number | null;
     /**
-     * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` clears the project's ceiling, leaving the deployment-wide `MAX_CONTINUATION_CHAIN_GENERATIONS`; otherwise an integer >= 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `maxChainGenerations` stop condition, so an agent author can be stricter than this number but never exceed it.
+     * Generations one continuation chain in this project may hold before the platform stops resuming it. `null` clears the project's ceiling, leaving the deployment-wide `MAX_CONTINUATION_CHAIN_GENERATIONS`; otherwise an integer >= 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `max_chain_generations` stop condition, so an agent author can be stricter than this number but never exceed it.
      */
     max_chain_generations?: number | null;
+    /**
+     * `loop` / `sub_orchestration` nesting levels a run tree in this project may reach before the engine refuses to start the next child. `null` clears the project's bound, leaving the deployment-wide `MAX_ORCHESTRATION_RUN_DEPTH` (default 10); otherwise an integer >= 1. The effective bound is the smaller of the two, so this can only be stricter than the deployment's — which is what makes it a bound a graph author cannot opt out of. A refused child fails its parent run with `ORCHESTRATION_RUN_DEPTH_LIMIT`.
+     */
+    max_run_depth?: number | null;
     /**
      * Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. The route must belong to this project (`400` otherwise). `null` clears the default, which is refused with `409` while any consumer inherits it — repointing it to another route is always allowed and immediately changes which targets those consumers use.
      */
@@ -17488,7 +17502,7 @@ declare class AiProviders {
   /**
    * Upsert per-provider price overrides
    *
-   * Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+   * Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future once the (model, component) has a price row — past prices are immutable, so corrections ship as new future-dated rows. A first price for a (model, component) nothing prices yet may be dated now or earlier, so a new provider is never live and unpriced.
    *
    */
   static updateAiProviderPrices<ThrowOnError extends boolean = false>(options: Options<UpdateAiProviderPricesData, ThrowOnError>): RequestResult<UpdateAiProviderPricesResponses, UpdateAiProviderPricesErrors, ThrowOnError>;
@@ -18142,6 +18156,8 @@ declare class Formations {
    *
    * A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.
    *
+   * A deploy that replaced a resource and could not delete the superseded one answers `status: "active"` with `error.code: "FORMATION_REPLACE_CLEANUP_FAILED"` — the desired state is realised, and `error.meta.failures` names every resource still live. The next deploy retries the disposal.
+   *
    */
   static updateFormation<ThrowOnError extends boolean = false>(options: Options<UpdateFormationData, ThrowOnError>): RequestResult<UpdateFormationResponses, UpdateFormationErrors, ThrowOnError>;
   /**
@@ -18573,7 +18589,7 @@ declare class Projects {
   /**
    * Update a project
    *
-   * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
+   * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
    */
   static updateProject<ThrowOnError extends boolean = false>(options: Options<UpdateProjectData, ThrowOnError>): RequestResult<UpdateProjectResponses, UpdateProjectErrors, ThrowOnError>;
   /**
@@ -18586,7 +18602,7 @@ declare class Projects {
   /**
    * Upsert a project's price rows
    *
-   * Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+   * Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable, so corrections ship as new future-dated rows. A first price, with no row for the project or the global default, may be dated now or earlier.
    *
    */
   static updateProjectPrices<ThrowOnError extends boolean = false>(options: Options<UpdateProjectPricesData, ThrowOnError>): RequestResult<UpdateProjectPricesResponses, UpdateProjectPricesErrors, ThrowOnError>;
@@ -18978,7 +18994,7 @@ declare class Usage {
   /**
    * Upsert price-book rows
    *
-   * Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows.
+   * Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows. A first price, with no row in this scope or any broader one, may be dated now or earlier.
    *
    */
   static upsertPriceBook<ThrowOnError extends boolean = false>(options: Options<UpsertPriceBookData, ThrowOnError>): RequestResult<UpsertPriceBookResponses, UpsertPriceBookErrors, ThrowOnError>;

package/dist/index.mjs

@@ -1043,7 +1043,7 @@ var AiProviders = class {
 	/**
 	* Upsert per-provider price overrides
 	*
-	* Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+	* Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The provider slug is taken from the AI provider itself, so only the model, rates, and effective_from are supplied. Authorized by the caller's access to the provider's project. `effective_from` must be in the future once the (model, component) has a price row — past prices are immutable, so corrections ship as new future-dated rows. A first price for a (model, component) nothing prices yet may be dated now or earlier, so a new provider is never live and unpriced.
 	*
 	*/
 	static updateAiProviderPrices(options) {
@@ -2316,6 +2316,8 @@ var Formations = class {
 	*
 	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.
 	*
+	* A deploy that replaced a resource and could not delete the superseded one answers `status: "active"` with `error.code: "FORMATION_REPLACE_CLEANUP_FAILED"` — the desired state is realised, and `error.meta.failures` names every resource still live. The next deploy retries the disposal.
+	*
 	*/
 	static updateFormation(options) {
 		return (options.client ?? client).put({
@@ -3161,7 +3163,7 @@ var Projects = class {
 	/**
 	* Update a project
 	*
-	* Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
+	* Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
 	*/
 	static updateProject(options) {
 		return (options.client ?? client).patch({
@@ -3188,7 +3190,7 @@ var Projects = class {
 	/**
 	* Upsert a project's price rows
 	*
-	* Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future — past prices are immutable, so ship corrections as new future-dated rows.
+	* Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable, so corrections ship as new future-dated rows. A first price, with no row for the project or the global default, may be dated now or earlier.
 	*
 	*/
 	static updateProjectPrices(options) {
@@ -3962,7 +3964,7 @@ var Usage = class {
 	/**
 	* Upsert price-book rows
 	*
-	* Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows.
+	* Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows. A first price, with no row in this scope or any broader one, may be dated now or earlier.
 	*
 	*/
 	static upsertPriceBook(options) {

package/package.json

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