@kindgi/api 0.1.4-rc.1 → 0.1.4-rc.2

package/src/routes/agents.ts

@@ -23,10 +23,18 @@ import {
   nextFreeAgentVersion,
 } from '../derive-agent-version.js';
 import { statusFor, toWireError } from '../errors.js';
+import type { AgentReleaseBindings } from '../live-version-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import { refuseWritesWhenReadOnly } from '../registry-read-only.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
 import type { AppEnv } from '../types.js';
+import {
+  type AgentReleaseGateDeps,
+  isPromotionCheck,
+  isPromotionWrite,
+  mountAgentReleaseRoutes,
+} from './agent-releases.js';
+import { liveScopeToWire } from './live-scope-wire.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
 
@@ -52,6 +60,10 @@ export function agentsRouter(
   authorizer?: Authorizer,
   toolRegistry?: ToolRegistryBinding,
   blockRegistry?: BlockRegistryBinding,
+  /** Live versions per scope and promotions (evals step 4); absent → those routes aren't mounted. */
+  releases?: AgentReleaseBindings,
+  /** What a promotion's gate reads besides the releases (evals step 4b). */
+  gateDeps?: AgentReleaseGateDeps,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
   // A read-only registry (under `kindgi dev`, the pack's files) refuses
@@ -71,6 +83,9 @@ export function agentsRouter(
   //   POST /:agentId/versions                        → publish on the agent (derive)
   //   POST /:agentId/versions/:version/unregister    → admin on the agent
   //   POST /:agentId/versions/:version/reinstate     → admin on the agent
+  //   POST /:agentId/promotions, /live/rollback, /live/unpin → promote on the agent
+  //   POST /:agentId/promotions/check                → read on the agent (changes nothing)
+  //   GET /:agentId/live, /live-versions, /promotions[/…]    → read on the agent
   //   GET / (list)                                   → tenant-scoped fetch;
   //                                                    with a project scope
   //                                                    (?scopeKind=project&scopeId=),
@@ -108,9 +123,16 @@ export function agentsRouter(
     });
     r.use('/:agentId/*', async (c, next) => {
       // Deriving a version (POST …/versions) is `publish` on the agent;
-      // unregister and reinstate are `admin`.
+      // changing what's live is its own permission (`promote`, granted to
+      // the agent's admins); unregister and reinstate are `admin`.
       const action =
-        c.req.method === 'GET' ? 'read' : c.req.path.endsWith('/versions') ? 'publish' : 'admin';
+        c.req.method === 'GET' || isPromotionCheck(c.req.method, c.req.path)
+          ? 'read'
+          : isPromotionWrite(c.req.method, c.req.path)
+            ? 'promote'
+            : c.req.path.endsWith('/versions')
+              ? 'publish'
+              : 'admin';
       const agentId = c.req.param('agentId') ?? '';
       const mw = authorizer.authorize(action, () => ref('agent', agentId));
       return mw(c, next);
@@ -434,6 +456,23 @@ export function agentsRouter(
     const version = c.req.param('version') as Semver;
 
     const outcome = await binding.unregister({ tenantId, agentId, version });
+    if (!outcome.unregistered && outcome.live !== undefined && outcome.live.length > 0) {
+      c.status(statusFor('agent-version-live') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'agent-version-live',
+            message: `${agentId as unknown as string} ${version as unknown as string} is live in ${
+              outcome.live.length === 1 ? 'a scope' : `${outcome.live.length} scopes`
+            }: roll back, unpin, or promote another version there first, then unregister it.`,
+            agentId: agentId as unknown as string,
+            version: version as unknown as string,
+            scopes: outcome.live.map(liveScopeToWire),
+          },
+          requestId,
+        ),
+      );
+    }
     if (!outcome.unregistered) {
       c.status(statusFor('agent-not-found') as never);
       return c.json(
@@ -489,6 +528,8 @@ export function agentsRouter(
     });
   });
 
+  if (releases !== undefined) mountAgentReleaseRoutes(r, binding, releases, gateDeps);
+
   return r;
 }
 

