@soat/sdk 0.44.0 → 0.46.0

package/dist/index.mjs

@@ -1068,7 +1068,11 @@ var ApiKeys = class {
 	/**
 	* List API keys
 	*
-	* 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.
+	* 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.
 	*
 	*/
 	static listApiKeys(options) {
@@ -2880,7 +2884,8 @@ var Orchestrations = class {
 	/**
 	* Get orchestration queue stats
 	*
-	* 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`.
+	* 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.
 	*
 	*/
 	static getQueueStats(options) {
@@ -3410,7 +3415,7 @@ var Sessions = class {
 	/**
 	* Get a session
 	*
-	* Returns details of a single session.
+	* 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.
 	*/
 	static getSession(options) {
 		return (options.client ?? client).get({
@@ -3746,6 +3751,7 @@ var Tools = class {
 	* 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.
 	*
 	*/
 	static callTool(options) {
@@ -3863,7 +3869,8 @@ var Triggers = class {
 	/**
 	* Update a trigger
 	*
-	* Updates an existing trigger's configuration. The type is immutable.
+	* 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.
+	*
 	*/
 	static updateTrigger(options) {
 		return (options.client ?? client).patch({
@@ -3939,7 +3946,9 @@ var Usage = class {
 	/**
 	* List usage events
 	*
-	* 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.
+	* 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.
 	*
 	*/
 	static listUsageEvents(options) {
@@ -3951,9 +3960,11 @@ var Usage = class {
 	/**
 	* Get aggregated usage for a project
 	*
-	* 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.
+	* 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.
+	* `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.
 	*
 	*/
 	static getUsageAggregate(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/sdk",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "TypeScript SDK for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",