@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/routes/cost.ts

@@ -6,12 +6,15 @@ import { Hono } from 'hono';
 import type { Cursor, TenantId, Timestamp } from '@kindgi/types';
 
 import {
+  COST_AGGREGATE_DEFAULT_LIMIT,
+  COST_AGGREGATE_MAX_LIMIT,
   COST_GROUP_DIMENSIONS,
   type CostAggregateGroup,
   type CostBinding,
   type CostGroupDimension,
   type CostRecord,
   type CostRecordFilter,
+  type CostTokenTotals,
 } from '../cost-binding.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { AppEnv } from '../types.js';
@@ -52,6 +55,11 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       c.status(statusFor('bad-input') as never);
       return c.json(toWireError({ code: 'bad-input', message: filter.error }, requestId));
     }
+    const include = parseInclude(c.req.query('include'));
+    if (include.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: include.error }, requestId));
+    }
 
     // Thread the ?scopeKind + ?scopeId + ?inherit
     // triplet as a sibling of `filter` (matches the binding's shape:
@@ -71,6 +79,7 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       filter: filter.value,
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+      ...(include.rawUsage && { includeRawUsage: true }),
     });
     return c.json({
       data: page.data.map(serializeRecord),
@@ -84,8 +93,17 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const recordId = c.req.param('recordId');
+    const include = parseInclude(c.req.query('include'));
+    if (include.kind === 'err') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: include.error }, requestId));
+    }
 
-    const record = await binding.getRecord({ tenantId, recordId });
+    const record = await binding.getRecord({
+      tenantId,
+      recordId,
+      ...(include.rawUsage && { includeRawUsage: true }),
+    });
     if (record === null) {
       c.status(statusFor('cost-record-not-found') as never);
       return c.json(
@@ -153,6 +171,21 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       }
     }
 
+    // limit — the most groups to return, the most expensive first.
+    const limit = parseAggregateLimit(query.limit);
+    if (limit === null) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`limit\` must be an integer from 1 to ${COST_AGGREGATE_MAX_LIMIT} (default ${COST_AGGREGATE_DEFAULT_LIMIT})`,
+          },
+          requestId,
+        ),
+      );
+    }
+
     // Time range — required. Default to last 30 days when both absent
     // (documented in the response `timeRange`). If only one endpoint is
     // supplied, reject — half-open defaults invite confusion.
@@ -224,12 +257,21 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       ...(Object.keys(filter.value).length > 0 && { filter: filter.value }),
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
+      limit,
     });
 