package/src/routes/approvals.ts

@@ -406,6 +406,7 @@ export function approvalsRouter(
     // override it, when the resume payload must carry more than the
     // decision (an agent gate refuses one, above).
     let waitpointResolved = false;
+    let resume: ResumeReport | undefined;
     if (
       approval.waitTokenId !== undefined &&
       approval.provenanceRef?.runId !== undefined &&
@@ -440,15 +441,12 @@ export function approvalsRouter(
       // journaled `wait.resumed`. The approval-complete surface reports
       // the decision as successful; a run that stayed suspended because
       // the inline resume failed can be resumed later.
+      //
+      // The response says how the resume went (`resume`), so a decision
+      // whose run couldn't go on (a tool version it started with is gone,
+      // say) isn't reported as plain success.
       if (runHandler !== undefined) {
-        try {
-          await runHandler.resumeRun({
-            tenantId,
-            runId: approval.provenanceRef.runId as RunId,
-          });
-        } catch {
-          // Soft-fail — the decision is durable; the run can be resumed later.
-        }
+        resume = await resumeInline(runHandler, tenantId, approval.provenanceRef.runId as RunId);
       }
     }
 
@@ -461,6 +459,7 @@ export function approvalsRouter(
         nextApproval: serializeApproval(result.nextApproval),
       }),
       waitpointResolved,
+      ...(resume !== undefined && { resume }),
     });
   });
 
@@ -808,3 +807,32 @@ function parseAuditBundleBody(
     },
   };
 }
+
+/** How the inline resume after a decision went. */
+type ResumeReport =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'failed'; readonly code: string; readonly message: string };
+
+/**
+ * Resume the run a decision released, in the same request. A resume that
+ * fails is reported, not raised: the decision is durable either way, and
+ * the runtime ends a run that can't go on, or resumes it later.
+ */
+async function resumeInline(
+  runHandler: RunHandlerBinding,
+  tenantId: TenantId,
+  runId: RunId,
+): Promise<ResumeReport> {
+  try {
+    const outcome = await runHandler.resumeRun({ tenantId, runId });
+    return outcome.kind === 'ok'
+      ? { kind: 'ok' }
+      : { kind: 'failed', code: outcome.error.code, message: outcome.error.message };
+  } catch (cause) {
+    return {
+      kind: 'failed',
+      code: 'resume-failed',
+      message: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+}

package/src/routes/audit.ts

@@ -21,6 +21,7 @@
 //   ?from=<iso>&to=<iso>
 //   ?runId=<id>
 //   ?limit=<n>&cursor=<opaque>
+//   ?order=asc|desc   (asc, oldest first, by default)
 //
 
 import { Hono } from 'hono';
@@ -83,6 +84,14 @@ export function auditRouter(binding: AuditEventBinding, authorizer?: Authorizer)
     const from = c.req.query('from');
     const to = c.req.query('to');
     const runId = c.req.query('runId');
+    const orderRaw = c.req.query('order');
+
+    if (orderRaw !== undefined && orderRaw !== 'asc' && orderRaw !== 'desc') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError({ code: 'bad-input', message: '`order` must be "asc" or "desc"' }, requestId),
+      );
+    }
 
     let outcome: 'allowed' | 'denied' | undefined;
     if (outcomeRaw === 'allowed' || outcomeRaw === 'denied') outcome = outcomeRaw;
@@ -130,6 +139,7 @@ export function auditRouter(binding: AuditEventBinding, authorizer?: Authorizer)
         ...(to !== undefined && to.length > 0 && { to }),
       },
       ...(cursor !== undefined && cursor.length > 0 && { cursor }),
+      ...(orderRaw !== undefined && { order: orderRaw }),
       limit,
     });
 

package/src/routes/auth.ts

