@kindgi/api 0.1.2 → 0.1.4-rc.0

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,16 @@ 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' },
+    replayOf: {
+      type: 'string',
+      format: 'uuid',
+      description: 'Set on a replay run (an eval run re-running a past run): the run it replays.',
+    },
+    evalRunId: {
+      type: 'string',
+      description: 'Set on a replay run: the eval run that started it.',
+    },
     publicAccessToken: {
       type: 'string',
       description:
@@ -557,6 +584,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 +649,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.",
     },
   },
 };
@@ -887,8 +937,23 @@ export const AgentSchema: JsonSchema = {
     version: { type: 'string', description: 'Semver.' },
     name: { type: 'string' },
     description: { type: 'string' },
-    instructions: { type: 'string' },
+    instructions: {
+      oneOf: [{ type: 'string', minLength: 1 }, { $ref: '#/components/schemas/PromptRef' }],
+      description:
+        'The system prompt (a Liquid template), or a prompt block by range whose template and parameters are used instead (pinned at publish, `pins.prompts`).',
+    },
     parameters: { type: 'array', items: { $ref: '#/components/schemas/PromptParameter' } },
+    settings: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/BlockRef' },
+      description:
+        'Settings blocks the agent reads, by range: tools read them as `ToolContext.settings[\'<id>\']`, templates as `settings["<id>"]`. Pinned at publish (`pins.settings`).',
+    },
+    modelSettings: {
+      $ref: '#/components/schemas/BlockRef',
+      description:
+        "A model-settings block by range: its `temperature` and `maxOutputTokens` go into the turn's model calls. Pinned at publish.",
+    },
     capabilities: { type: 'array', items: { $ref: '#/components/schemas/Capability' } },
     tools: { type: 'array', items: { $ref: '#/components/schemas/ToolRef' } },
     retrieval: { type: 'array', items: { $ref: '#/components/schemas/RetrievalIntent' } },
@@ -910,6 +975,108 @@ export const AgentSchema: JsonSchema = {
     tags: { type: 'array', items: { type: 'string' } },
     output: { $ref: '#/components/schemas/AgentOutputSpec' },
     toolErrors: { $ref: '#/components/schemas/ToolErrorsSpec' },
+    pins: { $ref: '#/components/schemas/AgentPins' },
+    derivedFrom: { $ref: '#/components/schemas/VersionDerivation' },
+    unregisteredAt: {
+      type: 'string',
+      format: 'date-time',
+      description:
+        'Present only on an unregistered version (`GET …/versions/{version}` reads those too). Unregister stops a version being chosen, not the pins that hold it: a new run naming it is refused, while a resumed run and a published version that pins it still run it.',
+    },
+    pinsDigest: {
+      type: 'string',
+      pattern: '^sha256:[0-9a-f]{64}$',
+      description:
+        "Set by the runtime with `pins`: `sha256:<hex>` of the pins' canonical JSON (sorted keys, no whitespace). Two agent versions with the same digest run the same blocks.",
+    },
+  },
+};
+
+export const VersionDerivationSchema: JsonSchema = {
+  description:
+    "Set by the runtime on an agent or flow version a deploy registered in place of the definition's version, which was registered already with other pins or content (versions never change). Never in the publish body.",
+  type: 'object',
+  additionalProperties: false,
+  required: ['version', 'reason'],
+  properties: {
+    version: { type: 'string', description: 'The version the definition names.' },
+    reason: {
+      type: 'string',
+      enum: ['pins-changed', 'unpinned', 'version-taken', 'edited'],
+      description:
+        "`pins-changed`: a block it uses has a new version; `unpinned`: the definition's version was published before pins existed; `version-taken`: the definition's version holds another definition; `edited`: derived from `version` with some data-block pins swapped (`POST /v1/agents/{agentId}/versions`).",
+    },
+    label: { type: 'string', description: 'For `edited`: a short label for the version.' },
+    by: { type: 'string', description: 'For `edited`: who derived it (`user:<id>`).' },
+  },
+};
+
+export const DeriveAgentVersionBodySchema: JsonSchema = {
+  description:
+    "Derive a new agent version from a pinned one with some data-block pins swapped: an expert's edit reaching an agent with no code change.",
+  type: 'object',
+  additionalProperties: false,
+  required: ['from', 'pins'],
+  properties: {
+    from: { type: 'string', description: 'The version to derive from (it must be pinned).' },
+    pins: { $ref: '#/components/schemas/AgentPinSwaps' },
+    label: { type: 'string', description: 'A short label for the new version.' },
+    projectId: {
+      type: 'string',
+      format: 'uuid',
+      description: "The agent's project, when the runtime doesn't record it on the version.",
+    },
+  },
+};
+
+const PinMapSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: { type: 'string' },
+};
+
+export const AgentPinSwapsSchema: JsonSchema = {
+  description:
+    'The data-block pins to swap, by block id → exact version. Only blocks the version already references; tool pins come from code.',
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    prompts: { ...PinMapSchema, description: 'Prompt block id → exact version.' },
+    settings: { ...PinMapSchema, description: 'Settings block id → exact version.' },
+  },
+};
+
+export const AgentPinsSchema: JsonSchema = {
+  description:
+    'The exact block versions an agent version runs: its lockfile. Set by the runtime when the version is published, never in the publish body: each tool range resolves once to the version every run of that agent version uses, so a new tool version reaches the agent only through a new agent version. Absent on a version published before pins existed (its ranges resolve per run).',
+  type: 'object',
+  additionalProperties: false,
+  required: ['tools', 'prompts', 'settings'],
+  properties: {
+    tools: { ...PinMapSchema, description: 'Tool id → exact version.' },
+    prompts: { ...PinMapSchema, description: 'Prompt block id → exact version.' },
+    settings: { ...PinMapSchema, description: 'Settings block id → exact version.' },
+  },
+};
+
+export const PromptRefSchema: JsonSchema = {
+  description: "A prompt block an agent's instructions come from, by id and semver range.",
+  type: 'object',
+  additionalProperties: false,
+  required: ['prompt', 'version'],
+  properties: {
+    prompt: { type: 'string', description: 'The prompt block id.' },
+    version: { type: 'string', description: 'A semver range (`^1.0.0`, `1.2.0`).' },
+  },
+};
+
+export const BlockRefSchema: JsonSchema = {
+  description: 'A settings block an agent reads, by id and semver range.',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version'],
+  properties: {
+    id: { type: 'string', description: 'The settings block id.' },
+    version: { type: 'string', description: 'A semver range (`^1.0.0`, `1.2.0`).' },
   },
 };
 
