@naturali/cli 0.115.1 → 0.117.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.115.1";
+var version = "0.117.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -3376,7 +3376,7 @@ var Orchestrations = class {
 	/**
 	* List orchestration runs
 	*
-	* Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+	* Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, by status, 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.
 	*/
@@ -3413,6 +3413,24 @@ var Orchestrations = class {
 		});
 	}
 	/**
+	* Pause an orchestration run
+	*
+	* Parks a run in flight as `awaiting_input` at its next checkpoint, with a `required_action` of type `paused` naming the pause as operator-initiated rather than a node's. Unlike cancel, the run keeps its last checkpoint and resume-orchestration-run re-drives it from there — so work already done is deferred rather than discarded.
+	* A `queued` or `sleeping` run is parked immediately (a sleeping run keeps the wake it was due, and resuming hands it back to the scheduler at that instant). A `running` run keeps running until the round in flight reaches its checkpoint, so the response may still read `running` while `pause_requested_at` is set. A run already parked on a human, webhook or approval node keeps that node's `required_action`; the pause is still recorded, which is what makes submit-human-input refuse until the run is resumed.
+	* The pause fans out to the run's `loop` / `sub_orchestration` descendants — each parks at its own next checkpoint — because otherwise a parent's pause would bound nothing. Resuming does not fan out: each parked descendant is resumed by its own id.
+	* Idempotent: pausing an already-paused run answers with it unchanged.
+	*/
+	static pauseOrchestrationRun(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/pause",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
 	* Submit human input
 	*
 	* Provides human input to a run that is awaiting_input at a human node.
@@ -3431,6 +3449,7 @@ var Orchestrations = class {
 	* Resume an orchestration run
 	*
 	* Re-drives an awaiting_input orchestration run from its last checkpoint. This does not satisfy the pause itself — it carries no node_id or payload, so a run parked on a human or webhook-receive node re-parks on the same node. Use submit-human-input to supply the awaited payload and advance the run.
+	* It is also the only thing that lifts an operator pause (pause-orchestration-run): a run parked with `required_action.type` of `paused` re-drives the frontier that had not run yet, and one paused mid-timer goes back to `sleeping` for the wake it was already due.
 	*/
 	static resumeOrchestrationRun(options) {
 		return (options.client ?? client).post({
@@ -3572,7 +3591,7 @@ var Quotas = class {
 	/**
 	* Create a quota
 	*
-	* Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.
+	* Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A `cost_usd` quota may name one `meter_type` to cap; omitting it caps every priced meter. A duplicate quota (same project, scope, scope_ref, metric, window, meter_type) is rejected with 409.
 	*/
 	static createQuota(options) {
 		return (options.client ?? client).post({
@@ -3879,7 +3898,7 @@ var Tasks = class {
 	/**
 	* List tasks
 	*
-	* Lists tasks (the board query). Filter by workflow, state, status, or assignee — `GET /tasks?workflow_id=...&state=...` is one board column.
+	* Lists tasks (the board query). Filter by workflow, state, status, automation status, or assignee — `GET /tasks?workflow_id=...&state=...` is one board column.
 	*/
 	static listTasks(options) {
 		return (options.client ?? client).get({
@@ -3955,6 +3974,36 @@ var Tasks = class {
 		});
 	}
 	/**
+	* Pause a task
+	*
+	* Pauses a task's automation. While a pause is in force no state's `on_enter` dispatches and no retry chain continues — an agent generation, a tool call and a sub-orchestration alike — so the task stops spending without losing its place.
+	* A workflow has no run object, so this is the workflow half of pause-orchestration-run: the pause lands on the instance, which is the task. Transitions are deliberately still allowed — a move costs nothing while every dispatch it would start is suppressed — so a board stays usable under a pause. Entering a state whose dispatch is suppressed records `automation_status: paused`, which resume-task reads to know that state still owes its work.
+	* A dispatch already in flight is left to finish, and its outcome still routes; only what would start after it is suppressed.
+	* Idempotent: pausing an already-paused task answers with it unchanged.
+	*/
+	static pauseTask(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/tasks/{task_id}/pause",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Resume a task
+	*
+	* Lifts a task's pause. When the pause suppressed the current state's `on_enter` — `automation_status: paused` — that dispatch is started now, as the caller resuming rather than as whoever last moved the task. A state whose dispatch had already completed, or that declares none, is left alone, so a resume never re-spends work the pause did not stop.
+	* This is the only way a pause is lifted; a task that is merely idle is advanced by firing a transition instead.
+	*/
+	static resumeTask(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/tasks/{task_id}/resume",
+			...options
+		});
+	}
+	/**
 	* Get task history
 	*
 	* Returns the append-only transition history of a task.
@@ -12934,7 +12983,7 @@ const routes = {
 	"list-orchestration-runs": {
 		serviceClass: "Orchestrations",
 		operationId: "listOrchestrationRuns",
-		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.",
+		description: "Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, by status, 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"],
@@ -12942,6 +12991,7 @@ const routes = {
 			"orchestration_id",
 			"parent_orchestration_run_id",
 			"nested",
+			"status",
 			"limit",
 			"offset"
 		],
@@ -12974,6 +13024,13 @@ const routes = {
 				"type": "boolean",
 				"in": "query"
 			},
+			{
+				"name": "status",
+				"description": "Filter by run status. Repeat the parameter to OR values — `status=queued&status=running&status=sleeping&status=awaiting_input` is the set still driving, which is how a caller finds live work without paging every run the project ever started.\n\nThere is no `non_terminal` shorthand on purpose: which statuses count as live is the caller's policy. A value outside the enum, empty string included, is a `400`.",
+				"required": false,
+				"type": "array",
+				"in": "query"
+			},
 			{
 				"name": "limit",
 				"description": "Maximum number of results to return",
@@ -13065,6 +13122,38 @@ const routes = {
 			"in": "path"
 		}]
 	},
+	"pause-orchestration-run": {
+		serviceClass: "Orchestrations",
+		operationId: "pauseOrchestrationRun",
+		description: "Parks a run in flight as `awaiting_input` at its next checkpoint, with a `required_action` of type `paused` naming the pause as operator-initiated rather than a node's. Unlike cancel, the run keeps its last checkpoint and resume-orchestration-run re-drives it from there — so work already done is deferred rather than discarded. A `queued` or `sleeping` run is parked immediately (a sleeping run keeps the wake it was due, and resuming hands it back to the scheduler at that instant). A `running` run keeps running until the round in flight reaches its checkpoint, so the response may still read `running` while `pause_requested_at` is set. A run already parked on a human, webhook or approval node keeps that node's `required_action`; the pause is still recorded, which is what makes submit-human-input refuse until the run is resumed. The pause fans out to the run's `loop` / `sub_orchestration` descendants — each parks at its own next checkpoint — because otherwise a parent's pause would bound nothing. Resuming does not fan out: each parked descendant is resumed by its own id. Idempotent: pausing an already-paused run answers with it unchanged.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/orchestrations",
+		httpMethod: "post",
+		pathParams: ["project_id", "orchestration_run_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "orchestration_run_id",
+				"description": "Public ID of the run (run_...)",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "reason",
+				"description": "Why the run is being paused, surfaced on the parked run's `required_action.reason` and on `pause_reason`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
 	"submit-human-input": {
 		serviceClass: "Orchestrations",
 		operationId: "submitHumanInput",
@@ -13107,7 +13196,7 @@ const routes = {
 	"resume-orchestration-run": {
 		serviceClass: "Orchestrations",
 		operationId: "resumeOrchestrationRun",
-		description: "Re-drives an awaiting_input orchestration run from its last checkpoint. This does not satisfy the pause itself — it carries no node_id or payload, so a run parked on a human or webhook-receive node re-parks on the same node. Use submit-human-input to supply the awaited payload and advance the run.",
+		description: "Re-drives an awaiting_input orchestration run from its last checkpoint. This does not satisfy the pause itself — it carries no node_id or payload, so a run parked on a human or webhook-receive node re-parks on the same node. Use submit-human-input to supply the awaited payload and advance the run. It is also the only thing that lifts an operator pause (pause-orchestration-run): a run parked with `required_action.type` of `paused` re-drives the frontier that had not run yet, and one paused mid-timer goes back to `sleeping` for the wake it was already due.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/orchestrations",
 		httpMethod: "post",
 		pathParams: ["project_id", "orchestration_run_id"],
@@ -13388,7 +13477,7 @@ const routes = {
 	"create-quota": {
 		serviceClass: "Quotas",
 		operationId: "createQuota",
-		description: "Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A duplicate quota (same project, scope, scope_ref, metric, window) is rejected with 409.",
+		description: "Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens` and `cost_usd` are valid for `scope: project`/`agent`/`actor`. Any other scope/metric pair is rejected with 400 (no attribution exists to enforce it). An `actor` quota caps one end user's spend, matched from the generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled project total. A `cost_usd` quota may name one `meter_type` to cap; omitting it caps every priced meter. A duplicate quota (same project, scope, scope_ref, metric, window, meter_type) is rejected with 409.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/quotas",
 		httpMethod: "post",
 		pathParams: ["project_id"],
@@ -13449,6 +13538,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "meter_type",
+				"description": "Only for metric cost_usd (400 on any other metric). The meter this cap answers for. Omit it and the cap sums every priced meter, which is the existing behaviour; name one and only that meter's cost counts, so an AI spend cap is not consumed by platform meters the operator prices (and vice versa). Part of the quota's identity, so two meter scopes can share a scope/metric/window and neither conflicts with an unscoped cap. Immutable after creation — replace the quota to change it.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -14232,7 +14328,7 @@ const routes = {
 	"list-tasks": {
 		serviceClass: "Tasks",
 		operationId: "listTasks",
-		description: "Lists tasks (the board query). Filter by workflow, state, status, or assignee — `GET /tasks?workflow_id=...&state=...` is one board column.",
+		description: "Lists tasks (the board query). Filter by workflow, state, status, automation status, or assignee — `GET /tasks?workflow_id=...&state=...` is one board column.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/tasks",
 		httpMethod: "get",
 		pathParams: ["project_id"],
@@ -14240,6 +14336,7 @@ const routes = {
 			"workflow_id",
 			"state",
 			"status",
+			"automation_status",
 			"assignee",
 			"limit",
 			"offset"
@@ -14273,6 +14370,13 @@ const routes = {
 				"type": "string",
 				"in": "query"
 			},
+			{
+				"name": "automation_status",
+				"description": "Filter by the current state's dispatch status. Repeat the parameter to OR values. `none` selects the tasks whose `automation_status` is `null` — the ones that never entered a state with an automation. It is a value a task really holds, so it is a value of the filter too; the parameter's own absence already means \"every task\".\n\nA value outside the enum, empty string included, is a `400`.",
+				"required": false,
+				"type": "array",
+				"in": "query"
+			},
 			{
 				"name": "assignee",
 				"description": "",
@@ -14499,6 +14603,60 @@ const routes = {
 			}
 		]
 	},
+	"pause-task": {
+		serviceClass: "Tasks",
+		operationId: "pauseTask",
+		description: "Pauses a task's automation. While a pause is in force no state's `on_enter` dispatches and no retry chain continues — an agent generation, a tool call and a sub-orchestration alike — so the task stops spending without losing its place. A workflow has no run object, so this is the workflow half of pause-orchestration-run: the pause lands on the instance, which is the task. Transitions are deliberately still allowed — a move costs nothing while every dispatch it would start is suppressed — so a board stays usable under a pause. Entering a state whose dispatch is suppressed records `automation_status: paused`, which resume-task reads to know that state still owes its work. A dispatch already in flight is left to finish, and its outcome still routes; only what would start after it is suppressed. Idempotent: pausing an already-paused task answers with it unchanged.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/tasks",
+		httpMethod: "post",
+		pathParams: ["project_id", "task_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "task_id",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "reason",
+				"description": "Why the task is being paused, surfaced on `pause_reason`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			}
+		]
+	},
+	"resume-task": {
+		serviceClass: "Tasks",
+		operationId: "resumeTask",
+		description: "Lifts a task's pause. When the pause suppressed the current state's `on_enter` — `automation_status: paused` — that dispatch is started now, as the caller resuming rather than as whoever last moved the task. A state whose dispatch had already completed, or that declares none, is left alone, so a resume never re-spends work the pause did not stop. This is the only way a pause is lifted; a task that is merely idle is advanced by firing a transition instead.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/tasks",
+		httpMethod: "post",
+		pathParams: ["project_id", "task_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "task_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
 	"get-task-history": {
 		serviceClass: "Tasks",
 		operationId: "getTaskHistory",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.115.1",
+  "version": "0.117.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.115.1"
+    "@naturali/sdk": "0.117.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",