@kindgi/client 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -1328,6 +1328,14 @@ export interface ConversationHitlPolicy {
 	 * (see `resolveEffectiveHitlPolicy`).
 	 */
 	readonly timeoutMs?: number;
+	/**
+	 * What happens when an approval's time runs out: it escalates one
+	 * reviewer tier, and at `admin` it expires (the turn fails with
+	 * `hitl-cancelled`). `'escalate'` is the only behavior today, and the
+	 * default; `'auto-approve'` and `'auto-reject'` are refused rather than
+	 * accepted and ignored.
+	 */
+	readonly onTimeout?: "escalate";
 }
 /**
  * Budgets guard a single agent turn. Every field is optional; unset
@@ -1711,18 +1719,6 @@ export interface DefineAgentSpec {
 	/** Free-form tags for catalog filtering. Not interpreted by the runtime. */
 	readonly tags?: readonly string[];
 }
-export type Scope = {
-	readonly kind: "tenant";
-	readonly tenantId: TenantId;
-} | {
-	readonly kind: "org";
-	readonly tenantId: TenantId;
-	readonly orgId: OrgId;
-} | {
-	readonly kind: "project";
-	readonly tenantId: TenantId;
-	readonly projectId: ProjectId;
-};
 export type GuardrailSeverity = "info" | "warn" | "error" | "critical";
 /**
  * Actions the engine surfaces when a check fails. Open string — the
@@ -1856,6 +1852,43 @@ export interface TurnFailedEvent {
 	readonly errorCode: string;
 	readonly message: string;
 }
+/**
+ * Wire-body serialization for `Scope` values.
+ *
+ * The `Scope` type from `@kindgi/platform` carries `tenantId` because
+ * server-internal code (routes, bindings, storage adapters) needs it
+ * everywhere the tuple flows. On the HTTP wire body, however, tenantId
+ * is redundant: every route derives it authoritatively from the bearer
+ * and any mismatched value is rejected as
+ * `scope-mismatch 400`.
+ *
+ * Client callers rarely know their session tenantId ahead of time, and
+ * a placeholder value would trip the mismatch check.
+ * `scopeForBody(scope)` strips tenantId at the SDK boundary so request
+ * bodies carry only the fields the server actually reads off the wire
+ * (`kind` + `orgId`/`projectId`).
+ *
+ * Use this ONLY for request bodies. Query-string helpers (`scopeToQuery`)
+ * already omit tenantId by construction and don't need this shim.
+ */
+/**
+ * A scope, as the client takes it: the kind and its id. `tenantId` is
+ * optional. The API derives the tenant from the bearer token, so the
+ * client never sends it, and an app needn't know it. `@kindgi/platform`'s
+ * `Scope`, which carries one, fits here as well.
+ */
+export type ScopeRef = {
+	readonly kind: "tenant";
+	readonly tenantId?: string;
+} | {
+	readonly kind: "org";
+	readonly orgId: string;
+	readonly tenantId?: string;
+} | {
+	readonly kind: "project";
+	readonly projectId: string;
+	readonly tenantId?: string;
+};
 /** @unwired SDK-defined id for a schedule. */
 export type ScheduleId = Brand<string, "ScheduleId">;
 /** @unwired SDK-defined id for a model provider. */
@@ -2323,6 +2356,25 @@ export interface Approval {
 	readonly updatedAt: Timestamp;
 	readonly decidedAt?: Timestamp;
 	readonly expiresAt?: Timestamp;
+	/**
+	 * The reviewer's decision, once one is recorded. Absent while the
+	 * approval is open, and when it ended without one (it expired, or a
+	 * timeout escalated it).
+	 */
+	readonly decision?: ApprovalDecisionRecord;
+}
+/**
+ * Wire shape — matches `@kindgi/api/openapi.json#ApprovalDecisionRecord`.
+ * An approval's recorded decision: what the reviewer decided, why, and who.
+ */
+export interface ApprovalDecisionRecord {
+	readonly decision: ApprovalDecision;
+	/** Who decided, as an actor: `user:<userId>`, the reviewer's user (the Kindgi runtime always records it). */
+	readonly decidedBy?: string;
+	readonly reviewerId: ReviewerId;
+	readonly reviewerRoleAtDecision: ReviewerRole$1;
+	readonly decidedAt: Timestamp;
+	readonly rationale?: string;
 }
 /**
  * Wire shape — matches `@kindgi/api/openapi.json#ReviewDecision`. Decision row
@@ -2595,6 +2647,12 @@ export interface Conversation {
 	readonly agentVersion: string;
 	readonly title: string;
 	readonly participantId?: string;
+	/**
+	 * The project the conversation is in: the project of the run that
+	 * opened it, or `projectId` on open (the tenant's Default project when
+	 * omitted). Absent on conversations from before 0.1.3.
+	 */
+	readonly projectId?: string;
 	/** Structural scope (project id, matter id, etc.). */
 	readonly scope: Readonly<Record<string, unknown>>;
 	readonly status: ConversationStatus;
