@soat/cli 0.45.0 → 0.46.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import * as os from "node:os";
 import { createHmac, timingSafeEqual } from "node:crypto";
 
 //#region package.json
-var version = "0.45.0";
+var version = "0.46.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -481,7 +481,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/actors",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["project_id", "external_id", "agent_id", "chat_id", "conversation_id", "limit", "offset"],
+    queryParams: ["project_id", "external_id", "name", "agent_id", "chat_id", "conversation_id", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Project ID (optional)",
@@ -494,6 +494,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "name",
+      "description": "Case-insensitive substring match on the actor name",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "agent_id",
       "description": "Return only actors linked to this agent",
@@ -3933,13 +3939,19 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     httpMethod: "get",
     pathParams: ["file_id"],
-    queryParams: [],
+    queryParams: ["token"],
     flags: [{
       "name": "file_id",
       "description": "File ID",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "token",
+      "description": "Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }]
   },
   "update-file-metadata": {
@@ -3983,13 +3995,19 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     httpMethod: "get",
     pathParams: ["file_id"],
-    queryParams: [],
+    queryParams: ["token"],
     flags: [{
       "name": "file_id",
       "description": "File ID",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "token",
+      "description": "Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }]
   },
   "get-file-tags": {
@@ -4265,7 +4283,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["agent_id", "trace_id", "initiator_generation_id", "chain_id", "orchestration_run_id", "node_id", "status", "limit", "offset"],
+    queryParams: ["agent_id", "trace_id", "session_id", "actor_id", "initiator_generation_id", "chain_id", "orchestration_run_id", "node_id", "status", "limit", "offset"],
     flags: [{
       "name": "agent_id",
       "description": "Filter by agent public ID",
@@ -4278,6 +4296,18 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "session_id",
+      "description": "Return only the generations dispatched through one session — the turns behind that conversation's spend. A session that does not exist in scope yields an empty page.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "actor_id",
+      "description": "Return only the generations one end user started, across every session they appear in. An actor that does not exist in scope yields an empty page.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "initiator_generation_id",
       "description": "Filter by the public ID of the parent generation. Returns all generations triggered by that generation — sub-agent invocations. Null-initiated (top-level) generations are not returned.\n",
@@ -6429,13 +6459,19 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/secrets",
     httpMethod: "delete",
     pathParams: ["secret_id"],
-    queryParams: [],
+    queryParams: ["force"],
     flags: [{
       "name": "secret_id",
       "description": "Secret ID",
       "required": true,
       "type": "string",
       "in": "path"
+    }, {
+      "name": "force",
+      "description": "Delete the secret even when AI providers reference it, destroying those providers too. Without it a referenced secret answers SECRET_HAS_DEPENDENTS.",
+      "required": false,
+      "type": "boolean",
+      "in": "query"
     }]
   },
   "list-sessions": {
@@ -6533,7 +6569,7 @@ var routes = {
   "get-session": {
     serviceClass: "Sessions",
     operationId: "getSession",
-    description: "Returns details of a single session.",
+    description: "Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, a split by day or model, or one end user across every session, narrow the usage aggregate with `session_id` / `actor_id` instead.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     httpMethod: "get",
     pathParams: ["session_id"],
@@ -7803,11 +7839,11 @@ var routes = {
   "list-usage-events": {
     serviceClass: "Usage",
     operationId: "listUsageEvents",
-    description: "Returns the raw usage events the caller can access, most recent first, optionally filtered by agent, generation, trace, actor, session, or `source`. Each event is the per-generation token usage as reported by the provider, for audit and reconciliation.",
+    description: "Returns the raw usage events the caller can access, most recent first, narrowed by any combination of the same filters the aggregate takes — agent, generation, trace, actor, session, AI provider, orchestration run, orchestration, trigger, action, meter type, model or `source` — so a rollup and the events behind it are addressed the same way. Each event is the per-generation token usage as reported by the provider, for audit and reconciliation. An id naming nothing in scope yields an empty page rather than dropping the filter, so a mistyped narrowing can never widen the list past what was asked for.",
     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", "source", "limit", "offset"],
+    queryParams: ["agent_id", "generation_id", "trace_id", "actor_id", "session_id", "ai_provider_id", "orchestration_run_id", "orchestration_id", "model", "trigger_id", "action_id", "meter_type", "source", "limit", "offset"],
     flags: [{
       "name": "agent_id",
       "description": "Filter by agent public ID",
@@ -7838,6 +7874,30 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "ai_provider_id",
+      "description": "Filter by the provider record the spend was billed against. A provider that does not exist in scope yields an empty page.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "orchestration_run_id",
+      "description": "Filter by the orchestration run that metered the event. A run that does not exist in scope yields an empty page.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "orchestration_id",
+      "description": "Filter by orchestration — the events of the runs it started itself, not the subtree its `loop` or `sub_orchestration` nodes started. An orchestration that does not exist in scope yields an empty page.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "model",
+      "description": "Filter by the as-billed SKU the event recorded. Matched as recorded, so it still selects events whose provider has since been deleted.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "trigger_id",
       "description": "Filter by the trigger that initiated the generation",
@@ -7879,11 +7939,11 @@ var routes = {
   "get-usage-aggregate": {
     serviceClass: "Usage",
     operationId: "getUsageAggregate",
-    description: "Returns a project's usage rolled up over an optional `[from, to]` time window, bucketed by a single dimension and optionally narrowed to one `meter_type`. Each group and the grand total carry an `event_count`, summed token counts, a measured `quantity` per component (so infra meters report their real amount, not zeros), and `cost_usd` (null when no event in the bucket was priced). This is the per-project cost-by-range/by-category query — a monthly figure without scanning raw usage events client-side. `groups` is paginated. Its `total` is the number of distinct buckets in the window — bucket cardinality, including a null bucket for the events the dimension does not apply to, and never a count of entities. To count entities, send `include=distinct` and read `totals.distinct`. `totals` always describes the whole window — never the page above it.",
+    description: "Returns a project's usage rolled up over an optional `[from, to]` time window, optionally bucketed by a single dimension and narrowed by any combination of thirteen filters — session, actor, agent, AI provider, orchestration run, orchestration, generation, trace, meter type, model, source, trigger and action. That is how \"what did this conversation cost\", \"what has this end user cost\" and \"what did this agent cost\" are answered. Each group and the grand total carry an `event_count`, summed token counts, a measured `quantity` per component (so infra meters report their real amount, not zeros), and `cost_usd` (null when no event in the bucket was priced). This is the per-project cost-by-range/by-category query — a monthly figure without scanning raw usage events client-side. Narrowings intersect and apply to the whole rollup — every bucket, `totals` and `totals.distinct` alike — so each composes with any `group_by`, and all thirteen are echoed back under `filters`. The eight naming a resource are resolved against the project, and one naming nothing there empties the rollup rather than being dropped: a mistyped id must never read back as the project's whole spend. The other five are matched against the value the event recorded. `groups` is paginated. Its `total` is the number of distinct buckets in the window — bucket cardinality, including a null bucket for the events the dimension does not apply to, and never a count of entities. To count entities, send `include=distinct` and read `totals.distinct`. `totals` always describes the whole window — never the page above it, and never the bucketing: omit `group_by` and `totals` is unchanged while `groups` is empty.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["project_id", "group_by", "include", "from", "to", "meter_type", "limit", "offset"],
+    queryParams: ["project_id", "group_by", "include", "from", "to", "meter_type", "session_id", "actor_id", "agent_id", "ai_provider_id", "orchestration_run_id", "orchestration_id", "generation_id", "trace_id", "model", "source", "trigger_id", "action_id", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Project public ID to aggregate usage for",
@@ -7892,8 +7952,8 @@ 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. `ai_provider` buckets on the provider the spend was billed against — a routed generation's serving target, or the agent's pinned provider. `model` buckets on the model id *and* the provider that served it, so one model name served by two providers is two groups (see `ai_provider_id`). `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. `orchestration_run` buckets on the orchestration run the event belongs to — a standalone generation runs no orchestration and collapses into the single `null` bucket, so the bucket count under this dimension is not a count of runs.\n",
-      "required": true,
+      "description": "Dimension to bucket by. Omit it to skip bucketing entirely: `totals` still describes the whole window and `groups` is an empty page, which is what \"what did this one thing cost\" wants. A value naming no dimension is a `400`. `day` buckets on the event's UTC calendar day; the others bucket on the matching column. `ai_provider` buckets on the provider the spend was billed against — a routed generation's serving target, or the agent's pinned provider. `model` buckets on the model id *and* the provider that served it, so one model name served by two providers is two groups (see `ai_provider_id`). `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. `orchestration_run` buckets on the orchestration run the event belongs to — a standalone generation runs no orchestration and collapses into the single `null` bucket, so the bucket count under this dimension is not a count of runs.\n",
+      "required": false,
       "type": "string",
       "in": "query"
     }, {
@@ -7920,6 +7980,78 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "session_id",
+      "description": "Narrow the whole rollup — every bucket, `totals` and `totals.distinct` alike — to one session's traffic. Combines with `group_by`: `group_by=day&session_id=…` is a conversation's spend per day, `group_by=model` is the same spend split by model. An id naming no session in this project yields an empty rollup, never the project total.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "actor_id",
+      "description": "The same narrowing, for one end user across every session they appear in. This is the figure behind a `scope: actor`, `metric: cost_usd` quota — what that actor has spent, against the cap it is held to.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "agent_id",
+      "description": "Narrow to one agent's traffic, across every session, run and trigger that dispatched it.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "ai_provider_id",
+      "description": "Narrow to the spend billed against one provider record — a routed generation's serving target, or the agent's pinned provider.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "orchestration_run_id",
+      "description": "Narrow to the events one orchestration run metered.",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "orchestration_id",
+      "description": "Narrow to the runs of one orchestration — the runs it started itself, never the subtree a `loop` or `sub_orchestration` node started under it, which is metered against the child orchestration where it was incurred. Additive: summed across a project's orchestrations the figures reach the project total exactly once. For the subtree figure of a single invocation, read `usage` on the run.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "generation_id",
+      "description": "Narrow to one generation's events. A generation writes more than one when it meters several dimensions (tokens and compute).\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "trace_id",
+      "description": "Narrow to the events recorded under one trace.",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "model",
+      "description": "Narrow to one model, matched against the as-billed SKU the event recorded. A value naming no model yields an empty rollup, not an error. Under `group_by=model` this is a single-bucket rollup; under any other dimension it is that model's spend split by the dimension.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "source",
+      "description": "Narrow by what the spend was incurred for — `eval` and `eval_judge` are verification spend. Ordinary traffic carries no source, so it cannot be selected by this filter; omit the filter for everything.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "trigger_id",
+      "description": "Narrow to the spend one trigger initiated. Matched as recorded rather than resolved, so it still selects the spend of a trigger that has since been deleted.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "action_id",
+      "description": "Narrow to one caller-supplied action label, for per-action spend. Matched as recorded, like `trigger_id`.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of `groups` entries to return. Clamped to 100. Does not affect `totals` or `groups.total`, which describe the whole window.\n",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "CLI for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",
@@ -22,7 +22,7 @@
   "dependencies": {
     "@inquirer/input": "^5.1.2",
     "@inquirer/password": "^5.1.1",
-    "@soat/sdk": "0.45.0",
+    "@soat/sdk": "0.46.0",
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1"