@kindgi/api 0.1.1 → 0.1.3

package/src/routes/approvals.ts

@@ -3,7 +3,8 @@
 
 import { Hono } from 'hono';
 
-import type { ConversationBinding } from '@kindgi/agents';
+import { AGENT_GATE_SUBJECTS, TOOL_CALL_GATE_SUBJECT } from '@kindgi/agents';
+import type { ConversationBinding, GateDecisionValue } from '@kindgi/agents';
 import { REVIEWER_ROLE_RANK, type ReviewerRole } from '@kindgi/authz';
 import { serializePublicKeyPem, signEd25519 } from '@kindgi/crypto';
 import type { SigningKeyBinding } from '@kindgi/crypto';
@@ -23,10 +24,18 @@ import type {
 
 import { statusFor, toWireError } from '../errors.js';
 import type { RunHandlerBinding } from '../handler-binding.js';
-import type { Approval, ApprovalStatus, HitlBinding, ReviewDecisionKind } from '../hitl-binding.js';
+import type {
+  Approval,
+  ApprovalStatus,
+  HitlBinding,
+  ReviewDecisionKind,
+  ReviewDecisionRecord,
+} from '../hitl-binding.js';
 import type { ReviewerBinding } from '../reviewer-binding.js';
+import { callerReviewerRole } from '../reviewer-role.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { parseListScope } from './scope-params.js';
 
 const APPROVAL_STATUSES: ReadonlySet<ApprovalStatus> = new Set([
   'pending',
@@ -80,10 +89,11 @@ export interface ApprovalsRouterOptions {
 /**
  * Approvals resource routes.
  *
- * Reviewer-role scoping: routes require `c.get('reviewerRole')` to be
- * set by the auth middleware (see `TokenResolution.reviewerRole`).
- * Tokens without a reviewer role get `403 permission-denied` on every
- * approvals route — this surface is reviewer-only.
+ * Reviewer-role scoping: routes require a reviewer role — the token's
+ * (`TokenResolution.reviewerRole`), or its user's in the reviewer roster
+ * (`ReviewerBinding.resolveReviewerRole`). A caller with neither gets
+ * `403 permission-denied` on every approvals route — this surface is
+ * reviewer-only.
  *
  * Visibility filter: a caller with role `R` sees approvals whose
  * `requiredRole` rank ≤ their rank (standard < senior < admin). The
@@ -103,9 +113,11 @@ export function approvalsRouter(
   const runHandler = options.runHandler;
 
   // ---------- role gate for the whole resource ----------
+  // A reviewer: a token that carries a role, or whose user the roster
+  // names (a session or API key of a registered reviewer).
   r.use('*', async (c, next) => {
     const requestId = c.get('requestId');
-    const role = c.get('reviewerRole');
+    const role = await callerReviewerRole(c, reviewerBinding);
     if (role === undefined) {
       c.status(statusFor('permission-denied') as never);
       return c.json(
@@ -113,7 +125,7 @@ export function approvalsRouter(
           {
             code: 'permission-denied',
             message:
-              'This token was not provisioned with a reviewer role; approvals surface is reviewer-only.',
+              "The caller isn't a reviewer: its token carries no reviewer role, and its user isn't registered as one (`kindgi reviewers register`). The approvals surface is reviewer-only.",
           },
           requestId,
         ),
@@ -130,6 +142,14 @@ export function approvalsRouter(
     const role = c.get('reviewerRole') as ReviewerRole;
     const limit = clampLimit(c.req.query('limit'));
 
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
     const statusRaw = c.req.query('status');
     let statusFilter: ApprovalStatus | undefined;
     if (statusRaw !== undefined && statusRaw.length > 0) {
@@ -213,6 +233,7 @@ export function approvalsRouter(
     const listInput = {
       tenantId,
       limit: HITL_LIMIT_CAP,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(statusFilter !== undefined && { status: statusFilter }),
       ...(requiredRoleFilter !== undefined && { requiredRole: requiredRoleFilter }),
       ...(createdAfterIso !== undefined && { since: createdAfterIso as unknown as Timestamp }),
@@ -327,6 +348,22 @@ export function approvalsRouter(
       );
     }
 
+    // An agent's tool-call and session gates resume on the decision alone
+    // (`readGateDecision` fails closed on anything else), so a `value`
+    // can't stand in for it: refused before anything is recorded.
+    if (parsed.value.value !== undefined && AGENT_GATE_SUBJECTS.has(approval.subjectKind)) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `An approval of an agent's ${approval.subjectKind === TOOL_CALL_GATE_SUBJECT ? 'tool call' : 'session'} takes a decision (approve or reject) and an optional rationale, not a \`value\`: the turn resumes on the decision alone.`,
+          },
+          requestId,
+        ),
+      );
+    }
+
     const reviewerId = await reviewerBinding.resolveReviewer({
       tenantId,
       userId: userId as UserId,
@@ -362,23 +399,25 @@ export function approvalsRouter(
     // stays suspended until the new (escalated) approval terminates,
     // or the run is cancelled explicitly.
     //
-    // Resume value shape: `{ decided, rationale? }` — the shape the
-    // agent's approval gate consumes. The caller CAN supply an explicit
-    // `value` in the wire body to override it, when the resume payload
-    // must carry more than the decision.
+    // Resume value shape: `GateDecisionValue`, `{ decided, rationale?,
+    // decidedBy, approvalId }`, the shape the agent's approval gate
+    // consumes; the run's journal keeps who decided which approval. For
+    // another subject, the caller CAN supply an explicit `value` to
+    // override it, when the resume payload must carry more than the
+    // decision (an agent gate refuses one, above).
     let waitpointResolved = false;
     if (
       approval.waitTokenId !== undefined &&
       approval.provenanceRef?.runId !== undefined &&
       (parsed.value.decision === 'approve' || parsed.value.decision === 'reject')
     ) {
-      const resumeValue =
-        parsed.value.value !== undefined
-          ? parsed.value.value
-          : {
-              decided: parsed.value.decision as 'approve' | 'reject',
-              ...(parsed.value.rationale !== undefined && { rationale: parsed.value.rationale }),
-            };
+      const decided: GateDecisionValue = {
+        decided: parsed.value.decision,
+        ...(parsed.value.rationale !== undefined && { rationale: parsed.value.rationale }),
+        decidedBy: `user:${userId as unknown as string}`,
+        approvalId: approval.id as unknown as string,
+      };
+      const resumeValue = parsed.value.value !== undefined ? parsed.value.value : decided;
       const resolved = await runBinding.completeToken(
         tenantId,
         approval.provenanceRef.runId as RunId,
@@ -661,6 +700,18 @@ function serializeApproval(a: Approval): Record<string, unknown> {
     updatedAt: a.updatedAt,
     decidedAt: a.decidedAt,
     expiresAt: a.expiresAt,
+    decision: a.decision === undefined ? undefined : serializeApprovalDecision(a.decision),
+  };
+}
+
+function serializeApprovalDecision(d: ReviewDecisionRecord): Record<string, unknown> {
+  return {
+    decision: d.decision,
+    ...(d.decidedBy !== undefined && { decidedBy: d.decidedBy }),
+    reviewerId: d.reviewerId,
+    reviewerRoleAtDecision: d.reviewerRoleAtDecision,
+    decidedAt: d.decidedAt,
+    ...(d.rationale !== undefined && { rationale: d.rationale }),
   };
 }
 

package/src/routes/conversations.ts

@@ -10,12 +10,16 @@ import type {
   ConversationMessage,
   ConversationPageCursor,
 } from '@kindgi/agents';
+import type { ProjectBinding } from '@kindgi/platform';
 import type { RunBinding } from '@kindgi/runtime';
-import type { AgentId, Semver, TenantId } from '@kindgi/types';
+import type { AgentId, ProjectId, Semver, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
+import { parseListScope } from './scope-params.js';
+
+const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /**
  * Conversations resource routes. All storage access goes through the
@@ -27,6 +31,11 @@ import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
 export function conversationsRouter(
   conversationBinding: ConversationBinding,
   runBinding: RunBinding,
+  /**
+   * When wired, a `projectId` given to `POST /` must be one of the
+   * tenant's projects, and an omitted one is the tenant's Default project.
+   */
+  projectBinding?: ProjectBinding,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
@@ -53,6 +62,14 @@ export function conversationsRouter(
 
     const agentIdRaw = c.req.query('agentId');
 
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
     let before: ConversationPageCursor | undefined;
     const rawCursor = c.req.query('cursor');
     if (rawCursor !== undefined && rawCursor.length > 0) {
@@ -68,6 +85,7 @@ export function conversationsRouter(
 
     const listResult = await conversationBinding.listConversationsPage({
       tenantId,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw as AgentId }),
       ...(statusFilter !== undefined && { status: statusFilter }),
       ...(before !== undefined && { before }),
@@ -126,9 +144,30 @@ export function conversationsRouter(
       c.status(statusFor(parsed.error.code) as never);
       return c.json(toWireError(parsed.error, requestId));
     }
+    const supplied = parsed.value.projectId;
+    if (
+      supplied !== undefined &&
+      projectBinding !== undefined &&
+      (await projectBinding.get(tenantId, supplied)) === undefined
+    ) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`projectId\` "${supplied as unknown as string}" does not resolve to a project in this tenant`,
+          },
+          requestId,
+        ),
+      );
+    }
+    // Omitted: the tenant's Default project, as for a run. No Default (or
+    // no project binding): no project, never a refusal.
+    const projectId = supplied ?? (await projectBinding?.getDefault(tenantId))?.id;
 
     const opened = await conversationBinding.openConversation({
       tenantId,
+      ...(projectId !== undefined && { projectId }),
       agentId: parsed.value.agentId,
       agentVersion: parsed.value.agentVersion,
       title: parsed.value.title,
@@ -232,6 +271,7 @@ function serializeConversation(c: Conversation): Record<string, unknown> {
     agentVersion: c.agentVersion as unknown as string,
     title: c.title,
     ...(c.participantId !== undefined && { participantId: c.participantId }),
+    ...(c.projectId !== undefined && { projectId: c.projectId as unknown as string }),
     scope: c.scope,
     status: (c.closedAt === undefined ? 'open' : 'closed') as 'open' | 'closed',
     openedAt: c.openedAt as unknown as string,
@@ -283,6 +323,7 @@ interface ParsedOpenBody {
   readonly agentVersion: Semver;
   readonly title: string;
   readonly scope: Readonly<Record<string, unknown>>;
+  readonly projectId?: ProjectId;
   readonly participantId?: string;
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
@@ -335,6 +376,20 @@ function parseOpenBody(
     scope = scopeRaw as Readonly<Record<string, unknown>>;
   }
 
+  const projectIdRaw = b.projectId;
+  if (
+    projectIdRaw !== undefined &&
+    (typeof projectIdRaw !== 'string' || !PROJECT_ID_RE.test(projectIdRaw))
+  ) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'bad-input',
+        message: '`projectId` must be a project id (a UUID) when supplied',
+      },
+    };
+  }
+
   const participantIdRaw = b.participantId;
   if (participantIdRaw !== undefined && typeof participantIdRaw !== 'string') {
     return {
@@ -362,6 +417,7 @@ function parseOpenBody(
       agentVersion: agentVersion as Semver,
       title,
       scope,
+      ...(projectIdRaw !== undefined && { projectId: projectIdRaw as ProjectId }),
       ...(participantIdRaw !== undefined && { participantId: participantIdRaw }),
       ...(metadata !== undefined && { metadata }),
     },

package/src/routes/cost.ts

@@ -12,6 +12,7 @@ import {
   type CostGroupDimension,
   type CostRecord,
   type CostRecordFilter,
+  type CostTokenTotals,
 } from '../cost-binding.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { AppEnv } from '../types.js';
@@ -52,6 +53,11 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       c.status(statusFor('bad-input') as never);
       return c.json(toWireError({ code: 'bad-input', message: filter.error }, requestId));
     }
+    const include = parseInclude(c.req.query('include'));
+    if (include.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: include.error }, requestId));
+    }
 
     // Thread the ?scopeKind + ?scopeId + ?inherit
     // triplet as a sibling of `filter` (matches the binding's shape:
@@ -71,6 +77,7 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       filter: filter.value,
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+      ...(include.rawUsage && { includeRawUsage: true }),
     });
     return c.json({
       data: page.data.map(serializeRecord),
@@ -84,8 +91,17 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const recordId = c.req.param('recordId');
+    const include = parseInclude(c.req.query('include'));
+    if (include.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: include.error }, requestId));
+    }
 
