@kindgi/api 0.1.3 → 0.1.4-rc.1

package/src/routes/deployments.ts

@@ -5,9 +5,10 @@ import { createHash } from 'node:crypto';
 
 import { Hono } from 'hono';
 
-import type { AgentId } from '@kindgi/agents';
+import type { Agent, AgentId, AgentPins } from '@kindgi/agents';
 import { tuplesForCreate } from '@kindgi/authz';
 import { parsePublicKeyPem, verifyEd25519 } from '@kindgi/crypto';
+import type { Flow, FlowPins } from '@kindgi/flow';
 import { type Guardrail, validateGuardrailSpec } from '@kindgi/guardrails';
 import type { ProjectBinding, Scope } from '@kindgi/platform';
 import { validateToolManifest } from '@kindgi/tools';
@@ -16,13 +17,20 @@ import type {
   FlowId,
   GuardrailId,
   ProjectId,
+  Semver,
   SigningKeyId,
   TenantId,
   ToolId,
 } from '@kindgi/types';
 
 import type { AgentRegistryBinding } from '../agent-binding.js';
+import { type UnpinnableRef, publishDeployedAgent, resolveAgentPins } from '../agent-pins.js';
+import type { BlockRegistryBinding } from '../block-binding.js';
+import type { DeployedVersionOutcome } from '../deploy-versions.js';
 import type {
+  DeployedAgent,
+  DeployedFlow,
+  DeployedVersion,
   Deployment,
   DeploymentBinding,
   DeploymentPrimitiveCounts,
@@ -30,8 +38,10 @@ import type {
 } from '../deployment-binding.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { FlowRegistryBinding } from '../flow-binding.js';
+import { publishDeployedFlow, resolveFlowPins } from '../flow-pins.js';
 import type { GuardrailRegistryBinding } from '../guardrail-binding.js';
 import type { ImageRegistryBinding } from '../image-registry-binding.js';
+import { type RegistryReadOnly, refuseReadOnly } from '../registry-read-only.js';
 import type { SecretBinding } from '../secrets-binding.js';
 import type { SigningKeyBinding as SigningKeyRegistryBinding } from '../signing-key-binding.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
@@ -112,6 +122,8 @@ export interface DeploymentsRouterBindings {
   readonly guardrailRegistry?: GuardrailRegistryBinding;
   readonly agentRegistry?: AgentRegistryBinding;
   readonly flowRegistry?: FlowRegistryBinding;
+  /** Data blocks: an agent's block references are pinned at deploy with its tools. */
+  readonly blockRegistry?: BlockRegistryBinding;
   /**
    * REQUIRED at runtime for `POST /v1/deployments/:deploymentId/secrets`.
    * Optional at the type level so app compositions without a secrets
@@ -476,6 +488,11 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
     }
     const validated = validation.value;
 
+    // A read-only registry (under `kindgi dev`, the pack's files) takes
+    // nothing a deployment brings: refuse before any write.
+    const readOnly = readOnlyTarget(validated, bindings);
+    if (readOnly !== undefined) return refuseReadOnly(c, readOnly);
+
     // ---- Registry upserts (with rollback tracking) ----
     //
     // Agent-registry, flow-registry, tool-registry, and
@@ -529,6 +546,10 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
     }
 
     const rolled: RollbackAction[] = [];
+    // The version each agent is registered under: its definition's, or
+    // the one a deploy registered in its place (`publishDeployedAgent`).
+    const deployedAgents: DeployedAgent[] = [];
+    const deployedFlows: DeployedFlow[] = [];
     try {
       if (bindings.toolRegistry !== undefined && defaultProjectId !== undefined) {
         for (const tool of validated.tools) {
@@ -578,58 +599,50 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
         }
       }
       if (bindings.agentRegistry !== undefined && defaultProjectId !== undefined) {
-        for (const agent of validated.agents) {
-          const projectIdForAgent = defaultProjectId;
-          const outcome = await bindings.agentRegistry.publish({
+        deployedAgents.push(
+          ...(await registerAgents({
+            agents: bindings.agentRegistry,
+            tools: bindings.toolRegistry,
+            blocks: bindings.blockRegistry,
             tenantId,
-            projectId: projectIdForAgent,
-            agent,
-            // Signed deploys have no per-request principal — pass parent-
-            // only tuples (no owner grant). Tenant admins keep access via
-            // `admin from parent` cascade.
-            enqueueTuples: (agentId) =>
-              tuplesForCreate({
-                kind: 'agent',
-                id: agentId as AgentId,
-                tenantId,
-                projectId: projectIdForAgent,
-              }),
-          });
-          if (outcome.kind === 'ok') {
-            const agentId = outcome.agentId;
-            const version = outcome.version;
-            rolled.push(async () => {
-              await bindings.agentRegistry?.unregister({ tenantId, agentId, version });
-            });
-          }
-        }
+            projectId: defaultProjectId,
+            defined: validated.agents,
+            rolled,
+          })),
+        );
+      } else {
+        deployedAgents.push(...validated.agents.map(deployedPrimitive));
       }
       if (bindings.flowRegistry !== undefined && defaultProjectId !== undefined) {
-        for (const flow of validated.flows) {
-          const projectIdForGraph = defaultProjectId;
-          const outcome = await bindings.flowRegistry.publish({
+        deployedFlows.push(
+          ...(await registerFlows({
+            flows: bindings.flowRegistry,
+            tools: bindings.toolRegistry,
+            agents: bindings.agentRegistry,
             tenantId,
-            projectId: projectIdForGraph,
-            flow,
-            enqueueTuples: (flowId) =>
-              tuplesForCreate({
-                kind: 'flow',
-                id: flowId as FlowId,
-                tenantId,
-                projectId: projectIdForGraph,
-              }),
-          });
-          if (outcome.kind === 'ok') {
-            const flowId = outcome.flowId;
-            const version = outcome.version;
-            rolled.push(async () => {
-              await bindings.flowRegistry?.unregister({ tenantId, flowId, version });
-            });
-          }
-        }
+            projectId: defaultProjectId,
+            defined: validated.flows,
+            rolled,
+          })),
+        );
+      } else {
+        deployedFlows.push(...validated.flows.map(deployedPrimitive));
       }
     } catch (cause) {
       await rollback(rolled);
+      if (cause instanceof UnpinnableDeploy) {
+        c.status(statusFor('invalid-agent') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'validation-failed',
+              message: `The deployment's agents or flows use tool or agent versions that aren't published (${cause.issues.length} issue${cause.issues.length === 1 ? '' : 's'}); nothing was deployed`,
+              issues: cause.issues as unknown as Record<string, unknown>[],
+            },
+            requestId,
+          ),
+        );
+      }
       c.status(statusFor('internal-server-error') as never);
       return c.json(
         toWireError(
@@ -669,14 +682,8 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             version: t.version,
           })),
           guardrails: validated.guardrails.map((g) => ({ id: g.id as unknown as string })),
-          agents: validated.agents.map((a) => ({
-            id: a.id as unknown as string,
-            version: a.version as unknown as string,
-          })),
-          flows: validated.flows.map((f) => ({
-            id: f.id as unknown as string,
-            version: f.version as unknown as string,
-          })),
+          agents: deployedAgents,
+          flows: deployedFlows,
         },
       });
     } catch (cause) {
@@ -1374,8 +1381,18 @@ function validateAgentIndexShape(
   if (typeof spec.name !== 'string' || (spec.name as string).length === 0) {
     out.push({ path: '/name', message: 'agent.name must be a non-empty string' });
   }
-  if (typeof spec.instructions !== 'string' || (spec.instructions as string).length === 0) {
-    out.push({ path: '/instructions', message: 'agent.instructions must be a non-empty string' });
+  const instructions = spec.instructions as { prompt?: unknown; version?: unknown } | string;
+  const promptRef =
+    typeof instructions === 'object' &&
+    instructions !== null &&
+    typeof instructions.prompt === 'string' &&
+    typeof instructions.version === 'string';
+  if (!promptRef && (typeof instructions !== 'string' || instructions.length === 0)) {
+    out.push({
+      path: '/instructions',
+      message:
+        'agent.instructions must be a non-empty string, or a prompt block { prompt, version }',
+    });
   }
   if (!Array.isArray(spec.capabilities)) {
     out.push({ path: '/capabilities', message: 'agent.capabilities must be an array' });
@@ -1411,6 +1428,205 @@ function validateFlowIndexShape(
 
 type RollbackAction = () => Promise<void>;
 
+/** A deploy whose agents or flows use a tool or agent with no published version in range. */
+class UnpinnableDeploy extends Error {
+  constructor(readonly issues: readonly UnpinnableRef[]) {
+    super('the deployment uses tools or agents that are not published');
+  }
+}
+
+/** A deployed agent or flow registered under its definition's version. */
+function deployedPrimitive(definition: { readonly id: string; readonly version: string }): {
+  id: string;
+  version: string;
+} {
+  return { id: definition.id, version: definition.version };
+}
+
+/** A deployed agent or flow, under the version the deploy rule registered it as. */
+function deployedVersion(
+  definition: { readonly id: string; readonly version: string },
+  outcome: DeployedVersionOutcome,
+): DeployedVersion {
+  return outcome.kind === 'reused' || outcome.kind === 'renumbered'
+    ? {
+        id: definition.id,
+        version: outcome.version,
+        authoredVersion: definition.version,
+        reason: outcome.reason,
+        newVersion: outcome.kind === 'renumbered',
+        ...(outcome.pinChanges !== undefined && { pinChanges: outcome.pinChanges }),
+      }
+    : deployedPrimitive(definition);
+}
+
+/**
+ * Register a deployment's agents, each under the version it's registered
+ * as (`DeployedAgent`), pushing a rollback for each version it writes.
+ *
+ * With a tool registry, every agent is pinned first (the pack's tools
+ * are registered by now): one whose range matches no published version
+ * throws `UnpinnableDeploy` before any agent is written, and the deploy
+ * rolls back. Each is then registered by `publishDeployedAgent`, which
+ * never keeps a version's old pins. Without one, agents register
+ * unpinned, as before pins existed.
+ */
+async function registerAgents(input: {
+  readonly agents: AgentRegistryBinding;
+  readonly tools: ToolRegistryBinding | undefined;
+  readonly blocks: BlockRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly defined: readonly Agent[];
+  readonly rolled: RollbackAction[];
+}): Promise<DeployedAgent[]> {
+  const { agents, tools, blocks, tenantId, projectId, rolled } = input;
+  // Signed deploys have no per-request principal — pass parent-only
+  // tuples (no owner grant). Tenant admins keep access via
+  // `admin from parent` cascade.
+  const enqueueTuples = (agentId: string) =>
+    tuplesForCreate({ kind: 'agent', id: agentId as AgentId, tenantId, projectId });
+  const written = (agentId: AgentId, version: Semver) =>
+    rolled.push(async () => {
+      await agents.unregister({ tenantId, agentId, version });
+    });
+
+  if (tools === undefined) {
+    for (const agent of input.defined) {
+      const outcome = await agents.publish({ tenantId, projectId, agent, enqueueTuples });
+      if (outcome.kind === 'ok') written(outcome.agentId, outcome.version);
+    }
+    return input.defined.map(deployedPrimitive);
+  }
+
+  const pinsOf = await pinAgents(tools, blocks, tenantId, input.defined);
+  const deployed: DeployedAgent[] = [];
+  for (const [i, agent] of input.defined.entries()) {
+    const pins = pinsOf[i] as AgentPins;
+    const outcome = await publishDeployedAgent({
+      agents,
+      tenantId,
+      projectId,
+      agent,
+      pins,
+      enqueueTuples,
+    });
+    if (outcome.kind === 'registered' || outcome.kind === 'renumbered') {
+      written(agent.id, outcome.version as unknown as Semver);
+    }
+    deployed.push(deployedVersion(agent, outcome));
+  }
+  return deployed;
+}
+
+/**
+ * Register a deployment's flows, each under the version it's registered
+ * as, pushing a rollback for each version it writes. Runs after the
+ * agents, so a flow's agent pins see the versions this deploy
+ * registered: a tool change cascades through an agent into a flow
+ * within the one deploy, each derived once.
+ *
+ * With the tool and agent registries, every flow is pinned first; one
+ * that runs a tool or agent with no published version throws
+ * `UnpinnableDeploy` before any flow is written, and the deploy rolls
+ * back. Without them, flows register unpinned, as before pins existed.
+ */
+async function registerFlows(input: {
+  readonly flows: FlowRegistryBinding;
+  readonly tools: ToolRegistryBinding | undefined;
+  readonly agents: AgentRegistryBinding | undefined;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  readonly defined: readonly Flow[];
+  readonly rolled: RollbackAction[];
+}): Promise<DeployedFlow[]> {
+  const { flows, tools, agents, tenantId, projectId, rolled } = input;
+  const enqueueTuples = (flowId: string) =>
+    tuplesForCreate({ kind: 'flow', id: flowId as FlowId, tenantId, projectId });
+  const written = (flowId: FlowId, version: string) =>
+    rolled.push(async () => {
+      await flows.unregister({ tenantId, flowId, version: version as never });
+    });
+
+  if (tools === undefined || agents === undefined) {
+    for (const flow of input.defined) {
+      const outcome = await flows.publish({ tenantId, projectId, flow, enqueueTuples });
+      if (outcome.kind === 'ok') written(outcome.flowId, outcome.version as unknown as string);
+    }
+    return input.defined.map(deployedPrimitive);
+  }
+
+  const pinsOf = await pinFlows(tools, agents, tenantId, input.defined);
+  const deployed: DeployedFlow[] = [];
+  for (const [i, flow] of input.defined.entries()) {
+    const outcome = await publishDeployedFlow({
+      flows,
+      tenantId,
+      projectId,
+      flow,
+      pins: pinsOf[i] as FlowPins,
+      enqueueTuples,
+    });
+    if (outcome.kind === 'registered' || outcome.kind === 'renumbered') {
+      written(flow.id, outcome.version);
+    }
+    deployed.push(deployedVersion(flow, outcome));
+  }
+  return deployed;
+}
+
+/** Each flow's pins, in order; throws `UnpinnableDeploy` naming every tool or agent with no published version. */
+async function pinFlows(
+  tools: ToolRegistryBinding,
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  defined: readonly Flow[],
+): Promise<FlowPins[]> {
+  const pins: FlowPins[] = [];
+  const unpinnable: UnpinnableRef[] = [];
+  for (const [i, flow] of defined.entries()) {
+    const resolved = await resolveFlowPins(tools, agents, tenantId, flow);
+    if (resolved.kind === 'ok') {
+      pins.push(resolved.pins);
+      continue;
+    }
+    for (const issue of resolved.issues) {
+      unpinnable.push({
+        path: `/flows/${i}${issue.path}`,
+        message: `flow "${flow.id as unknown as string}": ${issue.message}`,
+      });
+    }
+  }
+  if (unpinnable.length > 0) throw new UnpinnableDeploy(unpinnable);
+  return pins;
+}
+
+/** Each agent's pins, in order; throws `UnpinnableDeploy` naming every range that matches nothing. */
+async function pinAgents(
+  tools: ToolRegistryBinding,
+  blocks: BlockRegistryBinding | undefined,
+  tenantId: TenantId,
+  defined: readonly Agent[],
+): Promise<AgentPins[]> {
+  const pins: AgentPins[] = [];
+  const unpinnable: UnpinnableRef[] = [];
+  for (const [i, agent] of defined.entries()) {
+    const resolved = await resolveAgentPins(tools, tenantId, agent, blocks);
+    if (resolved.kind === 'ok') {
+      pins.push(resolved.pins);
+      continue;
+    }
+    for (const issue of resolved.issues) {
+      unpinnable.push({
+        path: `/agents/${i}${issue.path}`,
+        message: `agent "${agent.id as unknown as string}": ${issue.message}`,
+      });
+    }
+  }
+  if (unpinnable.length > 0) throw new UnpinnableDeploy(unpinnable);
+  return pins;
+}
+
 async function rollback(actions: readonly RollbackAction[]): Promise<void> {
   // Reverse order — last-in, first-out — so registrations are undone in
   // the mirror sequence of their creation.
@@ -1491,3 +1707,22 @@ export function sha256HexPrefixed(bytes: Uint8Array): string {
   const hex = createHash('sha256').update(bytes).digest('hex');
   return `sha256:${hex}`;
 }
+
+/** The first read-only registry a deployment would publish into, if any. */
+function readOnlyTarget(
+  validated: {
+    readonly tools: readonly unknown[];
+    readonly agents: readonly unknown[];
+    readonly flows: readonly unknown[];
+    readonly guardrails: readonly unknown[];
+  },
+  bindings: DeploymentsRouterBindings,
+): RegistryReadOnly | undefined {
+  const targets = [
+    [validated.tools, bindings.toolRegistry?.readOnly],
+    [validated.agents, bindings.agentRegistry?.readOnly],
+    [validated.flows, bindings.flowRegistry?.readOnly],
+    [validated.guardrails, bindings.guardrailRegistry?.readOnly],
+  ] as const;
+  return targets.find(([brought, readOnly]) => brought.length > 0 && readOnly !== undefined)?.[1];
+}

package/src/routes/eval-comparison.ts

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AgentId } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
+import type { ProjectId, Semver } from '@kindgi/types';
+
+import type { EvalBaseline, EvalComparison } from '../eval-run-binding.js';
+import { DEFAULT_COMPARISON } from '../judged-dispatcher.js';
+
+const MAX_REPETITIONS = 10;
+const MAX_K = 100;
+
+function obj(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function parseLive(raw: unknown): EvalBaseline | string {
+  const live = obj(raw);
+  if (live === undefined) return '`baseline.live` must be an object';
+  const segments = live.segments === undefined ? undefined : obj(live.segments);
+  const stringsOnly =
+    segments !== undefined && Object.values(segments).every((v) => typeof v === 'string');
+  if (live.segments !== undefined && !stringsOnly) {
+    return '`baseline.live.segments` must be an object of strings';
+  }
+  if (live.projectId !== undefined && typeof live.projectId !== 'string') {
+    return '`baseline.live.projectId` must be a string';
+  }
+  return {
+    live: {
+      ...(typeof live.projectId === 'string' && { projectId: live.projectId as ProjectId }),
+      ...(segments !== undefined && { segments: segments as Record<string, string> }),
+    },
+  };
+}
+
+function parseBaseline(raw: unknown): EvalBaseline | string {
+  if (raw === 'recorded') return 'recorded';
+  const o = obj(raw);
+  if (o === undefined) {
+    return "`baseline` must be 'recorded', { agentId, version } or { live: { projectId?, segments? } }";
+  }
+  if (o.live !== undefined) return parseLive(o.live);
+  if (typeof o.agentId !== 'string' || o.agentId === '' || typeof o.version !== 'string') {
+    return '`baseline` as a version needs `agentId` and `version`';
+  }
+  return { agentId: o.agentId as AgentId, version: o.version as Semver };
+}
+
+/** `{ id: version }` with non-empty strings; an error message otherwise. */
+function versionMap(raw: unknown, name: string): Readonly<Record<string, string>> | string {
+  const o = obj(raw);
+  const valid =
+    o !== undefined &&
+    Object.entries(o).every(([id, v]) => id !== '' && typeof v === 'string' && v !== '');
+  return valid
+    ? (o as Record<string, string>)
+    : `\`${name}\` must be an object of { id: version } with non-empty strings`;
+}
+
+/** `versions: { agents?, tools? }`; `undefined` when it names nothing. */
+function parseVersions(raw: unknown): FlowVersionOverrides | undefined | string {
+  const o = obj(raw);
+  if (o === undefined) return '`versions` must be an object: { agents?, tools? }';
+  const extra = Object.keys(o).filter((key) => key !== 'agents' && key !== 'tools');
+  if (extra.length > 0) return `\`versions\` takes \`agents\` and \`tools\`, not \`${extra[0]}\``;
+  const agents = o.agents === undefined ? {} : versionMap(o.agents, 'versions.agents');
+  if (typeof agents === 'string') return agents;
+  const tools = o.tools === undefined ? {} : versionMap(o.tools, 'versions.tools');
+  if (typeof tools === 'string') return tools;
+  if (Object.keys(agents).length === 0 && Object.keys(tools).length === 0) return undefined;
+  return {
+    ...(Object.keys(agents).length > 0 && { agents }),
+    ...(Object.keys(tools).length > 0 && { tools }),
+  };
+}
+
+function integerIn(raw: unknown, name: string, max: number): number | string {
+  return typeof raw === 'number' && Number.isInteger(raw) && raw >= 1 && raw <= max
+    ? raw
+    : `\`${name}\` must be an integer from 1 to ${max}`;
+}
+
+/**
+ * A comparison eval run's settings from the start body: `baseline`,
+ * `reads`, `repetitions`, `k` and a flow candidate's `versions`.
+ * `undefined` when none is given (the defaults apply); an error message
+ * for a bad one.
+ */
+export function parseComparison(
+  b: Readonly<Record<string, unknown>>,
+):
+  | { readonly kind: 'ok'; readonly value?: EvalComparison }
+  | { readonly kind: 'err'; readonly message: string } {
+  const { baseline, reads, repetitions, k } = b;
+  const versions = b.versions === undefined ? undefined : parseVersions(b.versions);
+  if (typeof versions === 'string') return { kind: 'err', message: versions };
+  if (
+    baseline === undefined &&
+    reads === undefined &&
+    repetitions === undefined &&
+    k === undefined &&
+    versions === undefined
+  ) {
+    return { kind: 'ok' };
+  }
+  const parsedBaseline =
+    baseline === undefined ? DEFAULT_COMPARISON.baseline : parseBaseline(baseline);
+  if (typeof parsedBaseline === 'string' && parsedBaseline !== 'recorded') {
+    return { kind: 'err', message: parsedBaseline };
+  }
+  if (reads !== undefined && reads !== 'recorded' && reads !== 'live') {
+    return { kind: 'err', message: "`reads` must be 'recorded' or 'live'" };
+  }
+  const reps =
+    repetitions === undefined
+      ? DEFAULT_COMPARISON.repetitions
+      : integerIn(repetitions, 'repetitions', MAX_REPETITIONS);
+  if (typeof reps === 'string') return { kind: 'err', message: reps };
+  const topK = k === undefined ? DEFAULT_COMPARISON.k : integerIn(k, 'k', MAX_K);
+  if (typeof topK === 'string') return { kind: 'err', message: topK };
+  return {
+    kind: 'ok',
+    value: {
+      baseline: parsedBaseline,
+      reads: reads ?? DEFAULT_COMPARISON.reads,
+      repetitions: reps,
+      k: topK,
+      ...(versions !== undefined && { versions }),
+    },
+  };
+}