@kindgi/api 0.1.3 → 0.1.4-rc.1

package/src/block-pins.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Agent, MODEL_SETTINGS_SCHEMA, settingsSchemaIssues } from '@kindgi/agents';
+import { pickVersion } from '@kindgi/tools';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import type { UnpinnableRef } from './agent-pins.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+
+/** The data-block versions an agent version pins, and the references that matched none. */
+export interface BlockPins {
+  readonly prompts: Readonly<Record<string, string>>;
+  readonly settings: Readonly<Record<string, string>>;
+  readonly issues: readonly UnpinnableRef[];
+}
+
+interface Ref {
+  readonly path: string;
+  readonly id: string;
+  readonly range: string;
+  readonly role: 'prompt' | 'settings' | 'model-settings';
+}
+
+/** Page size for reading a block's versions. */
+const VERSIONS_PAGE = 200;
+
+/**
+ * Pin the data blocks an agent references (its prompt block, settings
+ * blocks and model-settings block) when a version of it is published:
+ * each range resolves by `pickVersion` over the block's active versions,
+ * as a turn of an unpinned agent would. A reference that matches no
+ * published version, names a block of the other kind, or names model
+ * settings that aren't (`MODEL_SETTINGS_SCHEMA`) is an issue: the
+ * caller refuses the publish. So is any reference on a runtime with no
+ * block registry.
+ */
+export async function resolveBlockPins(
+  blocks: BlockRegistryBinding | undefined,
+  tenantId: TenantId,
+  agent: Agent,
+): Promise<BlockPins> {
+  const prompts: Record<string, string> = {};
+  const settings: Record<string, string> = {};
+  const issues: UnpinnableRef[] = [];
+  for (const ref of blockRefs(agent)) {
+    if (blocks === undefined) {
+      issues.push({
+        path: ref.path,
+        message: `${describe(ref)}: this runtime serves no data blocks`,
+      });
+      continue;
+    }
+    const available = await activeBlockVersions(blocks, tenantId, ref.id);
+    const pick = pickVersion(available, ref.range);
+    if (pick.kind !== 'ok') {
+      issues.push({
+        path: ref.path,
+        message:
+          available.length === 0
+            ? `${describe(ref)} has no published version; publish the block first`
+            : `${describe(ref)} has no published version in "${ref.range}" (published: ${available.join(', ')})`,
+      });
+      continue;
+    }
+    const block = await blocks.getVersion({ tenantId, blockId: ref.id, version: pick.version });
+    const problem =
+      block === null
+        ? `${describe(ref)} version ${pick.version} can't be read`
+        : misfit(ref, block);
+    if (problem !== undefined) {
+      issues.push({ path: ref.path, message: problem });
+      continue;
+    }
+    (ref.role === 'prompt' ? prompts : settings)[ref.id] = pick.version;
+  }
+  return { prompts, settings, issues };
+}
+
+function blockRefs(agent: Agent): Ref[] {
+  const refs: Ref[] = [];
+  if (typeof agent.instructions === 'object') {
+    refs.push({
+      path: '/instructions/version',
+      id: agent.instructions.prompt,
+      range: agent.instructions.version,
+      role: 'prompt',
+    });
+  }
+  for (const [i, s] of (agent.settings ?? []).entries()) {
+    refs.push({ path: `/settings/${i}/version`, id: s.id, range: s.version, role: 'settings' });
+  }
+  if (agent.modelSettings !== undefined) {
+    refs.push({
+      path: '/modelSettings/version',
+      id: agent.modelSettings.id,
+      range: agent.modelSettings.version,
+      role: 'model-settings',
+    });
+  }
+  return refs;
+}
+
+/** Why a block version can't serve its reference; undefined when it can. */
+function misfit(
+  ref: Ref,
+  block: { readonly kind: string; readonly version: string; readonly content: unknown },
+): string | undefined {
+  const wanted = ref.role === 'prompt' ? 'prompt' : 'settings';
+  if (block.kind !== wanted) return `${describe(ref)} is a ${block.kind} block`;
+  if (ref.role !== 'model-settings') return undefined;
+  const values = (block.content as { readonly values?: unknown }).values;
+  const issues = settingsSchemaIssues(values, MODEL_SETTINGS_SCHEMA);
+  return issues.length === 0
+    ? undefined
+    : `${describe(ref)} version ${block.version} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`;
+}
+
+function describe(ref: Ref): string {
+  const what =
+    ref.role === 'prompt'
+      ? 'prompt'
+      : ref.role === 'model-settings'
+        ? 'model-settings'
+        : 'settings';
+  return `${what} block "${ref.id}"`;
+}
+
+/** Every active version of a block, newest published first. */
+async function activeBlockVersions(
+  blocks: BlockRegistryBinding,
+  tenantId: TenantId,
+  blockId: string,
+): Promise<readonly string[]> {
+  const versions: string[] = [];
+  let cursor: Cursor | undefined;
+  do {
+    const page = await blocks.listVersions({
+      tenantId,
+      blockId,
+      limit: VERSIONS_PAGE,
+      ...(cursor !== undefined && { cursor }),
+    });
+    versions.push(...page.data.map((b) => b.version));
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return versions;
+}

package/src/cost-binding.ts

@@ -44,7 +44,10 @@ export interface CostBinding {
    * Multi-dimensional aggregate rollup. `groupBy` may combine any
    * subset of `COST_GROUP_DIMENSIONS`; the binding returns one group per
    * distinct key tuple within the required `from`..`to` window, with its
-   * cost and token sums.
+   * cost and token sums. With `limit`, a binding may return only the
+   * `limit` most expensive groups (`totalUsd` descending, ties by key)
+   * and the count before the cap in `totalGroups`; one that returns
+   * every group is capped by the route.
    */
   aggregate(input: CostAggregateInput): Promise<CostAggregateResult>;
 }
@@ -195,8 +198,20 @@ export interface CostAggregateInput {
    * shape uniformity.
    */
   readonly inherit?: boolean;
+  /**
+   * The most groups the caller wants (`?limit=`, 1..`COST_AGGREGATE_MAX_LIMIT`,
+   * default `COST_AGGREGATE_DEFAULT_LIMIT`): the most expensive ones. A
+   * binding may cap in its query; the window's totals stay over every
+   * record either way.
+   */
+  readonly limit?: number;
 }
 
+/** `GET /v1/cost/aggregate`'s `?limit=` when absent. */
+export const COST_AGGREGATE_DEFAULT_LIMIT = 1000;
+/** The largest `?limit=` the aggregate takes. */
+export const COST_AGGREGATE_MAX_LIMIT = 10_000;
+
 /**
  * One row of the aggregate result. `key` maps every requested `groupBy`
  * dimension to its value for this group — `null` when the underlying
@@ -226,6 +241,11 @@ export interface CostTokenTotals {
 
 export interface CostAggregateResult {
   readonly groups: readonly CostAggregateGroup[];
+  /**
+   * How many groups there were before a cap: set by a binding that caps
+   * (`CostAggregateInput.limit`). Absent: `groups` is every group.
+   */
+  readonly totalGroups?: number;
   readonly totalUsd: number;
   readonly totalRecords: number;
   readonly tokens: CostTokenTotals;

package/src/deploy-versions.ts

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type PinChange, type PinSet, pinChanges } from '@kindgi/agents';
+import { canonicalize } from '@kindgi/schema';
+import { nextVersion } from '@kindgi/tools';
+import type { VersionDerivation, VersionDerivationReason } from '@kindgi/types';
+
+/** A version a deploy registers with pins: an agent's or a flow's. */
+export interface PinnedDefinition {
+  readonly version: string;
+  readonly pins?: PinSet;
+  readonly pinsDigest?: string;
+  readonly derivedFrom?: VersionDerivation;
+}
+
+/**
+ * How a deploy registered one of its agents or flows, given its pins.
+ * A deploy never keeps a version's old pins and never refuses a
+ * routine deploy:
+ *
+ * - `registered`: the definition's version was free, and is now
+ *   registered with these pins;
+ * - `unchanged`: it's registered with the same definition and pins (or
+ *   its project is gone, which a deploy has always left as it is);
+ * - `reused`: an earlier deploy already registered this definition and
+ *   these pins under another number (`version`), so a redeploy changes
+ *   nothing;
+ * - `renumbered`: the definition's version is registered with other
+ *   pins or other content, and versions never change, so this deploy
+ *   registered the next free version in its line (`nextVersion`).
+ */
+export type DeployedVersionOutcome =
+  | { readonly kind: 'registered' | 'unchanged'; readonly version: string }
+  | {
+      readonly kind: 'reused' | 'renumbered';
+      readonly version: string;
+      readonly reason: VersionDerivationReason;
+      readonly pinChanges?: readonly PinChange[];
+    };
+
+/** What registering one version did: stored it, found the number taken, or left it (no project). */
+export type PublishOutcome = 'ok' | 'taken' | 'skipped';
+
+export interface DeployVersionInput<T extends PinnedDefinition> {
+  /** Names the definition in an error, e.g. `agent "acme.matcher"`. */
+  readonly label: string;
+  /** The definition as the pack has it, with no pins. */
+  readonly definition: T;
+  readonly pins: PinSet;
+  readonly pinsDigest: string;
+  /** Every active version registered under the definition's id. */
+  readonly existing: readonly T[];
+  /** Register one version. */
+  readonly publish: (version: T) => Promise<PublishOutcome>;
+}
+
+/** How many versions after the definition's a deploy tries before it gives up. */
+const MAX_RENUMBER = 100;
+
+/**
+ * Register a deployed agent or flow with its pins (see
+ * `DeployedVersionOutcome`): one rule for both, so they can't drift
+ * apart. Each definition is registered at most once per deploy, and a
+ * new version derives from the definition's version only, never from a
+ * version the same deploy created, so a change cascading from a tool
+ * through an agent into a flow ends within the one deploy.
+ */
+export async function deployVersion<T extends PinnedDefinition>(
+  input: DeployVersionInput<T>,
+): Promise<DeployedVersionOutcome> {
+  const { definition, pins, pinsDigest, existing } = input;
+  const authored = definition.version;
+  const key = definitionKey(definition);
+  const same = (v: T) => definitionKey(v) === key && v.pinsDigest === pinsDigest;
+
+  const atAuthored = existing.find((v) => v.version === authored);
+  if (atAuthored !== undefined && same(atAuthored)) return { kind: 'unchanged', version: authored };
+  if (atAuthored === undefined) {
+    const outcome = await input.publish({ ...definition, pins, pinsDigest });
+    if (outcome !== 'taken') {
+      return { kind: outcome === 'ok' ? 'registered' : 'unchanged', version: authored };
+    }
+    // Taken with no active version: an unregistered version holds the
+    // number. Register the next one.
+  }
+
+  const reason = derivationReason(atAuthored, key);
+  const changes =
+    reason === 'pins-changed' ? { pinChanges: pinChanges(atAuthored?.pins, pins) } : {};
+  const earlier = existing.find(same);
+  if (earlier !== undefined) {
+    return {
+      kind: 'reused',
+      version: earlier.version,
+      // An expert's edit reused by a deploy reports the deploy's own reason.
+      reason:
+        earlier.derivedFrom !== undefined && earlier.derivedFrom.reason !== 'edited'
+          ? earlier.derivedFrom.reason
+          : reason,
+      ...changes,
+    };
+  }
+  const taken = new Set(existing.map((v) => v.version));
+  const version = await registerNextFree(input, reason, taken);
+  return version === undefined
+    ? { kind: 'unchanged', version: authored }
+    : { kind: 'renumbered', version, reason, ...changes };
+}
+
+/** Why the definition's version can't be registered as it is. */
+function derivationReason(
+  atAuthored: PinnedDefinition | undefined,
+  key: string,
+): VersionDerivationReason {
+  if (atAuthored === undefined || definitionKey(atAuthored) !== key) return 'version-taken';
+  return atAuthored.pins === undefined ? 'unpinned' : 'pins-changed';
+}
+
+/**
+ * Register the definition with its pins under the first free version
+ * after its own (`nextVersion`), recording where it came from.
+ * `undefined` when it was left as it is (its project is gone).
+ */
+async function registerNextFree<T extends PinnedDefinition>(
+  input: DeployVersionInput<T>,
+  reason: VersionDerivationReason,
+  taken: ReadonlySet<string>,
+): Promise<string | undefined> {
+  const { definition, pins, pinsDigest } = input;
+  const authored = definition.version;
+  let candidate = nextVersion(authored);
+  for (let tries = 0; candidate !== undefined && tries < MAX_RENUMBER; tries++) {
+    if (!taken.has(candidate)) {
+      const outcome = await input.publish({
+        ...definition,
+        version: candidate,
+        pins,
+        pinsDigest,
+        derivedFrom: { version: authored, reason },
+      });
+      if (outcome === 'ok') return candidate;
+      if (outcome === 'skipped') return undefined;
+      // Taken: an unregistered version holds this one too.
+    }
+    candidate = nextVersion(candidate);
+  }
+  throw new Error(
+    `${input.label}: no free version after ${authored} to register its new pins under`,
+  );
+}
+
+/** A definition: everything but its version and what the runtime sets. */
+export function definitionKey(definition: PinnedDefinition): string {
+  const { version: _v, pins: _p, pinsDigest: _d, derivedFrom: _f, ...rest } = definition;
+  return canonicalize(rest);
+}

