@naturali/sdk 0.85.1 → 0.85.2

package/dist/index.d.cts

@@ -502,15 +502,15 @@ type Agent = {
    */
   tool_bindings?: Array<ToolBinding> | null;
   /**
-   * Maximum agent loop steps before stopping
+   * Maximum agent loop steps before stopping. The budget bounds a **turn**: a generation that pauses at `requires_action` and resumes after `submit-tool-outputs` continues the same turn and spends what is left of it, so a turn that arrives with nothing left completes with `stop_reason: "max_steps"` instead of calling the model again.
    */
   max_steps?: number | null;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`).
+   * 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?: unknown;
   /**
-   * Stop conditions
+   * 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.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -524,7 +524,7 @@ type Agent = {
    */
   guardrail_ids?: Array<string> | null;
   /**
-   * Per-step overrides
+   * Per-step overrides of `tool_choice` and `active_tool_ids`. Steps are numbered from the first step of the **turn**, and that numbering spans a `requires_action` pause — a rule fires once per turn, not once per resumption.
    */
   step_rules?: Array<{
     [key: string]: unknown;
@@ -593,6 +593,10 @@ type Agent = {
    * Agent-scope zero-retention setting. `null` (the default) inherits the project's `trace_content_mode`; `none` means this agent's trace and generation content is never persisted. An agent may tighten a storing project to `none` but cannot loosen a `none` project back to `full`.
    */
   trace_content_mode?: 'full' | 'none' | null;
+  /**
+   * What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
+   */
+  on_approval_expiry?: 'terminate' | 'react' | null;
   /**
    * Current config version. Starts at 1 and increments on every write that changes the config; each increment archives the new config as an `AgentVersion`. A write that changes nothing leaves it untouched.
    */
@@ -642,7 +646,7 @@ type AgentVersion = {
    */
   version?: number;
   /**
-   * The agent's configuration as it stood at this version: every mutable field of the `Agent` schema (`instructions`, `model`, `tool_bindings`, `max_steps`, `tool_choice`, `stop_conditions`, `active_tool_ids`, `step_rules`, `boundary_policy`, `temperature`, `knowledge_config`, `output_schema`, `max_context_messages`, `single_session_per_actor`, `guardrail_ids`, `ai_provider_id`, `model_route_id`, `name`), and none of its identity or bookkeeping fields (`id`, `project_id`, `version`, `active_release`, timestamps).
+   * The agent's configuration as it stood at this version: every mutable field of the `Agent` schema (`instructions`, `model`, `tool_bindings`, `max_steps`, `tool_choice`, `stop_conditions`, `active_tool_ids`, `step_rules`, `boundary_policy`, `temperature`, `knowledge_config`, `output_schema`, `max_context_messages`, `single_session_per_actor`, `on_approval_expiry`, `guardrail_ids`, `ai_provider_id`, `model_route_id`, `name`), and none of its identity or bookkeeping fields (`id`, `project_id`, `version`, `active_release`, timestamps).
    *
    * Deliberately open rather than a fixed schema: an archive written by an earlier release of the runtime reflects the agent surface **of its own time**, so it may carry fields the current schema no longer defines, or lack ones it has since gained. Knowledge retrieval is not part of the snapshot — a version records which `knowledge_config` applied, while the documents and memories it resolves keep their own histories and are pinned at generation time.
    */
@@ -718,9 +722,18 @@ 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" }`).
+   * 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?: 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": "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.
+   *
+   * 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.
+   */
   stop_conditions?: Array<{
     [key: string]: unknown;
   }>;
