@soat/cli 0.33.0 → 0.34.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import * as os from "node:os";
 import { createHmac, timingSafeEqual } from "node:crypto";
 
 //#region package.json
-var version = "0.33.0";
+var version = "0.34.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -299,22 +299,19 @@ var extractPositionalArgs = args => {
 /**
 * Coerce a raw flag value to the JSON type the spec declares for it.
 *
-* `declaredType` comes from the generated route manifest. A flag the spec
-* declares as `string` is passed through untouched — its content is data, not
-* syntax, so a value that merely *looks* like JSON (a GCP service account key
-* file in `create-secret --value`) or like a number (an account number) must
-* still arrive as a string. Coercing it produced a body the server rejects,
-* with no way to escape it from the shell.
+* A flag the spec declares as `string` is passed through untouched — its
+* content is data, not syntax, so a value that merely *looks* like JSON (a GCP
+* service account key in `create-secret --value`) or like a number must still
+* arrive as a string. Coercing it produced a body the server rejects, with no
+* way to escape it from the shell.
 *
-* The one value a string flag still coerces is the literal `null`: "set it to
-* null to clear" is the documented way to detach a nullable reference
-* (`--default_model_route_id null`, `--ai_provider_id null`), and the shell has
-* no other way to spell JSON null. The cost is that a string whose entire value
-* is `null` cannot be sent — a far rarer need than clearing a field.
+* The one exception is the literal `null`: "set it to null to clear" is the
+* documented way to detach a nullable reference and the shell has no other way
+* to spell JSON null. The cost is that a string whose entire value is `null`
+* cannot be sent.
 *
-* Every other flag keeps the permissive behavior: an undeclared type (a flag
-* the manifest has no entry for) is still sniffed, since that is the only
-* signal available.
+* Every other flag keeps the permissive behavior — an undeclared type is still
+* sniffed, since that is the only signal available.
 */
 var parseFlagValue = (value, declaredType) => {
   if (declaredType === "string") return value.trim() === "null" ? null : value;
@@ -793,13 +790,13 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_choice",
-      "description": "Tool choice strategy. Accepts a string (`\"auto\"`, `\"required\"`) or an object (`{ \"type\": \"tool\", \"tool_name\": \"my_tool\" }`).",
+      "description": "Tool choice strategy. Accepts a string (`\"auto\"`, `\"required\"`) or an object (`{ \"type\": \"tool\", \"tool_name\": \"my_tool\" }`). A forcing value (`\"required\"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.",
       "required": false,
       "type": "any",
       "in": "body"
     }, {
       "name": "stop_conditions",
-      "description": "",
+      "description": "Conditions that end the agent's work early, on top of `max_steps`. Two scopes:\n\n`{\"type\": \"hasToolCall\", \"tool_name\": \"<resolved tool name>\"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.\n\n`{\"type\": \"maxChainGenerations\", \"max_generations\": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.\n\nAn unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -863,6 +860,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "on_approval_expiry",
+      "description": "What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "version_label",
       "description": "Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change.",
@@ -945,13 +948,13 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_choice",
-      "description": "Tool choice strategy. Accepts a string (`\"auto\"`, `\"required\"`) or an object (`{ \"type\": \"tool\", \"tool_name\": \"my_tool\" }`).",
+      "description": "Tool choice strategy. Accepts a string (`\"auto\"`, `\"required\"`) or an object (`{ \"type\": \"tool\", \"tool_name\": \"my_tool\" }`). A forcing value (`\"required\"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.",
       "required": false,
       "type": "any",
       "in": "body"
     }, {
       "name": "stop_conditions",
-      "description": "",
+      "description": "Conditions that end the agent's work early, on top of `max_steps`. Two scopes:\n\n`{\"type\": \"hasToolCall\", \"tool_name\": \"<resolved tool name>\"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.\n\n`{\"type\": \"maxChainGenerations\", \"max_generations\": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.\n\nAn unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -1015,6 +1018,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "on_approval_expiry",
+      "description": "What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "version_label",
       "description": "Optional tag for the config version this write archives (e.g. `pre-tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.",
@@ -1081,13 +1090,13 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_choice",
-      "description": "Tool choice strategy. Accepts a string (`\"auto\"`, `\"required\"`) or an object (`{ \"type\": \"tool\", \"tool_name\": \"my_tool\" }`).",
+      "description": "Tool choice strategy. Accepts a string (`\"auto\"`, `\"required\"`) or an object (`{ \"type\": \"tool\", \"tool_name\": \"my_tool\" }`). A forcing value (`\"required\"` or the object form) forbids a final assistant message on every step of every turn, including a resumed or continued one, so it requires a `hasToolCall` entry in `stop_conditions` — otherwise the write is refused with `FORCED_TOOL_CHOICE_CANNOT_STOP`.",
       "required": false,
       "type": "any",
       "in": "body"
     }, {
       "name": "stop_conditions",
-      "description": "",
+      "description": "Conditions that end the agent's work early, on top of `max_steps`. Two scopes:\n\n`{\"type\": \"hasToolCall\", \"tool_name\": \"<resolved tool name>\"}` ends the **turn** after the step that calls the named tool. It narrows when the loop ends — it never lets it run past `max_steps`.\n\n`{\"type\": \"maxChainGenerations\", \"max_generations\": <n>}` bounds the **continuation chain** instead: once the chain has spawned that many generations, further resumptions stop with `chain_limit` rather than extending it. It never shortens a turn. The effective ceiling is the smaller of this and the deployment's `MAX_CONTINUATION_CHAIN_GENERATIONS`, so an agent can be stricter than the platform but never looser.\n\nAn unknown `type`, a `hasToolCall` without a `tool_name`, a `maxChainGenerations` whose `max_generations` is not a positive integer, or a non-object entry is rejected with 400.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -1151,6 +1160,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "on_approval_expiry",
+      "description": "What happens when one of this agent's held tool calls expires un-approved. `null` (the default) and `terminate` end the chain there — the expired approval, its `approvals.expired` event and the auto-filed `approval_expired` exception are the whole record. `react` spawns a continuation that reports the staleness to the agent, for an agent that acts on it.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "version_label",
       "description": "Optional tag for the config version this write archives (e.g. `pre-tone-change`). Annotates the version only — it is not stored on the agent and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes nothing, since no version is created.",
@@ -1973,7 +1988,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "resource_srn",
-      "description": "SRN prefix match, e.g. `srn:{project}:secret:`. Entries written before the `soat:` → `srn:` rename keep their original SRN (the log is append-only), so an `srn:` prefix also matches the equivalent `soat:` one and history stays reachable.",
+      "description": "SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN is never rewritten; the filter matches it as stored.",
       "required": false,
       "type": "string",
       "in": "query"
@@ -2037,7 +2052,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "resource_srn",
-      "description": "SRN prefix match, e.g. `srn:{project}:secret:`. Entries written before the `soat:` → `srn:` rename keep their original SRN (the log is append-only), so an `srn:` prefix also matches the equivalent `soat:` one and history stays reachable.",
+      "description": "SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN is never rewritten; the filter matches it as stored.",
       "required": false,
       "type": "string",
       "in": "query"
@@ -2071,6 +2086,62 @@ var routes = {
       "in": "path"
     }]
   },
