@kindgi/api 0.1.4 → 0.1.5-rc.0

package/src/proposal-status.ts

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { EvalRun, EvalRunStatus } from './eval-run-binding.js';
+import type { JudgedComparisonSummary } from './judged-dispatcher.js';
+import type { Promotion } from './live-version-binding.js';
+import type { ProposalObjective, StoredProposal } from './supervisor-binding.js';
+
+/**
+ * Where an improvement proposal stands. Never stored: it follows from the
+ * proposal's own steps, its comparison eval run and its promotion.
+ *
+ * - `draft`: not evaluated yet.
+ * - `evaluating`: its comparison is queued or running.
+ * - `evaluated`: the comparison finished and the candidate beat the
+ *   recorded outputs on the objective metric by more than the noise.
+ * - `not-better`: the comparison finished; the candidate didn't.
+ * - `evaluation-failed`: the comparison failed or was cancelled.
+ * - `in-review`: requested; the gate passed and an approval is open.
+ * - `promoted`: the candidate went live for the scope.
+ * - `refused`: requested; the gate refused it.
+ * - `rejected`: the reviewer rejected it.
+ * - `expired`: the approval expired undecided.
+ * - `superseded`: approved after the scope's live version or policy changed.
+ * - `rolled-back`: rolled back through the proposal.
+ * - `withdrawn`: withdrawn.
+ */
+export type FixProposalStatus =
+  | 'draft'
+  | 'evaluating'
+  | 'evaluated'
+  | 'not-better'
+  | 'evaluation-failed'
+  | 'in-review'
+  | 'promoted'
+  | 'refused'
+  | 'rejected'
+  | 'expired'
+  | 'superseded'
+  | 'rolled-back'
+  | 'withdrawn';
+
+export const FIX_PROPOSAL_STATUSES: readonly FixProposalStatus[] = [
+  'draft',
+  'evaluating',
+  'evaluated',
+  'not-better',
+  'evaluation-failed',
+  'in-review',
+  'promoted',
+  'refused',
+  'rejected',
+  'expired',
+  'superseded',
+  'rolled-back',
+  'withdrawn',
+];
+
+/** What a finished comparison says about the candidate, on the proposal's objective. */
+export interface ProposalEvaluationOutcome {
+  readonly runStatus: EvalRunStatus;
+  readonly objective: ProposalObjective;
+  /** The recorded (judged) outputs' score. `null` without judged evidence. */
+  readonly baseline?: number | null;
+  readonly candidate?: number | null;
+  readonly delta?: number | null;
+  /** With more than one repetition: the candidate's max − min. The noise a delta must beat. */
+  readonly spread?: number;
+  readonly cases?: number;
+  /** Set once the comparison finished. */
+  readonly better?: boolean;
+}
+
+/** Room for float rounding. */
+const EPSILON = 1e-9;
+
+/** A finished comparison's summary, or `null` for any other eval run. */
+export function comparisonSummaryOf(run: EvalRun): JudgedComparisonSummary | null {
+  const summary = run.result?.summary;
+  return run.kind === 'judged' && summary !== null && typeof summary === 'object'
+    ? (summary as JudgedComparisonSummary)
+    : null;
+}
+
+/** The proposal's evaluation, read off its eval run. */
+export function evaluationOutcome(
+  objective: ProposalObjective,
+  run: EvalRun,
+): ProposalEvaluationOutcome {
+  const summary = run.status === 'completed' ? comparisonSummaryOf(run) : null;
+  if (summary === null) return { runStatus: run.status, objective };
+  const metric = summary.metrics[objective];
+  const noise = metric.spread ?? 0;
+  return {
+    runStatus: run.status,
+    objective,
+    baseline: metric.baseline,
+    candidate: metric.candidate,
+    delta: metric.delta,
+    ...(metric.spread !== undefined && { spread: metric.spread }),
+    cases: summary.cases,
+    better: metric.delta !== null && metric.delta > noise + EPSILON,
+  };
+}
+
+const PROMOTION_STATUS: Readonly<Record<NonNullable<Promotion['status']>, FixProposalStatus>> = {
+  'pending-approval': 'in-review',
+  promoted: 'promoted',
+  refused: 'refused',
+  rejected: 'rejected',
+  expired: 'expired',
+  superseded: 'superseded',
+};
+
+/**
+ * A proposal's status from what's recorded: its own steps first
+ * (withdrawn, rolled back), then its promotion, then its comparison.
+ * `promotion` and `evaluation` are what the proposal's ids resolve to
+ * (`undefined` when it has none).
+ */
+export function proposalStatus(
+  proposal: StoredProposal,
+  promotion: Promotion | null | undefined,
+  evaluation: ProposalEvaluationOutcome | null | undefined,
+): FixProposalStatus {
+  if (proposal.withdrawn !== undefined) return 'withdrawn';
+  if (proposal.rolledBack !== undefined) return 'rolled-back';
+  if (promotion !== undefined && promotion !== null) {
+    return PROMOTION_STATUS[promotion.status ?? 'promoted'];
+  }
+  if (evaluation === undefined || evaluation === null) {
+    return proposal.evaluation === undefined ? 'draft' : 'evaluation-failed';
+  }
+  switch (evaluation.runStatus) {
+    case 'pending':
+    case 'running':
+      return 'evaluating';
+    case 'failed':
+    case 'cancelled':
+      return 'evaluation-failed';
+    case 'completed':
+      return evaluation.better === true ? 'evaluated' : 'not-better';
+  }
+}
+
+/** The lifecycle calls, and the statuses each starts from. */
+export const PROPOSAL_ACTIONS = {
+  evaluate: [
+    'draft',
+    'evaluated',
+    'not-better',
+    'evaluation-failed',
+    'refused',
+    'superseded',
+    'expired',
+  ],
+  // The gate decides what goes live: a candidate that isn't measurably
+  // better (a wording change) can still be requested through it.
+  request: ['evaluated', 'not-better', 'refused', 'superseded', 'expired'],
+  rollback: ['promoted'],
+  withdraw: [
+    'draft',
+    'evaluated',
+    'not-better',
+    'evaluation-failed',
+    'refused',
+    'superseded',
+    'expired',
+  ],
+} as const satisfies Readonly<Record<string, readonly FixProposalStatus[]>>;
+
+export type ProposalAction = keyof typeof PROPOSAL_ACTIONS;
+
+export function proposalActionAllowed(action: ProposalAction, status: FixProposalStatus): boolean {
+  return (PROPOSAL_ACTIONS[action] as readonly FixProposalStatus[]).includes(status);
+}

