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

package/src/openapi/operations.ts

@@ -385,6 +385,15 @@ const ApprovalRequiredRoleQueryParam: ParameterSpec = {
   schema: { $ref: '#/components/schemas/ReviewerRole' },
 };
 
+const WaitTokenIdQueryParam: ParameterSpec = {
+  name: 'waitTokenId',
+  in: 'query',
+  required: false,
+  description:
+    "Only approvals linked to one of these run waits (an approval's `waitTokenId`; a run's journal names its open waits in `wait.suspended` entries). Repeat it for several, at most 50.",
+  schema: { type: 'array', items: { type: 'string', minLength: 1 }, maxItems: 50 },
+};
+
 const CreatedAfterQueryParam: ParameterSpec = {
   name: 'createdAfter',
   in: 'query',
@@ -1612,6 +1621,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ApprovalStatusQueryParam,
       ApprovalRequiredRoleQueryParam,
       CreatedAfterQueryParam,
+      WaitTokenIdQueryParam,
     ],
     responses: {
       '200': { description: 'Page of approvals.', schema: ref('ApprovalCollectionPage') },
@@ -1962,7 +1972,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'agents.promotions.create',
     summary: 'Make a version live for a scope',
     description:
-      "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.",
+      "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.\n\nA pin in place skips the gate: when the scope has no live version of its own and already serves exactly `version` (from a scope above, or as the latest), pinning it there changes nothing any run gets, so it is promoted (`201`) with one passing `pinInPlace` check, no comparison and no approval, its reason starting `pin-in-place`. It is re-checked as it is written; if the scope moved meanwhile, `409 promotion-superseded`: check again.",
     tags: ['agents'],
     security: 'bearer',
     parameters: [AgentIdPathParam, IdempotencyKeyParam],
@@ -1978,7 +1988,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
         'The version is not registered, or was unregistered; or the eval run is not found.',
       ),
       '409': ErrorResponse(
-        "`promotion-superseded`: the scope's live version changed while the gate ran; check again.",
+        "`promotion-superseded`: the scope's live version changed while the gate ran; check again. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.",
       ),
       '422': ErrorResponse(
         '`gate-failed`: the gate refused it. `details.checks` has every check; the refusal is recorded (`details.promotionId`).',
@@ -2076,7 +2086,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ...CommonMutationErrors,
       '400': ErrorResponse('Validation failed (see `details.issues`).'),
       '409': ErrorResponse(
-        '`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: nothing covering the scope is pinned, so a published version would go live there ungated; pin a version for the scope, or one above it, first.',
+        '`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: the scope has no live version of its own; a gated scope holds its own pin (a pin above it is not enough, since a promotion there would change this scope ungated), so pin a version for the scope first.',
       ),
     },
   },
@@ -2158,6 +2168,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'The reinstated version.', schema: ref('GatePolicy') },
       ...CommonMutationErrors,
       '404': ErrorResponse('No such version.'),
+      '409': ErrorResponse(
+        '`gate-policy-scope-taken`: another policy gates the agent for the scope now (`details.heldBy`). `gate-policy-scope-unpinned`: the scope has no live version of its own; pin one first.',
+      ),
     },
   },
   {
@@ -2215,7 +2228,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Rolled back.', schema: ref('Promotion') },
       ...CommonMutationErrors,
       '404': ErrorResponse('`toVersion` is not registered, or was unregistered.'),
-      '409': ErrorResponse('The scope has no pin, or no earlier version to go back to.'),
+      '409': ErrorResponse(
+        '`not-pinned`: the scope has no pin of its own. `nothing-to-roll-back`: no earlier version to go back to. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.',
+      ),
     },
   },
   {
@@ -2234,7 +2249,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Unpinned.', schema: ref('Promotion') },
       ...CommonMutationErrors,
       '409': ErrorResponse(
-        '`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: unpinning would leave a scope a gate policy applies to on the latest version, where publishing goes live ungated.',
+        '`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: the scope has a gate policy of its own, and a gated scope keeps its own pin; unregister the policy first, or roll back instead. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.',
       ),
     },
   },

package/src/routes/agent-releases.ts

@@ -184,6 +184,7 @@ export function mountAgentReleaseRoutes(
         passed: gate.result.passed,
         ...(gate.result.approval !== undefined && { approval: gate.result.approval }),
         servingVersion: gate.servingVersion as Semver,
+        ...(gate.pinInPlace && { pinInPlace: true }),
       },
     });
     if (outcome.kind === 'err') return failed(c, requestId, outcome.error);
@@ -441,10 +442,32 @@ function summaryOf(run: EvalRun): JudgedComparisonSummary | null {
     : null;
 }
 
