@kindgi/api 0.1.2 → 0.1.3

package/src/openapi/schemas.ts

@@ -128,6 +128,23 @@ export const RunStatusSchema: JsonSchema = {
   enum: ['pending', 'running', 'suspended', 'completed', 'failed', 'cancelled'],
 };
 
+/**
+ * The agent a run is a turn of. A component of its own, so generated
+ * clients name it `RunAgent` (not after the `agent` property).
+ */
+export const RunAgentSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version', 'conversationId'],
+  description:
+    "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.",
+  properties: {
+    id: { type: 'string', description: 'The agent id.' },
+    version: { type: 'string', description: 'The agent version that ran (semver).' },
+    conversationId: { type: 'string', format: 'uuid' },
+  },
+};
+
 export const RunSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
@@ -167,6 +184,7 @@ export const RunSchema: JsonSchema = {
       type: 'string',
       description: 'Set on a child run: the node in the parent run that started it.',
     },
+    agent: { $ref: '#/components/schemas/RunAgent' },
     publicAccessToken: {
       type: 'string',
       description:
@@ -557,6 +575,29 @@ export const ApprovalSchema: JsonSchema = {
     updatedAt: { type: 'string', format: 'date-time' },
     decidedAt: { type: 'string', format: 'date-time' },
     expiresAt: { type: 'string', format: 'date-time' },
+    decision: {
+      description:
+        "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).",
+      $ref: '#/components/schemas/ApprovalDecisionRecord',
+    },
+  },
+};
+
+export const ApprovalDecisionRecordSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['decision', 'reviewerId', 'reviewerRoleAtDecision', 'decidedAt'],
+  properties: {
+    decision: ReviewDecisionKindSchema,
+    decidedBy: {
+      type: 'string',
+      description:
+        "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.",
+    },
+    reviewerId: { type: 'string', format: 'uuid' },
+    reviewerRoleAtDecision: ReviewerRoleSchema,
+    decidedAt: { type: 'string', format: 'date-time' },
+    rationale: { type: 'string' },
   },
 };
 
@@ -599,7 +640,7 @@ export const CompleteApprovalBodySchema: JsonSchema = {
     rationale: { type: 'string' },
     value: {
       description:
-        '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.",
     },
   },
 };
@@ -1652,6 +1693,12 @@ export const ConversationSchema: JsonSchema = {
     agentVersion: { type: 'string', description: 'Semver.' },
     title: { type: 'string' },
     participantId: { type: 'string' },
+    projectId: {
+      type: 'string',
+      format: 'uuid',
+      description:
+        "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.",
+    },
     scope: {
       type: 'object',
       additionalProperties: true,
@@ -1706,6 +1753,12 @@ export const OpenConversationBodySchema: JsonSchema = {
       type: 'string',
       description: 'Optional. Defaults to `"Untitled conversation"` when omitted.',
     },
+    projectId: {
+      type: 'string',
+      format: 'uuid',
+      description:
+        "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.",
+    },
     scope: {
       type: 'object',
       additionalProperties: true,
@@ -2483,6 +2536,12 @@ export const ProvenanceRecordMetadataSchema: JsonSchema = {
         'True when the emission-time signature is present. Independent of whether the export route can produce a signed bundle.',
     },
     createdAt: { type: 'string', format: 'date-time' },
+    projectId: {
+      type: 'string',
+      format: 'uuid',
+      description:
+        "The project of the record's run. Absent on records from before Kindgi 0.1.3; those are listed only without a scope.",
+    },
   },
 };
 
@@ -2508,6 +2567,22 @@ export const ProvenanceRecordSchema: JsonSchema = {
     },
     signature: ProvenanceSignatureSchema,
     createdAt: { type: 'string', format: 'date-time' },
+    callUsage: {
+      type: 'object',
+      description:
+        "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.",
+      additionalProperties: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['usage'],
+        properties: {
+          usage: { $ref: '#/components/schemas/ModelCallTokens' },
+          costUsd: { type: 'number', minimum: 0 },
+          durationMs: { type: 'integer', minimum: 0 },
+          servedModel: { type: 'string' },
+        },
+      },
+    },
   },
 };
 