@@ -2612,6 +2670,11 @@ export interface Conversation {
 export interface OpenConversationInput {
 	readonly agentId: AgentId;
 	readonly agentVersion: string;
+	/**
+	 * Put the conversation in a project (one of the tenant's): lists filter
+	 * by it. Omitted: the tenant's Default project, as for a run.
+	 */
+	readonly projectId?: string;
 	readonly scope?: Readonly<Record<string, unknown>>;
 	readonly participantId?: string;
 	readonly title?: string;
@@ -2782,6 +2845,17 @@ export interface ProvenanceRecord {
 		readonly value: string;
 		readonly signedAt: Timestamp;
 	};
+	/**
+	 * Each model call's usage from the cost ledger, by the `callId` in its
+	 * `model-call` node's attributes. Joined when read: not part of the
+	 * signed DAG.
+	 */
+	readonly callUsage?: Readonly<Record<string, {
+		readonly usage: ModelCallTokens;
+		readonly costUsd?: number;
+		readonly durationMs?: number;
+		readonly servedModel?: string;
+	}>>;
 }
 /**
  * Wire shape for records surfaced by `GET /v1/provenance` (list). The
@@ -2799,6 +2873,8 @@ export interface ProvenanceRecordMetadata {
 		readonly version: string;
 	};
 	readonly signed: boolean;
+	/** The project of the record's run; absent on records from before 0.1.3. */
+	readonly projectId?: string;
 }
 /**
  * Wire shape of a signed export bundle envelope — matches
@@ -2818,6 +2894,8 @@ export interface ExportedProvenance {
 	readonly exportedAt: Timestamp;
 }
 export interface ProvenanceQueryFilter extends Filter {
+	/** Only one project's records (`kind: 'project'`), or every project's in an org (`kind: 'org'`). */
+	readonly scope?: ScopeRef;
 	readonly runId?: RunId;
 	readonly agentId?: AgentId;
 	/** ISO 8601 timestamp — server filters `createdAt > createdAfter`. */
@@ -2879,6 +2957,69 @@ export interface CostRecord {
 	readonly occurredAt: Timestamp;
 	readonly metrics?: Readonly<Record<string, unknown>>;
 	readonly attributes?: Readonly<Record<string, unknown>>;
+	/** The call's id; its provenance `model-call` node carries it too. */
+	readonly callId?: string;
+	readonly projectId?: ProjectId;
+	/** The root of the record's run tree (a flow run, for its agent turns). */
+	readonly rootRunId?: RunId;
+	readonly parentRunId?: RunId;
+	readonly agentVersion?: string;
+	/** The flow of the run tree's root. */
+	readonly flowId?: string;
+	/** The step that made the call, and the turn's step number. */
+	readonly nodeId?: string;
+	readonly step?: number;
+	/** What the call was for, beyond the turn's own model step (`guardrail-judge:<id>`). */
+	readonly purpose?: string;
+	/** The model actually called. */
+	readonly model?: string;
+	/** The exact model version the vendor reported. */
+	readonly servedModel?: string;
+	/** The router picked a fallback provider for the turn. */
+	readonly fallback?: boolean;
+	/** `ok`: the provider answered. `failed`: the call threw. */
+	readonly status?: "ok" | "failed";
+	readonly usage?: ModelCallTokens;
+	readonly durationMs?: number;
+	readonly finishReason?: string;
+	/** The vendor's id for the request. */
+	readonly providerRequestId?: string;
+	/** HTTP attempts the call took, the client's retries included. */
+	readonly attempts?: number;
+	readonly error?: {
+		readonly message: string;
+	};
+	/** The vendor's own usage object, as it reported it (only with `includeRawUsage`). */
+	readonly rawUsage?: {
+		readonly provider: string;
+		readonly model: string;
+		readonly usage: Readonly<Record<string, unknown>>;
+	};
+}
+/**
+ * A model call's tokens. `promptTokens` / `completionTokens` are the
+ * totals; `cacheReadTokens` / `cacheWriteTokens` are parts of
+ * `promptTokens`, `reasoningTokens` of `completionTokens`, present when
+ * the provider reports them.
+ */
+export interface ModelCallTokens {
+	readonly promptTokens: number;
+	readonly completionTokens: number;
+	readonly cacheReadTokens?: number;
+	readonly cacheWriteTokens?: number;
+	readonly reasoningTokens?: number;
+}
+/**
+ * Token sums of an aggregate. `prompt` / `completion` are the totals;
+ * `cacheRead` / `cacheWrite` are parts of `prompt`, `reasoning` of
+ * `completion` (`0` where providers didn't report them).
+ */
+export interface CostTokenTotals {
+	readonly prompt: number;
+	readonly completion: number;
+	readonly cacheRead: number;
+	readonly cacheWrite: number;
+	readonly reasoning: number;
 }
 /** @deprecated Renamed to `CostRecord` to match the wire. */
 export type UsageRecord = CostRecord;
