@naturali/cli 0.58.0 → 0.59.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.58.0";
+var version = "0.59.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
@@ -1322,7 +1322,13 @@ var Generations = class {
 	/**
 	* Run an agent generation
 	*
-	* Sends messages to the agent, resolves its tools, and runs the model loop. Returns the final text when `status` is `completed` (plus `object` when the agent has an output schema), or the pending `tool_calls` when `status` is `requires_action`. With `stream: true` the response is a Server-Sent Events stream (Content-Type text/event-stream) proxied from the runtime instead of a single JSON body.
+	* Sends messages to the agent, resolves its tools, and runs the model loop.
+	*
+	* Background by default: this returns `202` immediately with a `generation_id`, and the turn runs on. Poll [`GET /v1/projects/{project_id}/generations/{generation_id}`](/docs/api/generations/get-generation) until its `status` leaves `in_progress`.
+	*
+	* Pass `?wait=true` to block instead and receive the turn itself — the final text when `status` is `completed` (plus `object` when the agent has an output schema), or the pending `tool_calls` when `status` is `requires_action`.
+	*
+	* With `stream: true` the response is a Server-Sent Events stream (Content-Type text/event-stream) proxied from the runtime. A stream holds the request open by definition, so it always waits; combining it with an explicit `wait=false` is a `400`.
 	*
 	*/
 	static createGeneration(options) {
@@ -1994,7 +2000,13 @@ var Sessions = class {
 	/**
 	* Generate a response
 	*
-	* Runs the agent over the session's accumulated messages and returns its reply. `status` is `completed` with the assistant `message`, or `requires_action` with the pending `required_action` tool calls. `model` overrides the agent's default model for this turn only.
+	* Runs the agent over the session's accumulated messages.
+	*
+	* Background by default: this returns `202` immediately and the turn runs on. The reply lands in the transcript, so poll [`GET /v1/projects/{project_id}/agents/{agent_id}/sessions/{session_id}/messages`](/docs/api/sessions/list-session-messages) for the assistant message, or read the session for its `status`.
+	*
+	* Pass `?wait=true` to block instead and receive the turn itself: `status` is `completed` with the assistant `message`, or `requires_action` with the pending `required_action` tool calls.
+	*
+	* `model` overrides the agent's default model for this turn only.
 	*
 	*/
 	static generateSessionResponse(options) {
@@ -4908,11 +4920,11 @@ const routes = {
 	"create-generation": {
 		serviceClass: "Generations",
 		operationId: "createGeneration",
-		description: "Sends messages to the agent, resolves its tools, and runs the model loop. Returns the final text when `status` is `completed` (plus `object` when the agent has an output schema), or the pending `tool_calls` when `status` is `requires_action`. With `stream: true` the response is a Server-Sent Events stream (Content-Type text/event-stream) proxied from the runtime instead of a single JSON body.",
+		description: "Sends messages to the agent, resolves its tools, and runs the model loop. Background by default: this returns `202` immediately with a `generation_id`, and the turn runs on. Poll [`GET /v1/projects/{project_id}/generations/{generation_id}`](/docs/api/generations/get-generation) until its `status` leaves `in_progress`. Pass `?wait=true` to block instead and receive the turn itself — the final text when `status` is `completed` (plus `object` when the agent has an output schema), or the pending `tool_calls` when `status` is `requires_action`. With `stream: true` the response is a Server-Sent Events stream (Content-Type text/event-stream) proxied from the runtime. A stream holds the request open by definition, so it always waits; combining it with an explicit `wait=false` is a `400`.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/generations",
 		httpMethod: "post",
 		pathParams: ["project_id", "agent_id"],
-		queryParams: [],
+		queryParams: ["wait"],
 		flags: [
 			{
 				"name": "project_id",
@@ -4928,6 +4940,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "wait",
+				"description": "When omitted or `false` (the default), the generation runs in the background and this returns `202` with a `generation_id` to poll. Pass `true` to block until the turn settles and receive it inline.",
+				"required": false,
+				"type": "boolean",
+				"in": "query"
+			},
 			{
 				"name": "messages",
 				"description": "The conversation to run the model turn over.",
@@ -6635,7 +6654,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value string headers injected into every tool call made during the session or generation.\n",
+				"description": "Context forwarded to every `http`/`mcp` tool call made during the session or generation: each entry is sent as an `X-Naturali-Context-<key>` request header, so a per-user credential can reach a tool endpoint without being written into the prompt.\n\nA key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.\n",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -6792,7 +6811,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value string headers injected into every tool call made during the session or generation.\n",
+				"description": "Context forwarded to every `http`/`mcp` tool call made during the session or generation: each entry is sent as an `X-Naturali-Context-<key>` request header, so a per-user credential can reach a tool endpoint without being written into the prompt.\n\nA key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.\n",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -6809,7 +6828,7 @@ const routes = {
 	"generate-session-response": {
 		serviceClass: "Sessions",
 		operationId: "generateSessionResponse",
-		description: "Runs the agent over the session's accumulated messages and returns its reply. `status` is `completed` with the assistant `message`, or `requires_action` with the pending `required_action` tool calls. `model` overrides the agent's default model for this turn only.",
+		description: "Runs the agent over the session's accumulated messages. Background by default: this returns `202` immediately and the turn runs on. The reply lands in the transcript, so poll [`GET /v1/projects/{project_id}/agents/{agent_id}/sessions/{session_id}/messages`](/docs/api/sessions/list-session-messages) for the assistant message, or read the session for its `status`. Pass `?wait=true` to block instead and receive the turn itself: `status` is `completed` with the assistant `message`, or `requires_action` with the pending `required_action` tool calls. `model` overrides the agent's default model for this turn only.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/sessions",
 		httpMethod: "post",
 		pathParams: [
@@ -6817,7 +6836,7 @@ const routes = {
 			"agent_id",
 			"session_id"
 		],
-		queryParams: [],
+		queryParams: ["wait"],
 		flags: [
 			{
 				"name": "project_id",
@@ -6840,6 +6859,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "wait",
+				"description": "When omitted or `false` (the default), the turn runs in the background and this returns `202`; its reply lands in the session transcript. Pass `true` to block until the turn settles and receive it inline.",
+				"required": false,
+				"type": "boolean",
+				"in": "query"
+			},
 			{
 				"name": "model",
 				"description": "Overrides the agent's default model for this turn only.",
@@ -6849,7 +6875,7 @@ const routes = {
 			},
 			{
 				"name": "tool_context",
-				"description": "Key-value string headers injected into every tool call made during the session or generation.\n",
+				"description": "Context forwarded to every `http`/`mcp` tool call made during the session or generation: each entry is sent as an `X-Naturali-Context-<key>` request header, so a per-user credential can reach a tool endpoint without being written into the prompt.\n\nA key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.\n",
 				"required": false,
 				"type": "object",
 				"in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/sdk": "0.58.0"
+    "@naturali/sdk": "0.59.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",