@@ -2544,7 +2619,7 @@ export const ExportProvenanceBodySchema: JsonSchema = {
 
 export const ExportProvenanceResultSchema: JsonSchema = {
   description:
-    '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.',
   type: 'object',
   additionalProperties: false,
   required: [
@@ -2566,7 +2641,8 @@ export const ExportProvenanceResultSchema: JsonSchema = {
     },
     bundleSchemaVersion: {
       type: 'string',
-      description: 'Semver for the shape of the bundle body. Currently `1.0.0`.',
+      description:
+        "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.",
     },
     algorithm: { type: 'string', const: 'ed25519' },
     signingKeyId: { type: 'string' },
@@ -3243,7 +3319,65 @@ export const GetMCPPromptResultSchema: JsonSchema = {
  */
 export const CostGroupDimensionSchema: JsonSchema = {
   type: 'string',
-  enum: ['agentId', 'runId', 'category', 'providerId', 'day', 'month', 'tenant', 'conversationId'],
+  enum: [
+    'agentId',
+    'runId',
+    'category',
+    'providerId',
+    'day',
+    'month',
+    'tenant',
+    'conversationId',
+    'model',
+    'servedModel',
+    'projectId',
+    'orgId',
+    'rootRunId',
+    'flowId',
+  ],
+};
+
+/** Why a model call failed, as its cost record carries it. */
+export const ModelCallErrorSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['message'],
+  description: 'Why a model call failed (`status: failed`).',
+  properties: { message: { type: 'string' } },
+};
+
+/** A model call's tokens, as a cost record and a provenance record carry them. */
+export const ModelCallTokensSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['promptTokens', 'completionTokens'],
+  description:
+    "The call's tokens. `promptTokens` / `completionTokens` are the totals; `cacheReadTokens` / `cacheWriteTokens` are parts of `promptTokens`, `reasoningTokens` of `completionTokens`, present when the provider reports them.",
+  properties: {
+    promptTokens: { type: 'integer', minimum: 0 },
+    completionTokens: { type: 'integer', minimum: 0 },
+    cacheReadTokens: { type: 'integer', minimum: 0 },
+    cacheWriteTokens: { type: 'integer', minimum: 0 },
+    reasoningTokens: { type: 'integer', minimum: 0 },
+  },
+};
+
+/**
+ * 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 const CostTokenTotalsSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['prompt', 'completion', 'cacheRead', 'cacheWrite', 'reasoning'],
+  properties: {
+    prompt: { type: 'integer', minimum: 0 },
+    completion: { type: 'integer', minimum: 0 },
+    cacheRead: { type: 'integer', minimum: 0 },
+    cacheWrite: { type: 'integer', minimum: 0 },
+    reasoning: { type: 'integer', minimum: 0 },
+  },
 };
 
 /**
@@ -3283,6 +3417,63 @@ export const CostRecordSchema: JsonSchema = {
       additionalProperties: true,
       description: 'Free-form filter/display tags — never counters.',
     },
+    callId: {
+      type: 'string',
+      description:
+        "A model call's id (`category` `llm.inference`); its provenance `model-call` node carries it too.",
+    },
+    projectId: { type: 'string', format: 'uuid' },
+    rootRunId: {
+      type: 'string',
+      format: 'uuid',
+      description: "The root of the record's run tree (a flow run, for its agent turns).",
+    },
+    parentRunId: { type: 'string', format: 'uuid' },
+    agentVersion: { type: 'string' },
+    flowId: { type: 'string', description: "The flow of the run tree's root." },
+    nodeId: { type: 'string', description: 'The step that made the call.' },
+    step: { type: 'integer', minimum: 1, description: "The turn's step number." },
+    purpose: {
+      type: 'string',
+      description:
+        "What the call was for, beyond the turn's own model step: `guardrail-judge:<guardrail id>`.",
+    },
+    model: { type: 'string', description: 'The model actually called.' },
+    servedModel: {
+      type: 'string',
+      description: 'The exact model version the vendor reported (vendors alias).',
+    },
+    fallback: {
+      type: 'boolean',
+      description: 'The router picked a fallback provider for the turn.',
+    },
+    status: {
+      type: 'string',
+      enum: ['ok', 'failed'],
+      description: '`ok`: the provider answered. `failed`: the call threw.',
+    },
+    usage: { $ref: '#/components/schemas/ModelCallTokens' },
+    durationMs: { type: 'integer', minimum: 0 },
+    finishReason: { type: 'string' },
+    providerRequestId: { type: 'string', description: "The vendor's id for the request." },
+    attempts: {
+      type: 'integer',
+      minimum: 1,
+      description: "HTTP attempts the call took, the client's retries included.",
+    },
+    error: { $ref: '#/components/schemas/ModelCallError' },
+    rawUsage: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['provider', 'model', 'usage'],
+      description:
+        "The vendor's own usage object, exactly as it reported it. Only with `include=rawUsage`.",
+      properties: {
+        provider: { type: 'string' },
+        model: { type: 'string' },
+        usage: { type: 'object', additionalProperties: true },
+      },
+    },
   },
 };
 
@@ -3303,7 +3494,7 @@ export const CostRecordCollectionPageSchema: JsonSchema = {
 export const CostAggregateGroupSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['key', 'count', 'totalUsd'],
+  required: ['key', 'count', 'totalUsd', 'tokens'],
   properties: {
     key: {
       type: 'object',
@@ -3313,13 +3504,14 @@ export const CostAggregateGroupSchema: JsonSchema = {
     },
     count: { type: 'integer', minimum: 0 },
     totalUsd: { type: 'number', minimum: 0 },
+    tokens: { $ref: '#/components/schemas/CostTokenTotals' },
   },
 };
 
 export const CostAggregateResultSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['groups', 'totalUsd', 'totalRecords', 'timeRange', 'groupBy'],
+  required: ['groups', 'totalUsd', 'totalRecords', 'tokens', 'timeRange', 'groupBy'],
   properties: {
     groups: {
       type: 'array',
@@ -3327,6 +3519,7 @@ export const CostAggregateResultSchema: JsonSchema = {
     },
     totalUsd: { type: 'number', minimum: 0 },
     totalRecords: { type: 'integer', minimum: 0 },
+    tokens: { $ref: '#/components/schemas/CostTokenTotals' },
     timeRange: {
       type: 'object',
       additionalProperties: false,
@@ -3980,7 +4173,7 @@ export const LogoutResultSchema: JsonSchema = {
 
 export const WhoamiResultSchema: JsonSchema = {
   description:
-    "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.",
   type: 'object',
   additionalProperties: false,
   required: ['tenantId', 'scopes'],
@@ -5844,6 +6037,20 @@ export const WebhookEndpointUnregisterResultSchema: JsonSchema = {
   },
 };
 
+/** A run tree's model calls, as `run.finished` carries them. */
+export const RunTreeUsageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['calls', 'costUsd', 'tokens'],
+  description:
+    "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.",
+  properties: {
+    calls: { type: 'integer', minimum: 0 },
+    costUsd: { type: 'number', minimum: 0 },
+    tokens: { $ref: '#/components/schemas/CostTokenTotals' },
+  },
+};
+
 export const FinishedRunSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
@@ -5873,6 +6080,7 @@ export const FinishedRunSchema: JsonSchema = {
     },
     createdAt: { type: 'string', format: 'date-time' },
     completedAt: { type: 'string', format: 'date-time' },
+    usage: { $ref: '#/components/schemas/RunTreeUsage' },
   },
 };
 
