@soat/sdk 0.18.3 → 0.18.5

package/dist/index.cjs

@@ -3173,7 +3173,7 @@ var Tasks = class {
 	/**
 	* Create a task
 	*
-	* Creates a task bound to a workflow. The task is placed in the workflow's initial state and that state's `on_enter` automation fires.
+	* Creates a task bound to a workflow. By default the task is placed in the workflow's initial state; passing `state` places it directly in that named state instead — an alternate entry point for starting a task mid-flow (e.g. "a new recorte for an existing theme by id"), rather than re-submitting from the initial state and hoping a guard or similarity gate recognizes it. Entering the resulting state, initial or named, behaves identically: that state's `on_enter` automation fires and its `stalled_after` clock arms.
 	*/
 	static createTask(options) {
 		return (options.client ?? client).post({

package/dist/index.d.cts

@@ -1597,13 +1597,9 @@ type DiscussionRunRecord = {
     [key: string]: unknown;
   } | null;
   /**
-   * Reserved for the generation that invoked this run as a tool. Not currently populated — see trace_id.
+   * Reserved for the generation that started this run. Not currently populated.
    */
   initiator_generation_id?: string | null;
-  /**
-   * Trace of the generation that invoked this run as a tool. Null for runs started directly via POST /discussions/{discussion_id}/runs.
-   */
-  trace_id?: string | null;
   completed_at?: Date | null;
   created_at?: Date;
   updated_at?: Date;
@@ -2221,6 +2217,16 @@ type ToolResourceProperties = {
     headers?: {
       [key: string]: unknown;
     } | null;
+    /**
+     * Request body encoding for `POST`/`PUT`/`PATCH`: `json` (default) or `multipart`. Incompatible with `auth.type: aws_sigv4`.
+     */
+    body_mode?: string | null;
+    /**
+     * Computed request credential. `type` is `aws_sigv4` (with `region`, `service`, `access_key_id`, `secret_access_key` and optional `session_token`) or `gcp_service_account` (with `credentials` and `scopes`). Credential fields accept `{{secret:...}}` references.
+     */
+    auth?: {
+      [key: string]: unknown;
+    } | null;
   } | null;
   /**
    * MCP server connection configuration. Required for `mcp` tools.
@@ -2257,10 +2263,6 @@ type ToolResourceProperties = {
   pipeline?: {
     [key: string]: unknown;
   } | null;
-  /**
-   * For `discussion` tools: the ID of the discussion to invoke.
-   */
-  discussion_id?: string | null;
   /**
    * Universal JSON Logic mapping applied to the tool's raw result, for every tool type. Evaluated over `{ output: <raw result> }`, e.g. `{ "var": "output.text" }`. For `pipeline` tools this runs after the pipeline's own `output` mapping.
    */
@@ -4342,7 +4344,7 @@ type Task = {
   };
   assignee?: string | null;
   /**
-   * { kind, id, status } of the current state's dispatch, if any.
+   * { kind, id, status } of the current state's dispatch, if any. Carries an additional `attempt` (1-based) while the state's `on_enter.retry` policy is in effect.
    */
   active_dispatch?: {
     [key: string]: unknown;
@@ -4385,6 +4387,10 @@ type CreateTaskRequest = {
     [key: string]: unknown;
   };
   assignee?: string | null;
+  /**
+   * Name of a declared workflow state to create the task in directly, instead of the workflow's `initial` state. Must name a state declared on the workflow, or the request is rejected with `TASK_STATE_NOT_FOUND` (400). Defaults to the `initial` state.
+   */
+  state?: string;
 };
 type UpdateTaskRequest = {
   title?: string;
@@ -4416,7 +4422,7 @@ type Tool = {
   /**
    * Tool type
    */
-  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline' | 'discussion';
+  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline';
   /**
    * What the tool does (sent to the model)
    */
@@ -4430,6 +4436,13 @@ type Tool = {
   /**
    * Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).
    *
+   * `auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:
+   *
+   * - `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.
+   * - `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.
+   *
+   * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
+   *
    */
   execute?: {
     [key: string]: unknown;
@@ -4461,11 +4474,7 @@ type Tool = {
     [key: string]: unknown;
   } | null;
   /**
-   * For `discussion` tools: the ID of the discussion to invoke. Calling the tool with a `topic` runs that discussion synchronously and returns its outcome + run id as the tool result.
-   */
-  discussion_id?: string | null;
-  /**
-   * Universal JSON Logic mapping applied to the tool's raw result, for every tool type (`http`, `mcp`, `soat`, `pipeline`, `client`). Evaluated over `{ output: <raw result> }`, so `{ "var": "output.text" }` extracts a bare scalar field instead of requiring a wrapping `pipeline` tool. For `pipeline` tools this runs *after* the pipeline's own `output` mapping, over that mapping's result.
+   * Universal JSON Logic mapping applied to the tool's raw result, for every tool type (`http`, `mcp`, `soat`, `pipeline`, `client`). Evaluated over `{ output: <raw result>, input: <merged input> }`, so `{ "var": "output.text" }` extracts a bare scalar field instead of requiring a wrapping `pipeline` tool, and `{ "var": "input.title" }` echoes back a field of the request that produced the response. For `pipeline` tools this runs *after* the pipeline's own `output` mapping, over that mapping's result.
    */
   output_mapping?: {
     [key: string]: unknown;
@@ -4489,7 +4498,7 @@ type CreateToolRequest = {
   /**
    * Tool type (default http)
    */
-  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline' | 'discussion';
+  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline';
   /**
    * What the tool does
    */
@@ -4503,6 +4512,13 @@ type CreateToolRequest = {
   /**
    * Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).
    *
+   * `auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:
+   *
+   * - `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.
+   * - `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.
+   *
+   * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
+   *
    */
   execute?: {
     [key: string]: unknown;
@@ -4533,10 +4549,6 @@ type CreateToolRequest = {
   pipeline?: {
     [key: string]: unknown;
   };
-  /**
-   * For `discussion` tools: the ID of the discussion to invoke.
-   */
-  discussion_id?: string;
   /**
    * Universal JSON Logic mapping applied to the tool's raw result. See the `output_mapping` field on the Tool schema for details.
    */
@@ -4558,6 +4570,13 @@ type UpdateToolRequest = {
   /**
    * Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).
    *
+   * `auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:
+   *
+   * - `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.
+   * - `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.
+   *
+   * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
+   *
    */
   execute?: {
     [key: string]: unknown;
@@ -4585,10 +4604,6 @@ type UpdateToolRequest = {
   pipeline?: {
     [key: string]: unknown;
   } | null;
-  /**
-   * For `discussion` tools: the ID of the discussion to invoke.
-   */
-  discussion_id?: string | null;
   /**
    * Universal JSON Logic mapping applied to the tool's raw result. See the `output_mapping` field on the Tool schema for details.
    */
@@ -5219,7 +5234,7 @@ type DeliveryListResponse = {
   offset?: number;
 };
 /**
- * A named state. Exactly one state must be `initial: true`; any number may be `terminal: true`. A `kind: human` state never dispatches — the task parks until a transition fires. `on_enter` (§5) dispatches one agent generation or orchestration run on entry.
+ * A named state. Exactly one state must be `initial: true`; any number may be `terminal: true`. A `kind: human` state never dispatches — the task parks until a transition fires. `on_enter` (§5) dispatches one agent generation or orchestration run on entry, optionally under a `retry` policy (`max_attempts` 1-10, `backoff_seconds`, `backoff_multiplier`) that re-runs execution failures before `on_failure` applies.
  */
 type WorkflowState = {
   name: string;
@@ -5853,7 +5868,8 @@ type DeleteAgentErrors = {
    */
   404: ErrorResponse;
   /**
-   * Agent has dependent generations or traces (pass `force=true` to delete anyway)
+   * 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.
+   *
    */
   409: ErrorResponse;
 };
@@ -12917,7 +12933,7 @@ type CreateTaskData = {
 };
 type CreateTaskErrors = {
   /**
-   * Bad request (invalid payload)
+   * Bad request — invalid payload (`TASK_PAYLOAD_INVALID`), or `state` does not name a declared state of the workflow (`TASK_STATE_NOT_FOUND`)
    */
   400: unknown;
   /**
@@ -16000,7 +16016,7 @@ declare class Tasks {
   /**
    * Create a task
    *
-   * Creates a task bound to a workflow. The task is placed in the workflow's initial state and that state's `on_enter` automation fires.
+   * Creates a task bound to a workflow. By default the task is placed in the workflow's initial state; passing `state` places it directly in that named state instead — an alternate entry point for starting a task mid-flow (e.g. "a new recorte for an existing theme by id"), rather than re-submitting from the initial state and hoping a guard or similarity gate recognizes it. Entering the resulting state, initial or named, behaves identically: that state's `on_enter` automation fires and its `stalled_after` clock arms.
    */
   static createTask<ThrowOnError extends boolean = false>(options: Options<CreateTaskData, ThrowOnError>): RequestResult<CreateTaskResponses, CreateTaskErrors, ThrowOnError>;
   /**

package/dist/index.d.mts

@@ -1597,13 +1597,9 @@ type DiscussionRunRecord = {
     [key: string]: unknown;
   } | null;
   /**
-   * Reserved for the generation that invoked this run as a tool. Not currently populated — see trace_id.
+   * Reserved for the generation that started this run. Not currently populated.
    */
   initiator_generation_id?: string | null;
-  /**
-   * Trace of the generation that invoked this run as a tool. Null for runs started directly via POST /discussions/{discussion_id}/runs.
-   */
-  trace_id?: string | null;
   completed_at?: Date | null;
   created_at?: Date;
   updated_at?: Date;
@@ -2221,6 +2217,16 @@ type ToolResourceProperties = {
     headers?: {
       [key: string]: unknown;
     } | null;
+    /**
+     * Request body encoding for `POST`/`PUT`/`PATCH`: `json` (default) or `multipart`. Incompatible with `auth.type: aws_sigv4`.
+     */
+    body_mode?: string | null;
+    /**
+     * Computed request credential. `type` is `aws_sigv4` (with `region`, `service`, `access_key_id`, `secret_access_key` and optional `session_token`) or `gcp_service_account` (with `credentials` and `scopes`). Credential fields accept `{{secret:...}}` references.
+     */
+    auth?: {
+      [key: string]: unknown;
+    } | null;
   } | null;
   /**
    * MCP server connection configuration. Required for `mcp` tools.
@@ -2257,10 +2263,6 @@ type ToolResourceProperties = {
   pipeline?: {
     [key: string]: unknown;
   } | null;
-  /**
-   * For `discussion` tools: the ID of the discussion to invoke.
-   */
-  discussion_id?: string | null;
   /**
    * Universal JSON Logic mapping applied to the tool's raw result, for every tool type. Evaluated over `{ output: <raw result> }`, e.g. `{ "var": "output.text" }`. For `pipeline` tools this runs after the pipeline's own `output` mapping.
    */
@@ -4342,7 +4344,7 @@ type Task = {
   };
   assignee?: string | null;
   /**
-   * { kind, id, status } of the current state's dispatch, if any.
+   * { kind, id, status } of the current state's dispatch, if any. Carries an additional `attempt` (1-based) while the state's `on_enter.retry` policy is in effect.
    */
   active_dispatch?: {
     [key: string]: unknown;
@@ -4385,6 +4387,10 @@ type CreateTaskRequest = {
     [key: string]: unknown;
   };
   assignee?: string | null;
+  /**
+   * Name of a declared workflow state to create the task in directly, instead of the workflow's `initial` state. Must name a state declared on the workflow, or the request is rejected with `TASK_STATE_NOT_FOUND` (400). Defaults to the `initial` state.
+   */
+  state?: string;
 };
 type UpdateTaskRequest = {
   title?: string;
@@ -4416,7 +4422,7 @@ type Tool = {
   /**
    * Tool type
    */
-  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline' | 'discussion';
+  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline';
   /**
    * What the tool does (sent to the model)
    */
@@ -4430,6 +4436,13 @@ type Tool = {
   /**
    * Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).
    *
+   * `auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:
+   *
+   * - `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.
+   * - `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.
+   *
+   * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
+   *
    */
   execute?: {
     [key: string]: unknown;
@@ -4461,11 +4474,7 @@ type Tool = {
     [key: string]: unknown;
   } | null;
   /**
-   * For `discussion` tools: the ID of the discussion to invoke. Calling the tool with a `topic` runs that discussion synchronously and returns its outcome + run id as the tool result.
-   */
-  discussion_id?: string | null;
-  /**
-   * Universal JSON Logic mapping applied to the tool's raw result, for every tool type (`http`, `mcp`, `soat`, `pipeline`, `client`). Evaluated over `{ output: <raw result> }`, so `{ "var": "output.text" }` extracts a bare scalar field instead of requiring a wrapping `pipeline` tool. For `pipeline` tools this runs *after* the pipeline's own `output` mapping, over that mapping's result.
+   * Universal JSON Logic mapping applied to the tool's raw result, for every tool type (`http`, `mcp`, `soat`, `pipeline`, `client`). Evaluated over `{ output: <raw result>, input: <merged input> }`, so `{ "var": "output.text" }` extracts a bare scalar field instead of requiring a wrapping `pipeline` tool, and `{ "var": "input.title" }` echoes back a field of the request that produced the response. For `pipeline` tools this runs *after* the pipeline's own `output` mapping, over that mapping's result.
    */
   output_mapping?: {
     [key: string]: unknown;
@@ -4489,7 +4498,7 @@ type CreateToolRequest = {
   /**
    * Tool type (default http)
    */
-  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline' | 'discussion';
+  type?: 'http' | 'client' | 'mcp' | 'soat' | 'pipeline';
   /**
    * What the tool does
    */
@@ -4503,6 +4512,13 @@ type CreateToolRequest = {
   /**
    * Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).
    *
+   * `auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:
+   *
+   * - `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.
+   * - `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.
+   *
+   * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
+   *
    */
   execute?: {
     [key: string]: unknown;
@@ -4533,10 +4549,6 @@ type CreateToolRequest = {
   pipeline?: {
     [key: string]: unknown;
   };
-  /**
-   * For `discussion` tools: the ID of the discussion to invoke.
-   */
-  discussion_id?: string;
   /**
    * Universal JSON Logic mapping applied to the tool's raw result. See the `output_mapping` field on the Tool schema for details.
    */
@@ -4558,6 +4570,13 @@ type UpdateToolRequest = {
   /**
    * Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).
    *
+   * `auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:
+   *
+   * - `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.
+   * - `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.
+   *
+   * Credential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.
+   *
    */
   execute?: {
     [key: string]: unknown;
@@ -4585,10 +4604,6 @@ type UpdateToolRequest = {
   pipeline?: {
     [key: string]: unknown;
   } | null;
-  /**
-   * For `discussion` tools: the ID of the discussion to invoke.
-   */
-  discussion_id?: string | null;
   /**
    * Universal JSON Logic mapping applied to the tool's raw result. See the `output_mapping` field on the Tool schema for details.
    */
@@ -5219,7 +5234,7 @@ type DeliveryListResponse = {
   offset?: number;
 };
 /**
- * A named state. Exactly one state must be `initial: true`; any number may be `terminal: true`. A `kind: human` state never dispatches — the task parks until a transition fires. `on_enter` (§5) dispatches one agent generation or orchestration run on entry.
+ * A named state. Exactly one state must be `initial: true`; any number may be `terminal: true`. A `kind: human` state never dispatches — the task parks until a transition fires. `on_enter` (§5) dispatches one agent generation or orchestration run on entry, optionally under a `retry` policy (`max_attempts` 1-10, `backoff_seconds`, `backoff_multiplier`) that re-runs execution failures before `on_failure` applies.
  */
 type WorkflowState = {
   name: string;
@@ -5853,7 +5868,8 @@ type DeleteAgentErrors = {
    */
   404: ErrorResponse;
   /**
-   * Agent has dependent generations or traces (pass `force=true` to delete anyway)
+   * 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.
+   *
    */
   409: ErrorResponse;
 };
@@ -12917,7 +12933,7 @@ type CreateTaskData = {
 };
 type CreateTaskErrors = {
   /**
-   * Bad request (invalid payload)
+   * Bad request — invalid payload (`TASK_PAYLOAD_INVALID`), or `state` does not name a declared state of the workflow (`TASK_STATE_NOT_FOUND`)
    */
   400: unknown;
   /**
@@ -16000,7 +16016,7 @@ declare class Tasks {
   /**
    * Create a task
    *
-   * Creates a task bound to a workflow. The task is placed in the workflow's initial state and that state's `on_enter` automation fires.
+   * Creates a task bound to a workflow. By default the task is placed in the workflow's initial state; passing `state` places it directly in that named state instead — an alternate entry point for starting a task mid-flow (e.g. "a new recorte for an existing theme by id"), rather than re-submitting from the initial state and hoping a guard or similarity gate recognizes it. Entering the resulting state, initial or named, behaves identically: that state's `on_enter` automation fires and its `stalled_after` clock arms.
    */
   static createTask<ThrowOnError extends boolean = false>(options: Options<CreateTaskData, ThrowOnError>): RequestResult<CreateTaskResponses, CreateTaskErrors, ThrowOnError>;
   /**

package/dist/index.mjs

@@ -3172,7 +3172,7 @@ var Tasks = class {
 	/**
 	* Create a task
 	*
-	* Creates a task bound to a workflow. The task is placed in the workflow's initial state and that state's `on_enter` automation fires.
+	* Creates a task bound to a workflow. By default the task is placed in the workflow's initial state; passing `state` places it directly in that named state instead — an alternate entry point for starting a task mid-flow (e.g. "a new recorte for an existing theme by id"), rather than re-submitting from the initial state and hoping a guard or similarity gate recognizes it. Entering the resulting state, initial or named, behaves identically: that state's `on_enter` automation fires and its `stalled_after` clock arms.
 	*/
 	static createTask(options) {
 		return (options.client ?? client).post({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/sdk",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "TypeScript SDK for the SOAT API",
   "type": "module",
   "main": "dist/index.mjs",