@kindgi/api 0.1.2 → 0.1.4-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.2",
+  "version": "0.1.4-rc.0",
   "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,30 +32,30 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.2",
-    "@kindgi/audit-events": "0.1.2",
-    "@kindgi/compliance": "0.1.2",
-    "@kindgi/authz": "0.1.2",
-    "@kindgi/blob-binding": "0.1.2",
-    "@kindgi/capabilities": "0.1.2",
-    "@kindgi/crypto": "0.1.2",
-    "@kindgi/flow": "0.1.2",
-    "@kindgi/guardrails": "0.1.2",
-    "@kindgi/memory": "0.1.2",
-    "@kindgi/platform": "0.1.2",
-    "@kindgi/provenance": "0.1.2",
-    "@kindgi/runtime": "0.1.2",
-    "@kindgi/policy-contract": "0.1.2",
-    "@kindgi/schema": "0.1.2",
-    "@kindgi/tools": "0.1.2",
-    "@kindgi/types": "0.1.2",
+    "@kindgi/agents": "0.1.4-rc.0",
+    "@kindgi/audit-events": "0.1.4-rc.0",
+    "@kindgi/compliance": "0.1.4-rc.0",
+    "@kindgi/authz": "0.1.4-rc.0",
+    "@kindgi/blob-binding": "0.1.4-rc.0",
+    "@kindgi/capabilities": "0.1.4-rc.0",
+    "@kindgi/crypto": "0.1.4-rc.0",
+    "@kindgi/flow": "0.1.4-rc.0",
+    "@kindgi/guardrails": "0.1.4-rc.0",
+    "@kindgi/memory": "0.1.4-rc.0",
+    "@kindgi/platform": "0.1.4-rc.0",
+    "@kindgi/provenance": "0.1.4-rc.0",
+    "@kindgi/runtime": "0.1.4-rc.0",
+    "@kindgi/policy-contract": "0.1.4-rc.0",
+    "@kindgi/schema": "0.1.4-rc.0",
+    "@kindgi/tools": "0.1.4-rc.0",
+    "@kindgi/types": "0.1.4-rc.0",
     "@scalar/hono-api-reference": "^0.12.2",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.2",
-    "@kindgi/specs": "0.1.2",
-    "@kindgi/testing": "0.1.2",
+    "@kindgi/audit-events-inmemory": "0.1.4-rc.0",
+    "@kindgi/specs": "0.1.4-rc.0",
+    "@kindgi/testing": "0.1.4-rc.0",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",

package/src/agent-binding.ts