@@ -6020,6 +6228,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['WireError', WireErrorSchema],
   ['HealthResult', HealthResultSchema],
   ['RunStatus', RunStatusSchema],
+  ['RunAgent', RunAgentSchema],
   ['Run', RunSchema],
   ['StartRunOptions', StartRunOptionsSchema],
   ['StartRunBody', StartRunBodySchema],
@@ -6047,6 +6256,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['ApprovalStatus', ApprovalStatusSchema],
   ['ReviewDecisionKind', ReviewDecisionKindSchema],
   ['Approval', ApprovalSchema],
+  ['ApprovalDecisionRecord', ApprovalDecisionRecordSchema],
   ['ReviewDecision', ReviewDecisionSchema],
   ['ApprovalCollectionPage', ApprovalCollectionPageSchema],
   ['CompleteApprovalBody', CompleteApprovalBodySchema],
@@ -6190,6 +6400,9 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['GetMCPPromptResult', GetMCPPromptResultSchema],
   ['CostGroupDimension', CostGroupDimensionSchema],
   ['CostRecord', CostRecordSchema],
+  ['ModelCallTokens', ModelCallTokensSchema],
+  ['ModelCallError', ModelCallErrorSchema],
+  ['CostTokenTotals', CostTokenTotalsSchema],
   ['CostRecordCollectionPage', CostRecordCollectionPageSchema],
   ['CostAggregateGroup', CostAggregateGroupSchema],
   ['CostAggregateResult', CostAggregateResultSchema],
@@ -6348,6 +6561,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['CreateWebhookEndpointBody', CreateWebhookEndpointBodySchema],
   ['PatchWebhookEndpointBody', PatchWebhookEndpointBodySchema],
   ['WebhookEndpointUnregisterResult', WebhookEndpointUnregisterResultSchema],
+  ['RunTreeUsage', RunTreeUsageSchema],
   ['FinishedRun', FinishedRunSchema],
   ['RunFinishedEvent', RunFinishedEventSchema],
   ['WebhookTestEvent', WebhookTestEventSchema],

package/src/provenance-binding.ts

@@ -8,7 +8,16 @@
 // touches provenance storage directly.
 //
 
-import type { FlowId, ProvenanceId, Result, RunId, TenantId, Timestamp } from '@kindgi/types';
+import type {
+  FlowId,
+  ListScope,
+  ProjectId,
+  ProvenanceId,
+  Result,
+  RunId,
+  TenantId,
+  Timestamp,
+} from '@kindgi/types';
 
 // ---------- domain type surface ----------
 
