@soat/sdk 0.18.4 → 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

@@ -2217,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.
@@ -4334,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;
@@ -4377,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;
@@ -4422,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;
@@ -4453,7 +4474,7 @@ type Tool = {
     [key: string]: unknown;
   } | 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;
@@ -4491,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;
@@ -4542,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;
@@ -5199,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;
@@ -5833,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;
 };
@@ -12897,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;
   /**
@@ -15980,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

@@ -2217,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.
@@ -4334,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;
@@ -4377,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;
@@ -4422,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;
@@ -4453,7 +4474,7 @@ type Tool = {
     [key: string]: unknown;
   } | 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;
@@ -4491,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;
@@ -4542,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;
@@ -5199,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;
@@ -5833,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;
 };
@@ -12897,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;
   /**
@@ -15980,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.4",
+  "version": "0.18.5",
   "description": "TypeScript SDK for the SOAT API",
   "type": "module",
   "main": "dist/index.mjs",