@naturali/cli 0.201.1 → 0.203.0

package/README.md

@@ -17,7 +17,7 @@ the environment:
 | Variable | Purpose |
 | --- | --- |
 | `NATURALI_TOKEN` | Bearer credential (`nat_sk_…` or a session JWT). Required. |
-| `NATURALI_PROJECT` | Default `--project-id` for commands that take one. An explicit `--project-id` still wins. |
+| `NATURALI_PROJECT_ID` | Default `--project-id` for commands that take one. An explicit `--project-id` still wins. |
 
 ## Commands
 

package/dist/index.mjs

@@ -17,7 +17,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.201.1";
+var version = "0.203.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -2925,7 +2925,7 @@ var Evaluations = class {
 	/**
 	* Cancel an eval run
 	*
-	* Cancels a queued or running run: its outstanding item tasks are dropped so it stops consuming provider budget, and the run settles as `canceled`.
+	* Cancels a queued or running run: its outstanding item tasks are dropped so it stops consuming provider budget, and the run settles as `cancelled`.
 	*
 	* Results already written are kept — they are real measurements of generations that were really paid for — and `completed_count` / `errored_count` report what ran. `aggregate_scores` is deliberately left null: a partial roll-up in the same field a completed run uses would read as a whole-dataset verdict.
 	*
@@ -4287,7 +4287,7 @@ var Orchestrations = class {
 	/**
 	* Validate an orchestration graph
 	*
-	* Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges reference existing nodes, the graph is acyclic (unless it contains a loop node), and every `input_mapping` `{"var": "..."}` reference resolves to a state key written by an upstream node or seeded by `input_schema`. Returns blocking `errors` and non-blocking `warnings` (e.g. a state key only written on a conditional branch). The same `errors` checks are enforced on create and update, which fail with `400` when any error is present.
+	* Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges reference existing nodes, the graph is acyclic (unless it contains a loop node), and every `input_mapping` `{"var": "..."}` reference resolves to a state key written by an upstream node or seeded by `input_schema`. Returns blocking `problems` and non-blocking `warnings` (e.g. a state key only written on a conditional branch). The same checks are enforced on create and update, which fail with `400 ORCHESTRATION_VALIDATION_FAILED` listing the same items under `meta.problems` and `meta.warnings`.
 	*
 	*/
 	static validateOrchestration(options) {
@@ -4438,7 +4438,7 @@ var Orchestrations = class {
 	/**
 	* Start an orchestration run
 	*
-	* Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status "queued" (a worker then claims it and moves it to "running") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as "sleeping" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.
+	* Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status "queued" (a worker then claims it and moves it to "running") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/completed/failed). Delay and poll waits park the run as "sleeping" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.
 	*/
 	static startOrchestrationRun(options) {
 		return (options.client ?? client).post({
@@ -4700,7 +4700,7 @@ var Playbooks = class {
 	/**
 	* Write a case's inputs
 	*
-	* Writes a batch of manual inputs, all or none. Each write names the revision it read in `expected_revision`, `null` for a field still unset; when any field has moved on the whole batch is refused with `409 PLAYBOOK_INPUT_CONFLICT` and `meta.conflicts` names each field. An input the case's version does not declare, one that reads another node, or a value its schema refuses is `400 PLAYBOOK_INPUT_INVALID`. A value equal to the field's current one writes no revision. Once written, every node the write makes runnable is queued to run, unless the case is paused. A write made with a credential the case's own work runs as — the case, one of its executions in flight, or the task or run one started — is `403 PLAYBOOK_SELF_WRITE`.
+	* Writes a batch of manual inputs, all or none. Each write names the revision it read in `expected_revision`, `null` for a field still unset; when any field has moved on the whole batch is refused with `409 PLAYBOOK_INPUT_CONFLICT` and `meta.conflicts` names each field. An input the case's version does not declare, one that reads another node, or a value its schema refuses is `400 PLAYBOOK_INPUT_INVALID`. A value equal to the field's current one writes no revision. Once written, every node the write makes runnable is queued to run, unless the case is paused. With `wait: true` it answers once every execution queued, and every one those queue, has settled or parked. A write made with a credential the case's own work runs as — the case, one of its executions in flight, or the task or run one started — is `403 PLAYBOOK_SELF_WRITE`.
 	*/
 	static writePlaybookCaseInputs(options) {
 		return (options.client ?? client).post({
@@ -4715,7 +4715,7 @@ var Playbooks = class {
 	/**
 	* List what a node still needs
 	*
-	* Returns the manual inputs still unset, or refused by their schema, before `node` can be reached, grouped in waves: nothing in a later wave can run before the earlier ones are filled.
+	* Returns the manual inputs still unset, or refused by their schema, before `node_id` can be reached, grouped in waves: nothing in a later wave can run before the earlier ones are filled.
 	*/
 	static getPlaybookCaseMissing(options) {
 		return (options.client ?? client).get({
@@ -4737,7 +4737,7 @@ var Playbooks = class {
 	/**
 	* Run a node of a case
 	*
-	* Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` one: this is how a failed node is retried. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs as the author of the case's playbook version, whose permission to start it is checked again here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`); an author that no longer exists is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`. Only a `ready`, `stale` or `failed` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
+	* Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` or `done` one: this is how a failed node is retried, and how a `done` node is recomputed after an upgrade changed its executor. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs as the author of the case's playbook version, whose permission to start it is checked again here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`); an author that no longer exists is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`. Only a `ready`, `stale`, `failed` or `done` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
 	*
 	* The output is written as an entry when the execution settles. A value equal to the node's current output writes no revision. If the node's inputs change while it runs, the execution settles as `superseded` and writes nothing.
 	*
@@ -4778,7 +4778,7 @@ var Playbooks = class {
 	/**
 	* Export a final node
 	*
-	* Renders one revision of a final node as files, one export per transformation: each transformation's tool is called with the case's `case_id` and `subject`, the `node`, the `revision` and that revision's `output`, and must answer a file (`execute.response_mode: base64`) of its `format`'s content type. The file is kept in the project's files under `/.system/playbooks/`. An export never feeds a node.
+	* Renders one revision of a final node as files, one export per transformation: each transformation's tool is called with the case's `case_id` and `subject`, the `node_id`, the `revision` and that revision's `output`, and must answer a file (`execute.response_mode: base64`) of its `format`'s content type. The file is kept in the project's files under `/.system/playbooks/`. An export never feeds a node.
 	*
 	* Without `revision` the node's current output is exported, which needs the node `done` (`409 PLAYBOOK_NODE_NOT_EXPORTABLE`); a `revision` names an earlier output or confirmation of the node. Each tool runs as the author of the case's playbook version, whose permission to call it is checked here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
 	*
@@ -4819,7 +4819,7 @@ var Playbooks = class {
 	/**
 	* Upgrade a case
 	*
-	* Moves a case to another version of its playbook: the playbook's current version, or the `version` named, an earlier one included. Values carry over by node key, and every node's state is read against the new version: a node added is open, a node removed leaves the structure while its entries stay, a node whose input reads another field is `stale`, and a value its input's new schema refuses is missing again. The cascade then runs what became runnable. Each upgrade is recorded with what moved; the version the case is already on records nothing.
+	* Moves a case to another version of its playbook: the playbook's current version, or the `version` named, an earlier one included. Values carry over by node ID, and every node's state is read against the new version: a node added is open, a node removed leaves the structure while its entries stay, a node whose input reads another field is `stale`, and a value its input's new schema refuses is missing again. The cascade then runs what became runnable. With `wait: true` it answers once every execution queued, and every one those queue, has settled or parked. Each upgrade is recorded with what moved; the version the case is already on records nothing.
 	*
 	* An execution running is `409 PLAYBOOK_CASE_BUSY`; one queued but not started settles `superseded`. An upgrade made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.
 	*/
@@ -4871,7 +4871,7 @@ var Playbooks = class {
 	*
 	* Approves or rejects a `confirm` node on the inputs the confirmer read. `expected_revisions` names the revision of each of the node's inputs as read (`nodes[].inputs[].revision` on the case); an input that moved since is `409 PLAYBOOK_INPUT_CONFLICT`, `meta.conflicts` naming each, and nothing is written.
 	*
-	* An approval writes a `confirmation` entry whose value is the node's input values: it is the node's output, and the nodes reading it run next. A rejection writes a `rejection` entry with the `reason`: the node is `rejected`, and every node reading it is blocked, until its inputs change or it is approved. Another node, or a `confirm` node with a required input unset or reading a node that is not `done`, is `409 PLAYBOOK_NODE_NOT_CONFIRMABLE`. A confirmation made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.
+	* An approval writes a `confirmation` entry whose value is the node's input values: it is the node's output, and the nodes reading it run next. With `wait: true` it answers once every execution queued, and every one those queue, has settled or parked. A rejection writes a `rejection` entry with the `reason`: the node is `rejected`, and every node reading it is blocked, until its inputs change or it is approved. Another node, or a `confirm` node with a required input unset or reading a node that is not `done`, is `409 PLAYBOOK_NODE_NOT_CONFIRMABLE`. A confirmation made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.
 	*/
 	static confirmPlaybookCaseNode(options) {
 		return (options.client ?? client).post({
@@ -5419,7 +5419,7 @@ var Sessions = class {
 	/**
 	* Add a user message
 	*
-	* Saves a user message to the session. When autoGenerate is enabled on the session and no generation is currently in progress, generation is triggered automatically and the response mirrors GenerateSessionResponse. Otherwise returns the saved user message.
+	* Saves a user message to the session. When `auto_generate` is enabled on the session and no generation is currently in progress, generation is triggered automatically and the response is the generated turn, the same body `?wait=true` generate answers. Otherwise returns the saved user message.
 	*
 	*/
 	static addSessionMessage(options) {
@@ -7018,13 +7018,14 @@ const placeFlags = (args) => {
 };
 const PROJECT_ID_PARAM = "project_id";
 /**
-* Falls back to `NATURALI_PROJECT` for the `project_id` path or query
+* Falls back to `NATURALI_PROJECT_ID` for the `project_id` path or query
 * parameter when a command doesn't pass `--project-id` explicitly, so a user
 * working within one project doesn't have to repeat it on every command.
+* `NATURALI_PROJECT` is read after it so shells that still export it work.
 */
 const applyProjectIdEnvDefault = (args) => {
 	const { route, call } = args;
-	const envProjectId = process.env["NATURALI_PROJECT"];
+	const envProjectId = process.env["NATURALI_PROJECT_ID"] || process.env["NATURALI_PROJECT"];
 	if (!envProjectId) return;
 	if (route.pathParams.includes(PROJECT_ID_PARAM) && !(PROJECT_ID_PARAM in call.path)) call.path[PROJECT_ID_PARAM] = envProjectId;
 	else if (route.queryParams.includes(PROJECT_ID_PARAM) && !(PROJECT_ID_PARAM in call.query)) call.query[PROJECT_ID_PARAM] = envProjectId;
@@ -9883,7 +9884,8 @@ const routes = {
 		queryParams: [
 			"status",
 			"origin",
-			"expires_before",
+			"expires_from",
+			"expires_to",
 			"limit",
 			"offset"
 		],
@@ -9899,9 +9901,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Filter by lifecycle status",
+				"description": "Filter by lifecycle status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -9912,8 +9914,15 @@ const routes = {
 				"in": "query"
 			},
 			{
-				"name": "expires_before",
-				"description": "Return only items expiring at or before this timestamp",
+				"name": "expires_from",
+				"description": "Only items whose `expires_at` is at or after this timestamp (ISO 8601)",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "expires_to",
+				"description": "Only items whose `expires_at` is at or before this timestamp (ISO 8601)",
 				"required": false,
 				"type": "string",
 				"in": "query"
@@ -9959,9 +9968,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Lifecycle status the groups are built from (default `rejected`)",
+				"description": "Lifecycle statuses the groups are built from (default `rejected`). Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -10589,9 +10598,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Filter by chain status",
+				"description": "Filter by chain status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -12448,9 +12457,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Only decisions in this status",
+				"description": "Only decisions in these statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -14229,7 +14238,7 @@ const routes = {
 	"cancel-eval-run": {
 		serviceClass: "Evaluations",
 		operationId: "cancelEvalRun",
-		description: "Cancels a queued or running run: its outstanding item tasks are dropped so it stops consuming provider budget, and the run settles as `canceled`. Results already written are kept — they are real measurements of generations that were really paid for — and `completed_count` / `errored_count` report what ran. `aggregate_scores` is deliberately left null: a partial roll-up in the same field a completed run uses would read as a whole-dataset verdict. A run that has already finished is rejected with 400.",
+		description: "Cancels a queued or running run: its outstanding item tasks are dropped so it stops consuming provider budget, and the run settles as `cancelled`. Results already written are kept — they are real measurements of generations that were really paid for — and `completed_count` / `errored_count` report what ran. `aggregate_scores` is deliberately left null: a partial roll-up in the same field a completed run uses would read as a whole-dataset verdict. A run that has already finished is rejected with 400.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/evaluations",
 		httpMethod: "post",
 		pathParams: [
@@ -14290,9 +14299,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Filter by triage status",
+				"description": "Filter by triage status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -15226,9 +15235,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Filter by lifecycle status",
+				"description": "Filter by lifecycle status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -16045,7 +16054,7 @@ const routes = {
 			},
 			{
 				"name": "metadata",
-				"description": "A `MetadataBag` on a field where `null` is meaningful — a full-replacement update that clears the bag, or a record whose bag was never set.",
+				"description": "A `MetadataBag` on a request field where `null` is meaningful: a full-replacement update that clears the bag. A record whose bag is unset leaves the field out.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -17133,7 +17142,7 @@ const routes = {
 			},
 			{
 				"name": "on",
-				"description": "The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
+				"description": "The event a firing reads. `generations.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversation_messages.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
 				"required": true,
 				"type": "string",
 				"in": "body"
@@ -17254,7 +17263,7 @@ const routes = {
 			},
 			{
 				"name": "on",
-				"description": "The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
+				"description": "The event a firing reads. `generations.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversation_messages.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -17569,7 +17578,8 @@ const routes = {
 			"mechanism",
 			"outcome",
 			"generation_id",
-			"since",
+			"from",
+			"to",
 			"limit",
 			"offset"
 		],
@@ -17612,8 +17622,15 @@ const routes = {
 				"in": "query"
 			},
 			{
-				"name": "since",
-				"description": "Only assertions recorded at or after this instant.",
+				"name": "from",
+				"description": "Only assertions recorded at or after this instant (ISO 8601).",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "to",
+				"description": "Only assertions recorded at or before this instant (ISO 8601).",
 				"required": false,
 				"type": "string",
 				"in": "query"
@@ -18343,7 +18360,7 @@ const routes = {
 			},
 			{
 				"name": "output_mapping",
-				"description": "The shape of a succeeded run's `output`, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as `summary.title` builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ \"state\": <final run state> }`, which includes `state.input` and `state.nodes.<id>`. A missing path maps to `null`; a mapping that throws fails the run. Null (or omitted) keys `output` by terminal node id. Versioned with the graph; `null` on update clears it.",
+				"description": "The shape of a completed run's `output`, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as `summary.title` builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ \"state\": <final run state> }`, which includes `state.input` and `state.nodes.<id>`. A missing path maps to `null`; a mapping that throws fails the run. Null (or omitted) keys `output` by terminal node id. Versioned with the graph; `null` on update clears it.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -18360,7 +18377,7 @@ const routes = {
 	"validate-orchestration": {
 		serviceClass: "Orchestrations",
 		operationId: "validateOrchestration",
-		description: "Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges reference existing nodes, the graph is acyclic (unless it contains a loop node), and every `input_mapping` `{\"var\": \"...\"}` reference resolves to a state key written by an upstream node or seeded by `input_schema`. Returns blocking `errors` and non-blocking `warnings` (e.g. a state key only written on a conditional branch). The same `errors` checks are enforced on create and update, which fail with `400` when any error is present.",
+		description: "Statically validates an orchestration graph without persisting anything. Checks that every node has its required field, node ids are unique, edges reference existing nodes, the graph is acyclic (unless it contains a loop node), and every `input_mapping` `{\"var\": \"...\"}` reference resolves to a state key written by an upstream node or seeded by `input_schema`. Returns blocking `problems` and non-blocking `warnings` (e.g. a state key only written on a conditional branch). The same checks are enforced on create and update, which fail with `400 ORCHESTRATION_VALIDATION_FAILED` listing the same items under `meta.problems` and `meta.warnings`.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/orchestrations",
 		httpMethod: "post",
 		pathParams: ["project_id"],
@@ -18550,7 +18567,7 @@ const routes = {
 			},
 			{
 				"name": "output_mapping",
-				"description": "The shape of a succeeded run's `output`, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as `summary.title` builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ \"state\": <final run state> }`, which includes `state.input` and `state.nodes.<id>`. A missing path maps to `null`; a mapping that throws fails the run. Null (or omitted) keys `output` by terminal node id. Versioned with the graph; `null` on update clears it.",
+				"description": "The shape of a completed run's `output`, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as `summary.title` builds a nested object); each value is JSON Logic (https://jsonlogic.com) evaluated against `{ \"state\": <final run state> }`, which includes `state.input` and `state.nodes.<id>`. A missing path maps to `null`; a mapping that throws fails the run. Null (or omitted) keys `output` by terminal node id. Versioned with the graph; `null` on update clears it.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -18791,7 +18808,7 @@ const routes = {
 	"start-orchestration-run": {
 		serviceClass: "Orchestrations",
 		operationId: "startOrchestrationRun",
-		description: "Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status \"queued\" (a worker then claims it and moves it to \"running\") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as \"sleeping\" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.",
+		description: "Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status \"queued\" (a worker then claims it and moves it to \"running\") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/completed/failed). Delay and poll waits park the run as \"sleeping\" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/orchestrations",
 		httpMethod: "post",
 		pathParams: ["project_id"],
@@ -18829,7 +18846,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call made by an agent node of this run — including the agents of any child run a `loop` or `sub_orchestration` node starts. The header name is `X-Naturali-Context-` plus the key verbatim; no character is re-cased.\n\nThe bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. It is **write-only**: a run is a record every principal who may read runs can read, and a credential in it is not theirs to see, so it is never returned on one. It also does not outlive the run: reaching a terminal status (`succeeded`, `failed`, `cancelled` or `expired`) clears it. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.\n\nThe reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here.",
+				"description": "Key-value pairs forwarded as `X-Naturali-Context-<key>` headers on every `http` and `mcp` tool call made by an agent node of this run — including the agents of any child run a `loop` or `sub_orchestration` node starts. The header name is `X-Naturali-Context-` plus the key verbatim; no character is re-cased.\n\nThe bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. It is **write-only**: a run is a record every principal who may read runs can read, and a credential in it is not theirs to see, so it is never returned on one. It also does not outlive the run: reaching a terminal status (`completed`, `failed`, `cancelled` or `expired`) clears it. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.\n\nThe reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -18850,7 +18867,7 @@ const routes = {
 			},
 			{
 				"name": "wait",
-				"description": "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.",
+				"description": "When true, block until the run reaches a terminal (completed/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.",
 				"required": false,
 				"type": "boolean",
 				"in": "body"
@@ -19458,9 +19475,9 @@ const routes = {
 			},
 			{
 				"name": "automation_status",
-				"description": "Only the cases in this automation status",
+				"description": "Only the cases in these automation statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -19530,7 +19547,7 @@ const routes = {
 	"write-playbook-case-inputs": {
 		serviceClass: "Playbooks",
 		operationId: "writePlaybookCaseInputs",
-		description: "Writes a batch of manual inputs, all or none. Each write names the revision it read in `expected_revision`, `null` for a field still unset; when any field has moved on the whole batch is refused with `409 PLAYBOOK_INPUT_CONFLICT` and `meta.conflicts` names each field. An input the case's version does not declare, one that reads another node, or a value its schema refuses is `400 PLAYBOOK_INPUT_INVALID`. A value equal to the field's current one writes no revision. Once written, every node the write makes runnable is queued to run, unless the case is paused. A write made with a credential the case's own work runs as — the case, one of its executions in flight, or the task or run one started — is `403 PLAYBOOK_SELF_WRITE`.",
+		description: "Writes a batch of manual inputs, all or none. Each write names the revision it read in `expected_revision`, `null` for a field still unset; when any field has moved on the whole batch is refused with `409 PLAYBOOK_INPUT_CONFLICT` and `meta.conflicts` names each field. An input the case's version does not declare, one that reads another node, or a value its schema refuses is `400 PLAYBOOK_INPUT_INVALID`. A value equal to the field's current one writes no revision. Once written, every node the write makes runnable is queued to run, unless the case is paused. With `wait: true` it answers once every execution queued, and every one those queue, has settled or parked. A write made with a credential the case's own work runs as — the case, one of its executions in flight, or the task or run one started — is `403 PLAYBOOK_SELF_WRITE`.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/playbooks",
 		httpMethod: "post",
 		pathParams: ["project_id", "case_id"],
@@ -19558,17 +19575,24 @@ const routes = {
 				"required": true,
 				"type": "array",
 				"in": "body"
+			},
+			{
+				"name": "wait",
+				"description": "Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
 			}
 		]
 	},
 	"get-playbook-case-missing": {
 		serviceClass: "Playbooks",
 		operationId: "getPlaybookCaseMissing",
-		description: "Returns the manual inputs still unset, or refused by their schema, before `node` can be reached, grouped in waves: nothing in a later wave can run before the earlier ones are filled.",
+		description: "Returns the manual inputs still unset, or refused by their schema, before `node_id` can be reached, grouped in waves: nothing in a later wave can run before the earlier ones are filled.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/playbooks",
 		httpMethod: "get",
 		pathParams: ["project_id", "case_id"],
-		queryParams: ["node"],
+		queryParams: ["node_id"],
 		headerParams: [],
 		cookieParams: [],
 		flags: [
@@ -19587,8 +19611,8 @@ const routes = {
 				"in": "path"
 			},
 			{
-				"name": "node",
-				"description": "The key of the node to reach, usually a final node",
+				"name": "node_id",
+				"description": "The ID of the node to reach, usually a final node",
 				"required": true,
 				"type": "string",
 				"in": "query"
@@ -19603,7 +19627,7 @@ const routes = {
 		httpMethod: "get",
 		pathParams: ["project_id", "case_id"],
 		queryParams: [
-			"node",
+			"node_id",
 			"limit",
 			"offset"
 		],
@@ -19625,7 +19649,7 @@ const routes = {
 				"in": "path"
 			},
 			{
-				"name": "node",
+				"name": "node_id",
 				"description": "Only the entries of this node",
 				"required": false,
 				"type": "string",
@@ -19650,7 +19674,7 @@ const routes = {
 	"run-playbook-case-node": {
 		serviceClass: "Playbooks",
 		operationId: "runPlaybookCaseNode",
-		description: "Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` one: this is how a failed node is retried. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs as the author of the case's playbook version, whose permission to start it is checked again here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`); an author that no longer exists is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`. Only a `ready`, `stale` or `failed` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`. The output is written as an entry when the execution settles. A value equal to the node's current output writes no revision. If the node's inputs change while it runs, the execution settles as `superseded` and writes nothing. Without `wait` the execution answers `running` and settles in the background. With `wait: true` it answers once the executor settles, or once it parks: a workflow task still open, or an orchestration run waiting on a person or a timer, settles the node when it closes or ends.",
+		description: "Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` or `done` one: this is how a failed node is retried, and how a `done` node is recomputed after an upgrade changed its executor. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs as the author of the case's playbook version, whose permission to start it is checked again here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`); an author that no longer exists is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`. Only a `ready`, `stale`, `failed` or `done` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`. The output is written as an entry when the execution settles. A value equal to the node's current output writes no revision. If the node's inputs change while it runs, the execution settles as `superseded` and writes nothing. Without `wait` the execution answers `running` and settles in the background. With `wait: true` it answers once the executor settles, or once it parks: a workflow task still open, or an orchestration run waiting on a person or a timer, settles the node when it closes or ends.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/playbooks",
 		httpMethod: "post",
 		pathParams: [
@@ -19678,7 +19702,7 @@ const routes = {
 			},
 			{
 				"name": "node",
-				"description": "The key of a node of the case's playbook version",
+				"description": "The ID of a node of the case's playbook version",
 				"required": true,
 				"type": "string",
 				"in": "path"
@@ -19700,7 +19724,7 @@ const routes = {
 		httpMethod: "get",
 		pathParams: ["project_id", "case_id"],
 		queryParams: [
-			"node",
+			"node_id",
 			"limit",
 			"offset"
 		],
@@ -19722,7 +19746,7 @@ const routes = {
 				"in": "path"
 			},
 			{
-				"name": "node",
+				"name": "node_id",
 				"description": "Only the executions of this node",
 				"required": false,
 				"type": "string",
@@ -19785,7 +19809,7 @@ const routes = {
 	"export-playbook-case-node": {
 		serviceClass: "Playbooks",
 		operationId: "exportPlaybookCaseNode",
-		description: "Renders one revision of a final node as files, one export per transformation: each transformation's tool is called with the case's `case_id` and `subject`, the `node`, the `revision` and that revision's `output`, and must answer a file (`execute.response_mode: base64`) of its `format`'s content type. The file is kept in the project's files under `/.system/playbooks/`. An export never feeds a node. Without `revision` the node's current output is exported, which needs the node `done` (`409 PLAYBOOK_NODE_NOT_EXPORTABLE`); a `revision` names an earlier output or confirmation of the node. Each tool runs as the author of the case's playbook version, whose permission to call it is checked here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`. Without `wait` every export answers `running` and settles in the background; with `wait: true` it answers once each has its file or its error.",
+		description: "Renders one revision of a final node as files, one export per transformation: each transformation's tool is called with the case's `case_id` and `subject`, the `node_id`, the `revision` and that revision's `output`, and must answer a file (`execute.response_mode: base64`) of its `format`'s content type. The file is kept in the project's files under `/.system/playbooks/`. An export never feeds a node. Without `revision` the node's current output is exported, which needs the node `done` (`409 PLAYBOOK_NODE_NOT_EXPORTABLE`); a `revision` names an earlier output or confirmation of the node. Each tool runs as the author of the case's playbook version, whose permission to call it is checked here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`. Without `wait` every export answers `running` and settles in the background; with `wait: true` it answers once each has its file or its error.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/playbooks",
 		httpMethod: "post",
 		pathParams: [
@@ -19813,7 +19837,7 @@ const routes = {
 			},
 			{
 				"name": "node",
-				"description": "The key of a node of the case's playbook version",
+				"description": "The ID of a node of the case's playbook version",
 				"required": true,
 				"type": "string",
 				"in": "path"
@@ -19849,7 +19873,7 @@ const routes = {
 		httpMethod: "get",
 		pathParams: ["project_id", "case_id"],
 		queryParams: [
-			"node",
+			"node_id",
 			"transformation",
 			"limit",
 			"offset"
@@ -19872,7 +19896,7 @@ const routes = {
 				"in": "path"
 			},
 			{
-				"name": "node",
+				"name": "node_id",
 				"description": "Only the exports of this node",
 				"required": false,
 				"type": "string",
@@ -19942,7 +19966,7 @@ const routes = {
 	"upgrade-playbook-case": {
 		serviceClass: "Playbooks",
 		operationId: "upgradePlaybookCase",
-		description: "Moves a case to another version of its playbook: the playbook's current version, or the `version` named, an earlier one included. Values carry over by node key, and every node's state is read against the new version: a node added is open, a node removed leaves the structure while its entries stay, a node whose input reads another field is `stale`, and a value its input's new schema refuses is missing again. The cascade then runs what became runnable. Each upgrade is recorded with what moved; the version the case is already on records nothing. An execution running is `409 PLAYBOOK_CASE_BUSY`; one queued but not started settles `superseded`. An upgrade made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.",
+		description: "Moves a case to another version of its playbook: the playbook's current version, or the `version` named, an earlier one included. Values carry over by node ID, and every node's state is read against the new version: a node added is open, a node removed leaves the structure while its entries stay, a node whose input reads another field is `stale`, and a value its input's new schema refuses is missing again. The cascade then runs what became runnable. With `wait: true` it answers once every execution queued, and every one those queue, has settled or parked. Each upgrade is recorded with what moved; the version the case is already on records nothing. An execution running is `409 PLAYBOOK_CASE_BUSY`; one queued but not started settles `superseded`. An upgrade made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/playbooks",
 		httpMethod: "post",
 		pathParams: ["project_id", "case_id"],
@@ -19970,6 +19994,13 @@ const routes = {
 				"required": false,
 				"type": "integer",
 				"in": "body"
+			},
+			{
+				"name": "wait",
+				"description": "Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
 			}
 		]
 	},
@@ -20065,7 +20096,7 @@ const routes = {
 	"confirm-playbook-case-node": {
 		serviceClass: "Playbooks",
 		operationId: "confirmPlaybookCaseNode",
-		description: "Approves or rejects a `confirm` node on the inputs the confirmer read. `expected_revisions` names the revision of each of the node's inputs as read (`nodes[].inputs[].revision` on the case); an input that moved since is `409 PLAYBOOK_INPUT_CONFLICT`, `meta.conflicts` naming each, and nothing is written. An approval writes a `confirmation` entry whose value is the node's input values: it is the node's output, and the nodes reading it run next. A rejection writes a `rejection` entry with the `reason`: the node is `rejected`, and every node reading it is blocked, until its inputs change or it is approved. Another node, or a `confirm` node with a required input unset or reading a node that is not `done`, is `409 PLAYBOOK_NODE_NOT_CONFIRMABLE`. A confirmation made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.",
+		description: "Approves or rejects a `confirm` node on the inputs the confirmer read. `expected_revisions` names the revision of each of the node's inputs as read (`nodes[].inputs[].revision` on the case); an input that moved since is `409 PLAYBOOK_INPUT_CONFLICT`, `meta.conflicts` naming each, and nothing is written. An approval writes a `confirmation` entry whose value is the node's input values: it is the node's output, and the nodes reading it run next. With `wait: true` it answers once every execution queued, and every one those queue, has settled or parked. A rejection writes a `rejection` entry with the `reason`: the node is `rejected`, and every node reading it is blocked, until its inputs change or it is approved. Another node, or a `confirm` node with a required input unset or reading a node that is not `done`, is `409 PLAYBOOK_NODE_NOT_CONFIRMABLE`. A confirmation made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/playbooks",
 		httpMethod: "post",
 		pathParams: [
@@ -20093,7 +20124,7 @@ const routes = {
 			},
 			{
 				"name": "node",
-				"description": "The key of a node of the case's playbook version",
+				"description": "The ID of a node of the case's playbook version",
 				"required": true,
 				"type": "string",
 				"in": "path"
@@ -20118,6 +20149,13 @@ const routes = {
 				"required": true,
 				"type": "object",
 				"in": "body"
+			},
+			{
+				"name": "wait",
+				"description": "Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
 			}
 		]
 	},
@@ -21051,7 +21089,7 @@ const routes = {
 			},
 			{
 				"name": "mode",
-				"description": "enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quota.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.",
+				"description": "enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the pre-generation check); monitor observes without blocking — a breach fires the quotas.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the request is let through.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -21376,9 +21414,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "Filter by session status (open, closed, or expired)",
+				"description": "Filter by session status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -21614,7 +21652,7 @@ const routes = {
 	"add-session-message": {
 		serviceClass: "Sessions",
 		operationId: "addSessionMessage",
-		description: "Saves a user message to the session. When autoGenerate is enabled on the session and no generation is currently in progress, generation is triggered automatically and the response mirrors GenerateSessionResponse. Otherwise returns the saved user message.",
+		description: "Saves a user message to the session. When `auto_generate` is enabled on the session and no generation is currently in progress, generation is triggered automatically and the response is the generated turn, the same body `?wait=true` generate answers. Otherwise returns the saved user message.",
 		moduleDocsUrl: "https://naturali.ai/docs/modules/sessions",
 		httpMethod: "post",
 		pathParams: ["project_id", "session_id"],
@@ -21999,9 +22037,9 @@ const routes = {
 			},
 			{
 				"name": "status",
-				"description": "",
+				"description": "Filter by whether the task is open or closed. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`.",
 				"required": false,
-				"type": "string",
+				"type": "array",
 				"in": "query"
 			},
 			{
@@ -22463,7 +22501,7 @@ const routes = {
 			},
 			{
 				"name": "preset_parameters",
-				"description": "Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.\n\nValues accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.",
+				"description": "Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key. On an `mcp` tool a preset reaches each action whose input schema declares it; an action whose schema declares no properties receives every one.\n\nValues accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -22605,7 +22643,7 @@ const routes = {
 			},
 			{
 				"name": "preset_parameters",
-				"description": "Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key.\n\nValues accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.",
+				"description": "Fixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key. On an `mcp` tool a preset reaches each action whose input schema declares it; an action whose schema declares no properties receives every one.\n\nValues accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's `tool_context` fails the call with `MISSING_TOOL_CONTEXT_KEY` rather than sending the literal placeholder. `{{secret:...}}` is not resolved here. See the Tool Context reference.",
 				"required": false,
 				"type": "object",
 				"in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.201.1",
+  "version": "0.203.0",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "keywords": [
     "naturali",
@@ -31,7 +31,7 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@naturali/sdk": "0.201.1",
+    "@naturali/sdk": "0.203.0",
     "@ttoss/openapi-codegen": "^0.5.0",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",