@@ -787,6 +800,10 @@ type CreateAgentRequest = {
    * Zero-retention opt-in for this agent. `null` inherits the project's setting; `none` means trace and generation content is never written. Setting `full` under a project whose own mode is `none` is refused with 400 — the project is a floor an agent may only tighten.
    */
   trace_content_mode?: 'full' | 'none' | null;
+  /**
+   * What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
+   */
+  on_approval_expiry?: 'terminate' | 'react' | null;
   /**
    * Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change.
    */
@@ -810,9 +827,18 @@ 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" }`).
+   * 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?: 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": "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.
+   *
+   * 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.
+   */
   stop_conditions?: Array<{
     [key: string]: unknown;
   }> | null;
@@ -879,6 +905,10 @@ type UpdateAgentRequest = {
    * Zero-retention opt-in for this agent. `null` inherits the project's setting; `none` means trace and generation content is never written. Setting `full` under a project whose own mode is `none` is refused with 400.
    */
   trace_content_mode?: 'full' | 'none' | null;
+  /**
+   * What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
+   */
+  on_approval_expiry?: 'terminate' | 'react' | null;
   /**
    * Optional tag for the config version this write archives (e.g. `pre-tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.
    */
@@ -2443,7 +2473,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'chain_limit' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -2659,17 +2689,21 @@ type AgentResourceProperties = {
    */
   tool_choice?: unknown;
   /**
-   * Conditions that stop multi-step generation early. The loop stops when any condition is met.
+   * Conditions that stop the agent's work early — turn-scoped (`hasToolCall`) or chain-scoped (`maxChainGenerations`).
    */
   stop_conditions?: Array<{
     /**
-     * Condition type — currently `hasToolCall`
+     * Condition type — `hasToolCall` or `maxChainGenerations`
      */
     type?: string;
     /**
      * Tool name to match when type is `hasToolCall`
      */
     tool_name?: string | null;
+    /**
+     * Generations the continuation chain may reach when type is `maxChainGenerations`
+     */
+    max_generations?: number | null;
   }> | null;
   /**
    * Subset of the bound tools that are active
@@ -2736,6 +2770,10 @@ type AgentResourceProperties = {
    * Agent-scope zero-retention setting (`full` or `none`). `null` inherits the project's setting. `full` is refused when the project's own mode is `none`.
    */
   trace_content_mode?: string | null;
+  /**
+   * What happens when a held tool call expires un-approved: `terminate` (the default when null) ends the chain, `react` spawns a continuation that reports the staleness to the agent.
+   */
+  on_approval_expiry?: string | null;
   /**
    * Knowledge retrieval configuration. When set, relevant documents and memory entries are injected into every generation.
    */
@@ -2831,9 +2869,9 @@ type AiProviderResourceProperties = {
    */
   name: string;
   /**
-   * Provider type (e.g. openai, anthropic)
+   * Provider type
    */
-  provider: string;
+  provider: 'openai' | 'anthropic' | 'google' | 'xai' | 'groq' | 'ollama' | 'azure' | 'bedrock' | 'vertex' | 'gateway' | 'custom';
   /**
    * Default model identifier (e.g. gpt-4o, claude-3-7-sonnet)
    */
@@ -3394,7 +3432,7 @@ type WorkflowResourceProperties = {
   } | null;
 };
 /**
- * Creates a quota — a project-scoped cap that blocks (`enforce`) or reports (`monitor`) when a windowed aggregate is exceeded. `requests` quotas are enforced by the request middleware; `tokens`/`cost_usd` quotas at the pre-generation check. Mirrors the quotas REST contract; `scope`, `metric`, and `window` are immutable after creation (only `limit` and `mode` update).
+ * Creates a quota — a project-scoped cap that blocks (`enforce`) or reports (`monitor`) when a windowed aggregate is exceeded. `requests` quotas are enforced by the request middleware; `tokens`/`cost_usd` quotas at the pre-generation check. Mirrors the quotas REST contract; `scope`, `metric`, and `window` are immutable after creation (only `limit`, `mode`, and `on_unpriced` update).
  */
 type QuotaResourceProperties = {
   /**
@@ -3421,6 +3459,10 @@ type QuotaResourceProperties = {
    * enforce blocks with 429; monitor fires the webhook only
    */
   mode?: 'enforce' | 'monitor';
+  /**
+   * Only for metric cost_usd. What an enforce quota does over a pricing blackout — block (the default) refuses generations with 409 QUOTA_UNENFORCEABLE, allow accepts the unmeasurable spend. See the quotas REST contract.
+   */
+  on_unpriced?: 'block' | 'allow';
 };
 /**
  * Creates a guardrail — an action-class document (`class`/`guard`) that gates tool-call autonomy. Attach it to a tool or agent via that resource's `guardrail_ids` (a `{ "ref": … }` to this resource in the same template resolves to its physical id at deploy time). Mirrors the guardrails REST contract; `class`/`default_class`/`guard`/`escalate` are flattened here from the REST API's single `document` object.
@@ -3677,6 +3719,11 @@ type Generation = {
    *
    */
   initiator_generation_id?: string | null;
+  /**
+   * Public ID of the continuation chain this generation belongs to. Set on every member of a chain — the continuations and the root they descend from — and null on a generation that is not part of one.
+   *
+   */
+  chain_id?: string | null;
   /**
    * Type of the principal that started the generation
    */
@@ -3696,7 +3743,8 @@ type Generation = {
   completed_at?: Date | null;
   last_activity_at?: Date | null;
   /**
-   * Why the generation stopped (e.g. 'stop', 'error')
+   * Why the generation stopped. Either the model provider's own finish reason relayed unchanged ('stop', 'tool-calls', 'length', …) or one the platform names itself: 'max_steps' when the turn spent its whole step budget on tool calls, 'depth_guard' when a nested call exceeded the call depth, 'chain_limit' when a continuation chain reached its generation budget, or 'error' when the turn failed.
+   *
    */
   stop_reason?: string | null;
   /**
@@ -3917,6 +3965,10 @@ type GenerationTranscript = {
    *
    */
   status?: 'in_progress' | 'requires_action' | 'completed' | 'failed';
+  /**
+   * Why the generation stopped — the provider's finish reason, or one of the platform's own ('max_steps', 'depth_guard', 'chain_limit', 'error').
+   *
+   */
   stop_reason?: string | null;
   started_at?: Date;
   completed_at?: Date | null;
@@ -3926,7 +3978,7 @@ type GenerationTranscript = {
    */
   step_count?: number;
   /**
-   * The messages the turn was asked, as recorded. Message content is caller-owned and passed through verbatim. Null when the content was never stored, has been purged, or predates input recording.
+   * The messages the turn was asked, as recorded. Message content is caller-owned and passed through verbatim. Null when the content was never stored or has been purged.
    *
    */
   input?: Array<{
@@ -4568,6 +4620,10 @@ type OrchestrationNode = {
    * For loop nodes — number of items to process in parallel.
    */
   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.
+   */
+  context_keys?: Array<string> | null;
   /**
    * For poll nodes — wait between attempts. Accepts a friendly suffix form (`5s`, `30s`, `5m`, `2h`, `500ms`) or ISO 8601 (e.g. PT5S).
    *
@@ -5205,6 +5261,10 @@ type Quota = {
   window?: 'rolling_1m' | 'rolling_1h' | 'rolling_24h' | 'calendar_month';
   limit?: number;
   mode?: 'enforce' | 'monitor';
+  /**
+   * Pricing posture of a cost_usd quota over an unpriced blackout — block refuses generations, allow lets them through (the quota_unpriced exception is filed either way). Null for metrics with no pricing dependency.
+   */
+  on_unpriced?: 'block' | 'allow' | null;
   /**
    * Current fixed-window usage for the requests metric. Null for token/cost quotas (which aggregate the usage meter at check time rather than keeping a counter) and in list responses.
    */
@@ -5786,6 +5846,14 @@ type CallToolRequest = {
   input?: {
     [key: string]: unknown;
   };
+  /**
+   * Key/value context for this call, forwarded to the tool as `X-Naturali-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`.
+   *
+   */
+  tool_context?: {
+    [key: string]: string;
+  };
 };
 type Trace = {
   /**
@@ -8648,7 +8716,7 @@ type ListAuditEntriesData = {
      */
     resource_public_id?: string;
     /**
-     * SRN prefix match, e.g. `srn:{project}:secret:`. An entry written before an earlier prefix rename keeps its original SRN (the log is append-only), and an `srn:` prefix matches those too, so history stays reachable.
+     * SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN is never rewritten; the filter matches it as stored.
      */
     resource_srn?: string;
     /**
@@ -8722,7 +8790,7 @@ type ExportAuditEntriesData = {
      */
     resource_public_id?: string;
     /**
-     * SRN prefix match, e.g. `srn:{project}:secret:`. An entry written before an earlier prefix rename keeps its original SRN (the log is append-only), and an `srn:` prefix matches those too, so history stays reachable.
+     * SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN is never rewritten; the filter matches it as stored.
      */
     resource_srn?: string;
     /**
@@ -11530,6 +11598,16 @@ type StartEvalRunData = {
     metadata?: {
       [key: string]: unknown;
     };
+    /**
+     * Key/value context forwarded to every item's generation, so an agent whose tools authorize through `tool_context` is scored against the configuration it runs in production rather than with an empty bag. Each key is forwarded as one `X-Naturali-Context-<key>` header and resolves any `{{context:<key>}}` token in a bound tool's headers or `preset_parameters`.
+     *
+     * 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.
+     */
+    tool_context?: {
+      [key: string]: string;
+    };
   };
   path: {
     /**
@@ -11546,7 +11624,7 @@ type StartEvalRunData = {
 };
 type StartEvalRunErrors = {
   /**
-   * Bad request (non-boolean wait, dataset empty or over the synchronous cap, unknown agent_version, invalid baseline, scorers no longer valid against the agent)
+   * Bad request (non-boolean wait, dataset empty or over the synchronous cap, unknown agent_version, invalid baseline, scorers no longer valid against the agent, a `tool_context` key that cannot become a header)
    */
   400: unknown;
   /**
@@ -11735,7 +11813,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'chain_limit' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -12777,6 +12855,11 @@ type ListGenerationsData = {
      *
      */
     initiator_generation_id?: string;
+    /**
+     * Filter by the continuation chain the generation belongs to. This is how a chain is expanded into its members — the chain record carries only their count.
+     *
+     */
+    chain_id?: string;
     /**
      * Filter by the orchestration run that dispatched the generation. This is how a run is traced back to what its agent nodes did — a node execution record stores no generation id.
      *
@@ -15414,6 +15497,10 @@ type CreateQuotaData = {
      * enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quota.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.
      */
     mode?: 'enforce' | 'monitor';
+    /**
+     * Only for metric cost_usd (400 on any other metric). What an enforce quota does when the current window is a pricing blackout — several metered events, none of them priced, so the aggregate is 0 however much was actually spent. block (the default) refuses new generations with 409 QUOTA_UNENFORCEABLE until pricing is configured; allow accepts the unmeasurable spend explicitly. Either way a quota_unpriced exception is filed. monitor-mode quotas never block regardless.
+     */
+    on_unpriced?: 'block' | 'allow';
   };
   path: {
     /**
@@ -15535,6 +15622,10 @@ type UpdateQuotaData = {
      * New mode
      */
     mode?: 'enforce' | 'monitor';
+    /**
+     * New pricing posture. Only for metric cost_usd (400 on any other metric); see the create operation for what block and allow mean.
+     */
+    on_unpriced?: 'block' | 'allow';
   };
   path: {
     /**

package/dist/index.d.mts

@@ -502,15 +502,15 @@ type Agent = {
    */
   tool_bindings?: Array<ToolBinding> | null;
   /**
-   * Maximum agent loop steps before stopping
+   * Maximum agent loop steps before stopping. The budget bounds a **turn**: a generation that pauses at `requires_action` and resumes after `submit-tool-outputs` continues the same turn and spends what is left of it, so a turn that arrives with nothing left completes with `stop_reason: "max_steps"` instead of calling the model again.
    */
   max_steps?: number | null;
   /**
-   * Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "tool_name": "my_tool" }`).
+   * 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?: unknown;
   /**
-   * Stop conditions
+   * 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.
    */
   stop_conditions?: Array<{
     [key: string]: unknown;
@@ -524,7 +524,7 @@ type Agent = {
    */
   guardrail_ids?: Array<string> | null;
   /**
-   * Per-step overrides
+   * Per-step overrides of `tool_choice` and `active_tool_ids`. Steps are numbered from the first step of the **turn**, and that numbering spans a `requires_action` pause — a rule fires once per turn, not once per resumption.
    */
   step_rules?: Array<{
     [key: string]: unknown;
@@ -593,6 +593,10 @@ type Agent = {
    * Agent-scope zero-retention setting. `null` (the default) inherits the project's `trace_content_mode`; `none` means this agent's trace and generation content is never persisted. An agent may tighten a storing project to `none` but cannot loosen a `none` project back to `full`.
    */
   trace_content_mode?: 'full' | 'none' | null;
+  /**
+   * What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
+   */
+  on_approval_expiry?: 'terminate' | 'react' | null;
   /**
    * Current config version. Starts at 1 and increments on every write that changes the config; each increment archives the new config as an `AgentVersion`. A write that changes nothing leaves it untouched.
    */
@@ -642,7 +646,7 @@ type AgentVersion = {
    */
   version?: number;
   /**
-   * The agent's configuration as it stood at this version: every mutable field of the `Agent` schema (`instructions`, `model`, `tool_bindings`, `max_steps`, `tool_choice`, `stop_conditions`, `active_tool_ids`, `step_rules`, `boundary_policy`, `temperature`, `knowledge_config`, `output_schema`, `max_context_messages`, `single_session_per_actor`, `guardrail_ids`, `ai_provider_id`, `model_route_id`, `name`), and none of its identity or bookkeeping fields (`id`, `project_id`, `version`, `active_release`, timestamps).
+   * The agent's configuration as it stood at this version: every mutable field of the `Agent` schema (`instructions`, `model`, `tool_bindings`, `max_steps`, `tool_choice`, `stop_conditions`, `active_tool_ids`, `step_rules`, `boundary_policy`, `temperature`, `knowledge_config`, `output_schema`, `max_context_messages`, `single_session_per_actor`, `on_approval_expiry`, `guardrail_ids`, `ai_provider_id`, `model_route_id`, `name`), and none of its identity or bookkeeping fields (`id`, `project_id`, `version`, `active_release`, timestamps).
    *
    * Deliberately open rather than a fixed schema: an archive written by an earlier release of the runtime reflects the agent surface **of its own time**, so it may carry fields the current schema no longer defines, or lack ones it has since gained. Knowledge retrieval is not part of the snapshot — a version records which `knowledge_config` applied, while the documents and memories it resolves keep their own histories and are pinned at generation time.
    */
@@ -718,9 +722,18 @@ 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" }`).
+   * 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?: 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": "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.
+   *
+   * 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.
+   */
   stop_conditions?: Array<{
     [key: string]: unknown;
   }>;
@@ -787,6 +800,10 @@ type CreateAgentRequest = {
    * Zero-retention opt-in for this agent. `null` inherits the project's setting; `none` means trace and generation content is never written. Setting `full` under a project whose own mode is `none` is refused with 400 — the project is a floor an agent may only tighten.
    */
   trace_content_mode?: 'full' | 'none' | null;
+  /**
+   * What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
+   */
+  on_approval_expiry?: 'terminate' | 'react' | null;
   /**
    * Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change.
    */
@@ -810,9 +827,18 @@ 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" }`).
+   * 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?: 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": "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.
+   *
+   * 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.
+   */
   stop_conditions?: Array<{
     [key: string]: unknown;
   }> | null;
@@ -879,6 +905,10 @@ type UpdateAgentRequest = {
    * Zero-retention opt-in for this agent. `null` inherits the project's setting; `none` means trace and generation content is never written. Setting `full` under a project whose own mode is `none` is refused with 400.
    */
   trace_content_mode?: 'full' | 'none' | null;
+  /**
+   * What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.
+   */
+  on_approval_expiry?: 'terminate' | 'react' | null;
   /**
    * Optional tag for the config version this write archives (e.g. `pre-tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.
    */
@@ -2443,7 +2473,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'chain_limit' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -2659,17 +2689,21 @@ type AgentResourceProperties = {
    */
   tool_choice?: unknown;
   /**
-   * Conditions that stop multi-step generation early. The loop stops when any condition is met.
+   * Conditions that stop the agent's work early — turn-scoped (`hasToolCall`) or chain-scoped (`maxChainGenerations`).
    */
   stop_conditions?: Array<{
     /**
-     * Condition type — currently `hasToolCall`
+     * Condition type — `hasToolCall` or `maxChainGenerations`
      */
     type?: string;
     /**
      * Tool name to match when type is `hasToolCall`
      */
     tool_name?: string | null;
+    /**
+     * Generations the continuation chain may reach when type is `maxChainGenerations`
+     */
+    max_generations?: number | null;
   }> | null;
   /**
    * Subset of the bound tools that are active
@@ -2736,6 +2770,10 @@ type AgentResourceProperties = {
    * Agent-scope zero-retention setting (`full` or `none`). `null` inherits the project's setting. `full` is refused when the project's own mode is `none`.
    */
   trace_content_mode?: string | null;
+  /**
+   * What happens when a held tool call expires un-approved: `terminate` (the default when null) ends the chain, `react` spawns a continuation that reports the staleness to the agent.
+   */
+  on_approval_expiry?: string | null;
   /**
    * Knowledge retrieval configuration. When set, relevant documents and memory entries are injected into every generation.
    */
@@ -2831,9 +2869,9 @@ type AiProviderResourceProperties = {
    */
   name: string;
   /**
-   * Provider type (e.g. openai, anthropic)
+   * Provider type
    */
-  provider: string;
+  provider: 'openai' | 'anthropic' | 'google' | 'xai' | 'groq' | 'ollama' | 'azure' | 'bedrock' | 'vertex' | 'gateway' | 'custom';
   /**
    * Default model identifier (e.g. gpt-4o, claude-3-7-sonnet)
    */
@@ -3394,7 +3432,7 @@ type WorkflowResourceProperties = {
   } | null;
 };
 /**
- * Creates a quota — a project-scoped cap that blocks (`enforce`) or reports (`monitor`) when a windowed aggregate is exceeded. `requests` quotas are enforced by the request middleware; `tokens`/`cost_usd` quotas at the pre-generation check. Mirrors the quotas REST contract; `scope`, `metric`, and `window` are immutable after creation (only `limit` and `mode` update).
+ * Creates a quota — a project-scoped cap that blocks (`enforce`) or reports (`monitor`) when a windowed aggregate is exceeded. `requests` quotas are enforced by the request middleware; `tokens`/`cost_usd` quotas at the pre-generation check. Mirrors the quotas REST contract; `scope`, `metric`, and `window` are immutable after creation (only `limit`, `mode`, and `on_unpriced` update).
  */
 type QuotaResourceProperties = {
   /**
@@ -3421,6 +3459,10 @@ type QuotaResourceProperties = {
    * enforce blocks with 429; monitor fires the webhook only
    */
   mode?: 'enforce' | 'monitor';
+  /**
+   * Only for metric cost_usd. What an enforce quota does over a pricing blackout — block (the default) refuses generations with 409 QUOTA_UNENFORCEABLE, allow accepts the unmeasurable spend. See the quotas REST contract.
+   */
+  on_unpriced?: 'block' | 'allow';
 };
 /**
  * Creates a guardrail — an action-class document (`class`/`guard`) that gates tool-call autonomy. Attach it to a tool or agent via that resource's `guardrail_ids` (a `{ "ref": … }` to this resource in the same template resolves to its physical id at deploy time). Mirrors the guardrails REST contract; `class`/`default_class`/`guard`/`escalate` are flattened here from the REST API's single `document` object.
@@ -3677,6 +3719,11 @@ type Generation = {
    *
    */
   initiator_generation_id?: string | null;
+  /**
+   * Public ID of the continuation chain this generation belongs to. Set on every member of a chain — the continuations and the root they descend from — and null on a generation that is not part of one.
+   *
+   */
+  chain_id?: string | null;
   /**
    * Type of the principal that started the generation
    */
@@ -3696,7 +3743,8 @@ type Generation = {
   completed_at?: Date | null;
   last_activity_at?: Date | null;
   /**
-   * Why the generation stopped (e.g. 'stop', 'error')
+   * Why the generation stopped. Either the model provider's own finish reason relayed unchanged ('stop', 'tool-calls', 'length', …) or one the platform names itself: 'max_steps' when the turn spent its whole step budget on tool calls, 'depth_guard' when a nested call exceeded the call depth, 'chain_limit' when a continuation chain reached its generation budget, or 'error' when the turn failed.
+   *
    */
   stop_reason?: string | null;
   /**
@@ -3917,6 +3965,10 @@ type GenerationTranscript = {
    *
    */
   status?: 'in_progress' | 'requires_action' | 'completed' | 'failed';
+  /**
+   * Why the generation stopped — the provider's finish reason, or one of the platform's own ('max_steps', 'depth_guard', 'chain_limit', 'error').
+   *
+   */
   stop_reason?: string | null;
   started_at?: Date;
   completed_at?: Date | null;
@@ -3926,7 +3978,7 @@ type GenerationTranscript = {
    */
   step_count?: number;
   /**
-   * The messages the turn was asked, as recorded. Message content is caller-owned and passed through verbatim. Null when the content was never stored, has been purged, or predates input recording.
+   * The messages the turn was asked, as recorded. Message content is caller-owned and passed through verbatim. Null when the content was never stored or has been purged.
    *
    */
   input?: Array<{
@@ -4568,6 +4620,10 @@ type OrchestrationNode = {
    * For loop nodes — number of items to process in parallel.
    */
   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.
+   */
+  context_keys?: Array<string> | null;
   /**
    * For poll nodes — wait between attempts. Accepts a friendly suffix form (`5s`, `30s`, `5m`, `2h`, `500ms`) or ISO 8601 (e.g. PT5S).
    *
@@ -5205,6 +5261,10 @@ type Quota = {
   window?: 'rolling_1m' | 'rolling_1h' | 'rolling_24h' | 'calendar_month';
   limit?: number;
   mode?: 'enforce' | 'monitor';
+  /**
+   * Pricing posture of a cost_usd quota over an unpriced blackout — block refuses generations, allow lets them through (the quota_unpriced exception is filed either way). Null for metrics with no pricing dependency.
+   */
+  on_unpriced?: 'block' | 'allow' | null;
   /**
    * Current fixed-window usage for the requests metric. Null for token/cost quotas (which aggregate the usage meter at check time rather than keeping a counter) and in list responses.
    */
@@ -5786,6 +5846,14 @@ type CallToolRequest = {
   input?: {
     [key: string]: unknown;
   };
+  /**
+   * Key/value context for this call, forwarded to the tool as `X-Naturali-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`.
+   *
+   */
+  tool_context?: {
+    [key: string]: string;
+  };
 };
 type Trace = {
   /**
@@ -8648,7 +8716,7 @@ type ListAuditEntriesData = {
      */
     resource_public_id?: string;
     /**
-     * SRN prefix match, e.g. `srn:{project}:secret:`. An entry written before an earlier prefix rename keeps its original SRN (the log is append-only), and an `srn:` prefix matches those too, so history stays reachable.
+     * SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN is never rewritten; the filter matches it as stored.
      */
     resource_srn?: string;
     /**
@@ -8722,7 +8790,7 @@ type ExportAuditEntriesData = {
      */
     resource_public_id?: string;
     /**
-     * SRN prefix match, e.g. `srn:{project}:secret:`. An entry written before an earlier prefix rename keeps its original SRN (the log is append-only), and an `srn:` prefix matches those too, so history stays reachable.
+     * SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN is never rewritten; the filter matches it as stored.
      */
     resource_srn?: string;
     /**
@@ -11530,6 +11598,16 @@ type StartEvalRunData = {
     metadata?: {
       [key: string]: unknown;
     };
+    /**
+     * Key/value context forwarded to every item's generation, so an agent whose tools authorize through `tool_context` is scored against the configuration it runs in production rather than with an empty bag. Each key is forwarded as one `X-Naturali-Context-<key>` header and resolves any `{{context:<key>}}` token in a bound tool's headers or `preset_parameters`.
+     *
+     * 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.
+     */
+    tool_context?: {
+      [key: string]: string;
+    };
   };
   path: {
     /**
@@ -11546,7 +11624,7 @@ type StartEvalRunData = {
 };
 type StartEvalRunErrors = {
   /**
-   * Bad request (non-boolean wait, dataset empty or over the synchronous cap, unknown agent_version, invalid baseline, scorers no longer valid against the agent)
+   * Bad request (non-boolean wait, dataset empty or over the synchronous cap, unknown agent_version, invalid baseline, scorers no longer valid against the agent, a `tool_context` key that cannot become a header)
    */
   400: unknown;
   /**
@@ -11735,7 +11813,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'chain_limit' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -12777,6 +12855,11 @@ type ListGenerationsData = {
      *
      */
     initiator_generation_id?: string;
+    /**
+     * Filter by the continuation chain the generation belongs to. This is how a chain is expanded into its members — the chain record carries only their count.
+     *
+     */
+    chain_id?: string;
     /**
      * Filter by the orchestration run that dispatched the generation. This is how a run is traced back to what its agent nodes did — a node execution record stores no generation id.
      *
@@ -15414,6 +15497,10 @@ type CreateQuotaData = {
      * enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quota.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.
      */
     mode?: 'enforce' | 'monitor';
+    /**
+     * Only for metric cost_usd (400 on any other metric). What an enforce quota does when the current window is a pricing blackout — several metered events, none of them priced, so the aggregate is 0 however much was actually spent. block (the default) refuses new generations with 409 QUOTA_UNENFORCEABLE until pricing is configured; allow accepts the unmeasurable spend explicitly. Either way a quota_unpriced exception is filed. monitor-mode quotas never block regardless.
+     */
+    on_unpriced?: 'block' | 'allow';
   };
   path: {
     /**
@@ -15535,6 +15622,10 @@ type UpdateQuotaData = {
      * New mode
      */
     mode?: 'enforce' | 'monitor';
+    /**
+     * New pricing posture. Only for metric cost_usd (400 on any other metric); see the create operation for what block and allow mean.
+     */
+    on_unpriced?: 'block' | 'allow';
   };
   path: {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.85.1",
+  "version": "0.85.2",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "sideEffects": false,
@@ -37,7 +37,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/api": "0.85.1"
+    "@naturali/api": "0.85.2"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",