+    // The most expensive groups, capped here too: a binding may return
+    // every group. The window's totals stay over every record.
+    const groups = [...result.groups].sort((a, b) => compareGroups(a, b, groupBy)).slice(0, limit);
+    const totalGroups = Math.max(result.totalGroups ?? 0, result.groups.length);
+
     return c.json({
-      groups: result.groups.map(serializeGroup),
+      groups: groups.map(serializeGroup),
+      totalGroups,
+      truncated: totalGroups > groups.length,
       totalUsd: result.totalUsd,
       totalRecords: result.totalRecords,
+      tokens: serializeTokens(result.tokens),
       timeRange: {
         from: result.timeRange.from,
         to: result.timeRange.to,
@@ -248,27 +290,34 @@ function parseRecordFilter(
   opts: { skipTime?: boolean } = {},
 ): { kind: 'ok'; value: CostRecordFilter } | { kind: 'err'; error: string } {
   const out: {
-    runId?: string;
-    agentId?: string;
-    conversationId?: string;
-    category?: string;
-    providerId?: string;
-    from?: Date;
-    to?: Date;
+    -readonly [K in keyof CostRecordFilter]: CostRecordFilter[K];
   } = {};
-  const strKeys: Array<
-    ['runId' | 'agentId' | 'conversationId' | 'category' | 'providerId', string]
-  > = [
-    ['runId', 'runId'],
-    ['agentId', 'agentId'],
-    ['conversationId', 'conversationId'],
-    ['category', 'category'],
-    ['providerId', 'providerId'],
-  ];
-  for (const [outKey, qKey] of strKeys) {
-    const raw = query[qKey];
+  const strKeys = [
+    'runId',
+    'agentId',
+    'conversationId',
+    'category',
+    'providerId',
+    'model',
+    'servedModel',
+    'rootRunId',
+  ] as const;
+  for (const key of strKeys) {
+    const raw = query[key];
     if (raw !== undefined && raw.length > 0) {
-      out[outKey] = raw;
+      out[key] = raw;
+    }
+  }
+  const descendants = query.includeDescendants;
+  if (descendants !== undefined && descendants.length > 0) {
+    if (descendants !== 'true' && descendants !== 'false') {
+      return { kind: 'err', error: '`includeDescendants` must be `true` or `false`' };
+    }
+    if (descendants === 'true') {
+      if (out.runId === undefined) {
+        return { kind: 'err', error: '`includeDescendants` needs a `runId`' };
+      }
+      out.includeDescendants = true;
     }
   }
   if (opts.skipTime !== true) {
@@ -291,6 +340,22 @@ function parseRecordFilter(
   return { kind: 'ok', value: out };
 }
 
+/** The `include` query: optional extra fields, comma-separated. Only `rawUsage` today. */
+function parseInclude(
+  raw: string | undefined,
+): { kind: 'ok'; rawUsage: boolean } | { kind: 'err'; error: string } {
+  const fields = (raw ?? '')
+    .split(',')
+    .map((f) => f.trim())
+    .filter((f) => f.length > 0);
+  for (const field of fields) {
+    if (field !== 'rawUsage') {
+      return { kind: 'err', error: `\`include\` value "${field}" is not known (one of: rawUsage)` };
+    }
+  }
+  return { kind: 'ok', rawUsage: fields.includes('rawUsage') };
+}
+
 function parseIsoDate(raw: string): Date | null {
   const t = Date.parse(raw);
   if (!Number.isFinite(t)) return null;
@@ -312,14 +377,87 @@ function serializeRecord(rec: CostRecord): Record<string, unknown> {
     occurredAt: rec.occurredAt as unknown as string,
     ...(rec.metrics !== undefined && { metrics: rec.metrics }),
     ...(rec.attributes !== undefined && { attributes: rec.attributes }),
+    ...pick(rec, MODEL_CALL_FIELDS),
   };
 }
 
+/** A model call's fields on the wire, as the binding gives them (all optional). */
+const MODEL_CALL_FIELDS = [
+  'callId',
+  'projectId',
+  'rootRunId',
+  'parentRunId',
+  'agentVersion',
+  'flowId',
+  'nodeId',
+  'step',
+  'purpose',
+  'model',
+  'servedModel',
+  'fallback',
+  'status',
+  'usage',
+  'durationMs',
+  'finishReason',
+  'providerRequestId',
+  'attempts',
+  'error',
+  'rawUsage',
+] as const satisfies readonly (keyof CostRecord)[];
+
+function pick(rec: CostRecord, keys: readonly (keyof CostRecord)[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of keys) {
+    if (rec[key] !== undefined) out[key] = rec[key];
+  }
+  return out;
+}
+
+/** `?limit=` on the aggregate: the default when absent, `null` when it isn't 1..max. */
+function parseAggregateLimit(raw: string | undefined): number | null {
+  if (raw === undefined) return COST_AGGREGATE_DEFAULT_LIMIT;
+  if (!/^\d+$/.test(raw)) return null;
+  const n = Number(raw);
+  return n >= 1 && n <= COST_AGGREGATE_MAX_LIMIT ? n : null;
+}
+
+/**
+ * The aggregate's order: `totalUsd` descending, then the key, dimension
+ * by dimension in `groupBy` order (code-point order; `null` last).
+ */
+function compareGroups(
+  a: CostAggregateGroup,
+  b: CostAggregateGroup,
+  groupBy: readonly CostGroupDimension[],
+): number {
+  if (a.totalUsd !== b.totalUsd) return b.totalUsd - a.totalUsd;
+  for (const dim of groupBy) {
+    const x = a.key[dim] ?? null;
+    const y = b.key[dim] ?? null;
+    if (x === y) continue;
+    if (x === null) return 1;
+    if (y === null) return -1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 function serializeGroup(g: CostAggregateGroup): Record<string, unknown> {
   return {
     key: g.key,
     count: g.count,
     totalUsd: g.totalUsd,
+    tokens: serializeTokens(g.tokens),
+  };
+}
+
+function serializeTokens(t: CostTokenTotals): CostTokenTotals {
+  return {
+    prompt: t.prompt,
+    completion: t.completion,
+    cacheRead: t.cacheRead,
+    cacheWrite: t.cacheWrite,
+    reasoning: t.reasoning,
   };
 }
 

package/src/routes/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,6 +38,7 @@ 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 { SecretBinding } from '../secrets-binding.js';
@@ -112,6 +121,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
@@ -529,6 +540,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 +593,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 +676,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 +1375,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 +1422,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.