@soat/cli 0.44.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.44.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",
@@ -1695,7 +1701,7 @@ var routes = {
   "list-api-keys": {
     serviceClass: "APIKeys",
     operationId: "listApiKeys",
-    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns only API keys scoped to that project.",
+    description: "Lists API keys accessible to the caller. - JWT admin: returns all API keys. - JWT regular user: returns only the user's own API keys. - Project-scoped credential (API key or OAuth token): returns the caller's own keys scoped to that project, or every key scoped to it when the credential holds `api-keys:ListApiKeys` on the project. Confinement to a project is not authority over it, and a key's metadata names its owner, prefix and attached policies.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/api-keys",
     httpMethod: "get",
     pathParams: [],
@@ -1926,7 +1932,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "arguments",
-      "description": "Edited arguments to execute instead of the proposed ones",
+      "description": "Edited arguments to execute instead of the proposed ones. Editing composes a new call, so it additionally requires permission to make that call: `tools:CallTool` on the tool, and for a `builtin` proposal the action's own IAM action.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -3006,7 +3012,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "inputs",
-      "description": "Batch of texts to embed.",
+      "description": "Batch of texts to embed. At most 256 per request — each input is one call to the embedding model, so a larger batch is refused (`VALIDATION_FAILED`) rather than queued. Split it across requests.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -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",
@@ -4712,7 +4742,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "content_type_glob",
-      "description": "MIME type glob matched against a file's content_type",
+      "description": "MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters — a MIME glob needs one on each side of the slash at most.",
       "required": true,
       "type": "string",
       "in": "body"
@@ -4810,7 +4840,7 @@ var routes = {
       "in": "path"
     }, {
       "name": "content_type_glob",
-      "description": "",
+      "description": "MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters.",
       "required": false,
       "type": "string",
       "in": "body"
@@ -4920,7 +4950,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "limit",
-      "description": "Maximum number of results to return (default 10)",
+      "description": "Maximum number of results to return (default 10). A value above 100 is clamped to 100 — the ceiling bounds the vector scan this one request performs, so a larger `limit` returns everything there is up to that many rows rather than being refused.",
       "required": false,
       "type": "integer",
       "in": "body"
@@ -5499,7 +5529,7 @@ var routes = {
   "get-queue-stats": {
     serviceClass: "Orchestrations",
     operationId: "getQueueStats",
-    description: "Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. A project-scoped caller sees only their own projects under `per_project`.",
+    description: "Returns a point-in-time snapshot of the orchestration run queue: how many tasks are waiting to be claimed (`queue_depth`), how many are currently claimed with a valid lease (`claimed_tasks`), the age of the oldest waiting task, recent claim-latency percentiles over a rolling in-process window, and a per-project breakdown. Intended for admin/operator policies; guarded by `orchestrations:GetQueueStats`. Every figure is scoped to what the caller may see. A project-scoped caller gets `per_project` for their own projects only, `queue_depth` and `claimed_tasks` summed over those same projects, and `null` for `oldest_queued_age_seconds` and the `claim_latency_ms` percentiles — both describe the whole deployment and cannot be narrowed, so they are withheld rather than approximated. An unrestricted caller (the action granted on every project) gets the deployment-wide figures.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/orchestrations",
     httpMethod: "get",
     pathParams: [],
@@ -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"],
@@ -7176,13 +7212,13 @@ 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\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\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\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\nA credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{\"no_echo\": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.\n\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\n",
       "required": false,
       "type": "object",
       "in": "body"
     }, {
       "name": "mcp",
-      "description": "MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.",
+      "description": "MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -7286,13 +7322,13 @@ 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\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\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\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\nA credential written as a **literal** is stored and still sent on every call, but it is masked on every read: `secret_access_key`, `session_token` and `credentials` under `auth`, and any credential-named `headers` value (`Authorization`, `Cookie`, or a name containing `api-key`/`token`/`secret`/`password`), come back as `{\"no_echo\": true}`. The mask is an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a `{{secret:...}}` reference is the wiring, not the credential, and stays readable.\n\n`headers` values additionally accept `{{context:<key>}}` references, resolved per call from the caller's `tool_context`, so a per-user credential can be placed in the real header the target expects (`Authorization: Bearer {{context:ocaToken}}`) instead of only in an `X-Soat-Context-<key>` header. Valid **only** inside `headers` — a context value is caller-supplied, so it may not steer the `url` — and a key missing from the `tool_context` at call time fails the tool call with `MISSING_TOOL_CONTEXT_KEY` rather than sending an empty credential. See the Tool Context reference.\n",
       "required": false,
       "type": "object",
       "in": "body"
     }, {
       "name": "mcp",
-      "description": "MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only.",
+      "description": "MCP server config (`url`, `headers`). `headers` values accept `{{secret:...}}` and `{{context:<key>}}` references, resolved right before the outbound MCP request; `url` accepts `{{secret:...}}` only. A literal credential in `headers` is masked on read, exactly as in `execute`.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -7359,7 +7395,7 @@ var routes = {
   "call-tool": {
     serviceClass: "Tools",
     operationId: "callTool",
-    description: "Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input. For `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` (\"not available on this tool\") before any outbound request is made. `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.",
+    description: "Directly invokes a tool and returns its output. Supported for `http`, `builtin`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input. For `builtin` and `mcp` tools the `action` field is required and identifies which action (SOAT) or tool name (MCP) to invoke. For `http` tools `action` is ignored. When a `builtin` or `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` (\"not available on this tool\") before any outbound request is made. `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent. Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with `422 TOOL_DISPATCH_FAILED`, whose `meta` carries the `tool_id` and the `outcome`. A `pipeline` tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/tools",
     httpMethod: "post",
     pathParams: ["tool_id"],
@@ -7613,7 +7649,7 @@ var routes = {
   "update-trigger": {
     serviceClass: "Triggers",
     operationId: "updateTrigger",
-    description: "Updates an existing trigger's configuration. The type is immutable.",
+    description: "Updates an existing trigger's configuration. The type is immutable. Changing `target_type` or `target_id` re-checks the target-start action (`orchestrations:StartRun`, `agents:CreateAgentGeneration` or `tools:CallTool`) against the resulting target, because a firing runs with the trigger creator's authority rather than the updater's. A caller who could not start the new target is answered `403` and the trigger keeps the target it had.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/triggers",
     httpMethod: "patch",
     pathParams: ["trigger_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.44.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.44.0",
+    "@soat/sdk": "0.46.0",
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1"