@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/provenance-binding.ts

@@ -8,7 +8,16 @@
 // touches provenance storage directly.
 //
 
-import type { FlowId, ProvenanceId, Result, RunId, TenantId, Timestamp } from '@kindgi/types';
+import type {
+  FlowId,
+  ListScope,
+  ProjectId,
+  ProvenanceId,
+  Result,
+  RunId,
+  TenantId,
+  Timestamp,
+} from '@kindgi/types';
 
 // ---------- domain type surface ----------
 
@@ -98,6 +107,8 @@ export interface ProvenanceListCursor {
 export interface ListProvenanceRecordsInput {
   readonly tenantId: TenantId;
   readonly limit: number;
+  /** Only one project's records, or every project's in an org. Absent: the tenant's. */
+  readonly scope?: ListScope;
   readonly runId?: RunId;
   readonly agentId?: string;
   readonly createdAfter?: Date;
@@ -117,6 +128,8 @@ export interface ProvenanceRecordSummary {
   readonly createdAt: Timestamp;
   readonly flowRef?: { readonly id: FlowId; readonly version: string };
   readonly signed: boolean;
+  /** The project of the record's run; absent on records from before it was stored. */
+  readonly projectId?: ProjectId;
 }
 
 export interface ListProvenanceRecordsResult {
@@ -166,4 +179,32 @@ export interface ProvenanceBinding {
    * tenant/run pair.
    */
   getByRunId(tenantId: TenantId, runId: RunId): Promise<Result<Provenance, ProvenanceBindingError>>;
+
+  /**
+   * The cost ledger's usage of each model call in the run's provenance,
+   * by the `callId` in its `model-call` node's attributes. Optional: a
+   * deployment without a cost ledger omits it. The routes add it to a
+   * read as `callUsage`, outside the signed DAG; a signed export
+   * includes it as it stood when signed.
+   */
+  getCallUsage?(
+    tenantId: TenantId,
+    runId: RunId,
+  ): Promise<Result<CallUsageByCallId, ProvenanceBindingError>>;
 }
+
+/** One model call's usage, as the cost ledger has it. */
+export interface CallUsage {
+  readonly usage: {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+  };
+  readonly costUsd?: number;
+  readonly durationMs?: number;
+  readonly servedModel?: string;
+}
+
+export type CallUsageByCallId = Readonly<Record<string, CallUsage>>;

package/src/provider-binding.ts

@@ -18,7 +18,7 @@ import type { CapabilityDescriptor } from './capability-binding.js';
  * endpoints, credentials) cross the HTTP boundary. Secrets stay inside
  * the binding implementation; the wire surface returns only routing-
  * relevant metadata: provider-level `id` / `region` / `attributes` /
- * `capabilityKind` + `models[]` (each entry carries `name`,
+ * `capabilityKind` / `labels` + `models[]` (each entry carries `name`,
  * `contextWindow`, `features`, `cost`, optional `p95LatencyMs`,
  * `maxOutputTokens`, `description`).
  *
@@ -38,8 +38,8 @@ export interface ProviderRegistryBinding {
    */
   list(input: ProviderListInput): Promise<ProviderPage>;
   /**
-   * Fetch a provider by id, or `null` when unknown. The route surfaces
-   * `null` as `404 provider-not-found`.
+   * Fetch a provider by id, or `null` when unknown or unregistered. The
+   * route surfaces `null` as `404 provider-not-found`.
    */
   get(input: ProviderGetInput): Promise<ProviderMetadata | null>;
   /**
@@ -47,13 +47,18 @@ export interface ProviderRegistryBinding {
    * the wire shape via the `@kindgi/capabilities` runtime rules
    * before calling — the binding receives well-formed metadata.
    * Bindings MAY reject with `already-registered` when the same
-   * `providerId` is re-registered; the route maps that to `409`.
+   * `providerId` is re-registered; the route maps that to `409`. An
+   * unregistered id is free: registering it again makes a new provider.
    */
   register(input: ProviderRegisterInput): Promise<ProviderRegisterOutcome>;
   /**
-   * Remove a specific provider. Returns `{ unregistered: true }` on
-   * success; `{ unregistered: false }` when the id was unknown — the
-   * route flips the latter to `404`.
+   * Unregister a provider: a tombstone, not an erase. From then on the
+   * provider is gone from `list`, `get`, `capabilitiesFor` and
+   * `resolveForRuntime`, and the router never picks it; a retention
+   * policy on the `provider` domain purges the row. Returns
+   * `{ unregistered: true }` on success; `{ unregistered: false }` when
+   * the id was unknown or already unregistered — the route flips the
+   * latter to `404`.
    */
   unregister(input: ProviderUnregisterInput): Promise<ProviderUnregisterOutcome>;
   /**

package/src/reviewer-binding.ts

@@ -6,16 +6,24 @@ import type { Cursor, ReviewerId, TenantId, Timestamp, UserId } from '@kindgi/ty
 
 /**
  * Translates the bearer-token identity (`UserId`) into the `ReviewerId`
- * that `HitlBinding.submitReview` needs. The API package intentionally does
+ * that `HitlBinding.submitReview` needs, and the reviewer role the
+ * approvals surface is scoped by. The API package intentionally does
  * NOT own the `user ↔ reviewer` mapping — deployments plug that in via
  * this binding, same pattern as `TokenResolver` (for auth read) and
  * `TokenAdmin` (for mint/revoke).
  *
- * Return `null` when the user has no registered reviewer row for the
+ * Both return `null` when the user has no active reviewer row for the
  * tenant (leads to `403 permission-denied` from the approvals route).
  */
 export interface ReviewerBinding {
   resolveReviewer(input: ReviewerLookupInput): Promise<ReviewerId | null>;
+  /**
+   * The user's reviewer role in the tenant. Consulted for a token that
+   * carries no `reviewerRole` of its own (a session or API key of a
+   * registered reviewer), so the roster, not the token, says who reviews.
+   * A binding without it: only a token that carries its role reviews.
+   */
+  resolveReviewerRole?(input: ReviewerLookupInput): Promise<ReviewerRole | null>;
 }
 
 export interface ReviewerLookupInput {

package/src/reviewer-role.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ReviewerRole } from '@kindgi/authz';
+import type { TenantId, UserId } from '@kindgi/types';
+import type { Context } from 'hono';
+
+import type { ReviewerBinding } from './reviewer-binding.js';
+import type { AppEnv } from './types.js';
+
+/**
+ * The caller's reviewer role: the one its token carries, else the one the
+ * roster gives its user (`ReviewerBinding.resolveReviewerRole`, when the
+ * binding has it), kept on the request. `undefined` for a caller that
+ * isn't a reviewer: a token with neither a role nor a user, or a user the
+ * roster doesn't know.
+ */
+export async function callerReviewerRole(
+  c: Context<AppEnv>,
+  reviewerBinding: ReviewerBinding | undefined,
+): Promise<ReviewerRole | undefined> {
+  const carried = c.get('reviewerRole');
+  if (carried !== undefined) return carried;
+  const userId = c.get('userId') as UserId | undefined;
+  if (userId === undefined || reviewerBinding?.resolveReviewerRole === undefined) {
+    return undefined;
+  }
+  const role = await reviewerBinding.resolveReviewerRole({
+    tenantId: c.get('tenantId') as TenantId,
+    userId,
+  });
+  if (role === null) return undefined;
+  c.set('reviewerRole', role);
+  return role;
+}

package/src/routes/agents.ts

@@ -1,15 +1,30 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import { Hono } from 'hono';
+import { type Context, Hono } from 'hono';
 
-import { type Agent, type AgentId, type DefineAgentSpec, defineAgent } from '@kindgi/agents';
+import {
+  type Agent,
+  type AgentId,
+  type DefineAgentSpec,
+  defineAgent,
+  pinsDigest,
+} from '@kindgi/agents';
 import { type Principal, ref, tuplesForCreate } from '@kindgi/authz';
 import type { Cursor, ProjectId, Semver, TenantId, UserId } from '@kindgi/types';
 
-import type { AgentRegistryBinding } from '../agent-binding.js';
+import type { AgentRegistryBinding, AgentVersionRecord } from '../agent-binding.js';
+import { resolveAgentPins } from '../agent-pins.js';
+import type { BlockRegistryBinding } from '../block-binding.js';
+import {
+  type DeriveAgentVersionOutcome,
+  type PinSwaps,
+  deriveAgentVersion,
+  nextFreeAgentVersion,
+} from '../derive-agent-version.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
+import type { ToolRegistryBinding } from '../tool-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
@@ -24,8 +39,19 @@ import { parseScopeParams } from './scope-params.js';
  *
  * Publish is data-as-code: the body is a full `DefineAgentSpec` (the
  * same value `defineAgent(...)` accepts).
+ *
+ * With `toolRegistry`, a published version is pinned: each tool range
+ * resolves once, at publish, to the exact version every run of that
+ * version uses (`pins`, see `resolveAgentPins`), and a range that
+ * matches no published version refuses the publish. Without it,
+ * versions carry no pins and resolve their ranges per run.
  */
-export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authorizer): Hono<AppEnv> {
+export function agentsRouter(
+  binding: AgentRegistryBinding,
+  authorizer?: Authorizer,
+  toolRegistry?: ToolRegistryBinding,
+  blockRegistry?: BlockRegistryBinding,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
   // Authorization — check the resource directly (ref('agent', businessId));
@@ -35,6 +61,7 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
   //
   //   POST /                                         → admin on body.projectId
   //   GET /:agentId, GET /:agentId/versions[/…]      → read on the agent
+  //   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
   //   GET / (list)                                   → tenant-scoped fetch;
@@ -73,7 +100,10 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
       return mw(c, next);
     });
     r.use('/:agentId/*', async (c, next) => {
-      const action = c.req.method === 'GET' ? 'read' : 'admin';
+      // Deriving a version (POST …/versions) is `publish` on the agent;
+      // unregister and reinstate are `admin`.
+      const action =
+        c.req.method === 'GET' ? 'read' : 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);
@@ -281,6 +311,28 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
       );
     }
 
+    // Pin the version: every tool range resolves now, once, to the
+    // version its runs use. A range nothing satisfies refuses the
+    // publish rather than store a partly pinned version.
+    let agent: Agent = defined.value;
+    if (toolRegistry !== undefined) {
+      const resolved = await resolveAgentPins(toolRegistry, tenantId, defined.value, blockRegistry);
+      if (resolved.kind === 'unpinnable') {
+        c.status(statusFor('invalid-agent') as never);
+        return c.json(
+          toWireError(
+            {
+              code: 'validation-failed',
+              message: `Agent "${defined.value.id as unknown as string}" uses tool versions that aren't published (${resolved.issues.length} issue${resolved.issues.length === 1 ? '' : 's'})`,
+              issues: resolved.issues as unknown as Record<string, unknown>[],
+            },
+            requestId,
+          ),
+        );
+      }
+      agent = { ...agent, pins: resolved.pins, pinsDigest: pinsDigest(resolved.pins) };
+    }
+
     const principal = c.get('principal') as Principal | undefined;
     const creatorUserId =
       principal?.actor.kind === 'user'
@@ -289,7 +341,7 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
     const outcome = await binding.publish({
       tenantId,
       projectId,
-      agent: defined.value,
+      agent,
       // Write the authorization tuples in the same transaction as the
       // registry row. The binding calls this with the business
       // `agentId`.
@@ -300,18 +352,7 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
         ),
     });
     if (outcome.kind === 'already-registered') {
-      c.status(statusFor('agent-already-registered') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'agent-already-registered',
-            message: `Agent "${outcome.agentId as unknown as string}" version "${outcome.version as unknown as string}" is already registered`,
-            agentId: outcome.agentId as unknown as string,
-            version: outcome.version as unknown as string,
-          },
-          requestId,
-        ),
-      );
+      return alreadyRegistered(c, binding, tenantId, outcome.agentId, outcome.version);
     }
     if (outcome.kind === 'project-not-found') {
       // Caller supplied a `projectId` that does not resolve within
@@ -337,6 +378,47 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
     });
   });
 