-    const record = await binding.getRecord({ tenantId, recordId });
+    const record = await binding.getRecord({
+      tenantId,
+      recordId,
+      ...(include.rawUsage && { includeRawUsage: true }),
+    });
     if (record === null) {
       c.status(statusFor('cost-record-not-found') as never);
       return c.json(
@@ -230,6 +246,7 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       groups: result.groups.map(serializeGroup),
       totalUsd: result.totalUsd,
       totalRecords: result.totalRecords,
+      tokens: serializeTokens(result.tokens),
       timeRange: {
         from: result.timeRange.from,
         to: result.timeRange.to,
@@ -248,27 +265,34 @@ function parseRecordFilter(
   opts: { skipTime?: boolean } = {},
 ): { kind: 'ok'; value: CostRecordFilter } | { kind: 'err'; error: string } {
   const out: {
-    runId?: string;
-    agentId?: string;
-    conversationId?: string;
-    category?: string;
-    providerId?: string;
-    from?: Date;
-    to?: Date;
+    -readonly [K in keyof CostRecordFilter]: CostRecordFilter[K];
   } = {};
-  const strKeys: Array<
-    ['runId' | 'agentId' | 'conversationId' | 'category' | 'providerId', string]
-  > = [
-    ['runId', 'runId'],
-    ['agentId', 'agentId'],
-    ['conversationId', 'conversationId'],
-    ['category', 'category'],
-    ['providerId', 'providerId'],
-  ];
-  for (const [outKey, qKey] of strKeys) {
-    const raw = query[qKey];
+  const strKeys = [
+    'runId',
+    'agentId',
+    'conversationId',
+    'category',
+    'providerId',
+    'model',
+    'servedModel',
+    'rootRunId',
+  ] as const;
+  for (const key of strKeys) {
+    const raw = query[key];
     if (raw !== undefined && raw.length > 0) {
-      out[outKey] = raw;
+      out[key] = raw;
+    }
+  }
+  const descendants = query.includeDescendants;
+  if (descendants !== undefined && descendants.length > 0) {
+    if (descendants !== 'true' && descendants !== 'false') {
+      return { kind: 'err', error: '`includeDescendants` must be `true` or `false`' };
+    }
+    if (descendants === 'true') {
+      if (out.runId === undefined) {
+        return { kind: 'err', error: '`includeDescendants` needs a `runId`' };
+      }
+      out.includeDescendants = true;
     }
   }
   if (opts.skipTime !== true) {
@@ -291,6 +315,22 @@ function parseRecordFilter(
   return { kind: 'ok', value: out };
 }
 
+/** The `include` query: optional extra fields, comma-separated. Only `rawUsage` today. */
+function parseInclude(
+  raw: string | undefined,
+): { kind: 'ok'; rawUsage: boolean } | { kind: 'err'; error: string } {
+  const fields = (raw ?? '')
+    .split(',')
+    .map((f) => f.trim())
+    .filter((f) => f.length > 0);
+  for (const field of fields) {
+    if (field !== 'rawUsage') {
+      return { kind: 'err', error: `\`include\` value "${field}" is not known (one of: rawUsage)` };
+    }
+  }
+  return { kind: 'ok', rawUsage: fields.includes('rawUsage') };
+}
+
 function parseIsoDate(raw: string): Date | null {
   const t = Date.parse(raw);
   if (!Number.isFinite(t)) return null;
@@ -312,14 +352,58 @@ function serializeRecord(rec: CostRecord): Record<string, unknown> {
     occurredAt: rec.occurredAt as unknown as string,
     ...(rec.metrics !== undefined && { metrics: rec.metrics }),
     ...(rec.attributes !== undefined && { attributes: rec.attributes }),
+    ...pick(rec, MODEL_CALL_FIELDS),
   };
 }
 
+/** A model call's fields on the wire, as the binding gives them (all optional). */
+const MODEL_CALL_FIELDS = [
+  'callId',
+  'projectId',
+  'rootRunId',
+  'parentRunId',
+  'agentVersion',
+  'flowId',
+  'nodeId',
+  'step',
+  'purpose',
+  'model',
+  'servedModel',
+  'fallback',
+  'status',
+  'usage',
+  'durationMs',
+  'finishReason',
+  'providerRequestId',
+  'attempts',
+  'error',
+  'rawUsage',
+] as const satisfies readonly (keyof CostRecord)[];
+
+function pick(rec: CostRecord, keys: readonly (keyof CostRecord)[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of keys) {
+    if (rec[key] !== undefined) out[key] = rec[key];
+  }
+  return out;
+}
+
 function serializeGroup(g: CostAggregateGroup): Record<string, unknown> {
   return {
     key: g.key,
     count: g.count,
     totalUsd: g.totalUsd,
+    tokens: serializeTokens(g.tokens),
+  };
+}
+
+function serializeTokens(t: CostTokenTotals): CostTokenTotals {
+  return {
+    prompt: t.prompt,
+    completion: t.completion,
+    cacheRead: t.cacheRead,
+    cacheWrite: t.cacheWrite,
+    reasoning: t.reasoning,
   };
 }
 

package/src/routes/identity.ts

@@ -11,6 +11,8 @@ import type {
   SessionSummary,
   UserRecord,
 } from '../identity-directory-binding.js';
+import type { ReviewerBinding } from '../reviewer-binding.js';
+import { callerReviewerRole } from '../reviewer-role.js';
 import type { SessionStoreBinding } from '../session-store-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
@@ -47,10 +49,16 @@ export interface IdentityRouterOptions {
    * deployments that don't wire an OAuth surface.
    */
   readonly sessionStore?: SessionStoreBinding;
+  /**
+   * Optional. When present, `whoami` reports the reviewer role of a
+   * caller whose token carries none from the roster, as the approvals
+   * routes resolve it.
+   */
+  readonly reviewerBinding?: ReviewerBinding;
 }
 
 export function identityRouter(options: IdentityRouterOptions = {}): Hono<AppEnv> {
-  const { directory, sessionStore } = options;
+  const { directory, sessionStore, reviewerBinding } = options;
   const r = new Hono<AppEnv>();
 
   // ---------- GET / whoami ----------
@@ -62,7 +70,7 @@ export function identityRouter(options: IdentityRouterOptions = {}): Hono<AppEnv
     const userId = c.get('userId') as UserId | undefined;
     const providerId = c.get('providerId') as string | undefined;
     const scopes = (c.get('scopes') as readonly string[] | undefined) ?? [];
-    const reviewerRole = c.get('reviewerRole') as string | undefined;
+    const reviewerRole = await callerReviewerRole(c, reviewerBinding);
 
     const body: Record<string, unknown> = { tenantId };
     if (sessionId !== undefined) body.sessionId = sessionId;

package/src/routes/provenance.ts

@@ -12,12 +12,15 @@ import type { ConversationId, RunId, SigningKeyId, TenantId, Timestamp } from '@
 import { statusFor, toWireError } from '../errors.js';
 
 import type {
+  CallUsageByCallId,
   ProvenanceBinding,
+  ProvenanceBindingError,
   ProvenanceListCursor,
   ProvenanceRecordSummary,
 } from '../provenance-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
+import { parseListScope } from './scope-params.js';
 
 /**
  * Provenance resource routes.
@@ -48,7 +51,8 @@ export interface ProvenanceRouterOptions {
 }
 
 /** Bundle schema version — bump when the wire shape of `bundle.body` changes. */
-const BUNDLE_SCHEMA_VERSION = '1.0.0';
+/** 1.1.0 adds `callUsage`: the model calls' usage from the cost ledger, when the run has any. */
+const BUNDLE_SCHEMA_VERSION = '1.1.0';
 
 export function provenanceRouter(
   binding: ProvenanceBinding,
@@ -76,6 +80,14 @@ export function provenanceRouter(
       cursorFilter = { createdAt: decoded.createdAt, id: decoded.id };
     }
 
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
     const runIdFilter = c.req.query('runId');
     const agentIdFilter = c.req.query('agentId');
     const createdAfterRaw = c.req.query('createdAfter');
@@ -98,6 +110,7 @@ export function provenanceRouter(
     const result = await binding.listRecords({
       tenantId,
       limit,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(runIdFilter !== undefined && runIdFilter.length > 0 && { runId: runIdFilter as RunId }),
       ...(agentIdFilter !== undefined && agentIdFilter.length > 0 && { agentId: agentIdFilter }),
       ...(createdAfter !== undefined && { createdAfter }),
@@ -148,6 +161,13 @@ export function provenanceRouter(
       );
     }
     const provenance = result.value;
+    const callUsage = await readCallUsage(binding, tenantId, runId);
+    if (callUsage.kind === 'err') {
+      c.status(statusFor(callUsage.error.code) as never);
+      return c.json(
+        toWireError({ code: callUsage.error.code, message: callUsage.error.message }, requestId),
+      );
+    }
     return c.json({
       id: provenance.id as unknown as string,
       runId: provenance.runId as unknown as string,
@@ -165,6 +185,7 @@ export function provenanceRouter(
         edges: provenance.edges,
       },
       ...(provenance.signature !== undefined && { signature: provenance.signature }),
+      ...(callUsage.value !== undefined && { callUsage: callUsage.value }),
     });
   });
 
@@ -232,6 +253,14 @@ export function provenanceRouter(
       );
     }
     const provenance = loaded.value;
+    // The calls' usage as it stands now: the signature covers it.
+    const callUsage = await readCallUsage(binding, tenantId, runId);
+    if (callUsage.kind === 'err') {
+      c.status(statusFor(callUsage.error.code) as never);
+      return c.json(
+        toWireError({ code: callUsage.error.code, message: callUsage.error.message }, requestId),
+      );
+    }
 
     // 2. Optionally hydrate conversation messages. Agent turns use the
     //    conversation id as the run id; for flow-only runs no
@@ -306,6 +335,7 @@ export function provenanceRouter(
         edges: provenance.edges,
       },
       ...(messages !== undefined && { messages }),
+      ...(callUsage.value !== undefined && { callUsage: callUsage.value }),
     };
     const canonicalBundleBytes = new TextEncoder().encode(canonicalize(bundleBody));
 
@@ -355,6 +385,7 @@ interface RecordMetadata {
   readonly createdAt: string;
   readonly flowRef?: { readonly id: string; readonly version: string };
   readonly signed: boolean;
+  readonly projectId?: string;
 }
 
 function serializeRecordMetadata(row: ProvenanceRecordSummary): RecordMetadata {
@@ -371,6 +402,7 @@ function serializeRecordMetadata(row: ProvenanceRecordSummary): RecordMetadata {
       },
     }),
     signed: row.signed,
+    ...(row.projectId !== undefined && { projectId: row.projectId as unknown as string }),
   };
 }
 
@@ -404,3 +436,18 @@ function parseExportBody(body: Record<string, unknown>): ParseResult<ValidatedEx
     },
   };
 }
+
+/** The run's call usage, when the binding has a cost ledger and the run made calls. */
+async function readCallUsage(
+  binding: ProvenanceBinding,
+  tenantId: TenantId,
+  runId: RunId,
+): Promise<
+  | { readonly kind: 'ok'; readonly value: CallUsageByCallId | undefined }
+  | { readonly kind: 'err'; readonly error: ProvenanceBindingError }
+> {
+  if (binding.getCallUsage === undefined) return { kind: 'ok', value: undefined };
+  const read = await binding.getCallUsage(tenantId, runId);
+  if (read.kind === 'err') return read;
+  return { kind: 'ok', value: Object.keys(read.value).length > 0 ? read.value : undefined };
+}