@@ -935,8 +1102,23 @@ export const PublishAgentBodySchema: JsonSchema = {
     name: { type: 'string' },
     description: { type: 'string' },
     projectId: ContentProjectIdProperty,
-    instructions: { type: 'string' },
+    instructions: {
+      oneOf: [{ type: 'string', minLength: 1 }, { $ref: '#/components/schemas/PromptRef' }],
+      description:
+        'The system prompt (a Liquid template), or a prompt block by range whose template and parameters are used instead (pinned at publish, `pins.prompts`).',
+    },
     parameters: { type: 'array', items: { $ref: '#/components/schemas/PromptParameter' } },
+    settings: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/BlockRef' },
+      description:
+        'Settings blocks the agent reads, by range: tools read them as `ToolContext.settings[\'<id>\']`, templates as `settings["<id>"]`. Pinned at publish (`pins.settings`).',
+    },
+    modelSettings: {
+      $ref: '#/components/schemas/BlockRef',
+      description:
+        "A model-settings block by range: its `temperature` and `maxOutputTokens` go into the turn's model calls. Pinned at publish.",
+    },
     capabilities: { type: 'array', items: { $ref: '#/components/schemas/Capability' } },
     tools: { type: 'array', items: { $ref: '#/components/schemas/ToolRef' } },
     retrieval: { type: 'array', items: { $ref: '#/components/schemas/RetrievalIntent' } },
@@ -1073,6 +1255,35 @@ export const FlowSchema: JsonSchema = {
     edges: { type: 'array', items: { $ref: '#/components/schemas/FlowEdge' } },
     maxParallelism: { type: 'integer', minimum: 1 },
     metadata: { type: 'object', additionalProperties: true },
+    pins: { $ref: '#/components/schemas/FlowPins' },
+    pinsDigest: {
+      type: 'string',
+      pattern: '^sha256:[0-9a-f]{64}$',
+      description:
+        "Set by the runtime with `pins`: `sha256:<hex>` of the pins' canonical JSON (sorted keys, no whitespace).",
+    },
+    derivedFrom: { $ref: '#/components/schemas/VersionDerivation' },
+    unregisteredAt: {
+      type: 'string',
+      format: 'date-time',
+      description:
+        'Present only on an unregistered version (`GET …/versions/{version}` reads those too). Unregister stops a version being chosen, not the pins that hold it: a new run naming it is refused, while a resumed run and a published version that pins it still run it.',
+    },
+  },
+};
+
+export const FlowPinsSchema: JsonSchema = {
+  description:
+    'The exact tool and agent versions a flow version runs: its lockfile. Set by the runtime when the version is published, never in the publish body: each tool the flow runs, and each agent it runs at no named version, resolves once to its latest version then, which every run of that flow version uses. Absent on a version published before pins existed (it binds the latest versions per run).',
+  type: 'object',
+  additionalProperties: false,
+  required: ['tools', 'agents'],
+  properties: {
+    tools: { ...PinMapSchema, description: 'Tool id → exact version.' },
+    agents: {
+      ...PinMapSchema,
+      description: 'Agent id → exact version, for agent nodes that name no version.',
+    },
   },
 };
 
@@ -1652,6 +1863,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 +1923,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,
@@ -1811,21 +2034,484 @@ export const ObservationSchema: JsonSchema = {
         provenanceId: { type: 'string', format: 'uuid' },
       },
     },
