@soat/sdk 0.54.0 → 0.56.0

package/dist/index.d.cts

@@ -482,7 +482,15 @@ type Agent = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
     /**
      * Public ID of the memory store the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
@@ -678,7 +686,15 @@ type CreateAgentRequest = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
     /**
      * Public ID of the memory store the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
@@ -768,7 +784,15 @@ type UpdateAgentRequest = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
     /**
      * Public ID of the memory store the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
@@ -869,7 +893,15 @@ type CreateAgentGenerationRequest = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
   } | null;
 };
@@ -1542,6 +1574,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 = {
   /**
@@ -4701,14 +4737,15 @@ type OrchestrationNode = {
     [key: string]: unknown;
   };
   /**
-   * Maps state write paths to values. Each key is a `state.<path>` destination (the `state.` prefix is optional); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ "output": <node artifact>, "state": <run state> }` — e.g. `{ "summary": {"var": "output.content"} }` writes the artifact's `content` field to `state.summary`. The same evaluator as input_mapping/transform/condition; only the context differs.
+   * Maps state write paths to values. Each key is a `state.<path>` destination (the `state.` prefix is optional); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ "output": <node artifact>, "state": <run state> }` — e.g. `{ "summary": {"var": "output.content"} }` writes the artifact's `content` field to `state.summary`. The same evaluator as input_mapping/transform/condition; only the context differs. An `agent` node's artifact always carries both `content` (the text response) and `object` (the parsed value when a schema applied, `null` otherwise), so `output.content` reads the same whether or not the node declares an `output_schema`.
    *
    */
   state_mapping?: {
     [key: string]: unknown;
   };
   /**
-   * For agent nodes — JSON Schema for structured output parsing.
+   * For agent nodes — JSON Schema the model's answer is parsed into, reaching the artifact as `object`. Declaring it here is only needed for an agent that carries no `output_schema` of its own: the agent's schema already produces the artifact's `object` wherever that agent generates.
+   *
    */
   output_schema?: {
     [key: string]: unknown;
@@ -5077,6 +5114,11 @@ type NodeExecution = {
    *
    */
   attempt: number;
+  /**
+   * How many times this attempt was dispatched, including the first. A worker that stops mid-node leaves its task to be redelivered, and the redelivery re-runs the node under this same record — so a count above 1 is work the run issued, and was billed for, more than once.
+   *
+   */
+  dispatches: number;
   /**
    * Node execution status. `running` marks an execution record whose node is still in flight. Open set — new statuses may be added in minor releases; clients must tolerate unknown values.
    */
@@ -5267,6 +5309,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.
    */
@@ -5642,6 +5688,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;
@@ -9345,6 +9393,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;
@@ -9448,6 +9500,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: {
     /**
@@ -9855,7 +9911,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;
@@ -11463,6 +11519,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.
      *
@@ -15437,6 +15497,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.
      */

package/dist/index.d.mts

@@ -482,7 +482,15 @@ type Agent = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
     /**
      * Public ID of the memory store the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
@@ -678,7 +686,15 @@ type CreateAgentRequest = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
     /**
      * Public ID of the memory store the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
@@ -768,7 +784,15 @@ type UpdateAgentRequest = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
     /**
      * Public ID of the memory store the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
@@ -869,7 +893,15 @@ type CreateAgentGenerationRequest = {
      * Key-value pairs a result's own `tags` must all contain (exact match). Scopes documents and memories alike.
      */
     tags?: TagBag;
+    /**
+     * Minimum raw cosine similarity (0–1) a vector candidate must reach to be ranked, the floor the search endpoint spells `min_similarity`. No default: omitted means no floor at all, and every one of the `limit` nearest chunks is injected however weak it is.
+     *
+     */
     min_score?: number;
+    /**
+     * Maximum number of results to inject. Omitted, 10 are injected.
+     *
+     */
     limit?: number;
   } | null;
 };
@@ -1542,6 +1574,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 = {
   /**
@@ -4701,14 +4737,15 @@ type OrchestrationNode = {
     [key: string]: unknown;
   };
   /**
-   * Maps state write paths to values. Each key is a `state.<path>` destination (the `state.` prefix is optional); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ "output": <node artifact>, "state": <run state> }` — e.g. `{ "summary": {"var": "output.content"} }` writes the artifact's `content` field to `state.summary`. The same evaluator as input_mapping/transform/condition; only the context differs.
+   * Maps state write paths to values. Each key is a `state.<path>` destination (the `state.` prefix is optional); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ "output": <node artifact>, "state": <run state> }` — e.g. `{ "summary": {"var": "output.content"} }` writes the artifact's `content` field to `state.summary`. The same evaluator as input_mapping/transform/condition; only the context differs. An `agent` node's artifact always carries both `content` (the text response) and `object` (the parsed value when a schema applied, `null` otherwise), so `output.content` reads the same whether or not the node declares an `output_schema`.
    *
    */
   state_mapping?: {
     [key: string]: unknown;
   };
   /**
-   * For agent nodes — JSON Schema for structured output parsing.
+   * For agent nodes — JSON Schema the model's answer is parsed into, reaching the artifact as `object`. Declaring it here is only needed for an agent that carries no `output_schema` of its own: the agent's schema already produces the artifact's `object` wherever that agent generates.
+   *
    */
   output_schema?: {
     [key: string]: unknown;
@@ -5077,6 +5114,11 @@ type NodeExecution = {
    *
    */
   attempt: number;
+  /**
+   * How many times this attempt was dispatched, including the first. A worker that stops mid-node leaves its task to be redelivered, and the redelivery re-runs the node under this same record — so a count above 1 is work the run issued, and was billed for, more than once.
+   *
+   */
+  dispatches: number;
   /**
    * Node execution status. `running` marks an execution record whose node is still in flight. Open set — new statuses may be added in minor releases; clients must tolerate unknown values.
    */
@@ -5267,6 +5309,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.
    */
@@ -5642,6 +5688,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;
@@ -9345,6 +9393,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;
@@ -9448,6 +9500,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: {
     /**
@@ -9855,7 +9911,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;
@@ -11463,6 +11519,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.
      *
@@ -15437,6 +15497,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.
      */

package/package.json

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