@soat/cli 0.45.0 → 0.47.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.47.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", "tags", "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",
@@ -512,6 +518,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of results to return",
@@ -634,7 +646,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "",
+      "description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -1284,7 +1296,7 @@ var routes = {
       "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.",
+      "description": "Per-generation knowledge retrieval override. Array filters (memory_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, limit) use the per-generation value when present.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -2295,7 +2307,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/conversations",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["project_id", "actor_id", "limit", "offset"],
+    queryParams: ["project_id", "actor_id", "tags", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Project ID (optional)",
@@ -2308,6 +2320,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of results to return",
@@ -2613,7 +2631,7 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["project_id", "path_prefix", "limit", "offset"],
+    queryParams: ["project_id", "path_prefix", "tags", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Project ID (optional)",
@@ -2626,6 +2644,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of results to return",
@@ -2686,7 +2710,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Key-value tags",
+      "description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -2744,7 +2768,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Key-value tags to attach to the document.",
+      "description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -2824,7 +2848,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Key-value tags",
+      "description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -3697,13 +3721,19 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/files",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["project_id", "limit", "offset"],
+    queryParams: ["project_id", "tags", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Filter files by project ID",
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of results to return",
@@ -3933,13 +3963,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 +4019,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 +4307,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 +4320,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",
@@ -4895,7 +4949,7 @@ var routes = {
   "search-knowledge": {
     serviceClass: "Knowledge",
     operationId: "searchKnowledge",
-    description: "Searches across documents and memory entries using semantic search, file paths, document IDs, or memory IDs/tags. At least one of `query`, `document_paths`, `document_ids`, `memory_ids`, or `memory_tags` must be provided.",
+    description: "Searches across documents and memory entries using semantic search, file paths, document IDs, memory IDs, or tags. At least one of `query`, `tags`, `document_paths`, `document_ids`, or `memory_ids` must be provided.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/knowledge",
     httpMethod: "post",
     pathParams: [],
@@ -4930,12 +4984,6 @@ var routes = {
       "required": false,
       "type": "array",
       "in": "body"
-    }, {
-      "name": "memory_tags",
-      "description": "Search entries in memories whose tags match any of these patterns (glob supported)",
-      "required": false,
-      "type": "array",
-      "in": "body"
     }, {
       "name": "document_paths",
       "description": "Filter results to documents whose file path starts with one of these prefixes",
@@ -4948,6 +4996,12 @@ var routes = {
       "required": false,
       "type": "array",
       "in": "body"
+    }, {
+      "name": "tags",
+      "description": "Filter results to documents and memory entries whose `tags` contain every one of these key-value pairs (exact, case-sensitive match). The only filter that scopes both stores, so passing it alone searches both. For memory it matches at entry granularity: an entry is returned when its parent memory's tags match or its own do.",
+      "required": false,
+      "type": "object",
+      "in": "body"
     }]
   },
   "list-memories": {
@@ -4966,7 +5020,7 @@ var routes = {
       "in": "query"
     }, {
       "name": "tags",
-      "description": "Filter memories by tag patterns. Supports glob syntax (`*` matches any substring, `?` matches any single character). Multiple values are ORed — a memory is returned if any of its tags match any of the provided patterns. Omit to return all memories.\n",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
       "required": false,
       "type": "array",
       "in": "query"
@@ -5012,9 +5066,9 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Optional list of tags for filtering in knowledge search",
+      "description": "Optional key-value tags. Scopes the memory in knowledge search, where every requested pair must match exactly.",
       "required": false,
-      "type": "array",
+      "type": "object",
       "in": "body"
     }]
   },
@@ -5062,9 +5116,9 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Optional list of tags for filtering in knowledge search",
+      "description": "Optional key-value tags. Replaces the stored bag; `null` clears it.",
       "required": false,
-      "type": "array",
+      "type": "object",
       "in": "body"
     }]
   },
@@ -5084,6 +5138,54 @@ var routes = {
       "in": "path"
     }]
   },