-    observedAt: { type: 'string', format: 'date-time' },
+    observedAt: { type: 'string', format: 'date-time' },
+  },
+};
+
+export const ObservationCollectionPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/Observation' } },
+    nextCursor: {
+      type: 'string',
+      description: 'Opaque ISO-timestamp cursor. Treat as opaque on the client.',
+    },
+    hasMore: { type: 'boolean' },
+  },
+};
+
+// ---------------- judgments + judge classes ----------------
+
+export const JudgeClassScopeSchema: JsonSchema = {
+  description:
+    'Where a judge class applies: the whole tenant, one project, or one agent in a project.',
+  oneOf: [
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind'],
+      properties: { kind: { type: 'string', const: 'tenant' } },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'projectId'],
+      properties: {
+        kind: { type: 'string', const: 'project' },
+        projectId: { type: 'string', minLength: 1 },
+      },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['kind', 'projectId', 'agentId'],
+      properties: {
+        kind: { type: 'string', const: 'agent' },
+        projectId: { type: 'string', minLength: 1 },
+        agentId: { type: 'string', minLength: 1 },
+      },
+    },
+  ],
+};
+
+export const JudgeClassSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'tenantId', 'scope', 'name', 'weight', 'createdAt', 'updatedAt'],
+  properties: {
+    id: { type: 'string' },
+    tenantId: { type: 'string' },
+    scope: { $ref: '#/components/schemas/JudgeClassScope' },
+    name: {
+      type: 'string',
+      description: 'The deployment\'s own word for the class: "expert", "user", "arbitrator".',
+    },
+    weight: {
+      type: 'number',
+      minimum: 0,
+      description: 'How much a judgment of this class counts, relative to the others.',
+    },
+    description: { type: 'string' },
+    createdAt: { type: 'string', format: 'date-time' },
+    updatedAt: { type: 'string', format: 'date-time' },
+    unregisteredAt: {
+      type: 'string',
+      format: 'date-time',
+      description: 'Set when the class was retired.',
+    },
+  },
+};
+
+export const JudgeClassCollectionPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/JudgeClass' } },
+    nextCursor: { type: 'string', description: 'Opaque cursor. Treat as opaque on the client.' },
+    hasMore: { type: 'boolean' },
+  },
+};
+
+export const CreateJudgeClassBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['scope', 'name', 'weight'],
+  properties: {
+    scope: { $ref: '#/components/schemas/JudgeClassScope' },
+    name: { type: 'string', minLength: 1, maxLength: 100 },
+    weight: { type: 'number', minimum: 0 },
+    description: { type: 'string' },
+  },
+};
+
+export const UpdateJudgeClassBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  minProperties: 1,
+  properties: {
+    weight: { type: 'number', minimum: 0 },
+    description: { type: 'string' },
+  },
+};
+
+export const UnregisterJudgeClassResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['judgeClassId', 'unregistered'],
+  properties: {
+    judgeClassId: { type: 'string' },
+    unregistered: { type: 'boolean', const: true },
+  },
+};
+
+export const JudgedSubjectSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['kind', 'id', 'version'],
+  description: 'What a judged run ran: an agent at a version, or a flow at a version.',
+  properties: {
+    kind: { type: 'string', enum: ['agent', 'flow'] },
+    id: { type: 'string' },
+    version: { type: 'string' },
+  },
+};
+
+export const JudgedItemSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['key'],
+  description: "The judged item of a run's output.",
+  properties: {
+    key: { type: 'string', minLength: 1, description: "The caller's stable id for the item." },
+    pointer: {
+      type: 'string',
+      description:
+        'Where the item is in the run\'s output, as a JSON Pointer (RFC 6901), e.g. `/matches/2`. `""` is the whole output.',
+    },
+    rank: {
+      type: 'integer',
+      minimum: 0,
+      description: "The item's position in a ranked list (0 = first).",
+    },
+  },
+};
+
+export const JudgmentAssertedBySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['kind', 'id'],
+  description: 'Who asserted a judgment: the authenticated caller, never a typed name.',
+  properties: {
+    kind: { type: 'string', enum: ['user', 'service'] },
+    id: {
+      type: 'string',
+      description: 'A user id, or for a service token its token or session id.',
+    },
+  },
+};
+
+export const JudgmentSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'id',
+    'tenantId',
+    'projectId',
+    'runId',
+    'subject',
+    'item',
+    'verdict',
+    'assertedBy',
+    'createdAt',
+  ],
+  properties: {
+    id: { type: 'string' },
+    tenantId: { type: 'string' },
+    projectId: { type: 'string' },
+    runId: { type: 'string' },
+    subject: { $ref: '#/components/schemas/JudgedSubject' },
+    item: { $ref: '#/components/schemas/JudgedItem' },
+    verdict: { type: 'string', enum: ['yes', 'no'] },
+    reason: { type: 'string' },
+    judgeClassId: {
+      type: 'string',
+      description:
+        'The judge class the judgment is recorded under. Absent when unclassified (counts with weight 1).',
+    },
+    assertedBy: { $ref: '#/components/schemas/JudgmentAssertedBy' },
+    participantId: {
+      type: 'string',
+      description:
+        "The app's opaque id for its end user who judged, when an app judged on their behalf.",
+    },
+    createdAt: { type: 'string', format: 'date-time' },
+    unregisteredAt: {
+      type: 'string',
+      format: 'date-time',
+      description: 'Set when the judgment was removed or superseded.',
+    },
+    supersededBy: { type: 'string', description: 'The judgment that replaced this one.' },
+  },
+};
+
+export const JudgedRunContextSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  description:
+    'What a judged run needs besides its input to be replayed, captured when it was first judged. For an agent turn: the conversation before it, what its retrievals returned, and the decision at its session approval gate. For a flow run: its tool calls with their results.',
+  properties: {
+    history: {
+      type: 'array',
+      items: {},
+      description:
+        "The conversation's messages before the turn, oldest first (at most the last 200).",
+    },
+    historyTruncated: {
+      type: 'boolean',
+      description: 'Whether older messages were left out of `history`.',
+    },
+    retrieved: { description: "What the turn's retrievals returned." },
+    sessionApproval: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['approved'],
+      description:
+        "The reviewer's decision at the turn's session approval gate, when the turn waited on one. A replay of the turn follows it.",
+      properties: {
+        approved: { type: 'boolean' },
+        rationale: { type: 'string', description: "The reviewer's reason for a rejection." },
+      },
+    },
+    flow: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['calls', 'steps'],
+      description:
+        "For a flow run: what it did, kept at its first judgment so it can be replayed. Every tool call it made with its result (at its tool nodes, in its agent steps' turns and in its sub-flows), at most 500, and its agent steps.",
+      properties: {
+        calls: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['runId', 'toolId'],
+            properties: {
+              runId: {
+                type: 'string',
+                description:
+                  "The run that made it: the flow run, a sub-flow's, or an agent step's turn.",
+              },
+              nodeId: {
+                type: 'string',
+                description: 'The tool node that made it, or the agent step whose turn did.',
+              },
+              scope: { type: 'string', description: 'The loop iteration, in a loop body.' },
+              toolId: { type: 'string' },
+              arguments: {},
+              result: {},
+            },
+          },
+        },
+        steps: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['runId', 'agentId', 'agentVersion'],
+            properties: {
+              runId: { type: 'string' },
+              nodeId: { type: 'string' },
+              scope: { type: 'string' },
+              agentId: { type: 'string' },
+              agentVersion: { type: 'string' },
+              retrieved: { description: "What the step's turn retrieved." },
+            },
+          },
+        },
+        truncated: { type: 'boolean', description: 'More calls were made than were kept.' },
+      },
+    },
+  },
+};
+
+export const JudgedRunCopySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['runId', 'subject', 'input', 'output', 'capturedAt'],
+  description:
+    "The stored copy of a judged run's input and output, taken when it was first judged.",
+  properties: {
+    runId: { type: 'string' },
+    subject: { $ref: '#/components/schemas/JudgedSubject' },
+    input: {},
+    context: {
+      $ref: '#/components/schemas/JudgedRunContext',
+    },
+    output: {},
+    capturedAt: { type: 'string', format: 'date-time' },
+  },
+};
+
+export const JudgmentWithCopiesSchema: JsonSchema = {
+  description: 'A judgment with the stored copies of what was judged.',
+  allOf: [
+    { $ref: '#/components/schemas/Judgment' },
+    {
+      type: 'object',
+      required: ['run'],
+      properties: {
+        run: { $ref: '#/components/schemas/JudgedRunCopy' },
+        itemValue: {
+          description: "The judged item's value, when the judgment pointed at it.",
+        },
+      },
+    },
+  ],
+};
+
+export const JudgmentCollectionPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/Judgment' } },
+    nextCursor: { type: 'string', description: 'Opaque cursor. Treat as opaque on the client.' },
+    hasMore: { type: 'boolean' },
+  },
+};
+
+export const CreateJudgmentBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['runId', 'item', 'verdict'],
+  properties: {
+    runId: { type: 'string', minLength: 1 },
+    item: { $ref: '#/components/schemas/JudgedItem' },
+    verdict: { type: 'string', enum: ['yes', 'no'] },
+    reason: { type: 'string', maxLength: 4000 },
+    judgeClassId: {
+      type: 'string',
+      minLength: 1,
+      description: 'Optional. When given it must exist and apply to the run.',
+    },
+    participantId: {
+      type: 'string',
+      minLength: 1,
+      description: "An app's opaque id for its end user, when judging on their behalf.",
+    },
+  },
+};
+
+export const UnregisterJudgmentResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['judgmentId', 'unregistered'],
+  properties: {
+    judgmentId: { type: 'string' },
+    unregistered: { type: 'boolean', const: true },
+  },
+};
+
+export const JudgedItemSummarySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['key', 'yes', 'no', 'yesWeight', 'totalWeight', 'reasons'],
+  description: "The judgments of one item of a case's output, summed up.",
+  properties: {
+    key: { type: 'string' },
+    pointer: { type: 'string' },
+    rank: { type: 'integer', minimum: 0 },
+    yes: { type: 'integer', minimum: 0, description: 'How many judgments said yes.' },
+    no: { type: 'integer', minimum: 0, description: 'How many judgments said no.' },
+    yesWeight: {
+      type: 'number',
+      description: 'The weight behind "yes" (an unclassified judgment counts 1).',
+    },
+    totalWeight: { type: 'number', description: 'The weight behind all judgments of the item.' },
+    reasons: {
+      type: 'array',
+      description: 'The reasons given, newest first.',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['verdict', 'reason'],
+        properties: {
+          verdict: { type: 'string', enum: ['yes', 'no'] },
+          reason: { type: 'string' },
+        },
+      },
+    },
+  },
+};
+
+export const JudgedEvalCaseSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['caseId', 'subject', 'input', 'output', 'items'],
+  description:
+    "One case of a `judged` eval suite: a copy of a judged run with its items' judgments summed up.",
+  properties: {
+    caseId: { type: 'string', description: "The judged run's id." },
+    subject: { $ref: '#/components/schemas/JudgedSubject' },
+    input: {},
+    context: { $ref: '#/components/schemas/JudgedRunContext' },
+    output: {},
+    items: { type: 'array', items: { $ref: '#/components/schemas/JudgedItemSummary' } },
+  },
+};
+
+export const JudgedEvalCaseCollectionPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/JudgedEvalCase' } },
+    nextCursor: { type: 'string', description: 'Opaque cursor. Treat as opaque on the client.' },
+    hasMore: { type: 'boolean' },
+  },
+};
+
+export const BuildJudgedSuiteBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['version', 'projectId'],
+  description: 'Name the agent (`agentId`) or the flow (`flowId`) whose judged runs to use.',
+  properties: {
+    version: { type: 'string', description: 'Semver version to publish, e.g. `1.0.0`.' },
+    projectId: { type: 'string', minLength: 1 },
+    agentId: { type: 'string', minLength: 1 },
+    agentVersion: { type: 'string', minLength: 1, description: 'Needs `agentId`.' },
+    flowId: { type: 'string', minLength: 1 },
+    since: {
+      type: 'string',
+      format: 'date-time',
+      description: 'Runs first judged at or after this time.',
+    },
+    until: {
+      type: 'string',
+      format: 'date-time',
+      description: 'Runs first judged before this time.',
+    },
+    judgeClassIds: {
+      type: 'array',
+      items: { type: 'string', minLength: 1 },
+      description: 'Count only judgments recorded under these judge classes.',
+    },
+    minJudgments: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Leave out runs with fewer counted judgments. Default 1.',
+    },
+    description: { type: 'string' },
   },
 };
 
