@soat/cli 0.18.4 → 0.18.6

package/dist/index.mjs

@@ -13,7 +13,7 @@ import { load } from "js-yaml";
 import * as os from "node:os";
 
 //#region package.json
-var version = "0.18.4";
+var version = "0.18.6";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -1188,7 +1188,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "metadata",
-      "description": "Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips when the generation is fetched via the generations API. Reserved server-owned keys (`action_id`, `trigger_id`, `orchestration_run_id`, `node_id`, `extraction`, and internal recovery state) cannot be set here and are rejected with 400.",
+      "description": "Caller-supplied key/value metadata attached to the generation record for per-run audit attribution (e.g. the knowledge-corpus version that produced this action). Round-trips verbatim when the generation is fetched via the generations API. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the model route's record, the extraction summary) lives in its own top-level generation fields and cannot be written from here. Use the request's own `action_id` field to set the usage-attribution label.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -3841,7 +3841,7 @@ var routes = {
   "update-generation": {
     serviceClass: "Generations",
     operationId: "updateGeneration",
-    description: "Attaches caller-supplied key/value metadata to a generation record for per-run audit attribution (e.g. recording which knowledge-corpus version produced an AI action). The provided keys are shallow-merged over the existing metadata, so repeated patches accumulate and system-owned keys are preserved. Reserved keys (`action_id`, `trigger_id`, `orchestration_run_id`, `node_id`, `extraction`, and internal recovery state) cannot be set and are rejected with 400.",
+    description: "Attaches caller-supplied key/value metadata to a generation record for per-run audit attribution (e.g. recording which knowledge-corpus version produced an AI action). The provided keys are shallow-merged over the existing `metadata`, so repeated patches accumulate. The bag is caller-owned and no key is reserved: server-owned state (usage attribution, the served agent version, the route's record, the extraction summary) lives in its own top-level fields and cannot be written from here.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
     httpMethod: "patch",
     pathParams: ["generation_id"],
@@ -3854,12 +3854,28 @@ var routes = {
       "in": "path"
     }, {
       "name": "metadata",
-      "description": "Caller-supplied key/value metadata to shallow-merge into the generation record. Reserved server-owned keys (`action_id`, `trigger_id`, `orchestration_run_id`, `node_id`, `extraction`, and internal recovery state) are rejected with 400.\n",
+      "description": "Caller-supplied key/value metadata to shallow-merge into the generation record's caller-owned `metadata` bag. No key is reserved: server-owned state lives in its own top-level fields and cannot be written from here.\n",
       "required": true,
       "type": "object",
       "in": "body"
     }]
   },