+  // ---------- POST /:agentId/versions (derive a version) ----------
+  r.post('/:agentId/versions', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const agentId = c.req.param('agentId') as AgentId;
+    const body = await jsonObject(c);
+    if (body === undefined) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          { code: 'bad-input', message: 'Request body must be a JSON object' },
+          requestId,
+        ),
+      );
+    }
+    const parsed = deriveBody(body);
+    if (typeof parsed === 'string') {
+      c.status(statusFor('bad-input') as never);
+      return c.json(toWireError({ code: 'bad-input', message: parsed }, requestId));
+    }
+    const principal = c.get('principal') as Principal | undefined;
+    const userId = principal?.actor.kind === 'user' ? (principal.actor.id as UserId) : undefined;
+    const outcome = await deriveAgentVersion({
+      agents: binding,
+      blocks: blockRegistry,
+      tenantId,
+      agentId,
+      from: parsed.from,
+      swaps: parsed.pins,
+      ...(parsed.label !== undefined && { label: parsed.label }),
+      ...(userId !== undefined && { by: `user:${userId as unknown as string}` }),
+      ...(parsed.projectId !== undefined && { projectId: parsed.projectId }),
+      tuplesFor: (projectId) => (id) =>
+        tuplesForCreate(
+          { kind: 'agent', id: id as AgentId, tenantId, projectId },
+          userId ?? ('00000000-0000-0000-0000-000000000000' as UserId),
+        ),
+    });
+    return derived(c, agentId, parsed.from, outcome);
+  });
+
   // ---------- POST /:agentId/versions/:version/unregister ----------
   r.post('/:agentId/versions/:version/unregister', async (c) => {
     const requestId = c.get('requestId');
@@ -403,7 +485,143 @@ export function agentsRouter(binding: AgentRegistryBinding, authorizer?: Authori
   return r;
 }
 
-function serializeAgent(a: Agent): Record<string, unknown> {
+/**
+ * The 409 for a publish whose number is taken. Versions never change, so
+ * it names the next free one (an expert's derived version may hold it).
+ */
+async function alreadyRegistered(
+  c: Context<AppEnv>,
+  binding: AgentRegistryBinding,
+  tenantId: TenantId,
+  agentId: AgentId,
+  version: Semver,
+) {
+  const next = await nextFreeAgentVersion(binding, tenantId, agentId, version as unknown as string);
+  const suggestion = next === undefined ? '' : `; publish it as ${next}, the next free version`;
+  c.status(statusFor('agent-already-registered') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'agent-already-registered',
+        message: `Agent "${agentId as unknown as string}" version "${version as unknown as string}" is already registered, and versions never change${suggestion}`,
+        agentId: agentId as unknown as string,
+        version: version as unknown as string,
+        ...(next !== undefined && { nextFreeVersion: next }),
+      },
+      c.get('requestId'),
+    ),
+  );
+}
+
+/** The request body as an object; undefined when it isn't JSON or isn't an object. */
+async function jsonObject(c: Context<AppEnv>): Promise<Record<string, unknown> | undefined> {
+  try {
+    const body = await c.req.json();
+    return body !== null && typeof body === 'object' && !Array.isArray(body)
+      ? (body as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+interface DeriveBody {
+  readonly from: string;
+  readonly pins: PinSwaps;
+  readonly label?: string;
+  readonly projectId?: ProjectId;
+}
+
+/** `{ from, pins: { prompts?, settings? }, label?, projectId? }`, or what's wrong with it. */
+function deriveBody(b: Record<string, unknown>): DeriveBody | string {
+  if (typeof b.from !== 'string' || b.from.length === 0) {
+    return '`from` (the version to derive from) is required';
+  }
+  const pins = pinSwapsOf(b.pins);
+  if (typeof pins === 'string') return pins;
+  for (const key of ['label', 'projectId'] as const) {
+    if (b[key] !== undefined && typeof b[key] !== 'string') return `\`${key}\` must be a string`;
+  }
+  return {
+    from: b.from,
+    pins,
+    ...(typeof b.label === 'string' && { label: b.label }),
+    ...(typeof b.projectId === 'string' && { projectId: b.projectId as ProjectId }),
+  };
+}
+
+/** `pins`: prompt and settings pins only, each block id → exact version; or what's wrong with it. */
+function pinSwapsOf(pins: unknown): PinSwaps | string {
+  if (pins === null || typeof pins !== 'object' || Array.isArray(pins)) {
+    return '`pins` must be { prompts?, settings? }';
+  }
+  for (const [kind, map] of Object.entries(pins)) {
+    if (kind !== 'prompts' && kind !== 'settings') {
+      return `\`pins.${kind}\` can't be swapped: only prompt and settings pins (tool pins come from code)`;
+    }
+    if (!isStringMap(map)) return `\`pins.${kind}\` must map block ids to exact versions`;
+  }
+  return pins as PinSwaps;
+}
+
+function isStringMap(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.values(value).every((v) => typeof v === 'string')
+  );
+}
+
+/** The response to a derive. */
+function derived(
+  c: Context<AppEnv>,
+  agentId: AgentId,
+  from: string,
+  outcome: DeriveAgentVersionOutcome,
+) {
+  const requestId = c.get('requestId');
+  const fail = (
+    status: string,
+    error: { code: string; message: string } & Record<string, unknown>,
+  ) => {
+    c.status(statusFor(status) as never);
+    return c.json(toWireError(error, requestId));
+  };
+  switch (outcome.kind) {
+    case 'ok':
+      c.status(201);
+      return c.json(serializeAgent(outcome.agent));
+    case 'not-found':
+      return fail('agent-not-found', {
+        code: 'agent-not-found',
+        message: `No agent "${agentId as unknown as string}" at version "${from}"`,
+      });
+    case 'unpinned':
+      return fail('validation-failed', {
+        code: 'validation-failed',
+        message: `Agent "${agentId as unknown as string}" version ${from} has no pins (it was published before pins); publish it again to pin it, then derive`,
+      });
+    case 'invalid':
+      return fail('validation-failed', {
+        code: 'validation-failed',
+        message: `Can't derive from version ${from} (${outcome.issues.length} issue${outcome.issues.length === 1 ? '' : 's'})`,
+        issues: outcome.issues as unknown as Record<string, unknown>[],
+      });
+    case 'no-project':
+      return fail('bad-input', {
+        code: 'bad-input',
+        message: "`projectId` is required: this runtime doesn't record the version's project",
+      });
+    case 'project-not-found':
+      return fail('bad-input', {
+        code: 'bad-input',
+        message: `\`projectId\` "${outcome.projectId as unknown as string}" does not resolve to a project in this tenant`,
+      });
+  }
+}
+
+function serializeAgent(a: AgentVersionRecord): Record<string, unknown> {
   return {
     id: a.id as unknown as string,
     version: a.version as unknown as string,
@@ -411,6 +629,8 @@ function serializeAgent(a: Agent): Record<string, unknown> {
     ...(a.description !== undefined && { description: a.description }),
     instructions: a.instructions,
     ...(a.parameters !== undefined && { parameters: a.parameters }),
+    ...(a.settings !== undefined && { settings: a.settings }),
+    ...(a.modelSettings !== undefined && { modelSettings: a.modelSettings }),
     capabilities: a.capabilities,
     tools: a.tools,
     retrieval: a.retrieval,
@@ -420,5 +640,9 @@ function serializeAgent(a: Agent): Record<string, unknown> {
     ...(a.tags !== undefined && { tags: a.tags }),
     ...(a.preferredProvider !== undefined && { preferredProvider: a.preferredProvider }),
     ...(a.preferredModel !== undefined && { preferredModel: a.preferredModel }),
+    ...(a.pins !== undefined && { pins: a.pins }),
+    ...(a.pinsDigest !== undefined && { pinsDigest: a.pinsDigest }),
+    ...(a.derivedFrom !== undefined && { derivedFrom: a.derivedFrom }),
+    ...(a.unregisteredAt !== undefined && { unregisteredAt: a.unregisteredAt }),
   };
 }