@@ -2888,12 +3029,25 @@ export type UsageRecord = CostRecord;
  */
 export interface CostRecordFilter extends Filter {
 	readonly runId?: RunId;
+	/** With `runId`: also every run it started, at any depth. */
+	readonly includeDescendants?: boolean;
+	/** Every record of the run tree whose root is this run. */
+	readonly rootRunId?: RunId;
 	readonly agentId?: AgentId;
 	readonly conversationId?: ThreadId;
 	readonly category?: string;
 	readonly providerId?: ProviderId;
+	/** The model actually called. */
+	readonly model?: string;
+	/** The exact model version the vendor reported. */
+	readonly servedModel?: string;
+	/** Records in this scope: a project, or every project of an org. */
+	readonly scope?: ScopeRef;
 	readonly from?: Timestamp;
+	/** Exclusive. */
 	readonly to?: Timestamp;
+	/** Add each model call's `rawUsage`: the vendor's own usage object. */
+	readonly includeRawUsage?: boolean;
 }
 /** @deprecated Renamed to `CostRecordFilter` to match the wire. */
 export type UsageQueryFilter = CostRecordFilter;
@@ -2901,7 +3055,7 @@ export type UsageQueryFilter = CostRecordFilter;
  * Wire enum of dimensions callers can pass to `cost.aggregate` — matches
  * `@kindgi/api/openapi.json#CostGroupDimension`.
  */