+  "list-chains": {
+    serviceClass: "Chains",
+    operationId: "listChains",
+    description: "Returns the continuation chains in a project, newest first. Filter by `status` to find the chains that may still be spending (`active`) or the ones a budget stopped (`budget_exhausted`).",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chains",
+    httpMethod: "get",
+    pathParams: [],
+    queryParams: ["project_id", "status", "agent_id", "limit", "offset"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "status",
+      "description": "Filter by chain status",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "agent_id",
+      "description": "Filter by the agent whose continuation opened the chain",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "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"
+    }]
+  },
+  "get-chain": {
+    serviceClass: "Chains",
+    operationId: "getChain",
+    description: "Returns a single continuation chain. To read the generations in it, list generations filtered by `chain_id`.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chains",
+    httpMethod: "get",
+    pathParams: ["chain_id"],
+    queryParams: [],
+    flags: [{
+      "name": "chain_id",
+      "description": "Continuation chain ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-chats": {
     serviceClass: "Chats",
     operationId: "listChats",
@@ -3427,6 +3498,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "tool_context",
+      "description": "Key/value context forwarded to every item's generation, so an agent whose tools authorize through `tool_context` is scored against the configuration it runs in production rather than with an empty bag. Each key is forwarded as one `X-Soat-Context-<key>` header and resolves any `{{context:<key>}}` token in a bound tool's headers or `preset_parameters`.\n\nStored on the run and re-read per item, since a queued run (the default) is driven by a worker with no request behind it. **Write-only**: no read of the run returns it, unlike `metadata` — a run is a report other people read, and a credential in it is not theirs to see. Cleared once the run reaches a terminal state.\n\nAn eval generation has no session, so the reserved keys `sessionId`, `actorId` and `actorExternalId` are dropped (in any casing) rather than forwarded. Every other key becomes an HTTP header name and must match that grammar, or the request is rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created.",
+      "required": false,
+      "type": "object",
+      "in": "body"
     }]
   },
   "get-eval-run": {
@@ -4182,7 +4259,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["agent_id", "trace_id", "initiator_generation_id", "orchestration_run_id", "node_id", "status", "limit", "offset"],
+    queryParams: ["agent_id", "trace_id", "initiator_generation_id", "chain_id", "orchestration_run_id", "node_id", "status", "limit", "offset"],
     flags: [{
       "name": "agent_id",
       "description": "Filter by agent public ID",
@@ -4201,6 +4278,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "chain_id",
+      "description": "Filter by the continuation chain the generation belongs to. This is how a chain is expanded into its members — the chain record carries only their count.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "orchestration_run_id",
       "description": "Filter by the orchestration run that dispatched the generation. This is how a run is traced back to what its agent nodes did — a node execution record stores no generation id.\n",
@@ -5920,7 +6003,7 @@ var routes = {
   "update-project": {
     serviceClass: "Projects",
     operationId: "updateProject",
-    description: "Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.",
+    description: "Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/projects",
     httpMethod: "patch",
     pathParams: ["project_id"],
@@ -5949,6 +6032,12 @@ var routes = {
       "required": false,
       "type": "integer",
       "in": "body"
+    }, {
+      "name": "max_chain_generations",
+      "description": "Generations one continuation chain in this project may hold before the platform stops resuming it. `null` clears the project's ceiling, leaving the deployment-wide `MAX_CONTINUATION_CHAIN_GENERATIONS`; otherwise an integer >= 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `maxChainGenerations` stop condition, so an agent author can be stricter than this number but never exceed it.",
+      "required": false,
+      "type": "integer",
+      "in": "body"
     }, {
       "name": "default_model_route_id",
       "description": "Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. The route must belong to this project (`400` otherwise). `null` clears the default, which is refused with `409` while any consumer inherits it — repointing it to another route is always allowed and immediately changes which targets those consumers use.",
@@ -6113,6 +6202,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "on_unpriced",
+      "description": "Only for metric cost_usd (400 on any other metric). What an enforce quota does when the current window is a pricing blackout — several metered events, none of them priced, so the aggregate is 0 however much was actually spent. block (the default) refuses new generations with 409 QUOTA_UNENFORCEABLE until pricing is configured; allow accepts the unmeasurable spend explicitly. Either way a quota_unpriced exception is filed. monitor-mode quotas never block regardless.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "get-quota": {
@@ -6157,6 +6252,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "on_unpriced",
+      "description": "New pricing posture. Only for metric cost_usd (400 on any other metric); see the create operation for what block and allow mean.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "delete-quota": {
@@ -7191,6 +7292,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "tool_context",
+      "description": "Key/value context for this call, forwarded to the tool as `X-Soat-Context-<key>` request headers and resolving any `{{context:<key>}}` token in the tool's `execute.headers`, `mcp.headers` or `preset_parameters`. Narrowed by the tool's `context_keys` allowlist when it sets one.\nThis route has no session, so it stamps no server-derived identity: the reserved keys `sessionId`, `actorId` and `actorExternalId` are dropped from this bag (in any casing) rather than forwarded, so a downstream tool can still trust that a context header naming one is server-derived. Every other key becomes an HTTP header name and must match that grammar, or the call fails with `INVALID_TOOL_CONTEXT_KEY`.\n",
+      "required": false,
+      "type": "object",
+      "in": "body"
     }]
   },
   "list-traces": {
@@ -8556,23 +8663,19 @@ var suggestionFor = args => {
   return near ? ` Did you mean --${toKebab(near)}?` : "";
 };
 /**
-* Reject an unrecognized flag **only where the server cannot catch it** — a flag
-* the CLI would otherwise append to the query string.
+* Reject an unrecognized flag **only where the server cannot catch it** — a
+* flag the CLI would otherwise append to the query string.
 *
 * An undeclared query param never reaches a check: the server ignores what it
-* does not know, so `list-agents --limitt 1` returned every row instead of one.
-* The filter failed **open**, with exit 0 and no warning, and the caller acted on
-* a superset it never asked for. The name does not survive the request, so only
+* does not know, so `list-agents --limitt 1` returned every row instead of one,
+* with exit 0 and no warning. The name does not survive the request, so only
 * the client can catch it.
 *
-* An unrecognized flag on a **write** is deliberately still forwarded. The server
-* already answers `400 VALIDATION_FAILED` naming the field (`strictFields`), and
-* that check is the authority on what a body may contain — rejecting locally
-* would front-run it, hide the real error, and make an older CLI refuse a field a
-* newer server accepts. It would also make the behavior untestable through the
-* CLI: `tests/smoke-tests.sh` asserts precisely that the server rejects
-* `update-agent --reasoning` with a 400, which a client-side refusal turns into a
-* usage error the assertion cannot read.
+* An unrecognized flag on a **write** is deliberately still forwarded. The
+* server already answers `400 VALIDATION_FAILED` naming the field, and that
+* check is the authority on what a body may contain — rejecting locally would
+* hide the real error and make an older CLI refuse a field a newer server
+* accepts. `tests/smoke-tests.sh` asserts precisely that server-side 400.
 *
 * Returns the error lines to print; empty when every flag is recognized.
 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "CLI for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",
@@ -22,7 +22,7 @@
   "dependencies": {
     "@inquirer/input": "^5.1.2",
     "@inquirer/password": "^5.1.1",
-    "@soat/sdk": "0.33.0",
+    "@soat/sdk": "0.34.0",
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1"