+/** Whether two live scopes are the same scope. */
+function sameScope(a: LiveScope, b: LiveScope): boolean {
+  switch (a.kind) {
+    case 'tenant':
+      return b.kind === 'tenant';
+    case 'org':
+      return b.kind === 'org' && b.orgId === a.orgId;
+    case 'project':
+      return b.kind === 'project' && b.projectId === a.projectId;
+    case 'segment':
+      return (
+        b.kind === 'segment' &&
+        b.projectId === a.projectId &&
+        b.path.length === a.path.length &&
+        b.path.every((s, i) => s.key === a.path[i]?.key && s.value === a.path[i]?.value)
+      );
+  }
+}
+
 /**
  * The gate for a promotion request: what serves the scope now, the
  * comparison it names, and the policy's checks against them. With no
- * policy there's nothing to check.
+ * policy there's nothing to check. A pin in place (the scope has no pin
+ * of its own and serves exactly the version already) changes nothing any
+ * run gets, so the policy's checks and approval don't apply: one passing
+ * `pinInPlace` check, and `pinInPlace` for the binding to re-check.
  */
 async function runGate(
   registry: AgentRegistryBinding,
@@ -459,7 +482,7 @@ async function runGate(
   },
   policy: GatePolicy | null,
 ): Promise<
-  | { kind: 'ok'; result: GateResult; servingVersion: string }
+  | { kind: 'ok'; result: GateResult; servingVersion: string; pinInPlace?: boolean }
   | { kind: 'err'; error: { code: string; message: string } }
 > {
   const { tenantId, agentId } = req;
@@ -483,6 +506,27 @@ async function runGate(
     servingVersion = latest.version as unknown as string;
   }
   if (policy === null) return { kind: 'ok', result: { checks: [], passed: true }, servingVersion };
+  if (servingVersion === (req.version as unknown as string)) {
+    const pins = await releases.live.list({ tenantId, agentId });
+    if (!pins.some((pin) => sameScope(pin.scope, req.scope))) {
+      const from = live === null ? 'as the latest version' : 'from a pin above it';
+      return {
+        kind: 'ok',
+        result: {
+          checks: [
+            {
+              name: 'pinInPlace',
+              passed: true,
+              message: `${agentId} ${servingVersion} already serves this scope (${from}), so pinning it here changes nothing for runs: the gate's checks and approval don't apply.`,
+            },
+          ],
+          passed: true,
+        },
+        servingVersion,
+        pinInPlace: true,
+      };
+    }
+  }
 
   let summary: JudgedComparisonSummary | null = null;
   if (req.evalRunId !== undefined) {

package/src/routes/approvals.ts

@@ -57,6 +57,10 @@ const DECISION_KINDS: ReadonlySet<ReviewDecisionKind> = new Set([
 
 const ROLE_VALUES: ReadonlySet<ReviewerRole> = new Set(['standard', 'senior', 'admin']);
 
+/** How many `waitTokenId` values a list takes, and how long each may be. */
+const MAX_WAIT_TOKEN_IDS = 50;
+const MAX_WAIT_TOKEN_ID_LENGTH = 512;
+
 /**
  * Terminal approval statuses — the ones an audit bundle can be exported for.
  * An `expired` approval has no recorded decision.
@@ -214,6 +218,23 @@ export function approvalsRouter(
       createdAfterIso = parsed.toISOString();
     }
 
+    const waitTokenIds = c.req.queries('waitTokenId') ?? [];
+    if (
+      waitTokenIds.length > MAX_WAIT_TOKEN_IDS ||
+      waitTokenIds.some((t) => t.length === 0 || t.length > MAX_WAIT_TOKEN_ID_LENGTH)
+    ) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`waitTokenId\` takes at most ${MAX_WAIT_TOKEN_IDS} values, each 1–${MAX_WAIT_TOKEN_ID_LENGTH} characters`,
+          },
+          requestId,
+        ),
+      );
+    }
+
     const cursor = c.req.query('cursor');
     if (cursor !== undefined && cursor.length > 0) {
       const parsed = new Date(cursor);
@@ -238,6 +259,7 @@ export function approvalsRouter(
       ...(requiredRoleFilter !== undefined && { requiredRole: requiredRoleFilter }),
       ...(createdAfterIso !== undefined && { since: createdAfterIso as unknown as Timestamp }),
       ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor as Cursor }),
+      ...(waitTokenIds.length > 0 && { waitTokenIds }),
     };
     const listed = await hitlBinding.listApprovals(listInput);
     if (listed.kind === 'err') {