@@ -76,7 +76,7 @@ export function authRouters(options: AuthRouterOptions): {
   authed.get('/providers', async (c) => {
     const tenantId = c.get('tenantId') as TenantId;
     const page = await identityProvider.list({ tenantId });
-    return c.json({ data: page.data.map(serializeProviderConfig) });
+    return c.json({ data: page.data.map(serializeProviderConfig), hasMore: false });
   });
 
   // ---------- POST /providers ----------

package/src/routes/conversations.ts

@@ -18,6 +18,7 @@ import { statusFor, toWireError } from '../errors.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
 import { parseListScope } from './scope-params.js';
+import { refuseMalformedUuidParam } from './uuid-param.js';
 
 const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -28,6 +29,15 @@ const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]
  * order); conversation list sort is `openedAt DESC, id DESC`
  * (most-recently-opened first).
  */
+/**
+ * A `:conversationId` that isn't a conversation id is a 400
+ * (`uuid-param.ts`), not a 500 from the uuid cast (as `runs` does).
+ */
+const refuseMalformedConversationId = refuseMalformedUuidParam(
+  'conversationId',
+  'a conversation id',
+);
+
 export function conversationsRouter(
   conversationBinding: ConversationBinding,
   runBinding: RunBinding,
@@ -62,6 +72,23 @@ export function conversationsRouter(
 
     const agentIdRaw = c.req.query('agentId');
 
+    // Replay conversations (a comparison's replays) are left out unless asked for.
+    const replaysRaw = c.req.query('replays');
+    if (
+      replaysRaw !== undefined &&
+      replaysRaw !== 'exclude' &&
+      replaysRaw !== 'include' &&
+      replaysRaw !== 'only'
+    ) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          { code: 'bad-input', message: '`replays` must be `exclude`, `include` or `only`' },
+          requestId,
+        ),
+      );
+    }
+
     const scopeParsed = parseListScope(c.req.query(), { tenantId });
     if (scopeParsed.kind === 'err') {
       c.status(statusFor('scope-invalid') as never);
@@ -88,6 +115,7 @@ export function conversationsRouter(
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw as AgentId }),
       ...(statusFilter !== undefined && { status: statusFilter }),
+      replays: replaysRaw ?? 'exclude',
       ...(before !== undefined && { before }),
       limit,
     });
@@ -112,7 +140,7 @@ export function conversationsRouter(
   });
 
   // ---------- GET /:conversationId ----------