@@ -98,6 +107,8 @@ export interface ProvenanceListCursor {
 export interface ListProvenanceRecordsInput {
   readonly tenantId: TenantId;
   readonly limit: number;
+  /** Only one project's records, or every project's in an org. Absent: the tenant's. */
+  readonly scope?: ListScope;
   readonly runId?: RunId;
   readonly agentId?: string;
   readonly createdAfter?: Date;
@@ -117,6 +128,8 @@ export interface ProvenanceRecordSummary {
   readonly createdAt: Timestamp;
   readonly flowRef?: { readonly id: FlowId; readonly version: string };
   readonly signed: boolean;
+  /** The project of the record's run; absent on records from before it was stored. */
+  readonly projectId?: ProjectId;
 }
 
 export interface ListProvenanceRecordsResult {
@@ -166,4 +179,32 @@ export interface ProvenanceBinding {
    * tenant/run pair.
    */
   getByRunId(tenantId: TenantId, runId: RunId): Promise<Result<Provenance, ProvenanceBindingError>>;
+
+  /**
+   * The cost ledger's usage of each model call in the run's provenance,
+   * by the `callId` in its `model-call` node's attributes. Optional: a
+   * deployment without a cost ledger omits it. The routes add it to a
+   * read as `callUsage`, outside the signed DAG; a signed export
+   * includes it as it stood when signed.
+   */
+  getCallUsage?(
+    tenantId: TenantId,
+    runId: RunId,
+  ): Promise<Result<CallUsageByCallId, ProvenanceBindingError>>;
 }
+
+/** One model call's usage, as the cost ledger has it. */
+export interface CallUsage {
+  readonly usage: {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+  };
+  readonly costUsd?: number;
+  readonly durationMs?: number;
+  readonly servedModel?: string;
+}
+
+export type CallUsageByCallId = Readonly<Record<string, CallUsage>>;

package/src/reviewer-binding.ts

@@ -6,16 +6,24 @@ import type { Cursor, ReviewerId, TenantId, Timestamp, UserId } from '@kindgi/ty
 
 /**
  * Translates the bearer-token identity (`UserId`) into the `ReviewerId`
- * that `HitlBinding.submitReview` needs. The API package intentionally does
+ * that `HitlBinding.submitReview` needs, and the reviewer role the
+ * approvals surface is scoped by. The API package intentionally does
  * NOT own the `user ↔ reviewer` mapping — deployments plug that in via
  * this binding, same pattern as `TokenResolver` (for auth read) and
  * `TokenAdmin` (for mint/revoke).
  *
- * Return `null` when the user has no registered reviewer row for the
+ * Both return `null` when the user has no active reviewer row for the
  * tenant (leads to `403 permission-denied` from the approvals route).
  */
 export interface ReviewerBinding {
   resolveReviewer(input: ReviewerLookupInput): Promise<ReviewerId | null>;
+  /**
+   * The user's reviewer role in the tenant. Consulted for a token that
+   * carries no `reviewerRole` of its own (a session or API key of a
+   * registered reviewer), so the roster, not the token, says who reviews.
+   * A binding without it: only a token that carries its role reviews.
+   */
+  resolveReviewerRole?(input: ReviewerLookupInput): Promise<ReviewerRole | null>;
 }
 
 export interface ReviewerLookupInput {

package/src/reviewer-role.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ReviewerRole } from '@kindgi/authz';
+import type { TenantId, UserId } from '@kindgi/types';
+import type { Context } from 'hono';
+
+import type { ReviewerBinding } from './reviewer-binding.js';
+import type { AppEnv } from './types.js';
+
+/**
+ * The caller's reviewer role: the one its token carries, else the one the
+ * roster gives its user (`ReviewerBinding.resolveReviewerRole`, when the
+ * binding has it), kept on the request. `undefined` for a caller that
+ * isn't a reviewer: a token with neither a role nor a user, or a user the
+ * roster doesn't know.
+ */
+export async function callerReviewerRole(
+  c: Context<AppEnv>,
+  reviewerBinding: ReviewerBinding | undefined,
+): Promise<ReviewerRole | undefined> {
+  const carried = c.get('reviewerRole');
+  if (carried !== undefined) return carried;
+  const userId = c.get('userId') as UserId | undefined;
+  if (userId === undefined || reviewerBinding?.resolveReviewerRole === undefined) {
+    return undefined;
+  }
+  const role = await reviewerBinding.resolveReviewerRole({
+    tenantId: c.get('tenantId') as TenantId,
+    userId,
+  });
+  if (role === null) return undefined;
+  c.set('reviewerRole', role);
+  return role;
+}