@naturali/sdk 0.53.0 → 0.54.0

package/dist/index.d.cts

@@ -811,32 +811,60 @@ type User = {
   created_at: Date;
 };
 /**
- * What a column runs when a card enters it — exactly one agent or one tool. A tool runs **deterministically**: there is no model in the loop, which is what makes a tool column different from an agent that happens to have one tool.
+ * What a column runs when a card enters it. A tool or poll dispatch runs **deterministically**: there is no model in the loop, which is what makes them different from an agent that happens to have one tool.
  *
  */
 type BoardDispatch = {
   /**
-   * Which reference below is expected. The other is rejected.
+   * What the column does on entry. `agent`/`tool`/`poll` take the reference field their kind names below (`agent_id`/`tool_id`); the others are rejected. `delay` names no resource at all.
+   *
    */
-  kind: 'agent' | 'tool';
+  kind: 'agent' | 'tool' | 'poll' | 'delay';
   /**
    * Required when `kind` is `agent` — an agent in this project.
    */
   agent_id?: string;
   /**
-   * Required when `kind` is `tool` — a tool in this project. Null only on a read, and only if the board's internal bookkeeping and its stored definition have drifted: the column still dispatches a tool, but which tool can no longer be resolved. Re-send the definition to repair it.
+   * Required when `kind` is `tool` or `poll` — a tool in this project. Null only on a read, and only if the board's internal bookkeeping and its stored definition have drifted: the column still dispatches a tool, but which tool can no longer be resolved. Re-send the definition to repair it.
    *
    */
   tool_id?: string | null;
   /**
-   * JSON Logic (https://jsonlogic.com) resolving the dispatch input from the card, evaluated against `{ task }` — so `{"var": "task.payload.theme"}` reads the card's payload. Each value is one expression; a plain string, number or boolean is passed through as a literal.
+   * JSON Logic (https://jsonlogic.com) resolving the dispatch input from the card, evaluated against `{ task }` — so `{"var": "task.payload.theme"}` reads the card's payload. Each value is one expression; a plain string, number or boolean is passed through as a literal. Not accepted on a `delay` dispatch, which names no resource to send it to.
    *
    */
   input_mapping?: {
     [key: string]: unknown;
   };
   /**
-   * JSON Logic writing selected fields of the dispatch's own result into named `task.payload` keys when the dispatch completes — a deterministic, no-model channel for state that must survive more than one column. Evaluated against the same `{ task, result }` context as `on_complete` (`result` is the tool's own result for a tool column, re-rooted the same way), and applied atomically alongside `last_result`. Each write is a raw overwrite of its key: a value from an earlier pass through a looping column lingers in the payload until the column runs again. Before this, carrying a value past one hop meant echoing it through an agent's `output_schema` or injecting it into an unrelated tool request purely so it would reappear in `last_result` downstream — both are unnecessary now.
+   * Required when `kind` is `poll` — JSON Logic stop condition, evaluated after every attempt against `{ response, attempt }` (`response` is the tool's latest result, `attempt` a 1-based count); a truthy result stops polling. The wait between attempts is durable and scheduler-driven — it does not hold a request open, and a card parked mid-poll survives a platform restart.
+   *
+   */
+  exit_condition?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Required when `kind` is `poll` — wait between attempts. Accepts a friendly suffix form (`5s`, `30s`, `5m`, `2h`, `500ms`) or ISO 8601 (e.g. `PT5S`).
+   *
+   */
+  interval?: string;
+  /**
+   * Only meaningful when `kind` is `poll` — maximum attempts before `on_timeout` decides the outcome. Defaults to 10 when omitted.
+   *
+   */
+  max_iterations?: number;
+  /**
+   * Only meaningful when `kind` is `poll` — what happens when `max_iterations` is reached without `exit_condition` becoming true. `fail` fails the dispatch (routed the same way any failed dispatch is, via `on_failure`); `continue` (the default) completes the dispatch with the condition unmet, so `on_complete` rules can branch on it.
+   *
+   */
+  on_timeout?: 'fail' | 'continue';
+  /**
+   * Required when `kind` is `delay` — how long the column waits before completing. Accepts a friendly suffix form (`5s`, `30s`, `5m`, `2h`, `500ms`) or ISO 8601 (e.g. `PT5S`). The wait is durable and scheduler-driven, the same as a poll's `interval` — it does not hold a request open, and a card parked mid-delay survives a platform restart.
+   *
+   */
+  duration?: string;
+  /**
+   * JSON Logic writing selected fields of the dispatch's own result into named `task.payload` keys when the dispatch completes — a deterministic, no-model channel for state that must survive more than one column. Evaluated against the same `{ task, result }` context as `on_complete` (`result` is the tool's/poll's own result for a tool/poll column, re-rooted the same way), and applied atomically alongside `last_result`. Each write is a raw overwrite of its key: a value from an earlier pass through a looping column lingers in the payload until the column runs again. Before this, carrying a value past one hop meant echoing it through an agent's `output_schema` or injecting it into an unrelated tool request purely so it would reappear in `last_result` downstream — both are unnecessary now.
    *
    */
   payload_writes?: {
@@ -1449,8 +1477,23 @@ type Generation = {
     [key: string]: unknown;
   } | null;
   /**
-   * Non-sensitive metadata recorded about the generation — whatever the caller attached, plus platform keys added by the backing platform: the label supplied as `action_id` on the run (which is how spend rolls up per action), the trigger that started it, and an `extraction` summary when the agent's knowledge config produced one.
-   * Platform keys come back **camelCase** (`actionId`, `triggerId`), unlike the snake_case request field they were set from — this object is passed through from the platform rather than re-cased, so read `metadata.actionId` when resolving what a run was labelled.
+   * The label supplied as `action_id` when the generation was run, recorded on its usage event so spend rolls up per action.
+   *
+   */
+  action_id: string | null;
+  /**
+   * The trigger that started this generation, when applicable.
+   */
+  trigger_id: string | null;
+  /**
+   * Memory-extraction summary recorded for this generation — set when the agent's knowledge config produced one for this turn (`candidates`, `created`, `updated`, `skipped`).
+   *
+   */
+  extraction: {
+    [key: string]: unknown;
+  } | null;
+  /**
+   * Caller-supplied key/value metadata attached to the generation record — nothing else. Server-owned state has its own top-level fields (`action_id`, `trigger_id`, `extraction`) and is never merged into this object.
    *
    */
   metadata: {

package/dist/index.d.mts

@@ -811,32 +811,60 @@ type User = {
   created_at: Date;
 };
 /**
- * What a column runs when a card enters it — exactly one agent or one tool. A tool runs **deterministically**: there is no model in the loop, which is what makes a tool column different from an agent that happens to have one tool.
+ * What a column runs when a card enters it. A tool or poll dispatch runs **deterministically**: there is no model in the loop, which is what makes them different from an agent that happens to have one tool.
  *
  */
 type BoardDispatch = {
   /**
-   * Which reference below is expected. The other is rejected.
+   * What the column does on entry. `agent`/`tool`/`poll` take the reference field their kind names below (`agent_id`/`tool_id`); the others are rejected. `delay` names no resource at all.
+   *
    */
-  kind: 'agent' | 'tool';
+  kind: 'agent' | 'tool' | 'poll' | 'delay';
   /**
    * Required when `kind` is `agent` — an agent in this project.
    */
   agent_id?: string;
   /**
-   * Required when `kind` is `tool` — a tool in this project. Null only on a read, and only if the board's internal bookkeeping and its stored definition have drifted: the column still dispatches a tool, but which tool can no longer be resolved. Re-send the definition to repair it.
+   * Required when `kind` is `tool` or `poll` — a tool in this project. Null only on a read, and only if the board's internal bookkeeping and its stored definition have drifted: the column still dispatches a tool, but which tool can no longer be resolved. Re-send the definition to repair it.
    *
    */
   tool_id?: string | null;
   /**
-   * JSON Logic (https://jsonlogic.com) resolving the dispatch input from the card, evaluated against `{ task }` — so `{"var": "task.payload.theme"}` reads the card's payload. Each value is one expression; a plain string, number or boolean is passed through as a literal.
+   * JSON Logic (https://jsonlogic.com) resolving the dispatch input from the card, evaluated against `{ task }` — so `{"var": "task.payload.theme"}` reads the card's payload. Each value is one expression; a plain string, number or boolean is passed through as a literal. Not accepted on a `delay` dispatch, which names no resource to send it to.
    *
    */
   input_mapping?: {
     [key: string]: unknown;
   };
   /**
-   * JSON Logic writing selected fields of the dispatch's own result into named `task.payload` keys when the dispatch completes — a deterministic, no-model channel for state that must survive more than one column. Evaluated against the same `{ task, result }` context as `on_complete` (`result` is the tool's own result for a tool column, re-rooted the same way), and applied atomically alongside `last_result`. Each write is a raw overwrite of its key: a value from an earlier pass through a looping column lingers in the payload until the column runs again. Before this, carrying a value past one hop meant echoing it through an agent's `output_schema` or injecting it into an unrelated tool request purely so it would reappear in `last_result` downstream — both are unnecessary now.
+   * Required when `kind` is `poll` — JSON Logic stop condition, evaluated after every attempt against `{ response, attempt }` (`response` is the tool's latest result, `attempt` a 1-based count); a truthy result stops polling. The wait between attempts is durable and scheduler-driven — it does not hold a request open, and a card parked mid-poll survives a platform restart.
+   *
+   */
+  exit_condition?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Required when `kind` is `poll` — wait between attempts. Accepts a friendly suffix form (`5s`, `30s`, `5m`, `2h`, `500ms`) or ISO 8601 (e.g. `PT5S`).
+   *
+   */
+  interval?: string;
+  /**
+   * Only meaningful when `kind` is `poll` — maximum attempts before `on_timeout` decides the outcome. Defaults to 10 when omitted.
+   *
+   */
+  max_iterations?: number;
+  /**
+   * Only meaningful when `kind` is `poll` — what happens when `max_iterations` is reached without `exit_condition` becoming true. `fail` fails the dispatch (routed the same way any failed dispatch is, via `on_failure`); `continue` (the default) completes the dispatch with the condition unmet, so `on_complete` rules can branch on it.
+   *
+   */
+  on_timeout?: 'fail' | 'continue';
+  /**
+   * Required when `kind` is `delay` — how long the column waits before completing. Accepts a friendly suffix form (`5s`, `30s`, `5m`, `2h`, `500ms`) or ISO 8601 (e.g. `PT5S`). The wait is durable and scheduler-driven, the same as a poll's `interval` — it does not hold a request open, and a card parked mid-delay survives a platform restart.
+   *
+   */
+  duration?: string;
+  /**
+   * JSON Logic writing selected fields of the dispatch's own result into named `task.payload` keys when the dispatch completes — a deterministic, no-model channel for state that must survive more than one column. Evaluated against the same `{ task, result }` context as `on_complete` (`result` is the tool's/poll's own result for a tool/poll column, re-rooted the same way), and applied atomically alongside `last_result`. Each write is a raw overwrite of its key: a value from an earlier pass through a looping column lingers in the payload until the column runs again. Before this, carrying a value past one hop meant echoing it through an agent's `output_schema` or injecting it into an unrelated tool request purely so it would reappear in `last_result` downstream — both are unnecessary now.
    *
    */
   payload_writes?: {
@@ -1449,8 +1477,23 @@ type Generation = {
     [key: string]: unknown;
   } | null;
   /**
-   * Non-sensitive metadata recorded about the generation — whatever the caller attached, plus platform keys added by the backing platform: the label supplied as `action_id` on the run (which is how spend rolls up per action), the trigger that started it, and an `extraction` summary when the agent's knowledge config produced one.
-   * Platform keys come back **camelCase** (`actionId`, `triggerId`), unlike the snake_case request field they were set from — this object is passed through from the platform rather than re-cased, so read `metadata.actionId` when resolving what a run was labelled.
+   * The label supplied as `action_id` when the generation was run, recorded on its usage event so spend rolls up per action.
+   *
+   */
+  action_id: string | null;
+  /**
+   * The trigger that started this generation, when applicable.
+   */
+  trigger_id: string | null;
+  /**
+   * Memory-extraction summary recorded for this generation — set when the agent's knowledge config produced one for this turn (`candidates`, `created`, `updated`, `skipped`).
+   *
+   */
+  extraction: {
+    [key: string]: unknown;
+  } | null;
+  /**
+   * Caller-supplied key/value metadata attached to the generation record — nothing else. Server-owned state has its own top-level fields (`action_id`, `trigger_id`, `extraction`) and is never merged into this object.
    *
    */
   metadata: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "sideEffects": false,
@@ -37,7 +37,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/api": "0.53.0"
+    "@naturali/api": "0.54.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",