+  "purge-generation-content": {
+    serviceClass: "Generations",
+    operationId: "purgeGenerationContent",
+    description: "Clears the generation's content — `metadata`, `error`, `extraction`, and the internal recovery state of a paused run — and stamps `content_redacted_at`. The usage and audit skeleton is preserved: ids, timestamps, status, stop reason, and the attribution fields (`action_id`, `trigger_id`, `orchestration_run_id`, `node_id`, `agent_version`, `routing`) the billing ledger reads. A purged generation reads back as that skeleton, not a 404. This does **not** delete the parent trace's steps object, which holds this generation's content alongside its siblings'. To erase the run's content completely, purge the trace (`DELETE /api/v1/traces/{trace_id}/content`), which cascades here. Idempotent — purging an already-purged generation succeeds and leaves the original `content_redacted_at` in place.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
+    httpMethod: "delete",
+    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",
@@ -6035,7 +6051,7 @@ var routes = {
   "create-task": {
     serviceClass: "Tasks",
     operationId: "createTask",
-    description: "Creates a task bound to a workflow. The task is placed in the workflow's initial state and that state's `on_enter` automation fires.",
+    description: "Creates a task bound to a workflow. By default the task is placed in the workflow's initial state; passing `state` places it directly in that named state instead — an alternate entry point for starting a task mid-flow (e.g. \"a new recorte for an existing theme by id\"), rather than re-submitting from the initial state and hoping a guard or similarity gate recognizes it. Entering the resulting state, initial or named, behaves identically: that state's `on_enter` automation fires and its `stalled_after` clock arms.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/tasks",
     httpMethod: "post",
     pathParams: [],
@@ -6070,6 +6086,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "body"
+    }, {
+      "name": "state",
+      "description": "Name of a declared workflow state to create the task in directly, instead of the workflow's `initial` state. Must name a state declared on the workflow, or the request is rejected with `TASK_STATE_NOT_FOUND` (400). Defaults to the `initial` state.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }]
   },
   "get-task": {
@@ -6091,7 +6113,7 @@ var routes = {
   "update-task": {
     serviceClass: "Tasks",
     operationId: "updateTask",
-    description: "Updates a task's payload, title, or assignee. `state` is never directly writable — move it with a transition; sending a `state` field is rejected as an unknown field (`VALIDATION_FAILED`). `payload` is shallow-merged over the existing payload (PATCH semantics): keys the request omits are preserved, so setting one field never discards values an on_enter automation wrote (e.g. `last_result`). The merged payload is validated against the workflow's `payload_schema`.",
+    description: "Updates a task's payload, title, or assignee. `state` is never directly writable — move it with a transition; sending a `state` field is rejected as an unknown field (`VALIDATION_FAILED`). `payload` is shallow-merged over the existing payload (PATCH semantics): keys the request omits are preserved. The payload is caller-owned; the automation result lives in the read-only `last_result` field, which no patch can reach. The merged payload is validated against the workflow's `payload_schema`.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/tasks",
     httpMethod: "patch",
     pathParams: ["task_id"],
@@ -6250,7 +6272,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "execute",
-      "description": "Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).\n",
+      "description": "Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).\n\n`auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:\n\n- `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.\n- `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.\n\nCredential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.\n",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6354,7 +6376,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "execute",
-      "description": "Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).\n",
+      "description": "Execution config for http tools. Supported fields: `url` (required), `method` (default `POST`), `headers`, and `body_mode`. The `url` may contain `{paramName}` placeholders (e.g. `/users/{userId}`) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. `body_mode` is `json` (default) or `multipart`. In `multipart` mode the merged tool arguments are sent as a `multipart/form-data` body: scalar fields become plain form fields and a field shaped like `{ content_type, filename, data_base64 }` is decoded from base64 and attached as a file part (the hardcoded `Content-Type: application/json` is dropped so `fetch` sets the multipart boundary itself).\n\n`auth` adds a computed request credential, for targets whose `Authorization` value cannot be expressed as a static header. Supported `auth.type` values:\n\n- `aws_sigv4` — signs the request with AWS Signature Version 4. Requires `region`, `service`, `access_key_id` and `secret_access_key`; `session_token` is optional (temporary credentials). Incompatible with `body_mode: multipart`, whose body bytes are not known at signing time.\n- `gcp_service_account` — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires `credentials` (the service account key file JSON, as a string) and `scopes` (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire.\n\nCredential fields accept `{{secret:...}}` references and should use them — a tool is readable by anyone who can `GET /tools`, and the stored reference is what is echoed back, never the resolved value.\n",
       "required": false,
       "type": "object",
       "in": "body"
@@ -6512,6 +6534,22 @@ var routes = {
       "in": "query"
     }]
   },
+  "purge-trace-content": {
+    serviceClass: "Traces",
+    operationId: "purgeTraceContent",
+    description: "Deletes the trace's steps object from storage and clears its content columns (`file_id`, `error`), cascading to every descendant trace and to all of their generations. A descendant holds its own steps object covering the same run, so the cascade is what makes the erasure complete rather than merely partial. The rows survive as auditable skeletons with `content_redacted_at` set — ids, timestamps, step counts, and the generations' usage-attribution fields are preserved, because the billing and audit ledger must outlive a tenant's erasure of the content. A purged trace therefore reads back as a skeleton, not a 404: a 404 would prove nothing. Idempotent — purging an already-purged trace succeeds and leaves the original `content_redacted_at` in place.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/traces",
+    httpMethod: "delete",
+    pathParams: ["trace_id"],
+    queryParams: [],
+    flags: [{
+      "name": "trace_id",
+      "description": "Public ID of the trace",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-triggers": {
     serviceClass: "Triggers",
     operationId: "listTriggers",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.18.4",
+  "version": "0.18.6",
   "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.18.4"
+    "@soat/sdk": "0.18.6"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",