@naturali/sdk 0.36.0 → 0.36.1

package/dist/index.d.cts

@@ -591,9 +591,10 @@ type BoardDispatch = {
    */
   agent_id?: string;
   /**
-   * Required when `kind` is `tool` — a tool in this project.
+   * 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.
+   *
    */
-  tool_id?: string;
+  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.
    *
@@ -608,7 +609,8 @@ type BoardDispatch = {
  */
 type BoardCompletionRule = {
   /**
-   * JSON Logic evaluated against `{ task, result }`. `result` is the dispatch's output: for an agent column its generation output (so `result.object.…` reads its structured output — routing on free text is not a thing, the agent needs an output schema); for a tool column the tool's own result object.
+   * JSON Logic evaluated against `{ task, result }`. `result` is the dispatch's output: for an agent column its generation output; for a tool column the tool's own result object.
+   * Routing an agent column on *structured* output (`result.object.…`) needs the agent to declare an output schema, and the Agents API does not expose one yet — so today an agent column can only route on what its generation happens to return.
    *
    */
   when: unknown;
@@ -631,6 +633,7 @@ type BoardOnEnter = {
   on_complete?: Array<BoardCompletionRule>;
   /**
    * Where a card goes when the dispatch fails terminally. Accepts either a declared move, or a column reachable from this one by exactly one declared move (which is resolved to that move — reads report the move name). Omit to leave a failed card in place for a person.
+   * **Known limitation — does not fire for a `tool` column.** The platform underneath reports a failed tool run as a *completed* dispatch, so a tool column's `on_failure` is never reached and its `on_complete` rules are evaluated instead, against the failed run's partial state. A catch-all `{"when": true}` rule on a tool column will therefore fire on failed work — including into a terminal column, which closes the card. Until this is fixed upstream, prefer an explicit rule that tests a field the tool really returns, so a failed run matches nothing and the card parks for a person. Agent columns are unaffected.
    *
    */
   on_failure?: string | null;
@@ -1803,6 +1806,7 @@ type Task = {
   status: 'open' | 'closed';
   /**
    * The card's working data — what a column's `input_mapping` reads and what a completed dispatch writes back to (`payload.last_result`). Store references to artifacts (file and document ids), not the artifacts themselves.
+   * **`last_result` is shaped by the kind of column that wrote it.** An agent column writes its generation output. A **tool** column writes the enclosing run's state, which puts the tool's own result one level down under `nodes.tool` — so a later column chains off a tool column with `{"var": "task.payload.last_result.nodes.tool.<field>"}`, not `last_result.<field>`. (Inside the tool column's *own* `on_complete`, `result.<field>` works as documented; only chaining from a *later* column sees the run-state shape.)
    *
    */
   payload: {
@@ -1818,7 +1822,8 @@ type Task = {
    */
   automation_status: 'running' | 'completed' | 'failed' | 'unrouted';
   /**
-   * `{ kind, id, status }` of the in-flight dispatch, if any.
+   * The in-flight dispatch, if any. An agent column reports `{ kind: "agent", id, status }`, where `id` is the generation — real provenance, readable through Generations. A tool column reports `{ kind: "tool", tool_id, status }`: the machinery a tool column runs on is naturali's own and is not addressable by a caller, so it is named by the tool it stands for rather than by an internal id.
+   *
    */
   active_dispatch: {
     [key: string]: unknown;

package/dist/index.d.mts

@@ -591,9 +591,10 @@ type BoardDispatch = {
    */
   agent_id?: string;
   /**
-   * Required when `kind` is `tool` — a tool in this project.
+   * 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.
+   *
    */
-  tool_id?: string;
+  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.
    *
@@ -608,7 +609,8 @@ type BoardDispatch = {
  */
 type BoardCompletionRule = {
   /**
-   * JSON Logic evaluated against `{ task, result }`. `result` is the dispatch's output: for an agent column its generation output (so `result.object.…` reads its structured output — routing on free text is not a thing, the agent needs an output schema); for a tool column the tool's own result object.
+   * JSON Logic evaluated against `{ task, result }`. `result` is the dispatch's output: for an agent column its generation output; for a tool column the tool's own result object.
+   * Routing an agent column on *structured* output (`result.object.…`) needs the agent to declare an output schema, and the Agents API does not expose one yet — so today an agent column can only route on what its generation happens to return.
    *
    */
   when: unknown;
@@ -631,6 +633,7 @@ type BoardOnEnter = {
   on_complete?: Array<BoardCompletionRule>;
   /**
    * Where a card goes when the dispatch fails terminally. Accepts either a declared move, or a column reachable from this one by exactly one declared move (which is resolved to that move — reads report the move name). Omit to leave a failed card in place for a person.
+   * **Known limitation — does not fire for a `tool` column.** The platform underneath reports a failed tool run as a *completed* dispatch, so a tool column's `on_failure` is never reached and its `on_complete` rules are evaluated instead, against the failed run's partial state. A catch-all `{"when": true}` rule on a tool column will therefore fire on failed work — including into a terminal column, which closes the card. Until this is fixed upstream, prefer an explicit rule that tests a field the tool really returns, so a failed run matches nothing and the card parks for a person. Agent columns are unaffected.
    *
    */
   on_failure?: string | null;
@@ -1803,6 +1806,7 @@ type Task = {
   status: 'open' | 'closed';
   /**
    * The card's working data — what a column's `input_mapping` reads and what a completed dispatch writes back to (`payload.last_result`). Store references to artifacts (file and document ids), not the artifacts themselves.
+   * **`last_result` is shaped by the kind of column that wrote it.** An agent column writes its generation output. A **tool** column writes the enclosing run's state, which puts the tool's own result one level down under `nodes.tool` — so a later column chains off a tool column with `{"var": "task.payload.last_result.nodes.tool.<field>"}`, not `last_result.<field>`. (Inside the tool column's *own* `on_complete`, `result.<field>` works as documented; only chaining from a *later* column sees the run-state shape.)
    *
    */
   payload: {
@@ -1818,7 +1822,8 @@ type Task = {
    */
   automation_status: 'running' | 'completed' | 'failed' | 'unrouted';
   /**
-   * `{ kind, id, status }` of the in-flight dispatch, if any.
+   * The in-flight dispatch, if any. An agent column reports `{ kind: "agent", id, status }`, where `id` is the generation — real provenance, readable through Generations. A tool column reports `{ kind: "tool", tool_id, status }`: the machinery a tool column runs on is naturali's own and is not addressable by a caller, so it is named by the tool it stands for rather than by an internal id.
+   *
    */
   active_dispatch: {
     [key: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "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.36.0"
+    "@naturali/api": "0.36.1"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",