@soat/cli 0.15.5 → 0.15.7

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.15.5";
+var version = "0.15.7";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -630,15 +630,21 @@ var routes = {
       "required": false,
       "type": "string",
       "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": "",
+      "description": "Deprecated shorthand — each entry becomes a bare `{ \"tool_id\": … }` binding. Use `tool_bindings` instead.",
       "required": false,
       "type": "array",
       "in": "body"
     }, {
       "name": "tools",
-      "description": "Ephemeral tool definitions available only to this agent's generations — no separate Tool resource is created (any `project_id` on an entry is ignored), so they never appear in `GET /tools` and cannot be targeted by `active_tool_ids`/ `step_rules` (which reference `tool_ids`). Cannot be of type `pipeline`; nest a persisted pipeline tool via `tool_ids` instead. Use `tool_ids` to reference existing tools and `tools` for ones scoped to just this agent.",
+      "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.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -762,15 +768,21 @@ var routes = {
       "required": false,
       "type": "string",
       "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": "",
+      "description": "Deprecated shorthand — replaces only the reference (`tool_id`) bindings, rewriting them bare (any `approval_policy` on them is dropped). Use `tool_bindings` instead.",
       "required": false,
       "type": "array",
       "in": "body"
     }, {
       "name": "tools",
-      "description": "Ephemeral tool definitions available only to this agent's generations — no separate Tool resource is created (any `project_id` on an entry is ignored), so they never appear in `GET /tools` and cannot be targeted by `active_tool_ids`/ `step_rules` (which reference `tool_ids`). Cannot be of type `pipeline`; nest a persisted pipeline tool via `tool_ids` instead. Replaces the agent's entire `tools` array; set to `null` to clear.",
+      "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.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -879,15 +891,21 @@ var routes = {
       "required": false,
       "type": "string",
       "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": "",
+      "description": "Deprecated shorthand — replaces only the reference (`tool_id`) bindings, rewriting them bare (any `approval_policy` on them is dropped). Use `tool_bindings` instead.",
       "required": false,
       "type": "array",
       "in": "body"
     }, {
       "name": "tools",
-      "description": "Ephemeral tool definitions available only to this agent's generations — no separate Tool resource is created (any `project_id` on an entry is ignored), so they never appear in `GET /tools` and cannot be targeted by `active_tool_ids`/ `step_rules` (which reference `tool_ids`). Cannot be of type `pipeline`; nest a persisted pipeline tool via `tool_ids` instead. Replaces the agent's entire `tools` array; set to `null` to clear.",
+      "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.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -1041,6 +1059,12 @@ var routes = {
       "required": false,
       "type": "string",
       "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`, `run_id`, `node_id`, `extraction`, and internal recovery state) cannot be set here and are rejected with 400.",
+      "required": false,
+      "type": "object",
+      "in": "body"
     }, {
       "name": "extract",
       "description": "Per-turn override of the agent's `knowledge_config.extraction` default. Omit to follow the agent's stored config. Set `false` to suppress automatic memory extraction for this turn (e.g. an operational or tool-listing turn that would only add noise to a curated memory). Set `true` to force extraction on for this turn even when the agent does not enable it by default, provided the agent has a `write_memory_id`. Has no effect on streaming or `requires_action` turns, which never extract.",
@@ -1289,7 +1313,7 @@ var routes = {
   "create-api-key": {
     serviceClass: "APIKeys",
     operationId: "createApiKey",
-    description: "Creates a new API key for the authenticated user. - `project_id` is required: every key is scoped to exactly one project. - 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.",
+    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).",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: [],
     queryParams: [],
@@ -1301,8 +1325,8 @@ var routes = {
       "in": "body"
     }, {
       "name": "project_id",
-      "description": "Project ID this key is scoped to. Required — keys cannot span projects.",
-      "required": true,
+      "description": "Optional project ID to scope the key to. Omit or set null to create an unscoped key that spans projects.",
+      "required": false,
       "type": "string",
       "in": "body"
     }, {
@@ -1331,7 +1355,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 but never cleared. 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.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     pathParams: ["api_key_id"],
     queryParams: [],
@@ -1349,7 +1373,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "project_id",
-      "description": "Re-scope the key to a different project. Cannot be null — keys are always project-scoped.",
+      "description": "Re-scope the key to a different project, or set null to clear the scope (unscoped key). Omit to leave the scope unchanged.",
       "required": false,
       "type": "string",
       "in": "body"
@@ -2981,7 +3005,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "metadata",
-      "description": "",
+      "description": "Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`.\n",
       "required": false,
       "type": "object",
       "in": "body"
@@ -3029,7 +3053,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "metadata",
-      "description": "",
+      "description": "Static annotations stored on the formation record. This field is NOT a substitution site: `sub`/`param`/`ref` expressions are rejected with 400 (`FORMATION_INVALID_METADATA`). For deploy-time substitution use the template's top-level `metadata` block, which is resolved into `resolved_metadata`.\n",
       "required": false,
       "type": "object",
       "in": "body"
@@ -3125,6 +3149,27 @@ var routes = {
       "in": "path"
     }]
   },
+  "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`, `run_id`, `node_id`, `extraction`, and internal recovery state) cannot be set and are rejected with 400.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
+    pathParams: ["generation_id"],
+    queryParams: [],
+    flags: [{
+      "name": "generation_id",
+      "description": "Public ID of the generation",
+      "required": true,
+      "type": "string",
+      "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`, `run_id`, `node_id`, `extraction`, and internal recovery state) are rejected with 400.\n",
+      "required": true,
+      "type": "object",
+      "in": "body"
+    }]
+  },
   "list-ingestion-rules": {
     serviceClass: "IngestionRules",
     operationId: "listIngestionRules",

package/package.json

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