@@ -36,11 +36,13 @@ export interface AgentRegistryBinding {
   get(input: AgentGetInput): Promise<Agent | null>;
   /**
    * Specific `(agentId, version)` lookup, or `null` if unknown.
-   * Returns tombstoned versions too (unlike `list` / `get` which
-   * filter them) — the specific-version lookup is used by provenance
-   * paths that need to resolve historical run references.
+   * Returns unregistered (tombstoned) versions too, unlike `list` /
+   * `get` which filter them, with `unregisteredAt` set. Unregister stops
+   * a version being *chosen*, not the pins that hold it: a resumed run,
+   * provenance, and a flow version that pins it read it, while a new run
+   * that names it is refused.
    */
-  getVersion(input: AgentGetVersionInput): Promise<Agent | null>;
+  getVersion(input: AgentGetVersionInput): Promise<AgentVersionRecord | null>;
   /**
    * Head-row existence check. Returns `true` iff the agent id has been
    * registered in the tenant (regardless of whether any versions are
@@ -88,6 +90,14 @@ export interface AgentRegistryBinding {
   reinstateVersion(input: AgentReinstateVersionInput): Promise<AgentReinstateVersionOutcome>;
 }
 
+/** An agent version as `getVersion` reads it: `unregisteredAt` is set when it's unregistered. */
+export type AgentVersionRecord = Agent & {
+  /** ISO-8601; present only on an unregistered version. */
+  readonly unregisteredAt?: string;
+  /** The project the version belongs to, when the store records it (a derived version is published there). */
+  readonly projectId?: ProjectId;
+};
+
 export interface AgentListInput {
   readonly tenantId: TenantId;
   readonly limit: number;
@@ -149,6 +159,11 @@ export interface AgentPublishInput {
    * silently falls back to Default.
    */
   readonly projectId: ProjectId;
+  /**
+   * The version to store, as given. When the route pinned it, it
+   * carries `pins` and `pinsDigest` (the exact block versions its runs
+   * use); a binding stores and returns them with the rest.
+   */
   readonly agent: Agent;
   /**
    * REQUIRED. Called inside the binding's write transaction after the

package/src/agent-pins.ts

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Agent, type AgentId, type AgentPins, pinsDigest } from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import { pickVersion } from '@kindgi/tools';
+import type { Cursor, ProjectId, TenantId, ToolId } from '@kindgi/types';
+
+import type { AgentRegistryBinding } from './agent-binding.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+import { resolveBlockPins } from './block-pins.js';
+import { type DeployedVersionOutcome, deployVersion } from './deploy-versions.js';
+import type { ToolRegistryBinding } from './tool-binding.js';
+
+/** One block reference that matched no published version. */
+export interface UnpinnableRef {
+  /** JSON pointer into the definition, e.g. `/tools/<i>/version`. */
+  readonly path: string;
+  readonly message: string;
+}
+
+export type AgentPinsOutcome =
+  | { readonly kind: 'ok'; readonly pins: AgentPins }
+  | { readonly kind: 'unpinnable'; readonly issues: readonly UnpinnableRef[] };
+
+/** Page size for reading a tool's versions. */
+const VERSIONS_PAGE = 200;
+
+/**
+ * Resolve an agent's tool ranges to the exact versions a version of it
+ * runs (its `pins`), when the version is published.
+ *
+ * Each range is picked by `pickVersion` over the tool's active versions,
+ * the same versions and the same rule a run resolves against, so the pin
+ * is the version a run would have picked at that moment. A range that
+ * matches nothing (the tool isn't published, or no version is in range)
+ * makes the agent unpinnable: the caller refuses the publish, naming
+ * each such tool, rather than store a partly pinned version.
+ */
+export async function resolveAgentPins(
+  tools: ToolRegistryBinding,
+  tenantId: TenantId,
+  agent: Agent,
+  blocks?: BlockRegistryBinding,
+): Promise<AgentPinsOutcome> {
+  const pinned: Record<string, string> = {};
+  const issues: UnpinnableRef[] = [];
+  const versionsOf = new Map<string, readonly string[]>();
+  for (const [i, ref] of agent.tools.entries()) {
+    let available = versionsOf.get(ref.id);
+    if (available === undefined) {
+      available = await activeToolVersions(tools, tenantId, ref.id as ToolId);
+      versionsOf.set(ref.id, available);
+    }
+    const pick = pickVersion(available, ref.version);
+    if (pick.kind === 'ok') {
+      pinned[ref.id] = pick.version;
+      continue;
+    }
+    issues.push({
+      path: `/tools/${i}/version`,
+      message:
+        available.length === 0
+          ? `tool "${ref.id}" has no published version; publish the tool first`
+          : `tool "${ref.id}" has no published version in "${ref.version}" (published: ${available.join(', ')}); publish one in range first, or change the range`,
+    });
+  }
+  // The data blocks it references, by the same rule (`resolveBlockPins`).
+  const blockPins = await resolveBlockPins(blocks, tenantId, agent);
+  issues.push(...blockPins.issues);
+  if (issues.length > 0) return { kind: 'unpinnable', issues };
+  return {
+    kind: 'ok',
+    pins: { tools: pinned, prompts: blockPins.prompts, settings: blockPins.settings },
+  };
+}
+
+/** Every active version of a tool, newest first; none when it isn't published. */
+export async function activeToolVersions(
+  tools: ToolRegistryBinding,
+  tenantId: TenantId,
+  toolId: ToolId,
+): Promise<readonly string[]> {
+  const versions: string[] = [];
+  let cursor: Cursor | undefined;
+  do {
+    const page = await tools.listVersions({
+      tenantId,
+      toolId,
+      limit: VERSIONS_PAGE,
+      ...(cursor !== undefined && { cursor }),
+    });
+    for (const manifest of page.data) versions.push(manifest.version as unknown as string);
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return versions;
+}
+
+export interface PublishDeployedAgentInput {
+  readonly agents: AgentRegistryBinding;
+  readonly tenantId: TenantId;
+  readonly projectId: ProjectId;
+  /** The agent as the pack defines it, with no pins. */
+  readonly agent: Agent;
+  readonly pins: AgentPins;
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+/** Register a deployed agent with its pins, by the deploy rule (`deployVersion`). */
+export async function publishDeployedAgent(
+  input: PublishDeployedAgentInput,
+): Promise<DeployedVersionOutcome> {
+  const { agents, tenantId, projectId, agent, pins, enqueueTuples } = input;
+  return deployVersion<Agent>({
+    label: `agent "${agent.id as unknown as string}"`,
+    definition: agent,
+    pins,
+    pinsDigest: pinsDigest(pins),
+    existing: await activeAgentVersions(agents, tenantId, agent.id),
+    publish: async (version) => {
+      const outcome = await agents.publish({ tenantId, projectId, agent: version, enqueueTuples });
+      if (outcome.kind === 'ok') return 'ok';
+      return outcome.kind === 'project-not-found' ? 'skipped' : 'taken';
+    },
+  });
+}
+
+/** Every active version of an agent. */
+export async function activeAgentVersions(
+  agents: AgentRegistryBinding,
+  tenantId: TenantId,
+  agentId: AgentId,
+): Promise<readonly Agent[]> {
+  const versions: Agent[] = [];
+  let cursor: Cursor | undefined;
+  do {
+    const page = await agents.listVersions({
+      tenantId,
+      agentId,
+      limit: VERSIONS_PAGE,
+      ...(cursor !== undefined && { cursor }),
+    });
+    versions.push(...page.data);
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return versions;
+}

package/src/app.ts

@@ -26,11 +26,13 @@ import type { MemoryQueryBinding } from '@kindgi/memory';
 import type { PolicyRegistryBinding } from '@kindgi/policy-contract';
 import type { AdapterRegistryBinding } from './adapter-binding.js';
 import type { AgentRegistryBinding } from './agent-binding.js';
+import type { BlockRegistryBinding } from './block-binding.js';
 import type { CapabilityRegistryBinding } from './capability-binding.js';
 import type { CostBinding } from './cost-binding.js';
 import type { DeploymentBinding } from './deployment-binding.js';
 import type { EnvBinding } from './env-binding.js';
 import type { WireErrorBody } from './errors.js';
+import type { EvalCaseStoreBinding } from './eval-case-binding.js';
 import type { EvalRunBinding } from './eval-run-binding.js';
 import type { EvalSuiteRegistryBinding } from './eval-suite-binding.js';
 import type { EventBusBinding } from './event-bus-binding.js';
@@ -45,6 +47,7 @@ import type {
   RefreshTokenFn,
 } from './identity-provider-binding.js';
 import type { ImageRegistryBinding } from './image-registry-binding.js';
+import type { JudgmentRegistryBinding } from './judgment-binding.js';
 import type { MCPClientProbeBinding, MCPEndpointRegistryBinding } from './mcp-endpoint-binding.js';
 import type { MemoryBinding } from './memory-binding.js';
 import { type TokenResolver, bearerAuthMiddleware } from './middleware/auth.js';
@@ -79,6 +82,7 @@ import { approvalsRouter } from './routes/approvals.js';
 import { artifactsRouter } from './routes/artifacts.js';
 import { auditRouter } from './routes/audit.js';
 import { authRouters } from './routes/auth.js';
+import { blocksRouter } from './routes/blocks.js';
 import { capabilitiesRouter } from './routes/capabilities.js';
 import { complianceRouter } from './routes/compliance.js';
 import { conversationsRouter } from './routes/conversations.js';
@@ -91,6 +95,8 @@ import { eventTriggersRouter } from './routes/event-triggers.js';
 import { flowsRouter } from './routes/flows.js';
 import { guardrailsRouter } from './routes/guardrails.js';
 import { identityRouter } from './routes/identity.js';
+import { judgedSuitesRouter } from './routes/judged-suites.js';
+import { judgeClassesRouter, judgmentsRouter } from './routes/judgments.js';
 import { mcpRouter } from './routes/mcp.js';
 import { memoryRouter } from './routes/memory.js';
 import { observationsRouter } from './routes/observations.js';
@@ -571,6 +577,12 @@ export interface CreateAppInput {
    * — new kinds require a spec + validator update in tandem.
    */
   readonly evalSuiteRegistry?: EvalSuiteRegistryBinding;
+  /**
+   * Data blocks (`/v1/blocks`): versioned prompts and settings that agent
+   * versions pin. Mounted when supplied. Authorized through each block's
+   * project; the binding writes no authorization tuples.
+   */
+  readonly blockRegistry?: BlockRegistryBinding;
   /**
    * Optional. When present alongside `evalSuiteRegistry`, mounts the
    * evaluation-run data-plane surface: `POST /v1/eval-suites/:suiteId/runs`
@@ -584,6 +596,19 @@ export interface CreateAppInput {
    * `422 dispatcher-not-registered`.
    */
   readonly evalRunBinding?: EvalRunBinding;
+  /**
+   * Optional. Mounts judgments, yes or no with an optional reason about
+   * one item of a run's output (`/v1/judgments`), and the judge classes
+   * they're recorded under, each with a weight (`/v1/judge-classes`).
+   * Caller-plugged: the API package doesn't own their storage.
+   */
+  readonly judgmentRegistry?: JudgmentRegistryBinding;
+  /**
+   * Optional. With `evalSuiteRegistry` and `judgmentRegistry`, mounts test
+   * sets built from judgments: `POST /v1/eval-suites/:suiteId/versions/from-judgments`
+   * and `GET /v1/eval-suites/:suiteId/versions/:version/cases`.
+   */
+  readonly evalCaseStore?: EvalCaseStoreBinding;
   /**
    * Optional. Push-based pub/sub binding used by SSE endpoints to
    * deliver run events without polling. When present, `GET
@@ -955,7 +980,10 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
       authorizer,
     ),
   );
-  v1.route('/conversations', conversationsRouter(input.conversationBinding, runBinding));
+  v1.route(
+    '/conversations',
+    conversationsRouter(input.conversationBinding, runBinding, input.projectBinding),
+  );
   if (publicRunTokenLimits !== undefined) {
     v1.route(
       '/tokens/public',
@@ -999,10 +1027,22 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
     v1.route('/observations', observationsRouter(input.supervisor));
   }
   if (input.agentRegistry !== undefined) {
-    v1.route('/agents', agentsRouter(input.agentRegistry, authorizer));
+    v1.route(
+      '/agents',
+      agentsRouter(input.agentRegistry, authorizer, input.toolRegistry, input.blockRegistry),
+    );
   }
   if (input.flowRegistry !== undefined) {
-    v1.route('/flows', flowsRouter(input.flowRegistry, authorizer));
+    v1.route(
+      '/flows',
+      flowsRouter(
+        input.flowRegistry,
+        authorizer,
+        input.toolRegistry !== undefined && input.agentRegistry !== undefined
+          ? { tools: input.toolRegistry, agents: input.agentRegistry }
+          : undefined,
+      ),
+    );
   }
   if (input.toolRegistry !== undefined) {
     v1.route('/tools', toolsRouter(input.toolRegistry, authorizer, input.onToolWrite));
@@ -1070,6 +1110,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
     identityRouter({
       ...(input.identityDirectory !== undefined && { directory: input.identityDirectory }),
       ...(input.sessionStore !== undefined && { sessionStore: input.sessionStore }),
+      ...(input.reviewerBinding !== undefined && { reviewerBinding: input.reviewerBinding }),
     }),
   );
   if (input.cost !== undefined) {
@@ -1096,6 +1137,37 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
   if (input.evalSuiteRegistry !== undefined) {
     v1.route('/eval-suites', evalSuitesRouter(input.evalSuiteRegistry, authorizer));
   }
+  if (input.blockRegistry !== undefined) {
+    v1.route('/blocks', blocksRouter(input.blockRegistry, authorizer));
+  }
+  if (input.judgmentRegistry !== undefined) {
+    v1.route(
+      '/judgments',
+      judgmentsRouter(
+        input.judgmentRegistry,
+        runBinding,
+        authorizer,
+        input.conversationBinding,
+        input.flowRegistry,
+      ),
+    );
+    v1.route('/judge-classes', judgeClassesRouter(input.judgmentRegistry, authorizer));
+  }
+  if (
+    input.evalSuiteRegistry !== undefined &&
+    input.judgmentRegistry !== undefined &&
+    input.evalCaseStore !== undefined
+  ) {
+    v1.route(
+      '/eval-suites',
+      judgedSuitesRouter(
+        input.evalSuiteRegistry,
+        input.judgmentRegistry,
+        input.evalCaseStore,
+        authorizer,
+      ),
+    );
+  }
   // ---------- platform hierarchy ----------
   // Mounts are independent: `/v1/orgs`, `/v1/teams`, `/v1/projects`,
   // `/v1/tenant`. Each requires its own binding. Team + Project
@@ -1187,6 +1259,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
         signingKeyRegistry: input.signingKeyRegistry,
         imageRegistry: input.imageRegistry,
         ...(input.toolRegistry !== undefined && { toolRegistry: input.toolRegistry }),
+        ...(input.blockRegistry !== undefined && { blockRegistry: input.blockRegistry }),
         ...(input.guardrailRegistry !== undefined && {
           guardrailRegistry: input.guardrailRegistry,
         }),

package/src/block-binding.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { BlockDefinition, BlockKind } from '@kindgi/agents';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, ProjectId, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the data-block registry: prompts and
+ * settings, versioned like tools (a head plus immutable versions, with
+ * unregister and reinstate). The API package does not own persistence;
+ * a deployment wires a store (a database, or in-memory in tests).
+ *
+ * A block belongs to one project, and is authorized through it: reading
+ * one is `read` on its project, publishing, unregistering or
+ * reinstating is `write` on it. There are no per-block grants, so the
+ * binding writes no authorization tuples.
+ *
+ * Every method is tenant-scoped.
+ */
+export interface BlockRegistryBinding {
+  /** Each block's latest active version, by id, cursor-paginated. */
+  list(input: BlockListInput): Promise<BlockPage>;
+  /** A block's latest active version, or `null` (never published, or every version unregistered). */
+  get(input: BlockGetInput): Promise<BlockRecord | null>;
+  /**
+   * A specific version, or `null` if it was never published. An
+   * unregistered version is returned too, with `unregisteredAt`: the
+   * agent versions that pin it still read it.
+   */
+  getVersion(input: BlockGetVersionInput): Promise<BlockRecord | null>;
+  /** A block's versions, newest published first; unregistered ones only with `includeTombstoned`. */
+  listVersions(input: BlockListVersionsInput): Promise<BlockPage>;
+  /**
+   * Publish a validated block version into a project. A version that's
+   * taken is `already-registered` (versions never change); a block's
+   * versions all live in its first version's project
+   * (`project-mismatch` otherwise).
+   */
+  publish(input: BlockPublishInput): Promise<BlockPublishOutcome>;
+  /** Soft-unregister a version: `{ unregistered: false }` when unknown or already unregistered. */
+  unregister(input: BlockVersionInput): Promise<{ readonly unregistered: boolean }>;
+  /** Reinstate an unregistered version, unchanged; idempotent. */
+  reinstateVersion(input: BlockVersionInput): Promise<BlockReinstateOutcome>;
+}
+
+/** A block version as the registry holds it. */
+export type BlockRecord = BlockDefinition & {
+  /** The project the block belongs to: its authorization comes from there. */
+  readonly projectId: ProjectId;
+  /** ISO-8601. */
+  readonly publishedAt: string;
+  /** ISO-8601; present only on an unregistered version. */
+  readonly unregisteredAt?: string;
+};
+
+export interface BlockListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Exact match on `kind`. */
+  readonly blockKind?: BlockKind;
+  /** Prefix match on the block id. */
+  readonly nameFilter?: string;
+  /**
+   * Narrow to a scope, as the other registries' lists do. Absent: every
+   * block in the tenant. A block always belongs to one project:
+   * - `{ kind: 'project', projectId }`: that project's blocks;
+   * - `{ kind: 'org', orgId }`: the blocks of every project in that org;
+   * - `{ kind: 'tenant' }`: every block in the tenant.
+   */
+  readonly scope?: Scope;
+}
+
+export interface BlockGetInput {
+  readonly tenantId: TenantId;
+  readonly blockId: string;
+}
+
+export interface BlockGetVersionInput {
+  readonly tenantId: TenantId;
+  readonly blockId: string;
+  readonly version: string;
+}
+
+export interface BlockListVersionsInput {
+  readonly tenantId: TenantId;
+  readonly blockId: string;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Include unregistered versions (each with `unregisteredAt`). Default `false`. */
+  readonly includeTombstoned?: boolean;
+}
+
+export interface BlockPublishInput {
+  readonly tenantId: TenantId;
+  /** The project to publish into. REQUIRED; the store never falls back to Default. */
+  readonly projectId: ProjectId;
+  readonly block: BlockDefinition;
+}
+
+export interface BlockVersionInput {
+  readonly tenantId: TenantId;
+  readonly blockId: string;
+  readonly version: string;
+}
+
+export interface BlockPage {
+  readonly data: readonly BlockRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+export type BlockPublishOutcome =
+  | { readonly kind: 'ok'; readonly blockId: string; readonly version: string }
+  | { readonly kind: 'already-registered'; readonly blockId: string; readonly version: string }
+  | {
+      /** The `projectId` isn't a project in this tenant. */
+      readonly kind: 'project-not-found';
+      readonly blockId: string;
+      readonly projectId: ProjectId;
+    }
+  | {
+      /** The block's earlier versions live in another project: a block belongs to one project. */
+      readonly kind: 'project-mismatch';
+      readonly blockId: string;
+      /** The project the block belongs to. */
+      readonly projectId: ProjectId;
+    };
+
+export type BlockReinstateOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly blockId: string;
+      readonly version: string;
+      readonly wasTombstoned: boolean;
+    }
+  | { readonly kind: 'not-found'; readonly blockId: string; readonly version: string };