@soat/cli 0.23.0 → 0.25.0

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2025, Terezinha Tech Operations (ttoss)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025-2026 Terezinha Tech Operations (ttoss)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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.23.0";
+var version = "0.25.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);
@@ -519,18 +573,6 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
-    }, {
-      "name": "memory_id",
-      "description": "Memory ID to link to this actor. Mutually exclusive with auto_create_memory.",
-      "required": false,
-      "type": "string",
-      "in": "body"
-    }, {
-      "name": "auto_create_memory",
-      "description": "When true, automatically creates a new memory container for this actor and links it. Ignored if memory_id is set. With external_id (idempotent), memory is only created on first creation.",
-      "required": false,
-      "type": "boolean",
-      "in": "body"
     }]
   },
   "get-actor": {
@@ -593,12 +635,6 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
-    }, {
-      "name": "memory_id",
-      "description": "Memory ID to link to this actor. Set to null to unlink.",
-      "required": false,
-      "type": "string",
-      "in": "body"
     }, {
       "name": "tags",
       "description": "",
@@ -1179,7 +1215,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"
@@ -1590,7 +1626,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"],
@@ -1644,7 +1680,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: [],
@@ -1666,7 +1702,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: [],
@@ -1694,7 +1730,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"],
@@ -1710,7 +1746,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"],
@@ -1744,7 +1780,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"],
@@ -2506,13 +2542,19 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["project_id", "limit", "offset"],
+    queryParams: ["project_id", "path_prefix", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Project ID (optional)",
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "path_prefix",
+      "description": "Only documents filed under this directory. The prefix is a path boundary, not a substring: `/reports` returns `/reports/q1.txt` and never `/reports-archive/q1.txt`, and `/` selects the whole project. A leading slash is optional and a trailing one is ignored, so `reports`, `/reports` and `/reports/` are the same filter. `%` and `_` are literal characters, not wildcards.",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of results to return",
@@ -3229,7 +3271,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "scorers",
-      "description": "Scorer configs, a discriminated union on `type`. Each type may appear at most once. Every scorer produces `{ score: 0–1, passed: boolean }`; binary scorers emit 0 or 1.\n\n`exact_match` compares the trimmed output text to `expected_output`. `contains` looks for `value` in the output text. `json_logic` evaluates `expression` over `{ input, output, object, expected, item.metadata }`, where `object` is the structured output (absent when the agent has no `output_schema`). `output_schema` validates the structured output against the scorer's own `schema`, falling back to the agent's; it requires the agent to carry an `output_schema`, because without one the platform emits no structured output and every item would score 0.\n\n`llm_judge` grades the output with a model completion, returning a continuous score plus its `reasoning`. Its `pass_threshold` is required: a continuous score says nothing about where \"good enough\" is, and a defaulted cutoff would silently decide the gate.",
+      "description": "Scorer configs, a discriminated union on `type`. Each type may appear at most once. Every scorer produces `{ score: 0–1, passed: boolean }`; binary scorers emit 0 or 1.\n\n`exact_match` compares the trimmed output text to `expected_output`. `contains` looks for `value` in the output text. `json_logic` evaluates `expression` over `{ input, output, object, expected, item.metadata }`, where `object` is the structured output (absent when the agent has no `output_schema`). `output_schema` validates the structured output against the scorer's own `schema`, falling back to the agent's; it requires the agent to carry an `output_schema`, because without one the platform emits no structured output and every item would score 0.\n\n`llm_judge` grades the output with a model completion, returning a continuous score plus its `reasoning`. Its `pass_threshold` is required: a continuous score says nothing about where \"good enough\" is, and a defaulted cutoff would silently decide the gate.\n\n`tool` runs a custom scoring algorithm: a server-callable project tool the engine invokes once per item with the item's context. Unlike the built-in types it may appear several times, each under a distinct `name` — outcomes and aggregates key on the name.",
       "required": true,
       "type": "array",
       "in": "body"
@@ -3291,7 +3333,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "scorers",
-      "description": "Scorer configs, a discriminated union on `type`. Each type may appear at most once. Every scorer produces `{ score: 0–1, passed: boolean }`; binary scorers emit 0 or 1.\n\n`exact_match` compares the trimmed output text to `expected_output`. `contains` looks for `value` in the output text. `json_logic` evaluates `expression` over `{ input, output, object, expected, item.metadata }`, where `object` is the structured output (absent when the agent has no `output_schema`). `output_schema` validates the structured output against the scorer's own `schema`, falling back to the agent's; it requires the agent to carry an `output_schema`, because without one the platform emits no structured output and every item would score 0.\n\n`llm_judge` grades the output with a model completion, returning a continuous score plus its `reasoning`. Its `pass_threshold` is required: a continuous score says nothing about where \"good enough\" is, and a defaulted cutoff would silently decide the gate.",
+      "description": "Scorer configs, a discriminated union on `type`. Each type may appear at most once. Every scorer produces `{ score: 0–1, passed: boolean }`; binary scorers emit 0 or 1.\n\n`exact_match` compares the trimmed output text to `expected_output`. `contains` looks for `value` in the output text. `json_logic` evaluates `expression` over `{ input, output, object, expected, item.metadata }`, where `object` is the structured output (absent when the agent has no `output_schema`). `output_schema` validates the structured output against the scorer's own `schema`, falling back to the agent's; it requires the agent to carry an `output_schema`, because without one the platform emits no structured output and every item would score 0.\n\n`llm_judge` grades the output with a model completion, returning a continuous score plus its `reasoning`. Its `pass_threshold` is required: a continuous score says nothing about where \"good enough\" is, and a defaulted cutoff would silently decide the gate.\n\n`tool` runs a custom scoring algorithm: a server-callable project tool the engine invokes once per item with the item's context. Unlike the built-in types it may appear several times, each under a distinct `name` — outcomes and aggregates key on the name.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -3996,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.",
+    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: [],
@@ -4052,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.",
+    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"],
@@ -4227,6 +4269,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",
@@ -4749,7 +4807,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"
@@ -4926,7 +4984,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_...)",
@@ -4945,12 +5003,18 @@ 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": {
     serviceClass: "MemoryEntries",
     operationId: "createMemoryEntry",
-    description: "Creates a new entry in the specified memory container. Automatically generates an embedding for semantic search.",
+    description: "Creates a new entry in the specified memory container. Automatically generates an embedding for semantic search, and skips the write when an existing entry is a near-duplicate (see `duplicate_threshold`). A merely similar fact is stored as its own entry: this path has no agent context and therefore no model to consolidate two facts into one.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memoryEntries",
     httpMethod: "post",
     pathParams: [],
@@ -4987,13 +5051,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "duplicate_threshold",
-      "description": "Cosine similarity score at or above which the incoming content is considered a duplicate and skipped (default 0.95)",
-      "required": false,
-      "type": "number",
-      "in": "body"
-    }, {
-      "name": "update_threshold",
-      "description": "Cosine similarity score at or above which the incoming content is appended to the existing entry (default 0.75)",
+      "description": "Cosine similarity score at or above which the incoming content is considered a duplicate of an existing entry and skipped (default 0.95). Below it the entry is always created.",
       "required": false,
       "type": "number",
       "in": "body"
@@ -6475,6 +6533,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",
@@ -8019,6 +8151,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",
@@ -8390,6 +8538,76 @@ var findUnknownFlags = args => {
   }), `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
 /**
@@ -8454,14 +8672,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;
@@ -8489,7 +8700,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"
@@ -8504,24 +8714,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"
       });
@@ -8529,7 +8743,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
       }));
     });
   });
@@ -8667,6 +8881,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,7 @@
 {
   "name": "@soat/cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
+  "license": "Apache-2.0",
   "type": "module",
   "dependencies": {
     "@inquirer/input": "^5.1.2",
@@ -8,7 +9,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.23.0"
+    "@soat/sdk": "0.25.0"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",