@soat/cli 0.26.0 → 0.28.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.26.0";
+var version = "0.28.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -1197,7 +1197,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "wait",
-      "description": "When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately with a `generation_id` to poll. Pass `true` to block until the generation settles and receive the result. Mutually exclusive with `stream: true`. A `soat` tool call always waits.",
+      "description": "When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately with a `generation_id` to poll. Pass `true` to block until the generation settles and receive the result. Mutually exclusive with `stream: true`. A `builtin` tool call always waits.",
       "required": false,
       "type": "boolean",
       "in": "query"
@@ -1239,7 +1239,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -1942,7 +1942,7 @@ var routes = {
   "list-audit-entries": {
     serviceClass: "AuditLog",
     operationId: "listAuditEntries",
-    description: "Returns audit-log entries visible to the caller, newest first. All filters are optional and combine with AND. `resource_srn` is a prefix match (e.g. `soat:{project}:secret:` matches every secret action); every other filter is exact.",
+    description: "Returns audit-log entries visible to the caller, newest first. All filters are optional and combine with AND. `resource_srn` is a prefix match (e.g. `srn:{project}:secret:` matches every secret action); every other filter is exact.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/audit-log",
     httpMethod: "get",
     pathParams: [],
@@ -1973,7 +1973,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "resource_srn",
-      "description": "SRN prefix match, e.g. `soat:{project}:secret:`",
+      "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.",
       "required": false,
       "type": "string",
       "in": "query"
@@ -2037,7 +2037,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "resource_srn",
-      "description": "SRN prefix match, e.g. `soat:{project}:secret:`",
+      "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.",
       "required": false,
       "type": "string",
       "in": "query"
@@ -2435,7 +2435,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "wait",
-      "description": "When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result. A `soat` tool call always waits.",
+      "description": "When omitted or `false` (default), the generation runs in the background and `202 Accepted` is returned immediately. Pass `true` to block until the generation settles and receive the result. A `builtin` tool call always waits.",
       "required": false,
       "type": "boolean",
       "in": "query"
@@ -2459,7 +2459,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased and keys are never case-converted, so they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased and keys are never case-converted, so they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -4038,7 +4038,7 @@ var routes = {
   "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 `soat` CLI exits non-zero on that body so `create-formation && …` does not lie.",
+    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://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "post",
     pathParams: [],
@@ -4094,7 +4094,7 @@ var routes = {
   "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 `soat` CLI exits non-zero on that body so `update-formation && …` does not lie.",
+    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://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "put",
     pathParams: ["formation_id"],
@@ -4316,7 +4316,7 @@ var routes = {
   "create-guardrail": {
     serviceClass: "Guardrails",
     operationId: "createGuardrail",
-    description: "Creates a new guardrail in the project, archiving its document as version 1. The `document` is validated on write: `class` must be a literal (A/B/C/D) or a JSON Logic expression, and every variable it (and `guard`) reference must resolve to the `args.*` / `context.*` / `soat.*` namespaces — an out-of-catalog `soat.*` key is rejected with 400.",
+    description: "Creates a new guardrail in the project, archiving its document as version 1. The `document` is validated on write: `class` must be a literal (A/B/C/D) or a JSON Logic expression, and every variable it (and `guard`) reference must resolve to the `args.*` / `context.*` / `runtime.*` namespaces — an out-of-catalog `runtime.*` key is rejected with 400.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
     httpMethod: "post",
     pathParams: [],
@@ -4341,7 +4341,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "document",
-      "description": "The action-class document. `class` maps a call to an action class; `guard` gates class-B autonomy. Both are single JSON Logic expressions over the `args.*` / `context.*` / `soat.*` namespaces.\n",
+      "description": "The action-class document. `class` maps a call to an action class; `guard` gates class-B autonomy. Both are single JSON Logic expressions over the `args.*` / `context.*` / `runtime.*` namespaces.\n",
       "required": true,
       "type": "object",
       "in": "body"
@@ -4409,7 +4409,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "document",
-      "description": "The action-class document. `class` maps a call to an action class; `guard` gates class-B autonomy. Both are single JSON Logic expressions over the `args.*` / `context.*` / `soat.*` namespaces.\n",
+      "description": "The action-class document. `class` maps a call to an action class; `guard` gates class-B autonomy. Both are single JSON Logic expressions over the `args.*` / `context.*` / `runtime.*` namespaces.\n",
       "required": false,
       "type": "object",
       "in": "body"
@@ -4530,7 +4530,7 @@ var routes = {
   "evaluate-guardrail": {
     serviceClass: "Guardrails",
     operationId: "evaluateGuardrail",
-    description: "Runs the full evaluation pipeline — the `class` expression, the guard, the context tool per `context_mode`, live `soat.*` resolution — against caller-supplied `args` and `guardrail_context`, and returns the exact `guardrail_evaluation` record a real call would produce. Nothing executes, no approval item is filed, and no activity entry is written. This is the adoption path: preview a document's decisions against production-shaped calls before attaching it — or before editing a widely-attached one. Pass an optional `tool_id` to resolve `soat.tool.*`.",
+    description: "Runs the full evaluation pipeline — the `class` expression, the guard, the context tool per `context_mode`, live `runtime.*` resolution — against caller-supplied `args` and `guardrail_context`, and returns the exact `guardrail_evaluation` record a real call would produce. Nothing executes, no approval item is filed, and no activity entry is written. This is the adoption path: preview a document's decisions against production-shaped calls before attaching it — or before editing a widely-attached one. Pass an optional `tool_id` to resolve `runtime.tool.*`.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/guardrails",
     httpMethod: "post",
     pathParams: ["guardrail_id"],
@@ -4555,7 +4555,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_id",
-      "description": "Optional tool to resolve `soat.tool.*` against.",
+      "description": "Optional tool to resolve `runtime.tool.*` against.",
       "required": false,
       "type": "string",
       "in": "body"
@@ -4623,7 +4623,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "action",
-      "description": "Operation id, required for soat/mcp tool converters",
+      "description": "Operation id, required for builtin/mcp tool converters",
       "required": false,
       "type": "string",
       "in": "body"
@@ -5617,7 +5617,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` 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-Soat-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. 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 (`sessionId`, `actorId`, `actorExternalId`) are stripped at generation time — a caller cannot address them from here.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` 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-Soat-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. 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 (`sessionId`, `actorId`, `actorExternalId`) are stripped at generation time — a caller cannot address them from here.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6329,7 +6329,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. 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`.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. 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`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6397,7 +6397,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. 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`.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this session. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. 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`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6453,7 +6453,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6499,7 +6499,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call in this generation. The header name is the deployment's configured context prefix (`X-Soat-Context-` by default) plus the key verbatim — no character is re-cased. Keys are never case-converted — they round-trip exactly as sent. An invalid or colliding key is rejected with `400 INVALID_TOOL_CONTEXT_KEY`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6753,7 +6753,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_context",
-      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `soat` tool call made by this task's automation dispatches — the agent generations a state's `on_enter` starts, and the agent nodes of any orchestration run it starts. The header name is `X-Soat-Context-` plus the key verbatim; no character is re-cased.\nCreation is the task's first move, so this is the bag the entry state's `on_enter` runs with. Each transition may replace it (see `TransitionTaskRequest.tool_context`).\nThe reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).\nWrite-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state.",
+      "description": "Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call made by this task's automation dispatches — the agent generations a state's `on_enter` starts, and the agent nodes of any orchestration run it starts. The header name is `X-Soat-Context-` plus the key verbatim; no character is re-cased.\nCreation is the task's first move, so this is the bag the entry state's `on_enter` runs with. Each transition may replace it (see `TransitionTaskRequest.tool_context`).\nThe reserved identity keys (`sessionId`, `actorId`, `actorExternalId`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400).\nWrite-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6955,7 +6955,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "actions",
-      "description": "Allowlist of actions. For `soat` tools: SOAT platform action names (required). For `mcp` tools: an optional allowlist of MCP tool names to scope the server surface — omit or set `null` to expose every tool the MCP server offers. Ignored for other tool types.",
+      "description": "Allowlist of actions. For `builtin` tools: SOAT platform action names (required). For `mcp` tools: an optional allowlist of MCP tool names to scope the server surface — omit or set `null` to expose every tool the MCP server offers. Ignored for other tool types.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -6973,7 +6973,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "preset_parameters",
-      "description": "Fixed parameters merged into every soat 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 merged into every builtin 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.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -7065,7 +7065,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "actions",
-      "description": "Allowlist of actions. For `soat` tools: SOAT platform action names. For `mcp` tools: an optional allowlist of MCP tool names to scope the server surface (`null` exposes every tool). Ignored for other tool types.",
+      "description": "Allowlist of actions. For `builtin` tools: SOAT platform action names. For `mcp` tools: an optional allowlist of MCP tool names to scope the server surface (`null` exposes every tool). Ignored for other tool types.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -7083,7 +7083,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "preset_parameters",
-      "description": "Fixed parameters merged into every soat 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 merged into every builtin 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.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -7126,7 +7126,7 @@ var routes = {
   "call-tool": {
     serviceClass: "Tools",
     operationId: "callTool",
-    description: "Directly invokes a tool and returns its output. Supported for `http`, `soat`, `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 `soat` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `soat` or `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`, `builtin`, `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 `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `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.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/tools",
     httpMethod: "post",
     pathParams: ["tool_id"],
@@ -7139,7 +7139,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "action",
-      "description": "For `soat` tools: the action name (must be in the tool's `actions` list). For `mcp` tools: the MCP tool name to invoke (must be in the tool's `actions` allowlist when one is set, and must not be in its `denied_actions` denylist). Ignored for `http` tools.\n",
+      "description": "For `builtin` tools: the action name (must be in the tool's `actions` list). For `mcp` tools: the MCP tool name to invoke (must be in the tool's `actions` allowlist when one is set, and must not be in its `denied_actions` denylist). Ignored for `http` tools.\n",
       "required": false,
       "type": "string",
       "in": "body"
@@ -7319,7 +7319,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "action",
-      "description": "Tool targets only — the action for soat/mcp tools",
+      "description": "Tool targets only — the action for builtin/mcp tools",
       "required": false,
       "type": "string",
       "in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "license": "Apache-2.0",
   "type": "module",
   "dependencies": {
@@ -9,7 +9,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.26.0"
+    "@soat/sdk": "0.28.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",