@kindgi/api 0.1.3 → 0.1.4-rc.1

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/registry-read-only.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context, MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from './errors.js';
+import type { AppEnv } from './types.js';
+
+/**
+ * A registry that takes no writes: it serves its definitions from
+ * somewhere else (under `kindgi dev`, the pack's files). A binding that
+ * sets it has every write refused before the binding is called:
+ * publish, unregister and reinstate (and, for agents, deriving a
+ * version), and a deploy that would publish into it. The refusal is
+ * `409 registry-read-only` with `reason` as its message.
+ */
+export interface RegistryReadOnly {
+  /** Why, and what to do instead, in plain words: the refusal's message. */
+  readonly reason: string;
+}
+
+/** The refusal of a write to a read-only registry. */
+export function refuseReadOnly(c: Context<AppEnv>, readOnly: RegistryReadOnly) {
+  c.status(statusFor('registry-read-only') as never);
+  return c.json(
+    toWireError({ code: 'registry-read-only', message: readOnly.reason }, c.get('requestId')),
+  );
+}
+
+/**
+ * A router's writes (every method but GET and HEAD) are refused while
+ * its registry is read-only. Read at request time, so a binding can
+ * become writable without a restart.
+ */
+export function refuseWritesWhenReadOnly(
+  readOnly: () => RegistryReadOnly | undefined,
+): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const marker = readOnly();
+    if (marker === undefined || c.req.method === 'GET' || c.req.method === 'HEAD') return next();
+    return refuseReadOnly(c, marker);
+  };
+}

package/src/routes/agents.ts

@@ -1,15 +1,31 @@
 // 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 { refuseWritesWhenReadOnly } from '../registry-read-only.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,9 +40,26 @@ 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>();
+  // A read-only registry (under `kindgi dev`, the pack's files) refuses
+  // every write before anything else runs.
+  r.use(
+    '*',
+    refuseWritesWhenReadOnly(() => binding.readOnly),
+  );
 
   // Authorization — check the resource directly (ref('agent', businessId));
   // permissions cascade from the parent project because the
@@ -35,6 +68,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 +107,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 +318,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 or data-block versions it can't pin (${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 +348,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 +359,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 +385,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 +492,145 @@ 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 'reused':
+      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 +638,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 +649,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 }),
   };
 }