@soat/cli 0.22.1 → 0.24.0

package/dist/index.mjs

@@ -1,5 +1,4 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-import { createHmac, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,13 +10,20 @@ import { program } from "commander";
 import * as fs from "node:fs";
 import { load } from "js-yaml";
 import * as os from "node:os";
+import { createHmac, timingSafeEqual } from "node:crypto";
 
 //#region package.json
-var version = "0.22.1";
+var version = "0.24.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
 var FORMATION_COMMANDS = ["validate-formation", "plan-formation", "create-formation", "update-formation"];
+/**
+* The two commands that *deploy*. `validate-formation` and `plan-formation`
+* report on a template without touching a resource, so their outcome is the
+* payload, not an exit code.
+*/
+var DEPLOY_COMMANDS = ["create-formation", "update-formation"];
 var TEMPLATE_PATH_FLAG = "template-path";
 var TEMPLATE_FILE_FLAG = "template-file";
 var ENV_FILE_FLAG = "env-file";
@@ -121,9 +127,45 @@ var resolveParameterPair = args => {
     })
   };
 };
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var readString = value => {
+  return typeof value === "string" && value ? value : void 0;
+};
+/** The reason line, from the response's `error` bag when it carries one. */
+var describeDeployReason = args => {
+  const reason = readString(args.error?.message);
+  if (!reason) return `No reason was reported on the response; run \`soat list-formation-events --formation-id ${args.formationId ?? "<id>"}\` for the operation history.`;
+  return `${readString(args.error?.code) ?? "UNKNOWN"}: ${reason}`;
+};
+/**
+* A deploy whose reconciliation failed, rendered for stderr.
+*
+* The server answers 2xx here on purpose — the operation ran, and partial
+* failure is modelled on the resource — so the body's `status` is the only
+* signal that anything went wrong. Turning it into a non-zero exit is what
+* stops `&&` chains from reporting a deploy that deployed nothing (#1028).
+*/
+var describeFailedDeploy = args => {
+  const {
+    commandName,
+    data
+  } = args;
+  if (!DEPLOY_COMMANDS.includes(commandName)) return null;
+  if (!isRecord(data) || data.status !== "failed") return null;
+  const error = isRecord(data.error) ? data.error : void 0;
+  const meta = isRecord(error?.meta) ? error.meta : void 0;
+  const logicalId = readString(meta?.logical_id);
+  return `${commandName}: the deploy failed${logicalId ? ` at resource '${logicalId}'` : ""} — the formation is 'failed'. ${describeDeployReason({
+    error,
+    formationId: readString(data.id)
+  })}`;
+};
 var formationsWrapper = {
   id: "formations-wrapper",
   commands: FORMATION_COMMANDS,
+  failureMessage: describeFailedDeploy,
   helpFlags: [{
     name: "template-path",
     description: "Path to template file (JSON or YAML). Alias: --template-file",
@@ -332,6 +374,18 @@ var applyWrapperForCommand = args => {
     }
   });
 };
