@soat/cli 0.14.1 → 0.14.3

package/dist/index.mjs

@@ -11,7 +11,7 @@ import { load } from "js-yaml";
 import * as os from "node:os";
 
 //#region package.json
-var version = "0.14.1";
+var version = "0.14.3";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -67,6 +67,7 @@ var readTemplateFromPath = args => {
     throw new Error(`Template file must contain valid JSON or YAML: ${templatePath}`);
   }
 };
+var OMIT_PARAMETER = Symbol("omit-parameter");
 var resolveEnvRef = args => {
   const {
     value,
@@ -75,8 +76,7 @@ var resolveEnvRef = args => {
   const atRef = /^@([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
   if (atRef) {
     const resolved = env[atRef[1]];
-    if (resolved === void 0) throw new Error(`Missing environment variable: ${atRef[1]}`);
-    return resolved;
+    return resolved === void 0 ? OMIT_PARAMETER : resolved;
   }
   const simple = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
   if (simple) {
@@ -103,10 +103,9 @@ var resolveParameterPair = args => {
     const key = pair.trim();
     if (!key) throw new Error(`Invalid --${PARAMETER_FLAG} value "${pair}". Parameter key cannot be empty.`);
     const resolved = env[key];
-    if (resolved === void 0) throw new Error(`Missing environment variable: ${key}`);
     return {
       key,
-      value: resolved
+      value: resolved === void 0 ? OMIT_PARAMETER : resolved
     };
   }
   const key = pair.slice(0, eqIdx).trim();
@@ -130,7 +129,7 @@ var formationsWrapper = {
     type: "string"
   }, {
     name: "parameter",
-    description: "Template parameter in key=value format (repeatable). Values support env var references: $VAR, ${VAR}, or @VAR_NAME (shell-safe). Omit the value entirely (--parameter KEY) to auto-read KEY from the merged env.",
+    description: "Template parameter in key=value format (repeatable). Values support env var references: $VAR, ${VAR}, or @VAR_NAME (shell-safe). Omit the value entirely (--parameter KEY) to auto-read KEY from the merged env. For @VAR_NAME and bare KEY, an unset env var omits the parameter instead of failing, so the server reuses a previous value (formation parameters declared `use_previous_value`) or errors if none exists.",
     required: false,
     type: "string"
   }, {
@@ -182,7 +181,7 @@ var formationsWrapper = {
           pair,
           env: mergedEnv
         });
-        resolvedParameters[key] = value;
+        if (value !== OMIT_PARAMETER) resolvedParameters[key] = value;
       }
       forcedBody[PARAMETERS_FIELD] = resolvedParameters;
     }
@@ -1010,6 +1009,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "action_id",
+      "description": "Logical action label recorded on the generation's usage meter, so spend can be rolled up per action (e.g. an A/B/C/D operating action).",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "knowledge_config",
       "description": "Per-generation knowledge retrieval override. Array filters (memory_ids, memory_tags, document_ids, document_paths) are unioned with the agent's stored knowledge_config; scalar fields (min_score, limit) use the per-generation value when present.",
@@ -4939,6 +4944,81 @@ var routes = {
       "in": "path"
     }]
   },
+  "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 and generation. 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",
+    pathParams: [],
+    queryParams: ["agent_id", "generation_id", "trace_id", "trigger_id", "action_id", "limit", "offset"],
+    flags: [{
+      "name": "agent_id",
+      "description": "Filter by agent public ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "generation_id",
+      "description": "Filter by generation public ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "trace_id",
+      "description": "Filter by trace public ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "trigger_id",
+      "description": "Filter by the trigger that initiated the generation",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "action_id",
+      "description": "Filter by logical action id",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "limit",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
+  "get-price-book": {
+    serviceClass: "Usage",
+    operationId: "getPriceBook",
+    description: "Returns the global price book — the versioned per-provider/model unit prices used to compute usage cost at write time. Readable by any authenticated user.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
+    pathParams: [],
+    queryParams: [],
+    flags: []
+  },
+  "upsert-price-book": {
+    serviceClass: "Usage",
+    operationId: "upsertPriceBook",
+    description: "Upserts price rows keyed on (provider, model, effective_from). Admin only. `effective_from` must be in the future — past prices are immutable so recorded costs stay explainable; ship corrections as new future-dated rows.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
+    pathParams: [],
+    queryParams: [],
+    flags: [{
+      "name": "prices",
+      "description": "",
+      "required": true,
+      "type": "array",
+      "in": "body"
+    }]
+  },
   "get-current-user": {
     serviceClass: "Users",
     operationId: "getCurrentUser",

package/package.json

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