@naturali/sdk 0.36.0 → 0.37.0

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.
+   * Fires for both kinds of column. A failed dispatch never reaches `on_complete`, so a catch-all `{"when": true}` rule cannot advance a card on failed work, and the failure leaves no `last_result` behind.
    *
    */
   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;
@@ -1891,16 +1896,12 @@ type TaskTransitionRecord = {
    */
   transition: string | null;
   /**
-   * What kind of actor made the move. `automation` is a column's own `on_complete` routing or its `on_failure`.
+   * What kind of principal made the move. `automation` is a column's own `on_complete` routing or its `on_failure`.
    * A move made through this API reports `api_key`: every call naturali makes reaches the platform under one service credential, so the record cannot distinguish a person from an integration. `user` is reserved for when it can.
+   * There is no `principal_id` counterpart. For a human or API move it would identify naturali's own service credential, which says nothing about the caller; for an `automation` move what caused the move is already reported by `generation_id` / `orchestration_run_id`.
    *
    */
-  actor_kind: 'user' | 'api_key' | 'automation';
-  /**
-   * For an `automation` move, what caused it (the generation or run). Null otherwise — for a human or API move the underlying value identifies naturali's own service credential, which says nothing about the caller.
-   *
-   */
-  actor_id: string | null;
+  principal_kind: 'user' | 'api_key' | 'automation';
   /**
    * The agent generation that caused the move, when one did.
    */

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.
+   * Fires for both kinds of column. A failed dispatch never reaches `on_complete`, so a catch-all `{"when": true}` rule cannot advance a card on failed work, and the failure leaves no `last_result` behind.
    *
    */
   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;
@@ -1891,16 +1896,12 @@ type TaskTransitionRecord = {
    */
   transition: string | null;
   /**
-   * What kind of actor made the move. `automation` is a column's own `on_complete` routing or its `on_failure`.
+   * What kind of principal made the move. `automation` is a column's own `on_complete` routing or its `on_failure`.
    * A move made through this API reports `api_key`: every call naturali makes reaches the platform under one service credential, so the record cannot distinguish a person from an integration. `user` is reserved for when it can.
+   * There is no `principal_id` counterpart. For a human or API move it would identify naturali's own service credential, which says nothing about the caller; for an `automation` move what caused the move is already reported by `generation_id` / `orchestration_run_id`.
    *
    */
-  actor_kind: 'user' | 'api_key' | 'automation';
-  /**
-   * For an `automation` move, what caused it (the generation or run). Null otherwise — for a human or API move the underlying value identifies naturali's own service credential, which says nothing about the caller.
-   *
-   */
-  actor_id: string | null;
+  principal_kind: 'user' | 'api_key' | 'automation';
   /**
    * The agent generation that caused the move, when one did.
    */

package/package.json

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