@soat/sdk 0.53.0 → 0.55.0

package/dist/index.cjs

@@ -623,7 +623,7 @@ var Activity = class {
 	/**
 	* List activity feed entries
 	*
-	* Returns activity entries for a project, newest first, filterable by kind and severity. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
+	* Returns activity entries for a project, newest first, filterable by kind, severity, agent, generation and orchestration run — every filter composable with the rest. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
 	*/
 	static listActivity(options) {
 		return (options?.client ?? client).get({

package/dist/index.d.cts

@@ -347,7 +347,7 @@ type ActivityEntry = {
    */
   summary?: string;
   /**
-   * Kind-specific structured context (tool, args digest, node id, generation id, guardrail policy version)
+   * Kind-specific structured context (tool, args digest, node id, guardrail policy version)
    */
   detail?: {
     [key: string]: unknown;
@@ -360,6 +360,10 @@ type ActivityEntry = {
    * Associated agent, if any
    */
   agent_id?: string | null;
+  /**
+   * The agent generation the entry was produced during, if any. Filter on it with the `generation_id` query parameter to read everything one turn did.
+   */
+  generation_id?: string | null;
   /**
    * Producer-specific reference (the approval, exception, or trigger firing id the entry came from, or the executed tool's id)
    */
@@ -1538,6 +1542,10 @@ type ConversationRecord = {
    * Actor ID associated with this conversation
    */
   actor_id?: string | null;
+  /**
+   * Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`.
+   */
+  retrieval?: 'embed' | 'none' | null;
 };
 type ConversationMessageRecord = {
   /**
@@ -5004,6 +5012,10 @@ type OrchestrationRun = {
   metadata?: {
     [key: string]: unknown;
   } | null;
+  /**
+   * The deduplication key the run was started under, unique within the project and claimed for as long as the run record exists. Null for a run started without one, which every platform-started run is.
+   */
+  idempotency_key?: string | null;
   /**
    * The run whose node started this one — set only on a child a `loop` or `sub_orchestration` node spawned, null for a run a caller started. A child is its own run with its own usage events, so this is what makes a delegated run's spend attributable to the run that ordered it.
    */
@@ -5180,6 +5192,14 @@ type StartOrchestrationRunRequest = {
   metadata?: {
     [key: string]: unknown;
   };
+  /**
+   * Deduplication key, unique within the project, that makes a retry of an ambiguous failure safe. The first request under a key starts the run and answers `201`; any later request carrying the same key answers `200` with that same run, whatever state it has reached — including a retry that arrives while the original is still running.
+   *
+   * The key is claimed by the run record and stays claimed for as long as the record exists, so it never silently expires and lets a second run through.
+   *
+   * `orchestration_id`, `input`, `tool_context` and `metadata` are the request the key names: reusing a key with any of them changed is `409 IDEMPOTENCY_KEY_REUSED` rather than a replay of a run that does something else. `wait` is not part of that comparison — it says how the caller waits, not what the run is — so a retry may flip it.
+   */
+  idempotency_key?: string;
   /**
    * When true, block until the run reaches a terminal (succeeded/failed) or awaiting_input state and return the settled run. When false (default), return immediately with status "queued" and execute the run in the background.
    */
@@ -5251,6 +5271,10 @@ type ProjectRecord = {
    * Whether `GET` requests naming this project are recorded in the audit log. `false` by default — v1 audits mutations only.
    */
   audit_reads_enabled?: boolean;
+  /**
+   * What a conversation that names no `retrieval` of its own does. `none` by default.
+   */
+  default_conversation_retrieval?: 'embed' | 'none';
   /**
    * Days of trace/generation content retention before the daily sweep purges it. `null` means retention is disabled (the default) and content is kept until purged on demand.
    */
@@ -5626,6 +5650,8 @@ type SubmitSessionToolOutputsRequest = {
 };
 /**
  * Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.
+ *
+ * Keys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.
  */
 type TagBag = {
   [key: string]: string;
@@ -7141,6 +7167,18 @@ type ListActivityData = {
      * Filter by severity
      */
     severity?: 'info' | 'warning' | 'critical';
+    /**
+     * Filter to entries produced by one agent. Composable with every other filter — entries carry one agent, one generation and one run, so naming two narrows to the rows where both hold.
+     */
+    agent_id?: string;
+    /**
+     * Filter to entries produced during one agent generation. This is what turns `tool_resolution_failed` from alertable into usable: the warning for a suspect turn is one query rather than a scan of the project's feed.
+     */
+    generation_id?: string;
+    /**
+     * Filter to entries produced during one orchestration run.
+     */
+    orchestration_run_id?: string;
     /**
      * Opaque cursor from a previous page's `next_cursor`
      */
@@ -9317,6 +9355,10 @@ type CreateConversationData = {
      * Actor ID to associate with this conversation
      */
     actor_id?: string | null;
+    /**
+     * Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`.
+     */
+    retrieval?: 'embed' | 'none' | null;
   };
   path?: never;
   query?: never;
@@ -9420,6 +9462,10 @@ type UpdateConversationData = {
      * New conversation name
      */
     name?: string | null;
+    /**
+     * Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`. Switching it on embeds the turns already in the conversation, so the whole conversation becomes retrievable rather than only what is said next.
+     */
+    retrieval?: 'embed' | 'none' | null;
   };
   path: {
     /**
@@ -9827,7 +9873,7 @@ type CreateDocumentData = {
     project_id?: string;
     content: string;
     /**
-     * Logical path within the project (e.g. /reports/q1.txt). Defaults to /filename if omitted.
+     * Logical path within the project (e.g. /reports/q1.txt). Defaults to `/<filename>`, or to `/<document_id>.txt` when neither is given — a document with no path is reachable only by its id, since a prefix filter never matches null.
      */
     path?: string;
     filename?: string;
@@ -11435,6 +11481,10 @@ type ListFilesData = {
      * Filter files by project ID
      */
     project_id?: string;
+    /**
+     * Only files under this directory. The prefix is a path boundary, not a substring: `/reports` returns `/reports/q1.txt` and never `/reports-archive/q1.txt`, and `/` selects the whole project. A leading slash is optional and a trailing one is ignored, so `reports`, `/reports` and `/reports/` are the same filter. `%` and `_` are literal characters, not wildcards. Naming a directory under `/.system/` is what includes platform-written files, which a list without this parameter leaves out.
+     */
+    path_prefix?: string;
     /**
      * Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.
      *
@@ -14852,7 +14902,7 @@ type StartOrchestrationRunData = {
 };
 type StartOrchestrationRunErrors = {
   /**
-   * Validation error (e.g. a `tool_context` key that cannot become a header, or `metadata` that is not a JSON object). No run is created.
+   * Validation error (e.g. a `tool_context` key that cannot become a header, `metadata` that is not a JSON object, or an `idempotency_key` that is not a non-empty string of at most 255 characters). No run is created.
    */
   400: unknown;
   /**
@@ -14867,8 +14917,16 @@ type StartOrchestrationRunErrors = {
    * Orchestration not found
    */
   404: unknown;
+  /**
+   * `IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a run started from a different request. No run is created.
+   */
+  409: unknown;
 };
 type StartOrchestrationRunResponses = {
+  /**
+   * Duplicate request — the run the `idempotency_key` already names is returned and no second run is started.
+   */
+  200: OrchestrationRun;
   /**
    * Run created and executed
    */
@@ -15401,6 +15459,10 @@ type UpdateProjectData = {
      * Opt the project into read auditing. When true, `GET` requests that name this project are recorded in the audit log alongside mutations. Defaults to `false`.
      */
     audit_reads_enabled?: boolean;
+    /**
+     * What a conversation that names no `retrieval` of its own does. `none` by default: a turn is embedded because someone asked for the conversation to be retrievable, never merely because it was said. Turns are stored and chunked on both settings.
+     */
+    default_conversation_retrieval?: 'embed' | 'none';
     /**
      * How long trace and generation content is kept before the daily retention sweep content-purges it. `null` (the default) disables retention; otherwise an integer >= 1. The sweep uses the same purge path as `DELETE /traces/{trace_id}/content`, so the row survives as an auditable skeleton with `content_redacted_at` set.
      */
@@ -18699,7 +18761,7 @@ export declare class Activity {
   /**
    * List activity feed entries
    *
-   * Returns activity entries for a project, newest first, filterable by kind and severity. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
+   * Returns activity entries for a project, newest first, filterable by kind, severity, agent, generation and orchestration run — every filter composable with the rest. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
    */
   static listActivity<ThrowOnError extends boolean = false>(options?: Options<ListActivityData, ThrowOnError>): RequestResult<ListActivityResponses, ListActivityErrors, ThrowOnError>;
 }

package/dist/index.d.mts

@@ -347,7 +347,7 @@ type ActivityEntry = {
    */
   summary?: string;
   /**
-   * Kind-specific structured context (tool, args digest, node id, generation id, guardrail policy version)
+   * Kind-specific structured context (tool, args digest, node id, guardrail policy version)
    */
   detail?: {
     [key: string]: unknown;
@@ -360,6 +360,10 @@ type ActivityEntry = {
    * Associated agent, if any
    */
   agent_id?: string | null;
+  /**
+   * The agent generation the entry was produced during, if any. Filter on it with the `generation_id` query parameter to read everything one turn did.
+   */
+  generation_id?: string | null;
   /**
    * Producer-specific reference (the approval, exception, or trigger firing id the entry came from, or the executed tool's id)
    */
@@ -1538,6 +1542,10 @@ type ConversationRecord = {
    * Actor ID associated with this conversation
    */
   actor_id?: string | null;
+  /**
+   * Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`.
+   */
+  retrieval?: 'embed' | 'none' | null;
 };
 type ConversationMessageRecord = {
   /**
@@ -5004,6 +5012,10 @@ type OrchestrationRun = {
   metadata?: {
     [key: string]: unknown;
   } | null;
+  /**
+   * The deduplication key the run was started under, unique within the project and claimed for as long as the run record exists. Null for a run started without one, which every platform-started run is.
+   */
+  idempotency_key?: string | null;
   /**
    * The run whose node started this one — set only on a child a `loop` or `sub_orchestration` node spawned, null for a run a caller started. A child is its own run with its own usage events, so this is what makes a delegated run's spend attributable to the run that ordered it.
    */
@@ -5180,6 +5192,14 @@ type StartOrchestrationRunRequest = {
   metadata?: {
     [key: string]: unknown;
   };
+  /**
+   * Deduplication key, unique within the project, that makes a retry of an ambiguous failure safe. The first request under a key starts the run and answers `201`; any later request carrying the same key answers `200` with that same run, whatever state it has reached — including a retry that arrives while the original is still running.
+   *
+   * The key is claimed by the run record and stays claimed for as long as the record exists, so it never silently expires and lets a second run through.
+   *
+   * `orchestration_id`, `input`, `tool_context` and `metadata` are the request the key names: reusing a key with any of them changed is `409 IDEMPOTENCY_KEY_REUSED` rather than a replay of a run that does something else. `wait` is not part of that comparison — it says how the caller waits, not what the run is — so a retry may flip it.
+   */
+  idempotency_key?: string;
   /**
    * When true, block until the run reaches a terminal (succeeded/failed) or awaiting_input state and return the settled run. When false (default), return immediately with status "queued" and execute the run in the background.
    */
@@ -5251,6 +5271,10 @@ type ProjectRecord = {
    * Whether `GET` requests naming this project are recorded in the audit log. `false` by default — v1 audits mutations only.
    */
   audit_reads_enabled?: boolean;
+  /**
+   * What a conversation that names no `retrieval` of its own does. `none` by default.
+   */
+  default_conversation_retrieval?: 'embed' | 'none';
   /**
    * Days of trace/generation content retention before the daily sweep purges it. `null` means retention is disabled (the default) and content is kept until purged on demand.
    */
@@ -5626,6 +5650,8 @@ type SubmitSessionToolOutputsRequest = {
 };
 /**
  * Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.
+ *
+ * Keys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.
  */
 type TagBag = {
   [key: string]: string;
@@ -7141,6 +7167,18 @@ type ListActivityData = {
      * Filter by severity
      */
     severity?: 'info' | 'warning' | 'critical';
+    /**
+     * Filter to entries produced by one agent. Composable with every other filter — entries carry one agent, one generation and one run, so naming two narrows to the rows where both hold.
+     */
+    agent_id?: string;
+    /**
+     * Filter to entries produced during one agent generation. This is what turns `tool_resolution_failed` from alertable into usable: the warning for a suspect turn is one query rather than a scan of the project's feed.
+     */
+    generation_id?: string;
+    /**
+     * Filter to entries produced during one orchestration run.
+     */
+    orchestration_run_id?: string;
     /**
      * Opaque cursor from a previous page's `next_cursor`
      */
@@ -9317,6 +9355,10 @@ type CreateConversationData = {
      * Actor ID to associate with this conversation
      */
     actor_id?: string | null;
+    /**
+     * Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`.
+     */
+    retrieval?: 'embed' | 'none' | null;
   };
   path?: never;
   query?: never;
@@ -9420,6 +9462,10 @@ type UpdateConversationData = {
      * New conversation name
      */
     name?: string | null;
+    /**
+     * Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`. Switching it on embeds the turns already in the conversation, so the whole conversation becomes retrievable rather than only what is said next.
+     */
+    retrieval?: 'embed' | 'none' | null;
   };
   path: {
     /**
@@ -9827,7 +9873,7 @@ type CreateDocumentData = {
     project_id?: string;
     content: string;
     /**
-     * Logical path within the project (e.g. /reports/q1.txt). Defaults to /filename if omitted.
+     * Logical path within the project (e.g. /reports/q1.txt). Defaults to `/<filename>`, or to `/<document_id>.txt` when neither is given — a document with no path is reachable only by its id, since a prefix filter never matches null.
      */
     path?: string;
     filename?: string;
@@ -11435,6 +11481,10 @@ type ListFilesData = {
      * Filter files by project ID
      */
     project_id?: string;
+    /**
+     * Only files under this directory. The prefix is a path boundary, not a substring: `/reports` returns `/reports/q1.txt` and never `/reports-archive/q1.txt`, and `/` selects the whole project. A leading slash is optional and a trailing one is ignored, so `reports`, `/reports` and `/reports/` are the same filter. `%` and `_` are literal characters, not wildcards. Naming a directory under `/.system/` is what includes platform-written files, which a list without this parameter leaves out.
+     */
+    path_prefix?: string;
     /**
      * Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.
      *
@@ -14852,7 +14902,7 @@ type StartOrchestrationRunData = {
 };
 type StartOrchestrationRunErrors = {
   /**
-   * Validation error (e.g. a `tool_context` key that cannot become a header, or `metadata` that is not a JSON object). No run is created.
+   * Validation error (e.g. a `tool_context` key that cannot become a header, `metadata` that is not a JSON object, or an `idempotency_key` that is not a non-empty string of at most 255 characters). No run is created.
    */
   400: unknown;
   /**
@@ -14867,8 +14917,16 @@ type StartOrchestrationRunErrors = {
    * Orchestration not found
    */
   404: unknown;
+  /**
+   * `IDEMPOTENCY_KEY_REUSED` — the key is already claimed by a run started from a different request. No run is created.
+   */
+  409: unknown;
 };
 type StartOrchestrationRunResponses = {
+  /**
+   * Duplicate request — the run the `idempotency_key` already names is returned and no second run is started.
+   */
+  200: OrchestrationRun;
   /**
    * Run created and executed
    */
@@ -15401,6 +15459,10 @@ type UpdateProjectData = {
      * Opt the project into read auditing. When true, `GET` requests that name this project are recorded in the audit log alongside mutations. Defaults to `false`.
      */
     audit_reads_enabled?: boolean;
+    /**
+     * What a conversation that names no `retrieval` of its own does. `none` by default: a turn is embedded because someone asked for the conversation to be retrievable, never merely because it was said. Turns are stored and chunked on both settings.
+     */
+    default_conversation_retrieval?: 'embed' | 'none';
     /**
      * How long trace and generation content is kept before the daily retention sweep content-purges it. `null` (the default) disables retention; otherwise an integer >= 1. The sweep uses the same purge path as `DELETE /traces/{trace_id}/content`, so the row survives as an auditable skeleton with `content_redacted_at` set.
      */
@@ -18699,7 +18761,7 @@ export declare class Activity {
   /**
    * List activity feed entries
    *
-   * Returns activity entries for a project, newest first, filterable by kind and severity. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
+   * Returns activity entries for a project, newest first, filterable by kind, severity, agent, generation and orchestration run — every filter composable with the rest. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
    */
   static listActivity<ThrowOnError extends boolean = false>(options?: Options<ListActivityData, ThrowOnError>): RequestResult<ListActivityResponses, ListActivityErrors, ThrowOnError>;
 }

package/dist/index.mjs

@@ -622,7 +622,7 @@ var Activity = class {
 	/**
 	* List activity feed entries
 	*
-	* Returns activity entries for a project, newest first, filterable by kind and severity. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
+	* Returns activity entries for a project, newest first, filterable by kind, severity, agent, generation and orchestration run — every filter composable with the rest. Paginated with an opaque cursor rather than offset/limit — pass the previous page's `next_cursor` to fetch the next one; a `null` `next_cursor` means there is no more data.
 	*/
 	static listActivity(options) {
 		return (options?.client ?? client).get({

package/package.json

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