package/src/provider-binding.ts

@@ -131,6 +131,14 @@ export interface ProviderRegisterInput {
    * to the runtime, never returned by `list` / `get`.
    */
   readonly adapterConfig?: AdapterConfig;
+  /**
+   * Whether the runtime sends each model call's W3C `traceparent` to this
+   * provider (as a header; ids only, never content), so the vendor's
+   * request logs can be matched to the run. Opt-in: absent or `false`
+   * sends none. The runtime enforces it, not the adapter: it sets
+   * `ModelCallInput.traceparent` only for a provider that opted in.
+   */
+  readonly sendTraceparent?: boolean;
 }
 
 export interface ProviderSecretRef {
@@ -152,6 +160,8 @@ export interface ProviderRuntimeEntry {
   readonly adapterId: string;
   readonly secretRef?: ProviderSecretRef;
   readonly adapterConfig?: AdapterConfig;
+  /** `ProviderRegisterInput.sendTraceparent`: absent is `false`. */
+  readonly sendTraceparent?: boolean;
 }
 
 export interface ProviderResolveForRuntimeInput {

package/src/publish-refused.ts

@@ -1,31 +1,60 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
+import type { ProjectId } from '@kindgi/types';
+
 import type { AgentRegistryBinding } from './agent-binding.js';
 import type { FlowRegistryBinding } from './flow-binding.js';
 import type { GuardrailRegistryBinding } from './guardrail-binding.js';
 import type { ToolRegistryBinding } from './tool-binding.js';
 
+type PublishedPrimitive = 'tool' | 'guardrail' | 'agent' | 'flow';
+
+/** A registry's answer to a deploy's publish, other than `ok` or `already-registered`. */
+type RefusedOutcome = Exclude<
+  | Awaited<ReturnType<ToolRegistryBinding['publish']>>
+  | Awaited<ReturnType<GuardrailRegistryBinding['register']>>
+  | Awaited<ReturnType<AgentRegistryBinding['publish']>>
+  | Awaited<ReturnType<FlowRegistryBinding['publish']>>,
+  { readonly kind: 'ok' | 'already-registered' }
+>;
+
 /**
  * A deploy's primitive came back from its registry with an outcome other
  * than `ok` or `already-registered` (e.g. `project-not-found`): the deploy
  * stops, what it published is rolled back, and the route answers with
  * that outcome's own status and code (T205). Before, such an outcome was
  * skipped, and the deployment was recorded without that primitive.
+ *
+ * A primitive whose id belongs to another project answers
+ * `<primitive>-project-mismatch`, as publishing it on its own does: a
+ * deploy never moves it. The project it belongs to (`projectId`) is for
+ * the log, never the answer.
  */
 export class PublishRefused extends Error {
+  /** The code the deploy answers with. */
+  readonly code:
+    | Exclude<RefusedOutcome['kind'], 'project-mismatch'>
+    | `${PublishedPrimitive}-project-mismatch`;
+  /** With `…-project-mismatch`: the project the primitive belongs to, for the log only. */
+  readonly projectId?: ProjectId;
+
   constructor(
-    readonly primitive: 'tool' | 'guardrail' | 'agent' | 'flow',
+    readonly primitive: PublishedPrimitive,
     readonly id: string,
-    readonly code: Exclude<
-      | Awaited<ReturnType<ToolRegistryBinding['publish']>>['kind']
-      | Awaited<ReturnType<GuardrailRegistryBinding['register']>>['kind']
-      | Awaited<ReturnType<AgentRegistryBinding['publish']>>['kind']
-      | Awaited<ReturnType<FlowRegistryBinding['publish']>>['kind'],
-      'ok' | 'already-registered'
-    >,
+    outcome: RefusedOutcome,
   ) {
-    super(`The ${primitive} ${id} wasn't published: ${code}`);
+    const code =
+      outcome.kind === 'project-mismatch'
+        ? (`${primitive}-project-mismatch` as const)
+        : outcome.kind;
+    super(
+      outcome.kind === 'project-mismatch'
+        ? `The ${primitive} ${id} wasn't published: it belongs to another project`
+        : `The ${primitive} ${id} wasn't published: ${code}`,
+    );
     this.name = 'PublishRefused';
+    this.code = code;
+    if (outcome.kind === 'project-mismatch') this.projectId = outcome.projectId;
   }
 }

package/src/routes/adapters.ts

@@ -17,8 +17,10 @@ import {
   type AdapterTestOutcome,
 } from '../adapter-binding.js';
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { tenantResourceAccess } from './tenant-access.js';
 
 /**
  * Adapters resource routes — part of the admin control plane. Unified
@@ -46,8 +48,10 @@ import { clampLimit } from './pagination.js';
 export function adaptersRouter(
   binding: AdapterRegistryBinding,
   factories?: AdapterFactoryRegistry,
+  authorizer?: Authorizer,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  r.use('*', tenantResourceAccess(authorizer));
 
   // ---------- GET / (list, cursor-paginated) ----------
   r.get('/', async (c) => {

package/src/routes/agent-releases.ts

@@ -12,11 +12,12 @@ import type { AgentRegistryBinding } from '../agent-binding.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { EvalRun, EvalRunBinding } from '../eval-run-binding.js';
 import type { GatePolicy } from '../gate-policy-binding.js';
-import { type GateResult, evaluateGate } from '../gate.js';
+import { type GateApproval, type GateCheck, type GateResult, evaluateGate } from '../gate.js';
 import type { JudgedComparisonSummary } from '../judged-dispatcher.js';
 import type {
   AgentReleaseBindings,
   LiveResolveInput,
+  PromoteInput,
   Promotion,
   PromotionActor,
 } from '../live-version-binding.js';
@@ -137,79 +138,17 @@ export function mountAgentReleaseRoutes(
     const requestId = c.get('requestId');
     const parsed = await readPromotionBody(c);
     if (parsed.kind === 'err') return badInput(c, requestId, parsed.message);
-    const tenantId = c.get('tenantId') as TenantId;
     const agentId = c.req.param('agentId');
-    const input = {
-      tenantId,
+    const outcome = await requestPromotion(registry, releases, deps, {
+      tenantId: c.get('tenantId') as TenantId,
       agentId,
       version: parsed.value.version,
       scope: parsed.value.scope,
       requestedBy: actorOf(c),
       ...(parsed.value.reason !== undefined && { reason: parsed.value.reason }),
       ...(parsed.value.evalRunId !== undefined && { evalRunId: parsed.value.evalRunId }),
-    };
-    const policy = await policyFor(releases, tenantId, agentId, parsed.value.scope);
-    if (releases.promotions.request === undefined) {
-      if (policy !== null) {
-        c.status(statusFor('promotion-gate-unsupported') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'promotion-gate-unsupported',
-              message: `Gate policy ${policy.id} ${policy.version} applies to this promotion, and this deployment can't record a gated promotion yet.`,
-            },
-            requestId,
-          ),
-        );
-      }
-      // No gate, and a binding from before gates: promote as before.
-      const outcome = await releases.promotions.promote(input);
-      if (outcome.kind === 'err') return failed(c, requestId, outcome.error);
-      c.status(201);
-      return c.json(serializePromotion(outcome.value));
-    }
-    const gate = await runGate(
-      registry,
-      releases,
-      deps,
-      { ...parsed.value, tenantId, agentId },
-      policy,
-    );
-    if (gate.kind === 'err') return failed(c, requestId, gate.error);
-    const outcome = await releases.promotions.request({
-      ...input,
-      gate: {
-        policy: policy === null ? null : { id: policy.id, version: policy.version },
-        checks: gate.result.checks,
-        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);
-    const promotion = outcome.value;
-    if (promotion.status === 'refused') {
-      const checks = promotion.checks ?? gate.result.checks;
-      c.status(statusFor('gate-failed') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'gate-failed',
-            message: `The gate refused ${agentId} ${parsed.value.version}: ${checks
-              .filter((check) => !check.passed)
-              .map((check) => check.message)
-              .join(' ')}`,
-            promotionId: promotion.id,
-            policy: promotion.policy ?? null,
-            checks,
-          },
-          requestId,
-        ),
-      );
-    }
-    c.status(promotion.status === 'pending-approval' ? 202 : 201);
-    return c.json(serializePromotion(promotion));
+    return promotionResponse(c, outcome);
   });
 
   r.post('/:agentId/promotions/check', async (c) => {
@@ -341,6 +280,119 @@ export function mountAgentReleaseRoutes(
 
 type Ctx = Context<AppEnv>;
 
+/** A promotion request's outcome: recorded, refused before recording, or unsupported here. */
+export type PromotionRequestOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly promotion: Promotion;
+      /** The gate's checks as they ran (a binding may not echo them on the row). */
+      readonly checks?: readonly GateCheck[];
+    }
+  | { readonly kind: 'err'; readonly error: { code: string; message: string } }
+  | { readonly kind: 'gate-unsupported'; readonly policy: GatePolicy };
+
+/**
+ * Request that `version` go live for `scope`, through the scope's gate:
+ * the binding records it as promoted, waiting for approval, or refused
+ * (`promotion.status`). Without gated requests in this deployment, an
+ * ungated scope promotes as before and a gated one is unsupported.
+ */
+export async function requestPromotion(
+  registry: AgentRegistryBinding,
+  releases: AgentReleaseBindings,
+  deps: AgentReleaseGateDeps,
+  input: PromoteInput,
+  options: {
+    /** An approval the promotion waits for even when the scope's policy asks for none. */
+    readonly requireApproval?: GateApproval;
+  } = {},
+): Promise<PromotionRequestOutcome> {
+  const policy = await policyFor(releases, input.tenantId, input.agentId, input.scope);
+  if (releases.promotions.request === undefined) {
+    if (policy !== null) return { kind: 'gate-unsupported', policy };
+    if (options.requireApproval !== undefined) {
+      return {
+        kind: 'err',
+        error: {
+          code: 'promotion-gate-unsupported',
+          message:
+            "This promotion waits for a reviewer's approval, and this deployment can't record a gated promotion yet.",
+        },
+      };
+    }
+    // No gate, and a binding from before gates: promote as before.
+    const outcome = await releases.promotions.promote(input);
+    return outcome.kind === 'err'
+      ? { kind: 'err', error: outcome.error }
+      : { kind: 'ok', promotion: outcome.value };
+  }
+  const gate = await runGate(registry, releases, deps, input, policy);
+  if (gate.kind === 'err') return gate;
+  const approval = gate.result.approval ?? options.requireApproval;
+  const outcome = await releases.promotions.request({
+    ...input,
+    gate: {
+      policy: policy === null ? null : { id: policy.id, version: policy.version },
+      checks: gate.result.checks,
+      passed: gate.result.passed,
+      ...(approval !== undefined && { approval }),
+      servingVersion: gate.servingVersion as Semver,
+      ...(gate.pinInPlace && { pinInPlace: true }),
+    },
+  });
+  return outcome.kind === 'err'
+    ? { kind: 'err', error: outcome.error }
+    : { kind: 'ok', promotion: outcome.value, checks: gate.result.checks };
+}
+
+/**
+ * The answer to a promotion request: 201 promoted, 202 waiting for
+ * approval, 422 `gate-failed` with the checks, or the error.
+ */
+export function promotionResponse(
+  c: Ctx,
+  outcome: PromotionRequestOutcome,
+  extra: Readonly<Record<string, unknown>> = {},
+) {
+  const requestId = c.get('requestId');
+  if (outcome.kind === 'gate-unsupported') {
+    c.status(statusFor('promotion-gate-unsupported') as never);
+    return c.json(
+      toWireError(
+        {
+          code: 'promotion-gate-unsupported',
+          message: `Gate policy ${outcome.policy.id} ${outcome.policy.version} applies to this promotion, and this deployment can't record a gated promotion yet.`,
+        },
+        requestId,
+      ),
+    );
+  }
+  if (outcome.kind === 'err') return failed(c, requestId, outcome.error);
+  const { promotion } = outcome;
+  if (promotion.status === 'refused') {
+    const checks = promotion.checks ?? outcome.checks ?? [];
+    c.status(statusFor('gate-failed') as never);
+    return c.json(
+      toWireError(
+        {
+          code: 'gate-failed',
+          message: `The gate refused ${promotion.agentId} ${promotion.toVersion as unknown as string}: ${checks
+            .filter((check) => !check.passed)
+            .map((check) => check.message)
+            .join(' ')}`,
+          promotionId: promotion.id,
+          policy: promotion.policy ?? null,
+          checks,
+          ...extra,
+        },
+        requestId,
+      ),
+    );
+  }
+  c.status(promotion.status === 'pending-approval' ? 202 : 201);
+  return c.json({ ...serializePromotion(promotion), ...extra });
+}
+
 async function readBody(c: Ctx): Promise<Record<string, unknown> | undefined> {
   try {
     const body: unknown = await c.req.json();
@@ -409,7 +461,7 @@ async function readPromotionBody(c: Ctx): Promise<
 }
 
 /** The gate policy for a promotion of `agentId` for `scope`; `null` when none applies. */
-async function policyFor(
+export async function policyFor(
   releases: AgentReleaseBindings,
   tenantId: TenantId,
   agentId: string,
@@ -421,7 +473,7 @@ async function policyFor(
 }
 
 /** The scope's coordinates, as a run in it would resolve its version. */
-function coordinatesOf(scope: LiveScope): Omit<LiveResolveInput, 'tenantId' | 'agentId'> {
+export function coordinatesOf(scope: LiveScope): Omit<LiveResolveInput, 'tenantId' | 'agentId'> {
   switch (scope.kind) {
     case 'tenant':
       return {};
@@ -566,7 +618,7 @@ async function runGate(
 }
 
 /** Who asked, from the request's principal. */
-function actorOf(c: Ctx): PromotionActor {
+export function actorOf(c: Ctx): PromotionActor {
   const actor = c.get('principal')?.actor;
   if (actor === undefined) return { kind: 'service', id: 'unknown' };
   return { kind: actor.kind === 'user' ? 'user' : 'service', id: actor.id };