-export type CostGroupDimension = "agentId" | "runId" | "category" | "providerId" | "day" | "month" | "tenant" | "conversationId";
+export type CostGroupDimension = "agentId" | "runId" | "category" | "providerId" | "day" | "month" | "tenant" | "conversationId" | "model" | "servedModel" | "projectId" | "orgId" | "rootRunId" | "flowId";
 /**
  * Wire shape for one aggregated bucket — matches
  * `@kindgi/api/openapi.json#CostAggregateGroup`.
@@ -2914,6 +3068,7 @@ export interface CostAggregateGroup {
 	readonly key: Readonly<Record<string, string | null>>;
 	readonly count: number;
 	readonly totalUsd: number;
+	readonly tokens: CostTokenTotals;
 }
 /**
  * Wire shape for `GET /v1/cost/aggregate` response — matches
@@ -2923,6 +3078,7 @@ export interface CostAggregateResult {
 	readonly groups: readonly CostAggregateGroup[];
 	readonly totalUsd: number;
 	readonly totalRecords: number;
+	readonly tokens: CostTokenTotals;
 	readonly timeRange: {
 		readonly from: Timestamp;
 		readonly to: Timestamp;
@@ -3374,7 +3530,7 @@ export interface RegisterMcpEndpointInput {
 	 */
 	readonly secretRef?: McpEndpointSecretRef;
 	/** The scope the endpoint is registered in; authorization checks it. */
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 }
 /**
  * @unwired SDK-defined event shapes; the API has no event emission or
@@ -3800,6 +3956,20 @@ declare namespace Schemas {
 	export type HealthResult = {
 		ok: true;
 	};
+	/**
+	 * Set on an agent's turn (an agent run, or the turn a flow's agent step started): the agent, the version that ran and the conversation. Absent on other runs, and on turns that ran before Kindgi 0.1.3.
+	 */
+	export type RunAgent = {
+		/**
+		 * The agent id.
+		 */
+		id: string;
+		/**
+		 * The agent version that ran (semver).
+		 */
+		version: string;
+		conversationId: string;
+	};
 	export type Run = {
 		/**
 		 * RunId.
@@ -3830,6 +4000,7 @@ declare namespace Schemas {
 		 * Set on a child run: the node in the parent run that started it.
 		 */
 		parentNodeId?: string;
+		agent?: RunAgent;
 		/**
 		 * Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.
 		 */
@@ -3938,6 +4109,7 @@ declare namespace Schemas {
 			 * Set on a child run: the node in the parent run that started it.
 			 */
 			parentNodeId?: string;
+			agent?: RunAgent;
 			/**
 			 * Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.
 			 */
@@ -4175,6 +4347,20 @@ declare namespace Schemas {
 	 */
 	export type ReviewerRole = "standard" | "senior" | "admin";
 	export type ApprovalStatus = "pending" | "assigned" | "in_review" | "approved" | "rejected" | "escalated" | "expired" | "withdrawn";
+	export type ApprovalDecisionRecord = {
+		decision: "approve" | "reject" | "escalate" | "withdraw";
+		/**
+		 * Who decided, as an actor: `user:<userId>`, the reviewer's user. The run's journal and provenance name the decider the same way. The Kindgi runtime always records it; a deployment whose HITL binding doesn't leaves it out.
+		 */
+		decidedBy?: string;
+		reviewerId: string;
+		/**
+		 * Reviewer role class. Hierarchy: standard < senior < admin.
+		 */
+		reviewerRoleAtDecision: "standard" | "senior" | "admin";
+		decidedAt: string;
+		rationale?: string;
+	};
 	export type Approval = {
 		id: string;
 		tenantId: string;
@@ -4200,6 +4386,7 @@ declare namespace Schemas {
 		updatedAt: string;
 		decidedAt?: string;
 		expiresAt?: string;
+		decision?: ApprovalDecisionRecord;
 	};
 	export type ReviewDecision = {
 		id: string;
@@ -4225,7 +4412,7 @@ declare namespace Schemas {
 		decision: "approve" | "reject" | "escalate" | "withdraw";
 		rationale?: string;
 		/**
-		 * Payload passed to the run waitpoint (`RunBinding.completeToken`) when the approval is linked to a suspended run and the decision is `approve` or `reject`.
+		 * Payload passed to the run waitpoint (`RunBinding.completeToken`) when the approval is linked to a suspended run and the decision is `approve` or `reject`. Refused (400 `bad-input`) for an agent's tool-call or session gate (`tool-call:pending`, `agent-turn:session-hitl-gate`): those resume on the decision alone.
 		 */
 		value?: unknown;
 	};
@@ -4925,6 +5112,10 @@ declare namespace Schemas {
 		agentVersion: string;
 		title: string;
 		participantId?: string;
+		/**
+		 * The project the conversation is in: the project of the run that opened it, or `projectId` on open (the tenant's Default project when omitted). Absent on conversations from before Kindgi 0.1.3; those are listed only without a scope.
+		 */
+		projectId?: string;
 		/**
 		 * Free-form scope object (currently `{ tenantId }` in tests; enterprises extend with `matterId`, `engagementId`, etc.).
 		 */
@@ -4969,6 +5160,10 @@ declare namespace Schemas {
 		 * Optional. Defaults to `"Untitled conversation"` when omitted.
 		 */
 		title?: string;
+		/**
+		 * The project the conversation is in; `GET /v1/conversations?scopeKind=project&scopeId=…` lists it. A project of the caller's tenant, else `400 bad-input`. Omitted: the tenant's Default project, as for a run.
+		 */
+		projectId?: string;
 		/**
 		 * Structural scope (project id, matter id, etc.). Treated opaquely by the runtime.
 		 */
@@ -5263,6 +5458,20 @@ declare namespace Schemas {
 		 */
 		signed: boolean;
 		createdAt: string;
+		/**
+		 * The project of the record's run. Absent on records from before Kindgi 0.1.3; those are listed only without a scope.
+		 */
+		projectId?: string;
+	};
+	/**
+	 * The call's tokens. `promptTokens` / `completionTokens` are the totals; `cacheReadTokens` / `cacheWriteTokens` are parts of `promptTokens`, `reasoningTokens` of `completionTokens`, present when the provider reports them.
+	 */
+	export type ModelCallTokens = {
+		promptTokens: number;
+		completionTokens: number;
+		cacheReadTokens?: number;
+		cacheWriteTokens?: number;
+		reasoningTokens?: number;
 	};
 	/**
 	 * Full provenance record including the DAG payload.
@@ -5307,6 +5516,15 @@ declare namespace Schemas {
 			signedAt: string;
 		};
 		createdAt: string;
+		/**
+		 * Each model call's usage from the cost ledger, by the `callId` in its `model-call` node's attributes. Joined when read: not part of the signed DAG. A signed export includes it, as it stood when signed.
+		 */
+		callUsage?: Record<string, {
+			usage: ModelCallTokens;
+			costUsd?: number;
+			durationMs?: number;
+			servedModel?: string;
+		}>;
 	};
 	export type ProvenanceCollectionPage = {
 		data: Array<ProvenanceRecordMetadata>;
@@ -5324,7 +5542,7 @@ declare namespace Schemas {
 		includeMessages?: boolean;
 	};
 	/**
-	 * Signed exportable bundle. `bundle` is base64 of the exact bytes that were signed (sorted-key canonical JSON, no whitespace); verifiers can pass those bytes directly to `verifyEd25519`. The bundle body itself includes `bundleSchemaVersion`, `runId`, `tenantId`, `dag: { nodes, edges }`, `messages?` (if requested), etc. See `canonicalization` for the deterministic serialization algorithm.
+	 * Signed exportable bundle. `bundle` is base64 of the exact bytes that were signed (sorted-key canonical JSON, no whitespace); verifiers can pass those bytes directly to `verifyEd25519`. The bundle body itself includes `bundleSchemaVersion`, `runId`, `tenantId`, `dag: { nodes, edges }`, `messages?` (if requested), `callUsage?` (the usage of the model calls, from the cost ledger), etc. See `canonicalization` for the deterministic serialization algorithm.
 	 */
 	export type ExportProvenanceResult = {
 		runId: string;
@@ -5333,7 +5551,7 @@ declare namespace Schemas {
 		 */
 		bundle: string;
 		/**
-		 * Semver for the shape of the bundle body. Currently `1.0.0`.
+		 * Semver for the shape of the bundle body. Currently `1.1.0`, which adds `callUsage`: each model call's usage from the cost ledger, by call id, as it stood when signed.
 		 */
 		bundleSchemaVersion: string;
 		algorithm: "ed25519";
@@ -5719,7 +5937,13 @@ declare namespace Schemas {
 	export type GetMCPPromptResult = {
 		messages: Array<MCPPromptMessage>;
 	};
-	export type CostGroupDimension = "agentId" | "runId" | "category" | "providerId" | "day" | "month" | "tenant" | "conversationId";
+	export type CostGroupDimension = "agentId" | "runId" | "category" | "providerId" | "day" | "month" | "tenant" | "conversationId" | "model" | "servedModel" | "projectId" | "orgId" | "rootRunId" | "flowId";
+	/**
+	 * Why a model call failed (`status: failed`).
+	 */
+	export type ModelCallError = {
+		message: string;
+	};
 	export type CostRecord = {
 		id: string;
 		tenantId: string;
@@ -5746,6 +5970,76 @@ declare namespace Schemas {
 		 * Free-form filter/display tags — never counters.
 		 */
 		attributes?: Record<string, unknown>;
+		/**
+		 * A model call's id (`category` `llm.inference`); its provenance `model-call` node carries it too.
+		 */
+		callId?: string;
+		projectId?: string;
+		/**
+		 * The root of the record's run tree (a flow run, for its agent turns).
+		 */
+		rootRunId?: string;
+		parentRunId?: string;
+		agentVersion?: string;
+		/**
+		 * The flow of the run tree's root.
+		 */
+		flowId?: string;
+		/**
+		 * The step that made the call.
+		 */
+		nodeId?: string;
+		/**
+		 * The turn's step number.
+		 */
+		step?: number;
+		/**
+		 * What the call was for, beyond the turn's own model step: `guardrail-judge:<guardrail id>`.
+		 */
+		purpose?: string;
+		/**
+		 * The model actually called.
+		 */
+		model?: string;
+		/**
+		 * The exact model version the vendor reported (vendors alias).
+		 */
+		servedModel?: string;
+		/**
+		 * The router picked a fallback provider for the turn.
+		 */
+		fallback?: boolean;
+		/**
+		 * `ok`: the provider answered. `failed`: the call threw.
+		 */
+		status?: "ok" | "failed";
+		usage?: ModelCallTokens;
+		durationMs?: number;
+		finishReason?: string;
+		/**
+		 * The vendor's id for the request.
+		 */
+		providerRequestId?: string;
+		/**
+		 * HTTP attempts the call took, the client's retries included.
+		 */
+		attempts?: number;
+		error?: ModelCallError;
+		/**
+		 * The vendor's own usage object, exactly as it reported it. Only with `include=rawUsage`.
+		 */
+		rawUsage?: {
+			provider: string;
+			model: string;
+			usage: Record<string, unknown>;
+		};
+	};
+	export type CostTokenTotals = {
+		prompt: number;
+		completion: number;
+		cacheRead: number;
+		cacheWrite: number;
+		reasoning: number;
 	};
 	export type CostRecordCollectionPage = {
 		data: Array<CostRecord>;
@@ -5759,11 +6053,13 @@ declare namespace Schemas {
 		key: Record<string, string | null>;
 		count: number;
 		totalUsd: number;
+		tokens: CostTokenTotals;
 	};
 	export type CostAggregateResult = {
 		groups: Array<CostAggregateGroup>;
 		totalUsd: number;
 		totalRecords: number;
+		tokens: CostTokenTotals;
 		timeRange: {
 			from: string;
 			to: string;
@@ -6082,7 +6378,7 @@ declare namespace Schemas {
 		metadata?: Record<string, unknown>;
 	};
 	/**
-	 * Introspection of the caller's current authentication context. Always carries `tenantId` and `scopes` (empty for static bearer tokens), plus `userId` when the token carries one; session-token callers additionally see `sessionId`, `providerId`, and `expiresAt`. `user` is the caller's directory record, present when the deployment wires an identity directory and it knows the `userId`. `reviewerRole` is set when the token carries a reviewer role — clients can use it to gate reviewer-only UI (the approvals surface) without a second round trip.
+	 * Introspection of the caller's current authentication context. Always carries `tenantId` and `scopes` (empty for static bearer tokens), plus `userId` when the token carries one; session-token callers additionally see `sessionId`, `providerId`, and `expiresAt`. `user` is the caller's directory record, present when the deployment wires an identity directory and it knows the `userId`. `reviewerRole` is set when the caller is a reviewer — its token carries a reviewer role, or its user is a registered reviewer — so clients can gate reviewer-only UI (the approvals surface) without a second round trip.
 	 */
 	export type WhoamiResult = {
 		tenantId: string;
@@ -6917,6 +7213,14 @@ declare namespace Schemas {
 		 */
 		unregistered: boolean;
 	};
+	/**
+	 * The model calls of the run tree (this run and every run it started) that the cost ledger had recorded when this run finished: a child run still running then isn't in it. `calls` counts failed calls too. Absent when the runtime records no usage.
+	 */
+	export type RunTreeUsage = {
+		calls: number;
+		costUsd: number;
+		tokens: CostTokenTotals;
+	};
 	/**
 	 * A finished top-level run: its identity and outcome, never its input or output. Field names match `GET /v1/runs/{runId}`.
 	 */
@@ -6936,6 +7240,7 @@ declare namespace Schemas {
 		failureMessage: string | null;
 		createdAt: string;
 		completedAt: string;
+		usage?: RunTreeUsage;
 	};
 	export type RunFinishedEvent = {
 		/**
@@ -6997,9 +7302,9 @@ export declare const RunProgress: z.ZodObject<{
 	flowVersion: z.ZodString;
 	status: z.ZodEnum<{
 		pending: "pending";
+		failed: "failed";
 		running: "running";
 		completed: "completed";
-		failed: "failed";
 		cancelled: "cancelled";
 		suspended: "suspended";
 	}>;
@@ -7444,9 +7749,9 @@ declare const ReinstateEvalSuiteVersionResult: z.ZodObject<{
 export type EvalRunStatus = Schemas.EvalRunStatus;
 declare const EvalRunStatus: z.ZodEnum<{
 	pending: "pending";
+	failed: "failed";
 	running: "running";
 	completed: "completed";
-	failed: "failed";
 	cancelled: "cancelled";
 }>;
 export type EvalRun = Schemas.EvalRun;
@@ -7473,9 +7778,9 @@ declare const EvalRun: z.ZodObject<{
 	}, z.core.$strict>>;
 	status: z.ZodEnum<{
 		pending: "pending";
+		failed: "failed";
 		running: "running";
 		completed: "completed";
-		failed: "failed";
 		cancelled: "cancelled";
 	}>;
 	dryRun: z.ZodBoolean;
@@ -7510,9 +7815,9 @@ declare const EvalRunCollectionPage: z.ZodObject<{
 		}, z.core.$strict>>;
 		status: z.ZodEnum<{
 			pending: "pending";
+			failed: "failed";
 			running: "running";
 			completed: "completed";
-			failed: "failed";
 			cancelled: "cancelled";
 		}>;
 		dryRun: z.ZodBoolean;
@@ -7848,9 +8153,9 @@ declare const ComplianceEvidence: z.ZodObject<{
 	outcome: z.ZodOptional<z.ZodEnum<{
 		succeeded: "succeeded";
 		escalated: "escalated";
+		failed: "failed";
 		allowed: "allowed";
 		denied: "denied";
-		failed: "failed";
 	}>>;
 	payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 	provenanceRef: z.ZodOptional<z.ZodObject<{
@@ -7892,9 +8197,9 @@ declare const ComplianceEvidenceCollectionPage: z.ZodObject<{
 		outcome: z.ZodOptional<z.ZodEnum<{
 			succeeded: "succeeded";
 			escalated: "escalated";
+			failed: "failed";
 			allowed: "allowed";
 			denied: "denied";
-			failed: "failed";
 		}>>;
 		payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 		provenanceRef: z.ZodOptional<z.ZodObject<{
@@ -8486,14 +8791,25 @@ declare const RunFinishedEvent: z.ZodObject<{
 			flowId: z.ZodString;
 			flowVersion: z.ZodString;
 			status: z.ZodEnum<{
-				completed: "completed";
 				failed: "failed";
+				completed: "completed";
 				cancelled: "cancelled";
 			}>;
 			dryRun: z.ZodBoolean;
 			failureMessage: z.ZodNullable<z.ZodString>;
 			createdAt: z.ZodISODateTime;
 			completedAt: z.ZodISODateTime;
+			usage: z.ZodOptional<z.ZodObject<{
+				calls: z.ZodNumber;
+				costUsd: z.ZodNumber;
+				tokens: z.ZodObject<{
+					prompt: z.ZodNumber;
+					completion: z.ZodNumber;
+					cacheRead: z.ZodNumber;
+					cacheWrite: z.ZodNumber;
+					reasoning: z.ZodNumber;
+				}, z.core.$strict>;
+			}, z.core.$strict>>;
 		}, z.core.$strict>;
 	}, z.core.$strict>;
 }, z.core.$strict>;
@@ -8518,14 +8834,25 @@ declare const WebhookEvent: z.ZodDiscriminatedUnion<[
 				flowId: z.ZodString;
 				flowVersion: z.ZodString;
 				status: z.ZodEnum<{
-					completed: "completed";
 					failed: "failed";
+					completed: "completed";
 					cancelled: "cancelled";
 				}>;
 				dryRun: z.ZodBoolean;
 				failureMessage: z.ZodNullable<z.ZodString>;
 				createdAt: z.ZodISODateTime;
 				completedAt: z.ZodISODateTime;
+				usage: z.ZodOptional<z.ZodObject<{
+					calls: z.ZodNumber;
+					costUsd: z.ZodNumber;
+					tokens: z.ZodObject<{
+						prompt: z.ZodNumber;
+						completion: z.ZodNumber;
+						cacheRead: z.ZodNumber;
+						cacheWrite: z.ZodNumber;
+						reasoning: z.ZodNumber;
+					}, z.core.$strict>;
+				}, z.core.$strict>>;
 			}, z.core.$strict>;
 		}, z.core.$strict>;
 		type: z.ZodLiteral<"run.finished">;
@@ -8560,14 +8887,25 @@ declare const WebhookDelivery: z.ZodObject<{
 					flowId: z.ZodString;
 					flowVersion: z.ZodString;
 					status: z.ZodEnum<{
-						completed: "completed";
 						failed: "failed";
+						completed: "completed";
 						cancelled: "cancelled";
 					}>;
 					dryRun: z.ZodBoolean;
 					failureMessage: z.ZodNullable<z.ZodString>;
 					createdAt: z.ZodISODateTime;
 					completedAt: z.ZodISODateTime;
+					usage: z.ZodOptional<z.ZodObject<{
+						calls: z.ZodNumber;
+						costUsd: z.ZodNumber;
+						tokens: z.ZodObject<{
+							prompt: z.ZodNumber;
+							completion: z.ZodNumber;
+							cacheRead: z.ZodNumber;
+							cacheWrite: z.ZodNumber;
+							reasoning: z.ZodNumber;
+						}, z.core.$strict>;
+					}, z.core.$strict>>;
 				}, z.core.$strict>;
 			}, z.core.$strict>;
 			type: z.ZodLiteral<"run.finished">;
@@ -8610,14 +8948,25 @@ declare const WebhookDeliveryCollectionPage: z.ZodObject<{
 						flowId: z.ZodString;
 						flowVersion: z.ZodString;
 						status: z.ZodEnum<{
-							completed: "completed";
 							failed: "failed";
+							completed: "completed";
 							cancelled: "cancelled";
 						}>;
 						dryRun: z.ZodBoolean;
 						failureMessage: z.ZodNullable<z.ZodString>;
 						createdAt: z.ZodISODateTime;
 						completedAt: z.ZodISODateTime;
+						usage: z.ZodOptional<z.ZodObject<{
+							calls: z.ZodNumber;
+							costUsd: z.ZodNumber;
+							tokens: z.ZodObject<{
+								prompt: z.ZodNumber;
+								completion: z.ZodNumber;
+								cacheRead: z.ZodNumber;
+								cacheWrite: z.ZodNumber;
+								reasoning: z.ZodNumber;
+							}, z.core.$strict>;
+						}, z.core.$strict>>;
 					}, z.core.$strict>;
 				}, z.core.$strict>;
 				type: z.ZodLiteral<"run.finished">;
@@ -8883,6 +9232,8 @@ export interface ApprovalFilter extends Omit<Filter<ApprovalStatus>, "status"> {
 	 * passing several is rejected client-side with `invalid-request`.
 	 */
 	readonly status?: ApprovalStatus;
+	/** Only one project's approvals (`kind: 'project'`), or every project's in an org (`kind: 'org'`). */
+	readonly scope?: ScopeRef;
 	/** Filter by required reviewer role. Caller must have rank ≥ value (else 403). */
 	readonly requiredRole?: ReviewerRole$1;
 	/** ISO 8601 timestamp — return approvals created strictly after this. */
@@ -9311,6 +9662,8 @@ export interface ConversationFilter extends Omit<Filter<ConversationStatus>, "st
 	 * passing several is rejected client-side with `invalid-request`.
 	 */
 	readonly status?: ConversationStatus;
+	/** Only one project's conversations (`kind: 'project'`), or every project's in an org (`kind: 'org'`). */
+	readonly scope?: ScopeRef;
 	readonly agent?: AgentId;
 	readonly participantId?: string;
 }
@@ -9333,8 +9686,10 @@ export interface CostClient {
 }
 export interface UsageClient {
 	/**
-	 * Paginated raw cost records. Filter by run, agent, conversation,
-	 * category, provider, and time window.
+	 * Paginated raw cost records: one per model call, with its model,
+	 * usage and what the vendor said about it. Filter by run (or a run
+	 * tree), scope, agent, conversation, category, provider, model and
+	 * time window.
 	 *
 	 * @wire `GET /v1/cost/records` — see
 	 *   `@kindgi/api/openapi.json#/paths/~1v1~1cost~1records/get`.
@@ -9346,26 +9701,25 @@ export interface UsageClient {
 	 * @wire `GET /v1/cost/records/{recordId}` — see
 	 *   `@kindgi/api/openapi.json#/paths/~1v1~1cost~1records~1{recordId}/get`.
 	 */
-	get(recordId: string): Promise<CostRecord>;
+	get(recordId: string, options?: {
+		readonly includeRawUsage?: boolean;
+	}): Promise<CostRecord>;
 	/**
-	 * Grouped aggregate — totals in USD, bucketed by requested dimensions
-	 * over the time window. Cheaper than paginating raw records for
-	 * dashboards.
+	 * Grouped aggregate — totals in USD and tokens, bucketed by requested
+	 * dimensions over the time window. Cheaper than paginating raw records
+	 * for dashboards. With `scope: { kind: 'org', orgId }`, one call sums
+	 * an org's spend across its projects.
 	 *
 	 * @wire `GET /v1/cost/aggregate` — see
 	 *   `@kindgi/api/openapi.json#/paths/~1v1~1cost~1aggregate/get`.
 	 */
 	summary(input: UsageSummaryInput): Promise<CostAggregateResult>;
 }
-export interface UsageSummaryInput {
+export interface UsageSummaryInput extends Omit<CostRecordFilter, "from" | "to" | "limit" | "cursor" | "includeRawUsage"> {
 	readonly from: Timestamp;
+	/** Exclusive. */
 	readonly to: Timestamp;
 	readonly groupBy?: readonly CostGroupDimension[];
-	readonly category?: string;
-	readonly providerId?: ProviderId;
-	readonly agentId?: AgentId;
-	readonly runId?: RunId;
-	readonly conversationId?: ThreadId;
 }
 export interface BudgetsClient {
 	/**
@@ -9459,19 +9813,19 @@ export interface EnvClient {
 	delete(input: EnvDeleteInput): Promise<EnvDeleteOutcome>;
 }
 export interface EnvListInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly cursor?: Cursor;
 	readonly namePrefix?: string;
 	readonly limit?: number;
 }
 export interface EnvGetInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 }
 export interface EnvSetInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly value: string;
@@ -9479,12 +9833,12 @@ export interface EnvSetInput {
 	readonly tags?: Readonly<Record<string, string>>;
 }
 export interface EnvDeleteInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 }
 export interface EnvRecord {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly value: string;
@@ -10742,10 +11096,14 @@ export interface RunJournalPage {
 export interface ListRunsFilter {
 	readonly limit?: number;
 	readonly cursor?: string;
+	/** Only one project's runs (`kind: 'project'`), or the runs of every project in an org (`kind: 'org'`). */
+	readonly scope?: ScopeRef;
 	/** Only the child runs of this run. */
 	readonly parentRunId?: RunId;
 	/** Only runs that are not a child of another run. */
 	readonly topLevel?: boolean;
+	/** Only this agent's turns, at any version (turns from before 0.1.3 don't name their agent). */
+	readonly agentId?: AgentId | string;
 	/** Include each run's `output` (omitted from lists by default). */
 	readonly includeOutput?: boolean;
 }
@@ -10792,11 +11150,20 @@ export interface ResumeRunInput {
 	readonly value?: unknown;
 	readonly idempotencyKey?: string;
 }
+/**
+ * The agent a run is a turn of (`@kindgi/api/openapi.json#RunAgent`):
+ * which agent, the version that ran, and the conversation.
+ */
+export interface RunAgent {
+	readonly id: string;
+	readonly version: string;
+	readonly conversationId: string;
+}
 /**
  * Wire shape — matches `@kindgi/api/openapi.json#Run`. Runs are
  * flow-native on the wire: an agent run executes as a flow on the
- * server, and the row reports that flow's `flowId` / `flowVersion`
- * rather than the `agentId`.
+ * server, and the row reports that flow's `flowId` / `flowVersion`;
+ * `agent` names the agent.
  */
 export interface Run {
 	readonly id: RunId;
@@ -10816,6 +11183,11 @@ export interface Run {
 	readonly parentRunId?: RunId;
 	/** Set on a child run: the node in the parent run that started it. */
 	readonly parentNodeId?: string;
+	/**
+	 * Set on an agent's turn (an agent run, or the turn a flow's agent step
+	 * started). Absent on other runs, and on turns from before 0.1.3.
+	 */
+	readonly agent?: RunAgent;
 }
 /**
  * What `runs.start` returns: the run, plus a public run token when the
@@ -10957,14 +11329,14 @@ export interface SecretRotationsClient {
 	}): AsyncIterable<unknown>;
 }
 export interface SecretRotationGetInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly rotationId: string;
 }
 export type SecretRotationEventsInput = SecretRotationGetInput;
 export interface SecretListInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly cursor?: Cursor;
 	readonly namePrefix?: string;
@@ -10972,25 +11344,25 @@ export interface SecretListInput {
 	readonly limit?: number;
 }
 export interface SecretGetInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 }
 export interface SecretGetVersionInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly versionId: number;
 }
 export interface SecretListVersionsInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly cursor?: Cursor;
 	readonly limit?: number;
 }
 export interface SecretSetInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly value: string;
@@ -11001,7 +11373,7 @@ export interface SecretSetInput {
 	readonly idempotencyKey?: string;
 }
 export interface SecretRotateInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly newValue?: string;
@@ -11032,14 +11404,14 @@ export interface PollingOverrides {
 	readonly sleep?: (ms: number) => Promise<void>;
 }
 export interface SecretRevokeInput {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly hard?: boolean;
 	readonly reason?: string;
 }
 export interface SecretRecord {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly currentVersion: number;
@@ -11051,7 +11423,7 @@ export interface SecretRecord {
 	readonly rotationDueAt?: string;
 }
 export interface SecretVersionRecord {
-	readonly scope: Scope;
+	readonly scope: ScopeRef;
 	readonly envName: EnvName;
 	readonly name: string;
 	readonly versionId: number;