+  "get-memory-tags": {
+    serviceClass: "Memories",
+    operationId: "getMemoryTags",
+    description: "Returns all tags attached to the memory",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
+    httpMethod: "get",
+    pathParams: ["memory_id"],
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "Memory ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "replace-memory-tags": {
+    serviceClass: "Memories",
+    operationId: "replaceMemoryTags",
+    description: "Replaces all tags on the memory with the provided tags (not merged)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
+    httpMethod: "put",
+    pathParams: ["memory_id"],
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "Memory ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "merge-memory-tags": {
+    serviceClass: "Memories",
+    operationId: "mergeMemoryTags",
+    description: "Merges provided tags with existing tags (existing tags are preserved unless overridden)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
+    httpMethod: "patch",
+    pathParams: ["memory_id"],
+    queryParams: [],
+    flags: [{
+      "name": "memory_id",
+      "description": "Memory ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-memory-entries": {
     serviceClass: "MemoryEntries",
     operationId: "listMemoryEntries",
@@ -5091,13 +5193,19 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-entries",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["memory_id", "limit", "offset", "include_invalidated"],
+    queryParams: ["memory_id", "tags", "limit", "offset", "include_invalidated"],
     flags: [{
       "name": "memory_id",
       "description": "Memory container to list entries from (mem_...)",
       "required": true,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "Maximum number of results to return",
@@ -5146,9 +5254,9 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Per-entry tag strings, used for entry-granularity filtering in search-knowledge (memory_tags)",
+      "description": "Per-entry key-value tags, used for entry-granularity filtering by `tags` in search-knowledge.",
       "required": false,
-      "type": "array",
+      "type": "object",
       "in": "body"
     }, {
       "name": "metadata",
@@ -5202,9 +5310,9 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Replaces the entry's tags. Pass null or an empty array to clear.",
+      "description": "Replaces the entry's tags. Pass null or an empty object to clear.",
       "required": false,
-      "type": "array",
+      "type": "object",
       "in": "body"
     }, {
       "name": "metadata",
@@ -5230,6 +5338,54 @@ var routes = {
       "in": "path"
     }]
   },
+  "get-memory-entry-tags": {
+    serviceClass: "MemoryEntries",
+    operationId: "getMemoryEntryTags",
+    description: "Returns all tags attached to the memory entry",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-entries",
+    httpMethod: "get",
+    pathParams: ["entry_id"],
+    queryParams: [],
+    flags: [{
+      "name": "entry_id",
+      "description": "Memory entry ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "replace-memory-entry-tags": {
+    serviceClass: "MemoryEntries",
+    operationId: "replaceMemoryEntryTags",
+    description: "Replaces all tags on the memory entry with the provided tags (not merged)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-entries",
+    httpMethod: "put",
+    pathParams: ["entry_id"],
+    queryParams: [],
+    flags: [{
+      "name": "entry_id",
+      "description": "Memory entry ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "merge-memory-entry-tags": {
+    serviceClass: "MemoryEntries",
+    operationId: "mergeMemoryEntryTags",
+    description: "Merges provided tags with existing tags (existing tags are preserved unless overridden)",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-entries",
+    httpMethod: "patch",
+    pathParams: ["entry_id"],
+    queryParams: [],
+    flags: [{
+      "name": "entry_id",
+      "description": "Memory entry ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-model-routes": {
     serviceClass: "ModelRoutes",
     operationId: "listModelRoutes",
@@ -6429,13 +6585,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": {
@@ -6445,8 +6607,14 @@ var routes = {
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/sessions",
     httpMethod: "get",
     pathParams: [],
-    queryParams: ["agent_id", "actor_id", "status", "limit", "offset"],
+    queryParams: ["project_id", "agent_id", "actor_id", "status", "tags", "limit", "offset"],
     flags: [{
+      "name": "project_id",
+      "description": "Filter by project public ID. Required for `soat:ResourceTag` policy conditions to narrow the listing: a policy is read per project, so without it the listing is scoped to the projects the caller can access and nothing further.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
       "name": "agent_id",
       "description": "Filter by agent public ID",
       "required": false,
@@ -6464,6 +6632,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "tags",
+      "description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
+      "required": false,
+      "type": "array",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "",
@@ -6533,7 +6707,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"],
@@ -6750,7 +6924,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Optional tags for the forked session",
+      "description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM `soat:ResourceTag/<key>` condition.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -7803,11 +7977,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 +8012,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 +8077,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 +8090,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 +8118,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.47.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.47.0",
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1"