+/**
+* What to report for a 2xx payload whose own body says the operation failed,
+* or null when there is nothing wrong with it. Drives the CLI's exit code.
+*/
+var resolveFailureMessage = args => {
+  return resolveWrapperForCommand({
+    commandName: args.commandName
+  })?.failureMessage?.({
+    commandName: args.commandName,
+    data: args.data
+  }) ?? null;
+};
 var getWrapperHelpFlags = commandName => {
   return WRAPPERS.find(w => {
     return w.commands.includes(commandName);
@@ -745,19 +799,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_bindings",
-      "description": "Tools to attach, one binding object per tool — the canonical attachment field. Cannot be combined with the deprecated `tool_ids`/`tools` shorthands (400). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tool_ids",
-      "description": "Deprecated shorthand — each entry becomes a bare `{ \"tool_id\": … }` binding. Use `tool_bindings` instead.",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tools",
-      "description": "Deprecated shorthand — each entry becomes a bare `{ \"tool\": … }` binding (an ephemeral definition: no separate Tool resource is created, any `project_id` on an entry is ignored, entries never appear in `GET /tools`, cannot be targeted by `active_tool_ids`/`step_rules`, and cannot be of type `pipeline`). Use `tool_bindings` instead.",
+      "description": "Tools to attach, one binding object per tool — the only attachment field. An entry is either a reference (`{ \"tool_id\": … }`) or an inline definition (`{ \"tool\": … }`). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
       "required": false,
       "type": "array",
       "in": "body"
@@ -909,19 +951,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_bindings",
-      "description": "Tools attached to the agent — the canonical attachment field. Replaces the whole binding list; set to `null` to clear. Cannot be combined with the deprecated `tool_ids`/`tools` shorthands (400). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tool_ids",
-      "description": "Deprecated shorthand — replaces only the reference (`tool_id`) bindings, rewriting them bare. Use `tool_bindings` instead.",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tools",
-      "description": "Deprecated shorthand — replaces only the inline (`tool`) bindings (ephemeral definitions: no separate Tool resource is created, any `project_id` on an entry is ignored, entries never appear in `GET /tools`, cannot be targeted by `active_tool_ids`/`step_rules`, and cannot be of type `pipeline`). Set to `null` to clear the inline bindings. Use `tool_bindings` instead.",
+      "description": "Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to `null` to clear. See [Tool Bindings](/docs/modules/agents#tool-bindings).",
       "required": false,
       "type": "array",
       "in": "body"
@@ -1057,19 +1087,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tool_bindings",
-      "description": "Tools attached to the agent — the canonical attachment field. Replaces the whole binding list; set to `null` to clear. Cannot be combined with the deprecated `tool_ids`/`tools` shorthands (400). See [Tool Bindings](/docs/modules/agents#tool-bindings).",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tool_ids",
-      "description": "Deprecated shorthand — replaces only the reference (`tool_id`) bindings, rewriting them bare. Use `tool_bindings` instead.",
-      "required": false,
-      "type": "array",
-      "in": "body"
-    }, {
-      "name": "tools",
-      "description": "Deprecated shorthand — replaces only the inline (`tool`) bindings (ephemeral definitions: no separate Tool resource is created, any `project_id` on an entry is ignored, entries never appear in `GET /tools`, cannot be targeted by `active_tool_ids`/`step_rules`, and cannot be of type `pipeline`). Set to `null` to clear the inline bindings. Use `tool_bindings` instead.",
+      "description": "Tools attached to the agent — the only attachment field. Replaces the whole binding list; set to `null` to clear. See [Tool Bindings](/docs/modules/agents#tool-bindings).",
       "required": false,
       "type": "array",
       "in": "body"
@@ -1215,7 +1233,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "trace_id",
-      "description": "Optional trace ID to group generations",
+      "description": "Optional trace ID to group generations. Each generation appends its own steps to the trace's steps object, and `step_count` covers them all.",
       "required": false,
       "type": "string",
       "in": "body"
@@ -1626,7 +1644,7 @@ var routes = {
   "list-ai-provider-models": {
     serviceClass: "AIProviders",
     operationId: "listAiProviderModels",
-    description: "Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry. Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time. Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`.",
+    description: "Asks the provider which models it can run, using this provider record's own credentials and configuration, and returns provider-native model ids — the same strings `default_model` and an agent's `model` carry. Which models are reachable is a property of the credential, not of the provider type: a Vertex provider sees only the publisher models its Google Cloud project and location serve, and a Bedrock provider only the foundation models enabled in its region. Reading the list is how a caller avoids pinning a model that fails at generation time. Not every provider type can answer. `azure` lists deployments an operator named rather than models, and `ollama` lists whatever was pulled onto that host, so both return `400 MODEL_LISTING_UNSUPPORTED`. Listing resolves credentials the same way generation does, so a record that can generate can list. The API-key types (`openai`, `groq`, `xai`, `gateway`, `custom`, `anthropic`, `google`) use the record's linked secret and cannot list without one. `bedrock` and `vertex` use the linked secret when there is one — IAM keys or a Bedrock API key, a Google service-account key — and otherwise fall back to the server environment (the AWS default credential chain, Google Application Default Credentials), so a record with no `secret_id` can still list. A Vertex record needs no `config.project` when its secret is a service-account key, since the key file names its own project. A Vertex record in express mode (API key) cannot list at all: express mode is a global, project-less endpoint and the publisher-model catalogue is per-project, so it returns `400 MODEL_LISTING_UNSUPPORTED`.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/ai-providers",
     httpMethod: "get",
     pathParams: ["ai_provider_id"],
@@ -1680,7 +1698,7 @@ var routes = {
   "list-api-keys": {
     serviceClass: "APIKeys",
     operationId: "listApiKeys",
-    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - API key: returns only API keys scoped to the key's project.",
+    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "get",
     pathParams: [],
@@ -1702,7 +1720,7 @@ var routes = {
   "create-api-key": {
     serviceClass: "APIKeys",
     operationId: "createApiKey",
-    description: "Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped).",
+    description: "Creates a new API key for the authenticated user. - `project_id` is optional. When set, the key is scoped to that single project. When omitted or null, the key is **unscoped** and spans every project its owner can reach. - If `policy_ids` is provided, the key's effective permissions are the intersection of the user's policies and the key's policies. - Otherwise the key inherits the user's permissions (confined to the key's project when scoped). - When the request is authenticated with a **project-scoped credential**, the new key is confined to that same project: omitting `project_id` defaults to it, naming a different project returns `403 API_KEY_PROJECT_SCOPE`, and `project_id: null` (an unscoped key) is likewise refused. Minting an unscoped key requires an unscoped credential.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "post",
     pathParams: [],
@@ -1730,7 +1748,7 @@ var routes = {
   "get-api-key": {
     serviceClass: "APIKeys",
     operationId: "getApiKey",
-    description: "Returns details of an API key. Only the owner or an admin can access it.",
+    description: "Returns details of an API key. Only the owner or an admin can access it, and a project-scoped credential can only reach keys in its own project.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "get",
     pathParams: ["api_key_id"],
@@ -1746,7 +1764,7 @@ var routes = {
   "update-api-key": {
     serviceClass: "APIKeys",
     operationId: "updateApiKey",
-    description: "Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it.",
+    description: "Updates an API key's name, project scope, or policies. The project scope can be changed to another project, set (scoping a previously unscoped key), or cleared with null (unscoping the key). Only the owner or an admin can update it. A project-scoped credential can only update keys in its own project, and cannot move a key to another project or unscope it.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "put",
     pathParams: ["api_key_id"],
@@ -1780,7 +1798,7 @@ var routes = {
   "delete-api-key": {
     serviceClass: "APIKeys",
     operationId: "deleteApiKey",
-    description: "Deletes an API key. Only the owner or an admin can delete it.",
+    description: "Deletes an API key. Only the owner or an admin can delete it, and a project-scoped credential can only delete keys in its own project.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "delete",
     pathParams: ["api_key_id"],
@@ -2126,7 +2144,7 @@ var routes = {
       "type": "string",
       "in": "body"
     }, {
-      "name": "system_message",
+      "name": "instructions",
       "description": "Optional system message applied to all completions on this chat",
       "required": false,
       "type": "string",
@@ -2171,57 +2189,35 @@ var routes = {
       "in": "path"
     }]
   },
-  "create-chat-completion-for-chat": {
+  "create-chat-completion": {
     serviceClass: "Chats",
-    operationId: "createChatCompletionForChat",
-    description: "Runs a completion using the AI provider and settings stored in the chat. Pass `stream: true` for SSE streaming. A system message in `messages` overrides the chat's stored system message for this call only. Messages may use `documentId` instead of `content`.",
+    operationId: "createChatCompletion",
+    description: "OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone. Names exactly one target. With `ai_provider_id` the completion is stateless: the provider's secret is decrypted and the appropriate Vercel AI SDK provider is called, with no server-side model fallback. With `chat_id` the stored chat supplies the provider (or the project's `default_model_route_id`), model and instructions. System content travels only in `instructions` — a `role: \"system\"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, a request `instructions` replaces the chat's stored one for this call only; the stored value applies when the request carries none, and the two are never merged. Messages may use `document_id` instead of `content` with either target. Chats hold no message history — send the full `messages` array every time.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
     httpMethod: "post",
-    pathParams: ["chat_id"],
+    pathParams: [],
     queryParams: [],
     flags: [{
-      "name": "chat_id",
-      "description": "",
-      "required": true,
+      "name": "ai_provider_id",
+      "description": "Public ID of the AI provider to run the completion against. Mutually exclusive with `chat_id`; exactly one of the two is required.\n",
+      "required": false,
       "type": "string",
-      "in": "path"
-    }, {
-      "name": "messages",
-      "description": "",
-      "required": true,
-      "type": "array",
       "in": "body"
     }, {
-      "name": "model",
-      "description": "Override the chat's default model for this call",
+      "name": "chat_id",
+      "description": "Public ID of a stored chat supplying the provider, model and instructions. Mutually exclusive with `ai_provider_id`; exactly one of the two is required.\n",
       "required": false,
       "type": "string",
       "in": "body"
     }, {
-      "name": "stream",
-      "description": "When `true` the response is an SSE stream.",
+      "name": "model",
+      "description": "Model identifier. Overrides the provider's `default_model`, or the chat's `model`, when specified.\n",
       "required": false,
-      "type": "boolean",
-      "in": "body"
-    }]
-  },
-  "create-chat-completion": {
-    serviceClass: "Chats",
-    operationId: "createChatCompletion",
-    description: "OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's `POST /v1/chat/completions` path so an OpenAI SDK can target it by base URL alone. Resolves the AI provider from `ai_provider_id`, decrypts its secret, and calls the appropriate Vercel AI SDK provider. `ai_provider_id` is required — there is no server-side model fallback.",
-    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/chats",
-    httpMethod: "post",
-    pathParams: [],
-    queryParams: [],
-    flags: [{
-      "name": "ai_provider_id",
-      "description": "Public ID of the AI provider to use.",
-      "required": true,
       "type": "string",
       "in": "body"
     }, {
-      "name": "model",
-      "description": "Model identifier. Overrides the provider's `default_model` when specified.\n",
+      "name": "instructions",
+      "description": "System instructions for this call. Sent to the provider as its `instructions` argument rather than as a message, which is the only place the AI SDK accepts system content (`allowSystemInMessages` defaults to false). This field is the only channel — a `role: \"system\"` entry in `messages` is refused with `400 SYSTEM_MESSAGE_NOT_ALLOWED`. With `chat_id`, this replaces the chat's stored `instructions` for this call only; the stored value applies when the request carries none, and the two are never merged.\n",
       "required": false,
       "type": "string",
       "in": "body"
@@ -3129,6 +3125,40 @@ var routes = {
       "in": "body"
     }]
   },
+  "create-dataset-item-from-generation": {
+    serviceClass: "Evaluations",
+    operationId: "createDatasetItemFromGeneration",
+    description: "Promotes a real, completed generation into a test case: its input messages become the item's `input`, and its own answer becomes `expected_output` unless you supply one. Use it to build an evaluation set out of production traffic rather than hand-authoring fixtures. The item is a **copy**, not a view. It keeps working after the source generation's content is purged, and `source_generation_id` goes null if that generation is deleted — a purge can never quietly stop a suite from being runnable. Requires both `evaluations:CreateDataset` and `generations:GetGeneration`: the call copies content out of a generation, so a principal that may not read that generation may not curate it either. Only a **completed** generation can be promoted (`409 GENERATION_NOT_COMPLETED`), and only while its content is still available: an agent or project running with `trace_content_mode: none` never stored the input, and a purged or expired generation no longer has it (`409 GENERATION_CONTENT_UNAVAILABLE`). Generations that predate input recording answer the same way.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/evaluations",
+    httpMethod: "post",
+    pathParams: ["dataset_id"],
+    queryParams: [],
+    flags: [{
+      "name": "dataset_id",
+      "description": "Dataset ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "generation_id",
+      "description": "The completed generation to promote. Must belong to the same project as the dataset.",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "expected_output",
+      "description": "Reference answer. Omit to use the generation's own answer; pass `null` to store the item with no reference answer.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "metadata",
+      "description": "Free-form tags, opaque to the platform",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
+  },
   "update-dataset-item": {
     serviceClass: "Evaluations",
     operationId: "updateDatasetItem",
@@ -4020,7 +4050,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.",
+    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.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "post",
     pathParams: [],
@@ -4076,7 +4106,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.",
+    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.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "put",
     pathParams: ["formation_id"],
@@ -4110,7 +4140,7 @@ var routes = {
   "delete-formation": {
     serviceClass: "Formations",
     operationId: "deleteFormation",
-    description: "Deletes the formation stack and all its managed resources in reverse dependency order.",
+    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 /api/v1/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://soat.ttoss.dev/docs/modules/formations",
     httpMethod: "delete",
     pathParams: ["formation_id"],
@@ -4251,6 +4281,22 @@ var routes = {
       "in": "path"
     }]
   },
+  "get-generation-transcript": {
+    serviceClass: "Generations",
+    operationId: "getGenerationTranscript",
+    description: "Returns one generation's turn read back as an ordered sequence of steps: what it was asked, each model step with its tool calls and results, and how it ended. The transcript is assembled at read time from the generation record and the trace's steps object; nothing is stored, so it cannot outlive the content it projects. Requires `traces:GetTrace` in addition to `generations:GetGeneration`, because the response merges content from both resources. A generation whose content is unavailable — never written under zero-retention, or cleared by a purge — returns `200` with the skeleton rather than an error: `input` and `output` are null, `steps` is empty, and the `content_redacted_*` fields say which happened. `content_redacted_by_principal_id` is `zero_retention` when the content was never stored, and the purging principal's ID when it was erased later. A generation that is still running returns the same shape with an empty `steps`; `status` disambiguates the two.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
+    httpMethod: "get",
+    pathParams: ["generation_id"],
+    queryParams: [],
+    flags: [{
+      "name": "generation_id",
+      "description": "Public ID of the generation",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-guardrails": {
     serviceClass: "Guardrails",
     operationId: "listGuardrails",
@@ -4773,7 +4819,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "min_score",
-      "description": "Minimum similarity score (0–1). Results with lower scores are excluded. Only applies when `query` is provided.",
+      "description": "Minimum `score` a result must reach to be returned. Filters on the implementation-defined `score`, not on `similarity_score`, so the cutoff follows the ranking. Only applies when `query` is provided. Because the scale behind `score` is not part of the contract, treat a tuned value as tied to the deployment rather than portable.",
       "required": false,
       "type": "number",
       "in": "body"
@@ -4950,7 +4996,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["memory_id", "limit", "offset"],
+    queryParams: ["memory_id", "limit", "offset", "include_invalidated"],
     flags: [{
       "name": "memory_id",
       "description": "Memory container to list entries from (mem_...)",
@@ -4969,6 +5015,12 @@ var routes = {
       "required": false,
       "type": "integer",
       "in": "query"
+    }, {
+      "name": "include_invalidated",
+      "description": "Include invalidated (superseded) entries. They are excluded by default; set this to audit the supersede history.",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
     }]
   },
   "create-memory-entry": {
@@ -5564,7 +5616,7 @@ var routes = {
   "start-orchestration-run": {
     serviceClass: "Orchestrations",
     operationId: "startOrchestrationRun",
-    description: "Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status \"queued\" (a worker then claims it and moves it to \"running\") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as \"sleeping\" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state (the legacy synchronous behaviour).",
+    description: "Creates a new run for the orchestration named by orchestration_id. By default the run executes durably in the background: the response returns immediately with status \"queued\" (a worker then claims it and moves it to \"running\") and progress is observed via get-orchestration-run or run lifecycle webhook events (orchestration_runs.started/awaiting_input/succeeded/failed). Delay and poll waits park the run as \"sleeping\" and are woken by a background scheduler, surviving restarts. Pass wait=true to block until the run reaches a terminal or awaiting_input state.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/orchestrations",
     httpMethod: "post",
     pathParams: [],
@@ -6499,6 +6551,80 @@ var routes = {
       "in": "body"
     }]
   },
+  "fork-session": {
+    serviceClass: "Sessions",
+    operationId: "forkSession",
+    description: "Branches a new session from a point in this session's history: same context, different continuation. The fork gets its own conversation whose messages **reference the same documents** as the parent rather than copying them, so there is one stored copy of the content and a retention purge erases it from both. Recorded tool results ride along on those messages and are **replayed** as model input on the fork's next turn — forking never re-invokes a tool, so exploring a \"what if\" cannot send an email or charge a card a second time. The consequence to accept is that a forked turn sees the tool data as it was, not as it is now. The fork is created **inert**: `auto_generate` is false and no generation is triggered. Drive it with the normal message and generate endpoints. The fork has no actor — attach one only if the branch is meant to be driven by the same end user, since `single_session_per_actor` agents allow one open session per actor.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
+    httpMethod: "post",
+    pathParams: ["session_id"],
+    queryParams: [],
+    flags: [{
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "fork_at_position",
+      "description": "The parent conversation `position` to branch after. Messages at positions 0..N are carried into the fork. Omit it to branch at the tip (the whole history).\n",
+      "required": false,
+      "type": "integer",
+      "in": "body"
+    }, {
+      "name": "agent_id",
+      "description": "Agent the fork runs against. Defaults to the parent session's agent; overriding it is the point of forking — same context, a different agent or agent version. Must belong to the same project as the session being forked.\n",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "name",
+      "description": "Optional name for the forked session",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Optional tags for the forked session",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "tool_context",
+      "description": "Overrides the parent's `tool_context` on the fork. Omit it and the fork inherits the parent's, so the branch is faithful to the run it came from.\n",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }]
+  },
+  "list-session-forks": {
+    serviceClass: "Sessions",
+    operationId: "listSessionForks",
+    description: "Returns the sessions forked directly from this one. One level of lineage: a fork of a fork is listed under its own parent.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
+    httpMethod: "get",
+    pathParams: ["session_id"],
+    queryParams: ["limit", "offset"],
+    flags: [{
+      "name": "session_id",
+      "description": "Session public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "limit",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
   "get-session-tags": {
     serviceClass: "Sessions",
     operationId: "getSessionTags",
@@ -7444,11 +7570,11 @@ var routes = {
   "list-usage-meters": {
     serviceClass: "Usage",
     operationId: "listUsageMeters",
-    description: "Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, or session. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.",
+    description: "Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, session, or `source`. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["agent_id", "generation_id", "trace_id", "actor_id", "session_id", "trigger_id", "action_id", "meter_type", "limit", "offset"],
+    queryParams: ["agent_id", "generation_id", "trace_id", "actor_id", "session_id", "trigger_id", "action_id", "meter_type", "source", "limit", "offset"],
     flags: [{
       "name": "agent_id",
       "description": "Filter by agent public ID",
@@ -7497,6 +7623,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "source",
+      "description": "Filter by what the spend was incurred for. `eval` is an eval run's item generations and `eval_judge` an `llm_judge` scorer's own completion, so verification spend is `source` in (`eval`, `eval_judge`). Ordinary agent traffic carries no source and is matched by neither.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "",
@@ -7527,7 +7659,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "group_by",
-      "description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column.\n",
+      "description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column. `source` buckets by what the spend was incurred for (`eval`, `eval_judge`), which is how verification spend is priced apart from the traffic serving real users; unlabelled traffic collapses into the single `null` bucket.\n",
       "required": true,
       "type": "string",
       "in": "query"
@@ -8037,6 +8169,22 @@ var routes = {
       "in": "path"
     }]
   },
+  "redeliver-webhook-delivery": {
+    serviceClass: "Webhooks",
+    operationId: "redeliverWebhookDelivery",
+    description: "Queues the stored payload of an existing delivery to be sent again. A new delivery record is created rather than the original being reset, so the original attempt stays in the history. The send happens in the background: poll the returned delivery to observe its outcome.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/webhooks",
+    httpMethod: "post",
+    pathParams: ["delivery_id"],
+    queryParams: [],
+    flags: [{
+      "name": "delivery_id",
+      "description": "Delivery to send again (wh_deliv_...)",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "get-webhook-secret": {
     serviceClass: "Webhooks",
     operationId: "getWebhookSecret",
@@ -8314,7 +8462,12 @@ var routes = {
 };
 
 //#endregion
-//#region src/index.ts
+//#region src/naming.ts
+/**
+* Flag-name spellings. The CLI accepts kebab-case (the documented convention),
+* snake_case (the wire spelling, so a body field can be typed exactly as the
+* spec names it), and camelCase alike; matching happens on the canonical form.
+*/
 /**
 * Normalize kebab-case, snake_case, or camelCase to camelCase for param matching.
 * e.g. agent-id → agentId, actor_id → actorId, agentId → agentId
@@ -8338,6 +8491,143 @@ var kebabToSnake = s => {
 var toKebab = s => {
   return s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
 };
+
+//#endregion
+//#region src/validateFlags.ts
+/** Accepted on any command: Commander globals plus the generic id alias. */
+var ALWAYS_ALLOWED = /* @__PURE__ */new Set(["profile", "id"]);
+/**
+* Every flag name this command accepts, canonicalized. Wrapper-added flags are
+* absent on purpose — a wrapper deletes the flags it consumed before this runs,
+* so anything left over really is unrecognized.
+*/
+var knownFlagsFor = route => {
+  return new Set([...route.flags.map(f => {
+    return f.name;
+  }), ...route.pathParams, ...route.queryParams].map(toCanonical));
+};
+/**
+* Offer the closest known flag, so a typo is one line away from its fix rather
+* than a trip to `--help`. Prefix matching in either direction covers the real
+* cases (`limitt`/`limit`, `agent`/`agent_id`) without a full edit-distance pass.
+*/
+var suggestionFor = args => {
+  const target = toCanonical(args.flag).toLowerCase();
+  const near = [...args.known].find(known => {
+    const candidate = known.toLowerCase();
+    return candidate.startsWith(target) || target.startsWith(candidate);
+  });
+  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.
+*
+* 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
+* 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.
+*
+* Returns the error lines to print; empty when every flag is recognized.
+*/
+var findUnknownFlags = args => {
+  if (args.route.httpMethod !== "get") return [];
+  const known = knownFlagsFor(args.route);
+  const unknown = args.flagKeys.filter(flagKey => {
+    if (ALWAYS_ALLOWED.has(flagKey)) return false;
+    return !known.has(toCanonical(flagKey));
+  });
+  if (unknown.length === 0) return [];
+  return [...unknown.map(flag => {
+    return `Unknown flag --${flag} for '${args.commandName}'.${suggestionFor({
+      flag,
+      known
+    })}`;
+  }), `Run "soat ${args.commandName} --help" to see the flags this command accepts.`];
+};
+
+//#endregion
+//#region src/webhookSignature.ts
+var digestMatches = args => {
+  const expectedBuffer = Buffer.from(args.expected, "utf8");
+  const actualBuffer = Buffer.from(args.actual, "utf8");
+  if (expectedBuffer.length !== actualBuffer.length) return false;
+  return timingSafeEqual(expectedBuffer, actualBuffer);
+};
+/** Deprecated scheme: `sha256=<hex>` over the bare body. */
+var verifyLegacySignature = args => {
+  const expected = createHmac("sha256", args.secret).update(args.payload).digest("hex");
+  return digestMatches({
+    expected,
+    actual: args.header
+  });
+};
+/**
+* Timestamped scheme: `t=<unix>,v1=<hex>` over `<t>.<body>`.
+*
+* The timestamp must be present, but its age is deliberately not enforced here:
+* this is a local debugging listener, and rejecting a delivery over clock skew
+* would read as a signing bug. A real subscriber should enforce a tolerance
+* window — the webhooks module docs show one.
+*/
+var verifyTimestampedSignature = args => {
+  const elements = new Map(args.header.split(",").map(part => {
+    const separator = part.indexOf("=");
+    return [part.slice(0, separator).trim(), part.slice(separator + 1)];
+  }));
+  const timestamp = elements.get("t");
+  const digest = elements.get("v1");
+  if (!timestamp || !digest) return false;
+  const expected = createHmac("sha256", args.secret).update(`${timestamp}.${args.payload}`).digest("hex");
+  return digestMatches({
+    expected,
+    actual: digest
+  });
+};
+var headerValue = value => {
+  if (Array.isArray(value)) return value[0] ?? "";
+  return value ?? "";
+};
+/**
+* Picks the scheme a delivery used and verifies it, when a secret is supplied.
+*/
+var inspectDeliverySignature = args => {
+  const timestamped = headerValue(args.headers["x-soat-signature-v2"]);
+  const legacy = headerValue(args.headers["x-soat-signature"]);
+  const scheme = timestamped ? "v2" : "v1";
+  const signature = timestamped || legacy;
+  if (!args.secret) return {
+    signature,
+    scheme,
+    valid: null
+  };
+  return {
+    signature,
+    scheme,
+    valid: scheme === "v2" ? verifyTimestampedSignature({
+      secret: args.secret,
+      payload: args.payload,
+      header: timestamped
+    }) : verifyLegacySignature({
+      secret: args.secret,
+      payload: args.payload,
+      header: legacy
+    })
+  };
+};
+
+//#endregion
+//#region src/index.ts
 /**
 * Renders a command's payload for stdout.
 *
@@ -8400,14 +8690,7 @@ var matchesFilter = (eventType, filter) => {
     return eventType === pattern;
   });
 };
-var verifySignature = (secret, payload, signatureHeader) => {
-  const expected = createHmac("sha256", secret).update(payload).digest("hex");
-  const expectedBuffer = Buffer.from(expected, "utf8");
-  const actualBuffer = Buffer.from(signatureHeader, "utf8");
-  if (expectedBuffer.length !== actualBuffer.length) return false;
-  return timingSafeEqual(expectedBuffer, actualBuffer);
-};
-program.command("listen").description("Start a local webhook listener for testing deliveries").option("--port <number>", "port to listen on", "8787").option("--path <path>", "request path to accept", "/webhook").option("--secret <secret>", "verify X-Soat-Signature with this webhook secret").option("--filter <pattern>", "filter event type(s), supports prefix wildcard and comma separation (e.g. sessions.generation.*,files.*)").option("--json", "print one JSON object per line").action(opts => {
+program.command("listen").description("Start a local webhook listener for testing deliveries").option("--port <number>", "port to listen on", "8787").option("--path <path>", "request path to accept", "/webhook").option("--secret <secret>", "verify the delivery signature with this webhook secret").option("--filter <pattern>", "filter event type(s), supports prefix wildcard and comma separation (e.g. sessions.generation.*,files.*)").option("--json", "print one JSON object per line").action(opts => {
   const port = Number(opts.port);
   const path = opts.path;
   const secret = opts.secret;
@@ -8435,7 +8718,6 @@ program.command("listen").description("Start a local webhook listener for testin
       const rawBody = Buffer.concat(chunks).toString("utf8");
       const eventType = String(req.headers["x-soat-event"] ?? "unknown");
       const deliveryId = String(req.headers["x-soat-delivery"] ?? "unknown");
-      const signature = String(req.headers["x-soat-signature"] ?? "");
       if (filter && !matchesFilter(eventType, filter)) {
         res.writeHead(200, {
           "Content-Type": "application/json"
@@ -8450,24 +8732,28 @@ program.command("listen").description("Start a local webhook listener for testin
       try {
         parsedPayload = JSON.parse(rawBody);
       } catch {}
-      let isSignatureValid = null;
-      if (secret) isSignatureValid = verifySignature(secret, rawBody, signature);
+      const inspected = inspectDeliverySignature({
+        secret,
+        payload: rawBody,
+        headers: req.headers
+      });
       const record = {
         timestamp: (/* @__PURE__ */new Date()).toISOString(),
         event_type: eventType,
         delivery_id: deliveryId,
-        signature,
-        signature_valid: isSignatureValid,
+        signature: inspected.signature,
+        signature_scheme: inspected.scheme,
+        signature_valid: inspected.valid,
         payload: parsedPayload
       };
       if (asJson) console.log(JSON.stringify(record));else {
         console.log("--- webhook received ---");
         console.log("event_type:", eventType);
         console.log("delivery_id:", deliveryId);
-        if (secret) console.log("signature_valid:", isSignatureValid);
+        if (secret) console.log("signature_valid:", inspected.valid);
         console.log("payload:", JSON.stringify(parsedPayload, null, 2));
       }
-      const responseStatus = secret && isSignatureValid === false ? 401 : 200;
+      const responseStatus = secret && inspected.valid === false ? 401 : 200;
       res.writeHead(responseStatus, {
         "Content-Type": "application/json"
       });
@@ -8475,7 +8761,7 @@ program.command("listen").description("Start a local webhook listener for testin
         ok: responseStatus === 200,
         event_type: eventType,
         delivery_id: deliveryId,
-        signature_valid: isSignatureValid
+        signature_valid: inspected.valid
       }));
     });
   });
@@ -8536,6 +8822,15 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
   const flagTypeByCanonical = new Map(route.flags.map(f => {
     return [toCanonical(f.name), f.type];
   }));
+  const unknownFlagErrors = findUnknownFlags({
+    commandName,
+    route,
+    flagKeys: Object.keys(flags)
+  });
+  if (unknownFlagErrors.length > 0) {
+    for (const line of unknownFlagErrors) console.error(line);
+    process.exit(1);
+  }
   const pathArgs = {};
   const queryArgs = {};
   const bodyArgs = {};
@@ -8604,6 +8899,14 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
     process.exit(1);
   }
   console.log(await formatResultData(result.data));
+  const failure = resolveFailureMessage({
+    commandName,
+    data: result.data
+  });
+  if (failure) {
+    console.error(failure);
+    process.exit(1);
+  }
 });
 var runCli = async args => {
   const previousArgv = process.argv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "type": "module",
   "dependencies": {
     "@inquirer/input": "^5.1.2",
@@ -8,7 +8,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.22.1"
+    "@soat/sdk": "0.24.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",