-  r.get('/:conversationId', async (c) => {
+  r.get('/:conversationId', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const conversationId = c.req.param('conversationId') as ConversationId;
@@ -186,7 +214,7 @@ export function conversationsRouter(
   });
 
   // ---------- POST /:conversationId/close (idempotent) ----------
-  r.post('/:conversationId/close', async (c) => {
+  r.post('/:conversationId/close', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const conversationId = c.req.param('conversationId') as ConversationId;
@@ -214,7 +242,7 @@ export function conversationsRouter(
   });
 
   // ---------- GET /:conversationId/messages (cursor-paginated, sequence asc) ----------
-  r.get('/:conversationId/messages', async (c) => {
+  r.get('/:conversationId/messages', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const conversationId = c.req.param('conversationId') as ConversationId;

package/src/routes/deployments.ts

@@ -38,9 +38,11 @@ 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 FlowPinsLive, publishDeployedFlow, resolveFlowPins } from '../flow-pins.js';
 import type { GuardrailRegistryBinding } from '../guardrail-binding.js';
 import type { ImageRegistryBinding } from '../image-registry-binding.js';
+import type { LiveVersionBinding } from '../live-version-binding.js';
+import { PublishRefused } from '../publish-refused.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';
@@ -122,6 +124,11 @@ export interface DeploymentsRouterBindings {
   readonly guardrailRegistry?: GuardrailRegistryBinding;
   readonly agentRegistry?: AgentRegistryBinding;
   readonly flowRegistry?: FlowRegistryBinding;
+  /**
+   * The agents' live versions: a deployed flow's agent step that names no
+   * version pins the one live for the deploy's project, else the latest.
+   */
+  readonly liveVersions?: LiveVersionBinding;
   /** Data blocks: an agent's block references are pinned at deploy with its tools. */
   readonly blockRegistry?: BlockRegistryBinding;
   /**
@@ -572,6 +579,8 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             rolled.push(async () => {
               await bindings.toolRegistry?.unregister({ tenantId, toolId, version });
             });
+          } else if (outcome.kind !== 'already-registered') {
+            throw new PublishRefused('tool', `${tool.id}@${tool.version}`, outcome.kind);
           }
         }
       }
@@ -595,6 +604,8 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             rolled.push(async () => {
               await bindings.guardrailRegistry?.unregister({ tenantId, guardrailId });
             });
+          } else if (outcome.kind !== 'already-registered') {
+            throw new PublishRefused('guardrail', guardrail.id, outcome.kind);
           }
         }
       }
@@ -619,6 +630,7 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
             flows: bindings.flowRegistry,
             tools: bindings.toolRegistry,
             agents: bindings.agentRegistry,
+            ...(bindings.liveVersions !== undefined && { live: bindings.liveVersions }),
             tenantId,
             projectId: defaultProjectId,
             defined: validated.flows,
@@ -630,6 +642,22 @@ export function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<App
       }
     } catch (cause) {
       await rollback(rolled);
+      // A primitive refused with a typed outcome is the caller's to fix:
+      // that outcome's own status and code. Anything thrown is a 500.
+      if (cause instanceof PublishRefused) {
+        c.status(statusFor(cause.code) as never);
+        return c.json(
+          toWireError(
+            {
+              code: cause.code,
+              message: `${cause.message}; nothing was deployed`,
+              primitive: cause.primitive,
+              id: cause.id,
+            },
+            requestId,
+          ),
+        );
+      }
       if (cause instanceof UnpinnableDeploy) {
         c.status(statusFor('invalid-agent') as never);
         return c.json(
@@ -1495,6 +1523,9 @@ async function registerAgents(input: {
     for (const agent of input.defined) {
       const outcome = await agents.publish({ tenantId, projectId, agent, enqueueTuples });
       if (outcome.kind === 'ok') written(outcome.agentId, outcome.version);
+      else if (outcome.kind !== 'already-registered') {
+        throw new PublishRefused('agent', `${agent.id}@${agent.version}`, outcome.kind);
+      }
     }
     return input.defined.map(deployedPrimitive);
   }
@@ -1524,7 +1555,10 @@ async function registerAgents(input: {
  * 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.
+ * within the one deploy, each derived once. An agent step that names no
+ * version pins what a run in the project gets: the agent's live version
+ * there, with `live`, else the latest (this deploy's, when it registered
+ * one).
  *
  * With the tool and agent registries, every flow is pinned first; one
  * that runs a tool or agent with no published version throws
@@ -1535,12 +1569,13 @@ async function registerFlows(input: {
   readonly flows: FlowRegistryBinding;
   readonly tools: ToolRegistryBinding | undefined;
   readonly agents: AgentRegistryBinding | undefined;
+  readonly live?: LiveVersionBinding;
   readonly tenantId: TenantId;
   readonly projectId: ProjectId;
   readonly defined: readonly Flow[];
   readonly rolled: RollbackAction[];
 }): Promise<DeployedFlow[]> {
-  const { flows, tools, agents, tenantId, projectId, rolled } = input;
+  const { flows, tools, agents, live, tenantId, projectId, rolled } = input;
   const enqueueTuples = (flowId: string) =>
     tuplesForCreate({ kind: 'flow', id: flowId as FlowId, tenantId, projectId });
   const written = (flowId: FlowId, version: string) =>
@@ -1552,11 +1587,20 @@ async function registerFlows(input: {
     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);
+      else if (outcome.kind !== 'already-registered') {
+        throw new PublishRefused('flow', `${flow.id}@${flow.version}`, outcome.kind);
+      }
     }
     return input.defined.map(deployedPrimitive);
   }
 
-  const pinsOf = await pinFlows(tools, agents, tenantId, input.defined);
+  const pinsOf = await pinFlows(
+    tools,
+    agents,
+    tenantId,
+    input.defined,
+    live !== undefined ? { binding: live, projectId } : undefined,
+  );
   const deployed: DeployedFlow[] = [];
   for (const [i, flow] of input.defined.entries()) {
     const outcome = await publishDeployedFlow({
@@ -1581,11 +1625,12 @@ async function pinFlows(
   agents: AgentRegistryBinding,
   tenantId: TenantId,
   defined: readonly Flow[],
+  live: FlowPinsLive | undefined,
 ): Promise<FlowPins[]> {
   const pins: FlowPins[] = [];
   const unpinnable: UnpinnableRef[] = [];
   for (const [i, flow] of defined.entries()) {
-    const resolved = await resolveFlowPins(tools, agents, tenantId, flow);
+    const resolved = await resolveFlowPins(tools, agents, tenantId, flow, live);
     if (resolved.kind === 'ok') {
       pins.push(resolved.pins);
       continue;

package/src/routes/env.ts

@@ -87,6 +87,7 @@ export function envRouter(envBinding: EnvBinding, authorizer?: Authorizer): Hono
     });
     return c.json({
       data: page.data.map(serializeEnvRecord),
+      hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
   });

package/src/routes/eval-comparison.ts

@@ -7,6 +7,7 @@ import type { ProjectId, Semver } from '@kindgi/types';
 
 import type { EvalBaseline, EvalComparison } from '../eval-run-binding.js';
 import { DEFAULT_COMPARISON } from '../judged-dispatcher.js';
+import { parseSegmentsBody } from './segments.js';
 
 const MAX_REPETITIONS = 10;
 const MAX_K = 100;
@@ -20,19 +21,18 @@ function obj(value: unknown): 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';
   }
+  const path = parseSegmentsBody(live.segments, 'baseline.live.segments');
+  if (path.kind === 'err') return path.message;
+  if (path.segments !== undefined && live.projectId === undefined) {
+    return '`baseline.live.segments` is a segment path in a project: it needs `baseline.live.projectId`';
+  }
   return {
     live: {
       ...(typeof live.projectId === 'string' && { projectId: live.projectId as ProjectId }),
-      ...(segments !== undefined && { segments: segments as Record<string, string> }),
+      ...(path.segments !== undefined && { segments: path.segments }),
     },
   };
 }
@@ -86,7 +86,8 @@ function integerIn(raw: unknown, name: string, max: number): number | string {
 
 /**
  * A comparison eval run's settings from the start body: `baseline`,
- * `reads`, `repetitions`, `k` and a flow candidate's `versions`.
+ * `reads`, `repetitions`, `k`, `classWeights` and a flow candidate's
+ * `versions`.
  * `undefined` when none is given (the defaults apply); an error message
  * for a bad one.
  */
@@ -95,7 +96,7 @@ export function parseComparison(
 ):
   | { readonly kind: 'ok'; readonly value?: EvalComparison }
   | { readonly kind: 'err'; readonly message: string } {
-  const { baseline, reads, repetitions, k } = b;
+  const { baseline, reads, repetitions, k, classWeights } = b;
   const versions = b.versions === undefined ? undefined : parseVersions(b.versions);
   if (typeof versions === 'string') return { kind: 'err', message: versions };
   if (
@@ -103,10 +104,22 @@ export function parseComparison(
     reads === undefined &&
     repetitions === undefined &&
     k === undefined &&
-    versions === undefined
+    versions === undefined &&
+    classWeights === undefined
   ) {
     return { kind: 'ok' };
   }
+  if (
+    classWeights !== undefined &&
+    classWeights !== 'as-recorded' &&
+    classWeights !== 'restricted-only'
+  ) {
+    return {
+      kind: 'err',
+      message:
+        "`classWeights` must be 'as-recorded' (every judgment at its class's weight) or 'restricted-only' (only judgments recorded under a restricted class)",
+    };
+  }
   const parsedBaseline =
     baseline === undefined ? DEFAULT_COMPARISON.baseline : parseBaseline(baseline);
   if (typeof parsedBaseline === 'string' && parsedBaseline !== 'recorded') {
@@ -130,6 +143,7 @@ export function parseComparison(
       repetitions: reps,
       k: topK,
       ...(versions !== undefined && { versions }),
+      ...(classWeights !== undefined && { classWeights }),
     },
   };
 }

package/src/routes/flows.ts

@@ -12,6 +12,7 @@ import type { UnpinnableRef } from '../agent-pins.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { FlowRegistryBinding, FlowVersionRecord } from '../flow-binding.js';
 import { resolveFlowPins } from '../flow-pins.js';
+import type { LiveVersionBinding } from '../live-version-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import { refuseWritesWhenReadOnly } from '../registry-read-only.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
@@ -37,16 +38,18 @@ import { parseScopeParams } from './scope-params.js';
  * `/v1/flows/:flowId/run` route is added here.
  *
  * With `pinning` (the tool and agent registries), a published version is
- * pinned: each tool it runs, and each agent it runs at no named version,
- * resolves once, at publish, to the latest version, which every run of
- * that version uses (`pins`, see `resolveFlowPins`); one with no
- * published version refuses the publish. Without it, versions carry no
- * pins and bind the latest versions per run.
+ * pinned: each tool it runs resolves once, at publish, to its latest
+ * version, and each agent it runs at no named version to what a run in
+ * the flow's project would get, its live version there with
+ * `pinning.live`, else its latest. Every run of that version uses those
+ * (`pins`, see `resolveFlowPins`); one with no published version refuses
+ * the publish. Without `pinning`, versions carry no pins and bind the
+ * latest versions per run.
  */
 export function flowsRouter(
   binding: FlowRegistryBinding,
   authorizer?: Authorizer,
-  pinning?: { readonly tools: ToolRegistryBinding; readonly agents: AgentRegistryBinding },
+  pinning?: FlowPinning,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
   // A read-only registry (under `kindgi dev`, the pack's files) refuses
@@ -300,7 +303,7 @@ export function flowsRouter(
     // Pin the version: every tool and unversioned agent resolves now,
     // once, to the version its runs use. One with no published version
     // refuses the publish rather than store a partly pinned version.
-    const pinned = await pinFlow(pinning, tenantId, loaded.value);
+    const pinned = await pinFlow(pinning, tenantId, projectId, loaded.value);
     if (pinned.kind === 'unpinnable') {
       c.status(statusFor('validation-failed') as never);
       return c.json(toWireError(unpinnableFlow(loaded.value, pinned.issues), requestId));
@@ -415,19 +418,32 @@ export function flowsRouter(
   return r;
 }
 
+/** The registries a published flow version is pinned against. */
+export interface FlowPinning {
+  readonly tools: ToolRegistryBinding;
+  readonly agents: AgentRegistryBinding;
+  /** The agents' live versions: an agent step pins the one live for the flow's project. */
+  readonly live?: LiveVersionBinding;
+}
+
 /** The flow with its pins, or the references with no published version; as it is without `pinning`. */
 async function pinFlow(
-  pinning:
-    | { readonly tools: ToolRegistryBinding; readonly agents: AgentRegistryBinding }
-    | undefined,
+  pinning: FlowPinning | undefined,
   tenantId: TenantId,
+  projectId: ProjectId,
   flow: Flow,
 ): Promise<
   | { readonly kind: 'ok'; readonly flow: Flow }
   | { readonly kind: 'unpinnable'; readonly issues: readonly UnpinnableRef[] }
 > {
   if (pinning === undefined) return { kind: 'ok', flow };
-  const resolved = await resolveFlowPins(pinning.tools, pinning.agents, tenantId, flow);
+  const resolved = await resolveFlowPins(
+    pinning.tools,
+    pinning.agents,
+    tenantId,
+    flow,
+    pinning.live !== undefined ? { binding: pinning.live, projectId } : undefined,
+  );
   if (resolved.kind === 'unpinnable') return resolved;
   return {
     kind: 'ok',