-export const ObservationCollectionPageSchema: JsonSchema = {
+export const BuildJudgedSuiteResultSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
-  required: ['data', 'hasMore'],
+  required: ['suiteId', 'version', 'kind', 'caseCount', 'truncated'],
   properties: {
-    data: { type: 'array', items: { $ref: '#/components/schemas/Observation' } },
-    nextCursor: {
-      type: 'string',
-      description: 'Opaque ISO-timestamp cursor. Treat as opaque on the client.',
+    suiteId: { type: 'string' },
+    version: { type: 'string' },
+    kind: { type: 'string', enum: ['judged'] },
+    caseCount: { type: 'integer', minimum: 0 },
+    truncated: {
+      type: 'boolean',
+      description: 'Whether more judged runs matched than the 1000 cases a set holds.',
     },
-    hasMore: { type: 'boolean' },
   },
 };
 
@@ -2483,6 +3169,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 +3200,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 +3252,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 +3274,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' },
@@ -2863,6 +3572,14 @@ export const ProviderMetadataSchema: JsonSchema = {
       description:
         "A fallback serves a capability only when no other provider satisfies it (e.g. `kindgi dev`'s scripted `dev-echo`); an agent turn routed to one carries a `fallback-provider` warning. Absent = `false`.",
     },
+    labels: {
+      type: 'object',
+      maxProperties: 32,
+      propertyNames: { pattern: '^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$' },
+      additionalProperties: { type: 'string', maxLength: 256 },
+      description:
+        'Bookkeeping, such as who manages the provider; the router ignores labels. At most 32 keys; a key is 1-63 lowercase letters and digits, with `.`, `-`, `_` or `/` inside; a value is at most 256 characters. The convention key `kindgi.com/managed-by` names the manager (`kindgi-dev`, `kindgi-deploy:<environment>`). Out of bounds: `400 invalid-provider`, reason `invalid-labels`.',
+    },
   },
 };
 
