@soat/sdk 0.58.7 → 0.59.0

package/dist/index.cjs

@@ -832,7 +832,7 @@ var Agents = class {
 	/**
 	* Run an agent generation
 	*
-	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
 	*
 	*/
 	static createAgentGeneration(options) {

package/dist/index.d.cts

@@ -914,6 +914,12 @@ type CreateAgentGenerationRequest = {
    * Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary) lives in its own top-level generation fields and cannot be written from here. Use the request's own `action_id` field to set the usage-attribution label.
    */
   metadata?: NullableMetadataBag;
+  /**
+   * Deduplication key, unique within the project, that makes a retry of an at-least-once delivery or an ambiguous failure safe. The first request under a key runs the generation; any later request carrying it runs nothing and answers `202` with the generation the key names, whatever state it has reached — including a retry that arrives while the original is still running. The key is claimed by the generation record for as long as the record exists.
+   *
+   * Every other body field except `stream` is the request the key names: reusing a key with any of them changed, or on another agent of the project, is `409 IDEMPOTENCY_KEY_REUSED`. `stream` and `wait` say how the caller receives the generation, not what it is, so a retry may flip them.
+   */
+  idempotency_key?: string;
   /**
    * Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, rrf_k, recency_half_life_days, limit) use the per-generation value when present.
    */
@@ -3014,7 +3020,7 @@ type TriggerResourceProperties = {
     [key: string]: unknown;
   } | null;
   /**
-   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:...}}` reference, which is what a template should carry — the credential stays in the secret store and only its name is checked in
+   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:sec_...}}` reference, which is what a template should carry — the credential stays in the secret store and only its id is checked in (a `sub` such as `{{secret:${MySecret}}}` for a template secret); a secret's name does not resolve and is refused
    */
   tool_context?: {
     [key: string]: string;
@@ -3866,6 +3872,10 @@ type Generation = {
      */
     estimated_tokens?: number;
   } | null;
+  /**
+   * The deduplication key the generation was started under, unique within the project and claimed for as long as the generation record exists. Null for a generation started without one.
+   */
+  idempotency_key?: string | null;
   /**
    * What the turn cost: token counts and `cost_usd` for every event metered against this generation. Present on the single-generation read; omitted from the listing, where it would be a query per row.
    *
@@ -4928,6 +4938,10 @@ type OrchestrationNode = {
    * For loop nodes — number of items to process in parallel.
    */
   parallelism?: number;
+  /**
+   * For loop nodes — what a failed item does. `fail` (the default) fails the node on the first item whose child run settles `failed`, `cancelled` or `expired`. `collect` keeps going: that item's entry in `results` becomes `{ "error": { "code", "message" }, "orchestration_run_id" }`, in its original position. Either way the artifact carries `failed_count`. A child run that could not be started (for example past the nesting depth bound) fails the node in both modes.
+   */
+  on_item_error?: 'fail' | 'collect';
   /**
    * 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. 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.
    */
@@ -6506,7 +6520,7 @@ type CreateTriggerRequest = {
    *
    * **Write-only.** It is accepted here and never returned on a read, so the record cannot be used to recover a value.
    *
-   * A value may be a `{{secret:...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its name on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference naming a secret that does not exist in this project is refused here rather than at fire time.
+   * A value may be a `{{secret:sec_...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its id on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference is refused here rather than at fire time when it is not in that id form (a secret's name does not resolve) or names a secret that does not exist in this project.
    *
    */
   tool_context?: {
@@ -8108,7 +8122,7 @@ type CreateAgentGenerationData = {
 };
 type CreateAgentGenerationErrors = {
   /**
-   * Bad Request
+   * Bad Request (e.g. an `idempotency_key` that is not a non-empty string of at most 255 characters)
    */
   400: ErrorResponse;
   /**
@@ -8123,6 +8137,10 @@ type CreateAgentGenerationErrors = {
    * Agent or AI provider not found
    */
   404: ErrorResponse;
+  /**
+   * `IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a generation started from a different request. Nothing runs.
+   */
+  409: ErrorResponse;
   /**
    * Upstream AI provider error (AI_PROVIDER_ERROR); model output that does not satisfy the agent's `output_schema` (OUTPUT_SCHEMA_VALIDATION_FAILED — the violated field is named in the message); or a model that wrote a tool invocation out as plain assistant text instead of calling the tool, so the tool never ran (TEXT_ENCODED_TOOL_CALL — `meta.tool_name` names the tool). The error `meta` includes the `generation_id` and `trace_id` of the failed generation for post-mortem debugging via GET /api/v1/generations/{generation_id}. Streaming requests report the provider error in a terminal SSE frame instead, since their status line is already on the wire.
    *
@@ -8136,7 +8154,7 @@ type CreateAgentGenerationResponses = {
    */
   200: AgentGenerationResponse;
   /**
-   * Generation accepted and running in the background (default, when `wait` is omitted or `false`). Poll `GET /api/v1/generations/{generation_id}` for the result.
+   * Generation accepted and running in the background (default, when `wait` is omitted or `false`), or — in every mode, streamed included — a duplicate request: the generation the `idempotency_key` already names is returned in whatever state it has reached and nothing runs. Poll `GET /api/v1/generations/{generation_id}` for the result.
    */
   202: AcceptedGenerationResponse;
 };
@@ -19924,7 +19942,7 @@ export declare class Agents {
   /**
    * Run an agent generation
    *
-   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
    *
    */
   static createAgentGeneration<ThrowOnError extends boolean = false>(options: Options<CreateAgentGenerationData, ThrowOnError>): RequestResult<CreateAgentGenerationResponses, CreateAgentGenerationErrors, ThrowOnError>;

package/dist/index.d.mts

@@ -914,6 +914,12 @@ type CreateAgentGenerationRequest = {
    * Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary) lives in its own top-level generation fields and cannot be written from here. Use the request's own `action_id` field to set the usage-attribution label.
    */
   metadata?: NullableMetadataBag;
+  /**
+   * Deduplication key, unique within the project, that makes a retry of an at-least-once delivery or an ambiguous failure safe. The first request under a key runs the generation; any later request carrying it runs nothing and answers `202` with the generation the key names, whatever state it has reached — including a retry that arrives while the original is still running. The key is claimed by the generation record for as long as the record exists.
+   *
+   * Every other body field except `stream` is the request the key names: reusing a key with any of them changed, or on another agent of the project, is `409 IDEMPOTENCY_KEY_REUSED`. `stream` and `wait` say how the caller receives the generation, not what it is, so a retry may flip them.
+   */
+  idempotency_key?: string;
   /**
    * Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, rrf_k, recency_half_life_days, limit) use the per-generation value when present.
    */
@@ -3014,7 +3020,7 @@ type TriggerResourceProperties = {
     [key: string]: unknown;
   } | null;
   /**
-   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:...}}` reference, which is what a template should carry — the credential stays in the secret store and only its name is checked in
+   * Caller context every firing forwards to the run it starts, so an agent whose tools authorize through `{{context:<key>}}` can be scheduled. Write-only. A value may be a `{{secret:sec_...}}` reference, which is what a template should carry — the credential stays in the secret store and only its id is checked in (a `sub` such as `{{secret:${MySecret}}}` for a template secret); a secret's name does not resolve and is refused
    */
   tool_context?: {
     [key: string]: string;
@@ -3866,6 +3872,10 @@ type Generation = {
      */
     estimated_tokens?: number;
   } | null;
+  /**
+   * The deduplication key the generation was started under, unique within the project and claimed for as long as the generation record exists. Null for a generation started without one.
+   */
+  idempotency_key?: string | null;
   /**
    * What the turn cost: token counts and `cost_usd` for every event metered against this generation. Present on the single-generation read; omitted from the listing, where it would be a query per row.
    *
@@ -4928,6 +4938,10 @@ type OrchestrationNode = {
    * For loop nodes — number of items to process in parallel.
    */
   parallelism?: number;
+  /**
+   * For loop nodes — what a failed item does. `fail` (the default) fails the node on the first item whose child run settles `failed`, `cancelled` or `expired`. `collect` keeps going: that item's entry in `results` becomes `{ "error": { "code", "message" }, "orchestration_run_id" }`, in its original position. Either way the artifact carries `failed_count`. A child run that could not be started (for example past the nesting depth bound) fails the node in both modes.
+   */
+  on_item_error?: 'fail' | 'collect';
   /**
    * 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. 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.
    */
@@ -6506,7 +6520,7 @@ type CreateTriggerRequest = {
    *
    * **Write-only.** It is accepted here and never returned on a read, so the record cannot be used to recover a value.
    *
-   * A value may be a `{{secret:...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its name on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference naming a secret that does not exist in this project is refused here rather than at fire time.
+   * A value may be a `{{secret:sec_...}}` reference, which keeps the credential in the [secret](/docs/modules/secrets) store and leaves only its id on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference is refused here rather than at fire time when it is not in that id form (a secret's name does not resolve) or names a secret that does not exist in this project.
    *
    */
   tool_context?: {
@@ -8108,7 +8122,7 @@ type CreateAgentGenerationData = {
 };
 type CreateAgentGenerationErrors = {
   /**
-   * Bad Request
+   * Bad Request (e.g. an `idempotency_key` that is not a non-empty string of at most 255 characters)
    */
   400: ErrorResponse;
   /**
@@ -8123,6 +8137,10 @@ type CreateAgentGenerationErrors = {
    * Agent or AI provider not found
    */
   404: ErrorResponse;
+  /**
+   * `IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a generation started from a different request. Nothing runs.
+   */
+  409: ErrorResponse;
   /**
    * Upstream AI provider error (AI_PROVIDER_ERROR); model output that does not satisfy the agent's `output_schema` (OUTPUT_SCHEMA_VALIDATION_FAILED — the violated field is named in the message); or a model that wrote a tool invocation out as plain assistant text instead of calling the tool, so the tool never ran (TEXT_ENCODED_TOOL_CALL — `meta.tool_name` names the tool). The error `meta` includes the `generation_id` and `trace_id` of the failed generation for post-mortem debugging via GET /api/v1/generations/{generation_id}. Streaming requests report the provider error in a terminal SSE frame instead, since their status line is already on the wire.
    *
@@ -8136,7 +8154,7 @@ type CreateAgentGenerationResponses = {
    */
   200: AgentGenerationResponse;
   /**
-   * Generation accepted and running in the background (default, when `wait` is omitted or `false`). Poll `GET /api/v1/generations/{generation_id}` for the result.
+   * Generation accepted and running in the background (default, when `wait` is omitted or `false`), or — in every mode, streamed included — a duplicate request: the generation the `idempotency_key` already names is returned in whatever state it has reached and nothing runs. Poll `GET /api/v1/generations/{generation_id}` for the result.
    */
   202: AcceptedGenerationResponse;
 };
@@ -19924,7 +19942,7 @@ export declare class Agents {
   /**
    * Run an agent generation
    *
-   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+   * Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
    *
    */
   static createAgentGeneration<ThrowOnError extends boolean = false>(options: Options<CreateAgentGenerationData, ThrowOnError>): RequestResult<CreateAgentGenerationResponses, CreateAgentGenerationErrors, ThrowOnError>;

package/dist/index.mjs

@@ -831,7 +831,7 @@ var Agents = class {
 	/**
 	* Run an agent generation
 	*
-	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting.
+	* Sends messages to the agent, resolves its tools, and runs the AI model loop. Background by default: returns `202 Accepted` with a `generation_id` to poll via `GET /api/v1/generations/{generation_id}`. Pass `?wait=true` to block and receive the result inline, where client tools pause the generation and return `requires_action`. Streaming (`stream: true`) implies waiting. Pass `idempotency_key` to make a retry safe: a request whose key is already claimed runs nothing and answers `202` with the generation the key names.
 	*
 	*/
 	static createAgentGeneration(options) {

package/package.json

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