package/src/deployment-binding.ts

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { Cursor, SigningKeyId, TenantId } from '@kindgi/types';
+import type { PinChange } from '@kindgi/agents';
+import type { Cursor, SigningKeyId, TenantId, VersionDerivationReason } from '@kindgi/types';
 
 /**
  * Caller-plugged surface for the deployment ledger — the audit anchor
@@ -127,11 +128,34 @@ export interface DeployedPrimitive {
   readonly version?: string;
 }
 
+/**
+ * An agent or flow a deployment shipped, under the version it's
+ * registered as. A deploy registers one under another version than its
+ * definition's when that version is registered already with other pins
+ * or content (versions never change); then `authoredVersion` is the
+ * definition's and `reason` says why.
+ */
+export interface DeployedVersion extends DeployedPrimitive {
+  /** The version the agent's definition names, when it differs from `version`. */
+  readonly authoredVersion?: string;
+  readonly reason?: VersionDerivationReason;
+  /** `true`: this deploy registered `version`; `false`: an earlier deploy did. */
+  readonly newVersion?: boolean;
+  /** For `pins-changed`: the pins that differ from `authoredVersion`'s. */
+  readonly pinChanges?: readonly PinChange[];
+}
+
+/** An agent a deployment shipped (`DeployedVersion`). */
+export type DeployedAgent = DeployedVersion;
+
+/** A flow a deployment shipped (`DeployedVersion`). */
+export type DeployedFlow = DeployedVersion;
+
 export interface DeploymentContents {
   readonly tools: readonly DeployedPrimitive[];
   readonly guardrails: readonly DeployedPrimitive[];
-  readonly agents: readonly DeployedPrimitive[];
-  readonly flows: readonly DeployedPrimitive[];
+  readonly agents: readonly DeployedAgent[];
+  readonly flows: readonly DeployedFlow[];
 }
 
 export interface DeploymentPrimitiveCounts {

package/src/derive-agent-version.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import {
+  type Agent,
+  type AgentId,
+  type AgentPins,
+  MODEL_SETTINGS_SCHEMA,
+  pinsDigest,
+  settingsSchemaIssues,
+} from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import { latestVersion, nextVersion } from '@kindgi/tools';
+import type { ProjectId, Semver, TenantId } from '@kindgi/types';
+
+import type { AgentRegistryBinding, AgentVersionRecord } from './agent-binding.js';
+import { activeAgentVersions } from './agent-pins.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+import { definitionKey } from './deploy-versions.js';
+
+/** Which data-block pins to swap, by kind then block id → exact version. */
+export interface PinSwaps {
+  readonly prompts?: Readonly<Record<string, string>>;
+  readonly settings?: Readonly<Record<string, string>>;
+}
+
+export interface DeriveAgentVersionInput {
+  readonly agents: AgentRegistryBinding;
+  readonly blocks: BlockRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  /** The version to derive from: it must be pinned. */
+  readonly from: string;
+  readonly swaps: PinSwaps;
+  /** A short label for the new version. */
+  readonly label?: string;
+  /** Who derived it (`user:<id>`). */
+  readonly by?: string;
+  /** The project, when the store doesn't record one on the version. */
+  readonly projectId?: ProjectId;
+  /** The authorization tuples for the new version, in the project it lands in. */
+  readonly tuplesFor: (projectId: ProjectId) => TupleEnqueueHook;
+}
+
+export interface SwapIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+export type DeriveAgentVersionOutcome =
+  | { readonly kind: 'ok'; readonly agent: Agent }
+  /** An active version already has this definition and these pins: that one, unchanged. */
+  | { readonly kind: 'reused'; readonly agent: Agent }
+  | { readonly kind: 'not-found' }
+  | { readonly kind: 'unpinned' }
+  | { readonly kind: 'invalid'; readonly issues: readonly SwapIssue[] }
+  | { readonly kind: 'no-project' }
+  | { readonly kind: 'project-not-found'; readonly projectId: ProjectId };
+
+/** How many numbers after the highest a derive tries before it gives up. */
+const MAX_TRIES = 100;
+
+/**
+ * Derive a new agent version from a pinned one with some data-block
+ * pins swapped: an expert's edit (a new prompt or settings version)
+ * reaching an agent without a code change. The new version is the old
+ * one's bag with those pins swapped (`derivedFrom: { version, reason:
+ * 'edited', label, by }`), numbered the next free patch after the
+ * agent's highest version (versions never change). If an active version
+ * already holds that definition and those pins (the same swap derived
+ * before, or a deploy that registered it), that version is returned
+ * unchanged (`reused`) rather than a duplicate.
+ *
+ * Only data-block pins swap: a swap must name a block the version
+ * already references (adding one is a code change), at a published,
+ * active version of the right kind (and, for the model-settings block,
+ * model settings). Tool pins come from code.
+ */
+export async function deriveAgentVersion(
+  input: DeriveAgentVersionInput,
+): Promise<DeriveAgentVersionOutcome> {
+  const { agents, tenantId, agentId } = input;
+  const from = await agents.getVersion({ tenantId, agentId, version: input.from as Semver });
+  if (from === null) return { kind: 'not-found' };
+  if (from.pins === undefined) return { kind: 'unpinned' };
+
+  const issues = await swapIssues(input, from, from.pins);
+  if (issues.length > 0) return { kind: 'invalid', issues };
+  const pins: AgentPins = {
+    tools: from.pins.tools,
+    prompts: { ...from.pins.prompts, ...(input.swaps.prompts ?? {}) },
+    settings: { ...from.pins.settings, ...(input.swaps.settings ?? {}) },
+  };
+  const digest = pinsDigest(pins);
+  if (digest === from.pinsDigest) {
+    return { kind: 'invalid', issues: [{ path: '/pins', message: 'no pin changes' }] };
+  }
+
+  const projectId = from.projectId ?? input.projectId;
+  if (projectId === undefined) return { kind: 'no-project' };
+  const { unregisteredAt: _u, projectId: _p, derivedFrom: _d, ...definition } = from;
+  return publishNextFree(input, projectId, {
+    ...definition,
+    pins,
+    pinsDigest: digest,
+    derivedFrom: {
+      version: from.version,
+      reason: 'edited',
+      ...(input.label !== undefined && { label: input.label }),
+      ...(input.by !== undefined && { by: input.by }),
+    },
+  });
+}
+
+/** Publish the derived version under the first free patch after the agent's highest. */
+async function publishNextFree(
+  input: DeriveAgentVersionInput,
+  projectId: ProjectId,
+  derived: Agent,
+): Promise<DeriveAgentVersionOutcome> {
+  const { agents, tenantId, agentId } = input;
+  const active = await activeAgentVersions(agents, tenantId, agentId);
+  // The same swap again (or a deploy that registered it) finds the
+  // version that already holds it: versions are never duplicated.
+  const key = definitionKey(derived);
+  const same = active.find((a) => a.pinsDigest === derived.pinsDigest && definitionKey(a) === key);
+  if (same !== undefined) return { kind: 'reused', agent: same };
+  const highest =
+    latestVersion(active.map((a) => a.version as unknown as string)) ??
+    (derived.version as unknown as string);
+  let candidate = nextVersion(highest);
+  for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+    const agent: Agent = { ...derived, version: candidate as Semver };
+    const outcome = await agents.publish({
+      tenantId,
+      projectId,
+      agent,
+      enqueueTuples: input.tuplesFor(projectId),
+    });
+    if (outcome.kind === 'ok') return { kind: 'ok', agent };
+    if (outcome.kind === 'project-not-found') return { kind: 'project-not-found', projectId };
+    candidate = nextVersion(candidate);
+  }
+  throw new Error(`agent "${agentId as unknown as string}": no free version after ${highest}`);
+}
+
+/** What's wrong with the swaps, against the version's references and the block store. */
+async function swapIssues(
+  input: DeriveAgentVersionInput,
+  from: AgentVersionRecord,
+  pins: AgentPins,
+): Promise<SwapIssue[]> {
+  const issues: SwapIssue[] = [];
+  const swaps = [
+    ...Object.entries(input.swaps.prompts ?? {}).map(([id, v]) => ['prompts', id, v] as const),
+    ...Object.entries(input.swaps.settings ?? {}).map(([id, v]) => ['settings', id, v] as const),
+  ];
+  if (swaps.length === 0)
+    return [{ path: '/pins', message: 'name at least one prompt or settings pin to swap' }];
+  for (const [kind, id, version] of swaps) {
+    const path = `/pins/${kind}/${id}`;
+    if (pins[kind][id] === undefined) {
+      issues.push({
+        path,
+        message: `agent version ${from.version} doesn't reference ${kind === 'prompts' ? 'prompt' : 'settings'} block "${id}"; adding a block is a code change`,
+      });
+      continue;
+    }
+    const problem = await blockProblem(input, from, kind, id, version);
+    if (problem !== undefined) issues.push({ path, message: problem });
+  }
+  return issues;
+}
+
+async function blockProblem(
+  input: DeriveAgentVersionInput,
+  from: AgentVersionRecord,
+  kind: 'prompts' | 'settings',
+  id: string,
+  version: string,
+): Promise<string | undefined> {
+  if (input.blocks === undefined) return 'this runtime serves no data blocks';
+  const block = await input.blocks.getVersion({ tenantId: input.tenantId, blockId: id, version });
+  const what = `block "${id}" version ${version}`;
+  if (block === null) return `${what} isn't published`;
+  if (block.unregisteredAt !== undefined) return `${what} is unregistered`;
+  const wanted = kind === 'prompts' ? 'prompt' : 'settings';
+  if (block.kind !== wanted) return `${what} is a ${block.kind} block, not ${wanted}`;
+  if (block.kind === 'settings' && from.modelSettings?.id === id) {
+    const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+    if (issues.length > 0) {
+      return `${what} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The first version after `after` that no version of the agent holds,
+ * active or unregistered (versions never change): what a refused
+ * publish of a taken number suggests, by the deploy rule's numbering.
+ * `undefined` when none is free within the tries.
+ */
+export async function nextFreeAgentVersion(
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  agentId: AgentId,
+  after: string,
+): Promise<string | undefined> {
+  let candidate = nextVersion(after);
+  for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+    const held = await agents.getVersion({ tenantId, agentId, version: candidate as Semver });
+    if (held === null) return candidate;
+    candidate = nextVersion(candidate);
+  }
+  return undefined;
+}

package/src/errors.ts

@@ -31,6 +31,7 @@ export interface WireError {
 export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   // 400 — bad request
   'validation-failed': 400,
+  'kind-not-applied': 400,
   'unknown-field': 400,
   'bad-input': 400,
   'unresolved-tool': 400,
@@ -66,6 +67,7 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'duplicate-edge-id': 409,
   'agent-version-mismatch': 409,
   'agent-already-registered': 409,
+  'registry-read-only': 409,
   'agent-gone': 410,
   'flow-gone': 410,
   'policy-gone': 410,
@@ -160,10 +162,22 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'policy-not-found': 404,
   'policy-already-registered': 409,
   // Admin plane — eval suites.
+  'block-not-found': 404,
+  'block-already-registered': 409,
+  'block-project-mismatch': 409,
   'eval-suite-not-found': 404,
   'eval-suite-already-registered': 409,
   // Admin plane — eval-run dispatch.
   'eval-run-not-found': 404,
+  // Judgments (yes/no on a run's output items) and judge classes.
+  'judgment-not-found': 404,
+  'judge-class-not-found': 404,
+  'judge-class-name-taken': 409,
+  'judge-class-not-applicable': 400,
+  'run-not-finished': 409,
+  'item-not-found': 400,
+  // The judgment binding can't list judged runs, so no test sets from judgments.
+  'test-sets-not-supported': 501,
   'eval-run-already-terminal': 409,
   'dispatcher-not-registered': 422,
   'dispatcher-input-invalid': 400,
@@ -215,6 +229,10 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'project-not-found': 404,
   'team-membership-not-found': 404,
   'project-membership-not-found': 404,
+  // A slug another org, team or project in the tenant already has; a
+  // second Default project.
+  'slug-conflict': 409,
+  'project-default-already-exists': 409,
   'tenant-not-found': 404,
   'tenant-config-not-found': 404,
   'tenant-config-revision-conflict': 409,