@naturali/cli 0.78.6 → 0.80.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.78.6";
+var version = "0.80.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -2479,6 +2479,126 @@ var Files = class {
 		});
 	}
 };
+var Formations = class {
+	/**
+	* Validate a formation template
+	*
+	* Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a YAML/JSON string.
+	*
+	*/
+	static validateFormation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/formations/validate",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Plan a formation deployment
+	*
+	* Computes a diff between the desired template and the current stack state without making any changes. Returns the list of planned actions.
+	*
+	*/
+	static planFormation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/formations/plan",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List formations
+	*
+	* Returns all formation stacks for a project
+	*/
+	static listFormations(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/formations",
+			...options
+		});
+	}
+	/**
+	* Create a new formation
+	*
+	* Validates the template, creates the formation record, then provisions all declared resources in dependency order.
+	*
+	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `201` and `status: "failed"`, and `error` explains why (the resources created before the failure are rolled back). Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `create-formation && …` does not lie.
+	*
+	*/
+	static createFormation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/formations",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete an formation
+	*
+	* Deletes the formation stack and all its managed resources in reverse dependency order.
+	*
+	* A resource the platform refuses to delete on its own — most often an agent that has generation or trace history — fails the teardown with `409 FORMATION_DELETE_FAILED`, naming every blocking resource in `error.meta.failures`. Resolve the blockers (for an agent, `DELETE /v1/projects/{project_id}/agents/{agent_id}?force=true` also removes its generations and traces, and `deletion_policy: retain` exempts it from teardown entirely) and delete the formation again.
+	*
+	* A refusal the platform can foresee is found by a pre-flight, before the first delete: nothing is removed, and the formation stays `active` and intact for the retry. An unforeseeable error surfaces mid-teardown instead, where resources deleted before the blocker stay deleted and the formation is left in `delete_failed`. The error message states which happened.
+	*
+	*/
+	static deleteFormation(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/formations/{formation_id}",
+			...options
+		});
+	}
+	/**
+	* Get a specific formation
+	*
+	* Returns the formation stack including its current resources.
+	*/
+	static getFormation(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/formations/{formation_id}",
+			...options
+		});
+	}
+	/**
+	* Update an formation
+	*
+	* Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.
+	*
+	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.
+	*
+	*/
+	static updateFormation(options) {
+		return (options.client ?? client).put({
+			url: "/v1/projects/{project_id}/formations/{formation_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List formation operation events
+	*
+	* Returns all operations (create, update, delete) with their event logs for the formation, ordered chronologically.
+	*
+	*/
+	static listFormationEvents(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/formations/{formation_id}/events",
+			...options
+		});
+	}
+};
 var Generations = class {
 	/**
 	* List generations
@@ -3139,7 +3259,9 @@ var Orchestrations = class {
 	/**
 	* List orchestration runs
 	*
-	* Returns orchestration runs the caller can access, optionally filtered by orchestration.
+	* Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+	*
+	* Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.
 	*/
 	static listOrchestrationRuns(options) {
 		return (options.client ?? client).get({
@@ -3789,7 +3911,7 @@ var Tools = class {
 	*
 	* Directly invokes a tool and returns its output. Supported for `http`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input.
 	* For `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` ("not available on this tool") before any outbound request is made.
-	* `preset_parameters` stored on the tool are merged with the caller-supplied `input` before execution; preset keys take lower precedence.
+	* `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.
 	*
 	*/
 	static callTool(options) {
@@ -4299,6 +4421,7 @@ var NaturaliClient = class {
 	evaluations;
 	exceptions;
 	files;
+	formations;
 	generations;
 	guardrails;
 	ingestionRules;
@@ -4346,6 +4469,7 @@ var NaturaliClient = class {
 		this.evaluations = bindResource(Evaluations, this.http);
 		this.exceptions = bindResource(Exceptions, this.http);
 		this.files = bindResource(Files, this.http);
+		this.formations = bindResource(Formations, this.http);
 		this.generations = bindResource(Generations, this.http);
 		this.guardrails = bindResource(Guardrails, this.http);
 		this.ingestionRules = bindResource(IngestionRules, this.http);
@@ -4388,6 +4512,7 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	Evaluations: () => Evaluations,
 	Exceptions: () => Exceptions,
 	Files: () => Files,
+	Formations: () => Formations,
 	Generations: () => Generations,
 	Guardrails: () => Guardrails,
 	IngestionRules: () => IngestionRules,
@@ -10107,6 +10232,284 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"validate-formation": {
+		serviceClass: "Formations",
+		operationId: "validateFormation",
+		description: "Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a YAML/JSON string.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "template",
+				"description": "A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing.\n",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "parameters",
+				"description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. When provided, the validation result also reports required parameters that are still missing after applying these values.\n",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			}
+		]
+	},
+	"plan-formation": {
+		serviceClass: "Formations",
+		operationId: "planFormation",
+		description: "Computes a diff between the desired template and the current stack state without making any changes. Returns the list of planned actions.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "formation_id",
+				"description": "Existing formation ID to compare against. Omit for new formation planning.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "template",
+				"description": "A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing.\n",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "parameters",
+				"description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. A parameter declared with `use_previous_value: true` may be omitted to reuse its stored value.\n",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			}
+		]
+	},
+	"list-formations": {
+		serviceClass: "Formations",
+		operationId: "listFormations",
+		description: "Returns all formation stacks for a project",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: ["limit", "offset"],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum number of results to return",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "Number of results to skip",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
+	"create-formation": {
+		serviceClass: "Formations",
+		operationId: "createFormation",
+		description: "Validates the template, creates the formation record, then provisions all declared resources in dependency order. A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `201` and `status: \"failed\"`, and `error` explains why (the resources created before the failure are rolled back). Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `create-formation && …` does not lie.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "name",
+				"description": "Human-readable name for the formation stack",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "template",
+				"description": "A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing.\n",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "parameters",
+				"description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here.\n",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "metadata",
+				"description": "Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`.\n",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			}
+		]
+	},
+	"get-formation": {
+		serviceClass: "Formations",
+		operationId: "getFormation",
+		description: "Returns the formation stack including its current resources.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "get",
+		pathParams: ["project_id", "formation_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "formation_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"update-formation": {
+		serviceClass: "Formations",
+		operationId: "updateFormation",
+		description: "Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state. A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: \"failed\"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "put",
+		pathParams: ["project_id", "formation_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "formation_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "template",
+				"description": "A formation template supplied as either a JSON object or a YAML/JSON string. When a string is provided the server parses it with a YAML parser (JSON is valid YAML) before processing.\n",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "parameters",
+				"description": "Runtime parameter values that override or supply template parameter defaults. Keys must match parameter names declared in `template.parameters`. Required parameters (those without a default) must be provided here, unless the parameter is declared with `use_previous_value: true`, in which case omitting it reuses the previously stored value.\n",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "metadata",
+				"description": "Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`.\n",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			}
+		]
+	},
+	"delete-formation": {
+		serviceClass: "Formations",
+		operationId: "deleteFormation",
+		description: "Deletes the formation stack and all its managed resources in reverse dependency order. A resource the platform refuses to delete on its own — most often an agent that has generation or trace history — fails the teardown with `409 FORMATION_DELETE_FAILED`, naming every blocking resource in `error.meta.failures`. Resolve the blockers (for an agent, `DELETE /v1/projects/{project_id}/agents/{agent_id}?force=true` also removes its generations and traces, and `deletion_policy: retain` exempts it from teardown entirely) and delete the formation again. A refusal the platform can foresee is found by a pre-flight, before the first delete: nothing is removed, and the formation stays `active` and intact for the retry. An unforeseeable error surfaces mid-teardown instead, where resources deleted before the blocker stay deleted and the formation is left in `delete_failed`. The error message states which happened.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "delete",
+		pathParams: ["project_id", "formation_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "formation_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"list-formation-events": {
+		serviceClass: "Formations",
+		operationId: "listFormationEvents",
+		description: "Returns all operations (create, update, delete) with their event logs for the formation, ordered chronologically.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/formations",
+		httpMethod: "get",
+		pathParams: ["project_id", "formation_id"],
+		queryParams: ["limit", "offset"],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "formation_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum number of results to return",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "Number of results to skip",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
 	"list-generations": {
 		serviceClass: "Generations",
 		operationId: "listGenerations",
@@ -12073,12 +12476,14 @@ const routes = {
 	"list-orchestration-runs": {
 		serviceClass: "Orchestrations",
 		operationId: "listOrchestrationRuns",
-		description: "Returns orchestration runs the caller can access, optionally filtered by orchestration.",
+		description: "Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all. Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/orchestrations",
 		httpMethod: "get",
 		pathParams: ["project_id"],
 		queryParams: [
 			"orchestration_id",
+			"parent_orchestration_run_id",
+			"nested",
 			"limit",
 			"offset"
 		],
@@ -12097,6 +12502,20 @@ const routes = {
 				"type": "string",
 				"in": "query"
 			},
+			{
+				"name": "parent_orchestration_run_id",
+				"description": "Filter to the runs one specific parent run's `loop` / `sub_orchestration` nodes started (run_...). This is how a caller holding a parent names the individual children behind its `usage`.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "nested",
+				"description": "Filter by whether the run was started by another run. `false` returns only the runs a caller started (no parent), which is the set to sum `usage` over; `true` returns only the runs a `loop` / `sub_orchestration` node started, across every parent. Omit to return both.\n\nContradicting `parent_orchestration_run_id` with `nested=false` is a `400`; any value other than `true` or `false` is a `400`.",
+				"required": false,
+				"type": "boolean",
+				"in": "query"
+			},
 			{
 				"name": "limit",
 				"description": "Maximum number of results to return",
@@ -13727,7 +14146,7 @@ const routes = {
 			},
 			{
 				"name": "preset_parameters",
-				"description": "Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.",
+				"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.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -13865,7 +14284,7 @@ const routes = {
 			},
 			{
 				"name": "preset_parameters",
-				"description": "Fixed parameters merged into every action-based tool call. Keys matching fields in the action's input schema are removed from the schema shown to the model and injected automatically at execution time.",
+				"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.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -13918,7 +14337,7 @@ const routes = {
 	"call-tool": {
 		serviceClass: "Tools",
 		operationId: "callTool",
-		description: "Directly invokes a tool and returns its output. Supported for `http`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input. For `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` (\"not available on this tool\") before any outbound request is made. `preset_parameters` stored on the tool are merged with the caller-supplied `input` before execution; preset keys take lower precedence.",
+		description: "Directly invokes a tool and returns its output. Supported for `http`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input. For `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` (\"not available on this tool\") before any outbound request is made. `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/tools",
 		httpMethod: "post",
 		pathParams: ["project_id", "tool_id"],
@@ -13947,7 +14366,7 @@ const routes = {
 			},
 			{
 				"name": "input",
-				"description": "Input parameters for the tool call. These are merged with the tool's `preset_parameters` before execution (caller-supplied values take precedence).\n",
+				"description": "Input parameters for the tool call. These are merged with the tool's `preset_parameters` before execution; a preset value wins over the same key sent here.\n",
 				"required": false,
 				"type": "object",
 				"in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.78.6",
+  "version": "0.80.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.78.6"
+    "@naturali/sdk": "0.80.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",