@@ -3243,7 +3960,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 +4058,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 +4135,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,20 +4145,35 @@ 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',
       items: { $ref: '#/components/schemas/CostAggregateGroup' },
+      description:
+        'The most expensive groups first (`totalUsd` descending, ties by key), at most `limit`.',
+    },
+    totalGroups: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'How many groups there were before the `limit` cap. Absent from a runtime before 0.1.5.',
+    },
+    truncated: {
+      type: 'boolean',
+      description:
+        '`true` when there were more groups than `limit`: `groups` holds the most expensive ones, and `totalUsd` / `totalRecords` / `tokens` still cover every record. Absent from a runtime before 0.1.5.',
     },
     totalUsd: { type: 'number', minimum: 0 },
     totalRecords: { type: 'integer', minimum: 0 },
+    tokens: { $ref: '#/components/schemas/CostTokenTotals' },
     timeRange: {
       type: 'object',
       additionalProperties: false,
@@ -3610,7 +4457,7 @@ export const ReinstatePolicyVersionResultSchema: JsonSchema = {
  */
 export const EvalKindSchema: JsonSchema = {
   type: 'string',
-  enum: ['accuracy', 'pairwise', 'regression', 'human-review', 'benchmark', 'custom'],
+  enum: ['accuracy', 'pairwise', 'regression', 'human-review', 'benchmark', 'custom', 'judged'],
 };
 
 /**
@@ -3711,6 +4558,138 @@ export const ReinstateEvalSuiteVersionResultSchema: JsonSchema = {
   },
 };
 
+// ---------------- data blocks ----------------
+
+export const BlockKindSchema: JsonSchema = {
+  type: 'string',
+  enum: ['prompt', 'settings'],
+  description:
+    '`prompt`: a Liquid template an agent renders as its instructions. `settings`: a JSON object tools and templates read.',
+};
+
+export const PromptBlockContentSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['template'],
+  properties: {
+    template: {
+      type: 'string',
+      minLength: 1,
+      description:
+        "Liquid, rendered as an agent's instructions are (same parameters and auto-injected variables).",
+    },
+    parameters: { type: 'array', items: { $ref: '#/components/schemas/PromptParameter' } },
+  },
+};
+
+export const SettingsBlockContentSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['values'],
+  properties: {
+    values: {
+      type: 'object',
+      additionalProperties: true,
+      description:
+        'What tools read (`ToolContext.settings[<block id>]`) and templates read (`settings.<block id>.<key>`).',
+    },
+    schema: {
+      type: 'object',
+      additionalProperties: true,
+      description:
+        "JSON Schema (draft 2020-12) the values must satisfy. A later version's values must satisfy the latest version's schema too.",
+    },
+  },
+};
+
+export const BlockSchema: JsonSchema = {
+  description:
+    'A data block version: a prompt or settings, versioned like a tool (immutable versions, soft unregister). An agent version pins the block versions it uses when it is published. Belongs to one project and is authorized through it.',
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version', 'kind', 'content', 'projectId', 'publishedAt'],
+  properties: {
+    id: { type: 'string', description: 'Dotted lowercase id (e.g. `acme.intake-prompt`).' },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    kind: { $ref: '#/components/schemas/BlockKind' },
+    description: { type: 'string' },
+    content: {
+      oneOf: [
+        { $ref: '#/components/schemas/PromptBlockContent' },
+        { $ref: '#/components/schemas/SettingsBlockContent' },
+      ],
+      description: '`PromptBlockContent` for a prompt, `SettingsBlockContent` for settings.',
+    },
+    projectId: { type: 'string', format: 'uuid' },
+    publishedAt: { type: 'string', format: 'date-time' },
+    unregisteredAt: {
+      type: 'string',
+      format: 'date-time',
+      description:
+        'Present only on an unregistered version; agent versions that pin it still read it.',
+    },
+  },
+};
+
+export const BlockCollectionPageSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['data', 'hasMore'],
+  properties: {
+    data: { type: 'array', items: { $ref: '#/components/schemas/Block' } },
+    nextCursor: { type: 'string' },
+    hasMore: { type: 'boolean' },
+  },
+};
+
+export const PublishBlockBodySchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['projectId', 'id', 'version', 'kind', 'content'],
+  properties: {
+    projectId: ContentProjectIdProperty,
+    id: { type: 'string', minLength: 1 },
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    kind: { $ref: '#/components/schemas/BlockKind' },
+    description: { type: 'string' },
+    content: {
+      oneOf: [
+        { $ref: '#/components/schemas/PromptBlockContent' },
+        { $ref: '#/components/schemas/SettingsBlockContent' },
+      ],
+    },
+  },
+};
+
+export const PublishBlockResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['blockId', 'version'],
+  properties: { blockId: { type: 'string' }, version: { type: 'string' } },
+};
+
+export const UnregisterBlockResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['blockId', 'version', 'unregistered'],
+  properties: {
+    blockId: { type: 'string' },
+    version: { type: 'string' },
+    unregistered: { type: 'boolean', const: true },
+  },
+};
+
+export const ReinstateBlockResultSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['blockId', 'version', 'wasTombstoned'],
+  properties: {
+    blockId: { type: 'string' },
+    version: { type: 'string' },
+    wasTombstoned: { type: 'boolean' },
+  },
+};
+
 // ---------------- eval runs (admin plane) ----------------
 
 /**
@@ -3743,6 +4722,53 @@ export const EvalRunFlowRefSchema: JsonSchema = {
   },
 };
 
+export const EvalBaselineSchema: JsonSchema = {
+  description:
+    "What a comparison compares the candidate against: `'recorded'` (each case's recorded output, what was judged), a version (`{ agentId, version }`, replayed under the same rules), or the version live in a scope (`{ live: { projectId?, segments? } }`). Only `'recorded'` runs today; the others are refused when the run starts.",
+  oneOf: [
+    { type: 'string', enum: ['recorded'] },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['agentId', 'version'],
+      properties: { agentId: { type: 'string' }, version: { type: 'string' } },
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['live'],
+      properties: {
+        live: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            projectId: { type: 'string' },
+            segments: { type: 'object', additionalProperties: { type: 'string' } },
+          },
+        },
+      },
+    },
+  ],
+};
+
+export const EvalComparisonSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['baseline', 'reads', 'repetitions', 'k'],
+  description: "A comparison eval run's settings (a `judged` suite).",
+  properties: {
+    baseline: { $ref: '#/components/schemas/EvalBaseline' },
+    reads: {
+      type: 'string',
+      enum: ['recorded', 'live'],
+      description:
+        "Whether replayed reads use the past run's results when it has them (`recorded`), or run live.",
+    },
+    repetitions: { type: 'integer', minimum: 1, maximum: 10 },
+    k: { type: 'integer', minimum: 1, maximum: 100 },
+  },
+};
+
 export const EvalRunSchema: JsonSchema = {
   type: 'object',
   additionalProperties: false,
@@ -3772,10 +4798,11 @@ export const EvalRunSchema: JsonSchema = {
       type: 'object',
       additionalProperties: true,
       description:
-        'Kind-specific opaque JSON. For `accuracy`, contains `{ passCount, totalCount, meanScore, perCase[] }`. Other kinds define their own shapes as their dispatchers ship.',
+        'Kind-specific opaque JSON. For `accuracy`, contains `{ passCount, totalCount, meanScore, perCase[] }`. For `judged` (a comparison), `{ summary, perCase[] }`: the summary has the baseline (the versions behind the recorded runs) and the candidate (`{ kind: "agent", agentId, version }` or `{ kind: "flow", flowId, version }`), the case counts (`cases`, `diverged`, `refusedWrites`, `errors`, and `stopped`: flow cases that stopped at a write the replay refused, left out of the metrics), the models that answered, and `metrics` (`weightedYesShare`, `judgedCoverage`, `weightedPrecisionAtK`, each `{ baseline, candidate, delta, n, weight, baselineN, baselineWeight, direction, k?, spread? }`); each case has its replay runs, the scores, the items kept, dropped and new, the tool calls with what happened to each, and `stopped` (what it would have done) when it stopped. Other kinds define their own shapes as their dispatchers ship.',
     },
     error: { type: 'string' },
     correlationId: { type: 'string' },
+    comparison: { $ref: '#/components/schemas/EvalComparison' },
   },
 };
 
@@ -3800,9 +4827,13 @@ export const StartEvalRunBodySchema: JsonSchema = {
     flowRef: { $ref: '#/components/schemas/EvalRunFlowRef' },
     dryRun: { type: 'boolean' },
     correlationId: { type: 'string' },
+    baseline: { $ref: '#/components/schemas/EvalBaseline' },
+    reads: { type: 'string', enum: ['recorded', 'live'] },
+    repetitions: { type: 'integer', minimum: 1, maximum: 10 },
+    k: { type: 'integer', minimum: 1, maximum: 100 },
   },
   description:
-    'Exactly one of `agentRef` or `flowRef` MUST be supplied. `dryRun: true` returns a plan preview without invoking the subject.',
+    "Exactly one of `agentRef` or `flowRef` MUST be supplied. `dryRun: true` returns a plan preview without invoking the subject. For a `judged` suite (a test set), the run is a comparison: `agentRef` or `flowRef` with its `version` is the candidate, replayed on each case without doing anything the past run didn't (a flow stops at a write the replay refuses); `baseline` (default `'recorded'`), `reads` (default `recorded`), `repetitions` (default 1) and `k` (default 10) set how.",
 };
 
 export const StartEvalRunResultSchema: JsonSchema = {
@@ -3980,7 +5011,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'],
@@ -4090,6 +5121,49 @@ const DeployedPrimitiveSchema: JsonSchema = {
   },
 };
 
+const DeployedVersionSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['id', 'version'],
+  properties: {
+    id: { type: 'string' },
+    version: { type: 'string', description: 'The version the agent is registered as.' },
+    authoredVersion: {
+      type: 'string',
+      description:
+        "The version the agent's or flow's definition names, present when it differs from `version`: that version was registered already with other pins or content, and versions never change, so the deploy registered the next free version in its line (or an earlier deploy did).",
+    },
+    reason: {
+      type: 'string',
+      enum: ['pins-changed', 'unpinned', 'version-taken'],
+      description:
+        'Why `version` differs from `authoredVersion`: `pins-changed` (a tool or agent it uses has a new version), `unpinned` (`authoredVersion` was published before pins existed), `version-taken` (`authoredVersion` is registered with other content).',
+    },
+    newVersion: {
+      type: 'boolean',
+      description: '`true`: this deploy registered `version`; `false`: an earlier deploy did.',
+    },
+    pinChanges: {
+      type: 'array',
+      description: "For `pins-changed`: the pins that differ from `authoredVersion`'s.",
+      items: { $ref: '#/components/schemas/PinChange' },
+    },
+  },
+};
+
+export const PinChangeSchema: JsonSchema = {
+  description: 'One pin that differs between two versions of an agent or a flow.',
+  type: 'object',
+  additionalProperties: false,
+  required: ['kind', 'id'],
+  properties: {
+    kind: { type: 'string', enum: ['tool', 'prompt', 'setting', 'agent'] },
+    id: { type: 'string' },
+    from: { type: 'string', description: "The earlier version's pin; absent when it had none." },
+    to: { type: 'string', description: "The later version's pin; absent when it has none." },
+  },
+};
+
 /**
  * Exactly what a deployment shipped. Versions are immutable, so this
  * says which code the deployment made live.
@@ -4101,8 +5175,8 @@ export const DeploymentContentsSchema: JsonSchema = {
   properties: {
     tools: { type: 'array', items: DeployedPrimitiveSchema },
     guardrails: { type: 'array', items: DeployedPrimitiveSchema },
-    agents: { type: 'array', items: DeployedPrimitiveSchema },
-    flows: { type: 'array', items: DeployedPrimitiveSchema },
+    agents: { type: 'array', items: DeployedVersionSchema },
+    flows: { type: 'array', items: DeployedVersionSchema },
   },
 };
 
@@ -5844,6 +6918,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 +6961,7 @@ export const FinishedRunSchema: JsonSchema = {
     },
     createdAt: { type: 'string', format: 'date-time' },
     completedAt: { type: 'string', format: 'date-time' },
+    usage: { $ref: '#/components/schemas/RunTreeUsage' },
   },
 };
 
@@ -6020,6 +7109,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 +7137,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['ApprovalStatus', ApprovalStatusSchema],
   ['ReviewDecisionKind', ReviewDecisionKindSchema],
   ['Approval', ApprovalSchema],
+  ['ApprovalDecisionRecord', ApprovalDecisionRecordSchema],
   ['ReviewDecision', ReviewDecisionSchema],
   ['ApprovalCollectionPage', ApprovalCollectionPageSchema],
   ['CompleteApprovalBody', CompleteApprovalBodySchema],
@@ -6060,6 +7151,27 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['ObservationStatus', ObservationStatusSchema],
   ['Observation', ObservationSchema],
   ['ObservationCollectionPage', ObservationCollectionPageSchema],
+  ['JudgeClassScope', JudgeClassScopeSchema],
+  ['JudgeClass', JudgeClassSchema],
+  ['JudgeClassCollectionPage', JudgeClassCollectionPageSchema],
+  ['CreateJudgeClassBody', CreateJudgeClassBodySchema],
+  ['UpdateJudgeClassBody', UpdateJudgeClassBodySchema],
+  ['UnregisterJudgeClassResult', UnregisterJudgeClassResultSchema],
+  ['JudgedSubject', JudgedSubjectSchema],
+  ['JudgedItem', JudgedItemSchema],
+  ['JudgmentAssertedBy', JudgmentAssertedBySchema],
+  ['Judgment', JudgmentSchema],
+  ['JudgedRunContext', JudgedRunContextSchema],
+  ['JudgedRunCopy', JudgedRunCopySchema],
+  ['JudgmentWithCopies', JudgmentWithCopiesSchema],
+  ['JudgmentCollectionPage', JudgmentCollectionPageSchema],
+  ['CreateJudgmentBody', CreateJudgmentBodySchema],
+  ['UnregisterJudgmentResult', UnregisterJudgmentResultSchema],
+  ['JudgedItemSummary', JudgedItemSummarySchema],
+  ['JudgedEvalCase', JudgedEvalCaseSchema],
+  ['JudgedEvalCaseCollectionPage', JudgedEvalCaseCollectionPageSchema],
+  ['BuildJudgedSuiteBody', BuildJudgedSuiteBodySchema],
+  ['BuildJudgedSuiteResult', BuildJudgedSuiteResultSchema],
   ['PromptParameter', PromptParameterSchema],
   ['RetrievalIntent', RetrievalIntentSchema],
   ['ConversationPolicy', ConversationPolicySchema],
@@ -6069,6 +7181,14 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['AgentOutputSpec', AgentOutputSpecSchema],
   ['ToolErrorsSpec', ToolErrorsSpecSchema],
   ['Agent', AgentSchema],
+  ['AgentPins', AgentPinsSchema],
+  ['PromptRef', PromptRefSchema],
+  ['BlockRef', BlockRefSchema],
+  ['PinChange', PinChangeSchema],
+  ['VersionDerivation', VersionDerivationSchema],
+  ['DeriveAgentVersionBody', DeriveAgentVersionBodySchema],
+  ['AgentPinSwaps', AgentPinSwapsSchema],
+  ['FlowPins', FlowPinsSchema],
   ['PublishAgentBody', PublishAgentBodySchema],
   ['PublishAgentResult', PublishAgentResultSchema],
   ['UnregisterAgentResult', UnregisterAgentResultSchema],
@@ -6190,6 +7310,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],
@@ -6215,9 +7338,20 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['PublishEvalSuiteResult', PublishEvalSuiteResultSchema],
   ['UnregisterEvalSuiteResult', UnregisterEvalSuiteResultSchema],
   ['ReinstateEvalSuiteVersionResult', ReinstateEvalSuiteVersionResultSchema],
+  ['BlockKind', BlockKindSchema],
+  ['PromptBlockContent', PromptBlockContentSchema],
+  ['SettingsBlockContent', SettingsBlockContentSchema],
+  ['Block', BlockSchema],
+  ['BlockCollectionPage', BlockCollectionPageSchema],
+  ['PublishBlockBody', PublishBlockBodySchema],
+  ['PublishBlockResult', PublishBlockResultSchema],
+  ['UnregisterBlockResult', UnregisterBlockResultSchema],
+  ['ReinstateBlockResult', ReinstateBlockResultSchema],
   ['EvalRunStatus', EvalRunStatusSchema],
   ['EvalRunAgentRef', EvalRunAgentRefSchema],
   ['EvalRunFlowRef', EvalRunFlowRefSchema],
+  ['EvalBaseline', EvalBaselineSchema],
+  ['EvalComparison', EvalComparisonSchema],
   ['EvalRun', EvalRunSchema],
   ['EvalRunCollectionPage', EvalRunCollectionPageSchema],
   ['StartEvalRunBody', StartEvalRunBodySchema],
@@ -6348,6 +7482,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['CreateWebhookEndpointBody', CreateWebhookEndpointBodySchema],
   ['PatchWebhookEndpointBody', PatchWebhookEndpointBodySchema],
   ['WebhookEndpointUnregisterResult', WebhookEndpointUnregisterResultSchema],
+  ['RunTreeUsage', RunTreeUsageSchema],
   ['FinishedRun', FinishedRunSchema],
   ['RunFinishedEvent', RunFinishedEventSchema],
   ['WebhookTestEvent', WebhookTestEventSchema],