@soat/sdk 0.30.0 → 0.31.0

package/dist/index.d.cts

@@ -1879,6 +1879,12 @@ type EvalRun = {
   item_count?: number;
   completed_count?: number;
   errored_count?: number;
+  /**
+   * The caller-owned key/value metadata supplied when the run was started, returned verbatim. Null when the run was started without any (a trigger-started run included — see `trigger_id` for that provenance). The server writes nothing here.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   started_at?: Date | null;
   finished_at?: Date | null;
   created_at?: Date;
@@ -1916,7 +1922,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -2684,7 +2690,7 @@ type WebhookResourceProperties = {
   events: Array<string>;
 };
 /**
- * Binds a starter (manual, webhook, or schedule) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
+ * Binds a starter (manual, webhook, schedule, or event) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
  */
 type TriggerResourceProperties = {
   /**
@@ -2698,7 +2704,7 @@ type TriggerResourceProperties = {
   /**
    * Starter type. Immutable after creation
    */
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   /**
    * The kind of resource this trigger activates
    */
@@ -2721,6 +2727,10 @@ type TriggerResourceProperties = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern (`*`, `prefix.*`, or an exact event name). Required when type is event, rejected otherwise
+   */
+  event_pattern?: string | null;
   /**
    * Whether the trigger fires (default true)
    */
@@ -3095,9 +3105,12 @@ type GuardrailResourceProperties = {
 };
 type ResourceDeclaration = {
   /**
-   * Resource type
+   * Resource type. The built-in types are `ai_provider`, `tool`, `agent`, `actor`, `api_key`, `chat`, `conversation`, `dataset`, `dataset_item`, `document`, `file`, `guardrail`, `ingestion_rule`, `memory`, `memory_entry`, `model_route`, `eval`, `orchestration`, `policy`, `project_price`, `quota`, `secret`, `session`, `webhook`, `trigger` and `workflow`.
+   *
+   * This is deliberately not an enum: a deployment operator can register additional resource types backed by their own handler, and those are declared here exactly like a built-in one. The set a given deployment accepts is authoritative in the server, which rejects an unregistered type with `VALIDATION_FAILED` and lists what it does support.
+   *
    */
-  type: 'ai_provider' | 'tool' | 'agent' | 'actor' | 'api_key' | 'chat' | 'conversation' | 'dataset' | 'dataset_item' | 'document' | 'file' | 'guardrail' | 'ingestion_rule' | 'memory' | 'memory_entry' | 'model_route' | 'eval' | 'orchestration' | 'policy' | 'project_price' | 'quota' | 'secret' | 'session' | 'webhook' | 'trigger' | 'workflow';
+  type: string;
   /**
    * Resource properties, as authored in the template and echoed back verbatim. The allowed fields, required fields, and field types for each resource `type` are defined by the corresponding `<Type>ResourceProperties` schema in this document (e.g. `model_route` → `ModelRouteResourceProperties`), which the server enforces at validate/deploy time. The declaration itself is free-form here because property values may be substitution expressions rather than final values: `{ "ref": "logicalId" }` references another resource's physical ID, `{ "param": "ParamName" }` substitutes a parameter value, and `{ "sub": "text ${ParamName}" }` interpolates parameters into a string.
    *
@@ -4574,6 +4587,12 @@ type OrchestrationRun = {
   tool_context?: {
     [key: string]: string;
   } | null;
+  /**
+   * The caller-owned key/value metadata supplied at run creation, returned verbatim. Null when the run was started without any. The server writes nothing here and no key is reserved; the bag is never merged into `state`, so nothing in it reaches the graph.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -4712,6 +4731,16 @@ type StartRunRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read.
+   *
+   * The bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own `input` and accumulated `state`) lives in its own top-level field and cannot be written from here.
+   *
+   * It is **not** merged into run state: no graph node sees it, and an `input_schema` never has to tolerate it — which is what makes it the place for an infrastructural label, rather than `input`. Keys are never transformed. It is not inherited by the child runs a `loop` or `sub_orchestration` node starts; each child carries whatever the graph gives it, which today is nothing.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
   /**
    * 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.
    */
@@ -5155,6 +5184,12 @@ type Task = {
   payload?: {
     [key: string]: unknown;
   };
+  /**
+   * The caller-owned key/value metadata supplied when the task was created, returned verbatim. Null when the task was created without any. Unlike `payload` it is invisible to guards and to `payload_writes`, so it is the place for an attribution label rather than task data.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   /**
    * Server-owned. The result of the current state's last completed dispatch, overwritten on every dispatch. Read-only — exposed to transition guards and `on_complete`/`payload_writes` expressions as `task.last_result`, a namespace a caller cannot write.
    */
@@ -5235,6 +5270,16 @@ type CreateTaskRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own).
+   *
+   * The bag is caller-owned and no key is reserved: everything the engine decides about a task (`state`, `status`, `workflow_version`, `last_result`, `active_dispatch`, the automation fields) is a field of its own and cannot be written from here.
+   *
+   * Prefer this over `payload` for anything that is not task data: `payload` is read by every guard as `task.payload` and may be written by the workflow's declared `payload_writes`, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with `400 VALIDATION_FAILED` and no task is created.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
 };
 type UpdateTaskRequest = {
   title?: string;
@@ -5612,7 +5657,7 @@ type Trigger = {
   project_id?: string;
   name?: string;
   description?: string | null;
-  type?: 'manual' | 'webhook' | 'schedule';
+  type?: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
   /**
    * Public ID of the target resource (orchestration, agent, tool, or eval)
@@ -5632,6 +5677,10 @@ type Trigger = {
    * 5-field cron expression (UTC). Present only for schedule triggers
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern. Present only for event triggers: `*`, `prefix.*`, or an exact event name
+   */
+  event_pattern?: string | null;
   active?: boolean;
   /**
    * Optional boundary policy that further restricts firings
@@ -5657,7 +5706,7 @@ type CreateTriggerRequest = {
   project_id?: string;
   name: string;
   description?: string;
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type: 'orchestration' | 'agent' | 'tool' | 'eval';
   target_id: string;
   /**
@@ -5671,6 +5720,10 @@ type CreateTriggerRequest = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string;
+  /**
+   * Internal-event subscription pattern. Required when type is event, rejected otherwise. `*` matches every event, `prefix.*` a namespace, or give an exact event name such as `documents.ingested`
+   */
+  event_pattern?: string;
   active?: boolean;
   policy_id?: string;
 };
@@ -5684,6 +5737,7 @@ type UpdateTriggerRequest = {
     [key: string]: unknown;
   } | null;
   cron?: string | null;
+  event_pattern?: string | null;
   active?: boolean;
   policy_id?: string | null;
 };
@@ -5702,7 +5756,7 @@ type TriggerFiring = {
   id?: string;
   trigger_id?: string;
   project_id?: string;
-  source?: 'manual' | 'webhook' | 'schedule';
+  source?: 'manual' | 'webhook' | 'schedule' | 'event';
   status?: 'pending' | 'running' | 'succeeded' | 'failed';
   input?: {
     [key: string]: unknown;
@@ -5991,6 +6045,11 @@ type UsageReceipt = {
     meter_type?: string;
     provider?: string;
     model?: string;
+    /**
+     * Orchestration node that produced the event. On a run receipt every line carries it — an `agent` node's `llm_tokens` line and the `compute_execution` line of each node execution alike — so grouping the lines by `node_id` gives the per-node cost the receipt total alone hides. The event records no attempt number, so a retried node's attempts share one `node_id`, which is the intended reading for spend: a retry is real money. Null when no node produced the event (a standalone generation, a run-level meter).
+     *
+     */
+    node_id?: string | null;
     cost_usd?: number | null;
     components?: Array<UsageComponent>;
   }>;
@@ -10226,6 +10285,14 @@ type StartEvalRunData = {
      * A terminal run of the same eval to compare against. The finished run's `aggregate_scores.baseline` reports per-scorer deltas over the item intersection. A run of a different eval is rejected with 400.
      */
     baseline_run_id?: string | null;
+    /**
+     * Caller-supplied key/value metadata attached to the run record for attribution — what this measurement was of (the commit or release candidate being scored, the CI job that asked for it). Round-trips verbatim on every read of the run, the list included.
+     *
+     * The bag is caller-owned and no key is reserved: everything the platform decides about a run (`status`, `agent_version`, `baseline_run_id`, `aggregate_scores`, `passed`, the counts) is a field of its own and cannot be written from here. Nothing in the scoring path reads it. A non-object is rejected with `400 VALIDATION_FAILED` and no run is created.
+     */
+    metadata?: {
+      [key: string]: unknown;
+    };
   };
   path: {
     /**
@@ -10414,7 +10481,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -13304,7 +13371,7 @@ type StartOrchestrationRunData = {
 };
 type StartOrchestrationRunErrors = {
   /**
-   * Validation error
+   * 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.
    */
   400: unknown;
   /**
@@ -15447,7 +15514,7 @@ type ListTriggersData = {
   path?: never;
   query?: {
     project_id?: string;
-    type?: 'manual' | 'webhook' | 'schedule';
+    type?: 'manual' | 'webhook' | 'schedule' | 'event';
     target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
     /**
      * Maximum number of results to return

package/dist/index.d.mts

@@ -1879,6 +1879,12 @@ type EvalRun = {
   item_count?: number;
   completed_count?: number;
   errored_count?: number;
+  /**
+   * The caller-owned key/value metadata supplied when the run was started, returned verbatim. Null when the run was started without any (a trigger-started run included — see `trigger_id` for that provenance). The server writes nothing here.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   started_at?: Date | null;
   finished_at?: Date | null;
   created_at?: Date;
@@ -1916,7 +1922,7 @@ type ExceptionItem = {
   /**
    * How the exception was filed
    */
-  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+  kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
   /**
    * Human-readable one-line summary
    */
@@ -2684,7 +2690,7 @@ type WebhookResourceProperties = {
   events: Array<string>;
 };
 /**
- * Binds a starter (manual, webhook, or schedule) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
+ * Binds a starter (manual, webhook, schedule, or event) to an executable target (orchestration, agent, tool, or eval). Firings run under the project owner's confined run-as identity.
  */
 type TriggerResourceProperties = {
   /**
@@ -2698,7 +2704,7 @@ type TriggerResourceProperties = {
   /**
    * Starter type. Immutable after creation
    */
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   /**
    * The kind of resource this trigger activates
    */
@@ -2721,6 +2727,10 @@ type TriggerResourceProperties = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern (`*`, `prefix.*`, or an exact event name). Required when type is event, rejected otherwise
+   */
+  event_pattern?: string | null;
   /**
    * Whether the trigger fires (default true)
    */
@@ -3095,9 +3105,12 @@ type GuardrailResourceProperties = {
 };
 type ResourceDeclaration = {
   /**
-   * Resource type
+   * Resource type. The built-in types are `ai_provider`, `tool`, `agent`, `actor`, `api_key`, `chat`, `conversation`, `dataset`, `dataset_item`, `document`, `file`, `guardrail`, `ingestion_rule`, `memory`, `memory_entry`, `model_route`, `eval`, `orchestration`, `policy`, `project_price`, `quota`, `secret`, `session`, `webhook`, `trigger` and `workflow`.
+   *
+   * This is deliberately not an enum: a deployment operator can register additional resource types backed by their own handler, and those are declared here exactly like a built-in one. The set a given deployment accepts is authoritative in the server, which rejects an unregistered type with `VALIDATION_FAILED` and lists what it does support.
+   *
    */
-  type: 'ai_provider' | 'tool' | 'agent' | 'actor' | 'api_key' | 'chat' | 'conversation' | 'dataset' | 'dataset_item' | 'document' | 'file' | 'guardrail' | 'ingestion_rule' | 'memory' | 'memory_entry' | 'model_route' | 'eval' | 'orchestration' | 'policy' | 'project_price' | 'quota' | 'secret' | 'session' | 'webhook' | 'trigger' | 'workflow';
+  type: string;
   /**
    * Resource properties, as authored in the template and echoed back verbatim. The allowed fields, required fields, and field types for each resource `type` are defined by the corresponding `<Type>ResourceProperties` schema in this document (e.g. `model_route` → `ModelRouteResourceProperties`), which the server enforces at validate/deploy time. The declaration itself is free-form here because property values may be substitution expressions rather than final values: `{ "ref": "logicalId" }` references another resource's physical ID, `{ "param": "ParamName" }` substitutes a parameter value, and `{ "sub": "text ${ParamName}" }` interpolates parameters into a string.
    *
@@ -4574,6 +4587,12 @@ type OrchestrationRun = {
   tool_context?: {
     [key: string]: string;
   } | null;
+  /**
+   * The caller-owned key/value metadata supplied at run creation, returned verbatim. Null when the run was started without any. The server writes nothing here and no key is reserved; the bag is never merged into `state`, so nothing in it reaches the graph.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   /**
    * Terminal node artifact(s) when the run has succeeded.
    */
@@ -4712,6 +4731,16 @@ type StartRunRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read.
+   *
+   * The bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own `input` and accumulated `state`) lives in its own top-level field and cannot be written from here.
+   *
+   * It is **not** merged into run state: no graph node sees it, and an `input_schema` never has to tolerate it — which is what makes it the place for an infrastructural label, rather than `input`. Keys are never transformed. It is not inherited by the child runs a `loop` or `sub_orchestration` node starts; each child carries whatever the graph gives it, which today is nothing.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
   /**
    * 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.
    */
@@ -5155,6 +5184,12 @@ type Task = {
   payload?: {
     [key: string]: unknown;
   };
+  /**
+   * The caller-owned key/value metadata supplied when the task was created, returned verbatim. Null when the task was created without any. Unlike `payload` it is invisible to guards and to `payload_writes`, so it is the place for an attribution label rather than task data.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  } | null;
   /**
    * Server-owned. The result of the current state's last completed dispatch, overwritten on every dispatch. Read-only — exposed to transition guards and `on_complete`/`payload_writes` expressions as `task.last_result`, a namespace a caller cannot write.
    */
@@ -5235,6 +5270,16 @@ type CreateTaskRequest = {
   tool_context?: {
     [key: string]: string;
   };
+  /**
+   * Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own).
+   *
+   * The bag is caller-owned and no key is reserved: everything the engine decides about a task (`state`, `status`, `workflow_version`, `last_result`, `active_dispatch`, the automation fields) is a field of its own and cannot be written from here.
+   *
+   * Prefer this over `payload` for anything that is not task data: `payload` is read by every guard as `task.payload` and may be written by the workflow's declared `payload_writes`, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with `400 VALIDATION_FAILED` and no task is created.
+   */
+  metadata?: {
+    [key: string]: unknown;
+  };
 };
 type UpdateTaskRequest = {
   title?: string;
@@ -5612,7 +5657,7 @@ type Trigger = {
   project_id?: string;
   name?: string;
   description?: string | null;
-  type?: 'manual' | 'webhook' | 'schedule';
+  type?: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
   /**
    * Public ID of the target resource (orchestration, agent, tool, or eval)
@@ -5632,6 +5677,10 @@ type Trigger = {
    * 5-field cron expression (UTC). Present only for schedule triggers
    */
   cron?: string | null;
+  /**
+   * Internal-event subscription pattern. Present only for event triggers: `*`, `prefix.*`, or an exact event name
+   */
+  event_pattern?: string | null;
   active?: boolean;
   /**
    * Optional boundary policy that further restricts firings
@@ -5657,7 +5706,7 @@ type CreateTriggerRequest = {
   project_id?: string;
   name: string;
   description?: string;
-  type: 'manual' | 'webhook' | 'schedule';
+  type: 'manual' | 'webhook' | 'schedule' | 'event';
   target_type: 'orchestration' | 'agent' | 'tool' | 'eval';
   target_id: string;
   /**
@@ -5671,6 +5720,10 @@ type CreateTriggerRequest = {
    * 5-field cron expression (UTC). Required when type is schedule
    */
   cron?: string;
+  /**
+   * Internal-event subscription pattern. Required when type is event, rejected otherwise. `*` matches every event, `prefix.*` a namespace, or give an exact event name such as `documents.ingested`
+   */
+  event_pattern?: string;
   active?: boolean;
   policy_id?: string;
 };
@@ -5684,6 +5737,7 @@ type UpdateTriggerRequest = {
     [key: string]: unknown;
   } | null;
   cron?: string | null;
+  event_pattern?: string | null;
   active?: boolean;
   policy_id?: string | null;
 };
@@ -5702,7 +5756,7 @@ type TriggerFiring = {
   id?: string;
   trigger_id?: string;
   project_id?: string;
-  source?: 'manual' | 'webhook' | 'schedule';
+  source?: 'manual' | 'webhook' | 'schedule' | 'event';
   status?: 'pending' | 'running' | 'succeeded' | 'failed';
   input?: {
     [key: string]: unknown;
@@ -5991,6 +6045,11 @@ type UsageReceipt = {
     meter_type?: string;
     provider?: string;
     model?: string;
+    /**
+     * Orchestration node that produced the event. On a run receipt every line carries it — an `agent` node's `llm_tokens` line and the `compute_execution` line of each node execution alike — so grouping the lines by `node_id` gives the per-node cost the receipt total alone hides. The event records no attempt number, so a retried node's attempts share one `node_id`, which is the intended reading for spend: a retry is real money. Null when no node produced the event (a standalone generation, a run-level meter).
+     *
+     */
+    node_id?: string | null;
     cost_usd?: number | null;
     components?: Array<UsageComponent>;
   }>;
@@ -10226,6 +10285,14 @@ type StartEvalRunData = {
      * A terminal run of the same eval to compare against. The finished run's `aggregate_scores.baseline` reports per-scorer deltas over the item intersection. A run of a different eval is rejected with 400.
      */
     baseline_run_id?: string | null;
+    /**
+     * Caller-supplied key/value metadata attached to the run record for attribution — what this measurement was of (the commit or release candidate being scored, the CI job that asked for it). Round-trips verbatim on every read of the run, the list included.
+     *
+     * The bag is caller-owned and no key is reserved: everything the platform decides about a run (`status`, `agent_version`, `baseline_run_id`, `aggregate_scores`, `passed`, the counts) is a field of its own and cannot be written from here. Nothing in the scoring path reads it. A non-object is rejected with `400 VALIDATION_FAILED` and no run is created.
+     */
+    metadata?: {
+      [key: string]: unknown;
+    };
   };
   path: {
     /**
@@ -10414,7 +10481,7 @@ type ListExceptionsData = {
     /**
      * Filter by how the exception was filed
      */
-    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'manual';
+    kind?: 'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'manual';
     /**
      * Maximum number of results to return
      */
@@ -13304,7 +13371,7 @@ type StartOrchestrationRunData = {
 };
 type StartOrchestrationRunErrors = {
   /**
-   * Validation error
+   * 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.
    */
   400: unknown;
   /**
@@ -15447,7 +15514,7 @@ type ListTriggersData = {
   path?: never;
   query?: {
     project_id?: string;
-    type?: 'manual' | 'webhook' | 'schedule';
+    type?: 'manual' | 'webhook' | 'schedule' | 'event';
     target_type?: 'orchestration' | 'agent' | 'tool' | 'eval';
     /**
      * Maximum number of results to return

package/package.json

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