@kindgi/api 0.1.3 → 0.1.4-rc.1

package/src/routes/orgs.ts

@@ -11,6 +11,7 @@ import type { Cursor, OrgId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
+import { orgDeleteSlugConflictError, slugConflictError } from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -19,10 +20,13 @@ import { clampLimit } from './pagination.js';
  * Five endpoints on `/v1/orgs`:
  *   - `GET    /`                — cursor-paginated list; optional
  *                                 `?limit=` / `?cursor=` / `?nameContains=`.
- *   - `POST   /`                — create; body `{ name, slug }`; 201 `{ id }`.
+ *   - `POST   /`                — create; body `{ name, slug }`; 201 `{ id }`;
+ *                                 409 `slug-conflict` when the tenant has
+ *                                 an org with that slug.
  *   - `GET    /:orgId`          — 200 `Org`; 404 `org-not-found`.
  *   - `PATCH  /:orgId`          — partial update via `OrgPatch`; 204 on
- *                                 success; 404 `org-not-found`.
+ *                                 success; 404 `org-not-found`; 409
+ *                                 `slug-conflict`.
  *   - `DELETE /:orgId`          — 204 idempotent (unknown is 204 per the
  *                                 binding's delete-is-a-no-op contract).
  *
@@ -142,17 +146,24 @@ export function orgsRouter(
           : ('00000000-0000-0000-0000-000000000000' as UserId);
       const result = await tenantHierarchy.createOrg({ tenantId, creatorUserId, spec });
       if (result.kind === 'err') {
-        const code =
-          result.error.code === 'slug-conflict' ? 'slug-conflict' : 'internal-server-error';
-        c.status(statusFor(code) as never);
-        return c.json(toWireError({ code, message: result.error.message }, requestId));
+        const error =
+          result.error.code === 'slug-conflict'
+            ? slugConflictError('org', spec.slug)
+            : { code: 'internal-server-error', message: result.error.message };
+        c.status(statusFor(error.code) as never);
+        return c.json(toWireError(error, requestId));
       }
       c.status(201);
       return c.json({ id: result.value.orgId as unknown as string });
     }
-    const id = await binding.create(tenantId, spec);
+    const outcome = await binding.create(tenantId, spec);
+    if (outcome.kind === 'slug-conflict') {
+      const error = slugConflictError('org', outcome.slug);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
+    }
     c.status(201);
-    return c.json({ id: id as unknown as string });
+    return c.json({ id: outcome.orgId as unknown as string });
   });
 
   // ---------- GET /:orgId ----------
@@ -226,24 +237,24 @@ export function orgsRouter(
       shaped.slug = b.slug;
     }
 
-    try {
-      await binding.update(tenantId, orgId, shaped);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('org-not-found')) {
-        c.status(statusFor('org-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'org-not-found',
-              message: `No org with id "${orgId as unknown as string}"`,
-              orgId: orgId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await binding.update(tenantId, orgId, shaped);
+    if (outcome.kind === 'org-not-found') {
+      c.status(statusFor('org-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'org-not-found',
+            message: `No org with id "${orgId as unknown as string}"`,
+            orgId: orgId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'slug-conflict') {
+      const error = slugConflictError('org', outcome.slug);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
     }
     c.status(204);
     return c.body(null);
@@ -251,9 +262,15 @@ export function orgsRouter(
 
   // ---------- DELETE /:orgId ----------
   r.delete('/:orgId', async (c) => {
+    const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const orgId = c.req.param('orgId') as OrgId;
-    await binding.delete(tenantId, orgId);
+    const outcome = await binding.delete(tenantId, orgId);
+    if (outcome?.kind === 'slug-conflict') {
+      const error = orgDeleteSlugConflictError(outcome.slugs);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
+    }
     c.status(204);
     return c.body(null);
   });

package/src/routes/policies.ts

@@ -6,10 +6,12 @@ import { Hono } from 'hono';
 import type { Cursor, TenantId } from '@kindgi/types';
 
 import {
+  APPLIED_POLICY_KINDS,
   POLICY_KINDS,
   type Policy,
   type PolicyKind,
   type PolicyRegistryBinding,
+  isAppliedPolicyKind,
   validatePolicySpec,
 } from '@kindgi/policy-contract';
 import { statusFor, toWireError } from '../errors.js';
@@ -221,6 +223,23 @@ export function policiesRouter(binding: PolicyRegistryBinding): Hono<AppEnv> {
       );
     }
 
+    // A known kind no runtime consumer applies yet: publishing it would
+    // change nothing, silently.
+    if (!isAppliedPolicyKind(validation.value.kind)) {
+      c.status(statusFor('kind-not-applied') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'kind-not-applied',
+            message: `This runtime doesn't apply "${validation.value.kind}" policies yet, so publishing one would change nothing. Policy kinds it applies: ${APPLIED_POLICY_KINDS.join(', ')}.`,
+            kind: validation.value.kind,
+            appliedKinds: [...APPLIED_POLICY_KINDS],
+          },
+          requestId,
+        ),
+      );
+    }
+
     const outcome = await binding.publish({ tenantId, policy: validation.value });
     if (outcome.kind === 'already-registered') {
       c.status(statusFor('policy-already-registered') as never);

package/src/routes/projects.ts

@@ -19,6 +19,11 @@ import type { Cursor, OrgId, ProjectId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
+import {
+  orgNotFoundError,
+  projectDefaultAlreadyExistsError,
+  slugConflictError,
+} from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -30,12 +35,20 @@ import { clampLimit } from './pagination.js';
  *                                          `?nameContains=`.
  *   - `POST   /`                         — create; body `{ name, slug,
  *                                          orgId?, description?, isDefault? }`;
- *                                          201 `{ id }`.
+ *                                          201 `{ id }`; 409 `slug-conflict`
+ *                                          when its org (or, without an org,
+ *                                          the tenant's projects without one)
+ *                                          has a project with that slug, or
+ *                                          `project-default-already-exists`
+ *                                          for a second Default.
  *   - `GET    /default`                  — returns the tenant's Default
  *                                          project or 404 `project-not-found`.
  *                                          MUST be mounted BEFORE `/:projectId`.
  *   - `GET    /:projectId`               — get; 200 or 404 `project-not-found`.
- *   - `PATCH  /:projectId`               — partial update; 204 or 404.
+ *   - `PATCH  /:projectId`               — partial update; 204, 404
+ *                                          `project-not-found` or 409
+ *                                          `slug-conflict` (a new slug, or a
+ *                                          move to an org that has it).
  *   - `DELETE /:projectId`               — 204 idempotent.
  *   - `GET    /:projectId/memberships`   — list; cursor-paginated.
  *   - `POST   /:projectId/memberships`   — add member; body `{ userId, role }`;
@@ -235,23 +248,35 @@ export function projectsRouter(
           : ('00000000-0000-0000-0000-000000000000' as UserId);
       const result = await tenantHierarchy.createProject({ tenantId, creatorUserId, spec });
       if (result.kind === 'err') {
-        const code =
+        const error =
           result.error.code === 'slug-conflict'
-            ? 'slug-conflict'
-            : result.error.code === 'default-conflict'
-              ? 'project-default-already-exists'
-              : 'internal-server-error';
-        c.status(statusFor(code) as never);
-        return c.json(toWireError({ code, message: result.error.message }, requestId));
+            ? slugConflictError('project', spec.slug)
+            : result.error.code === 'org-not-found'
+              ? orgNotFoundError(result.error.orgId as unknown as string)
+              : result.error.code === 'default-conflict'
+                ? projectDefaultAlreadyExistsError()
+                : { code: 'internal-server-error', message: result.error.message };
+        c.status(statusFor(error.code) as never);
+        return c.json(toWireError(error, requestId));
       }
       c.status(201);
       return c.json({ id: result.value.projectId as unknown as string });
     }
     // No authorizer configured — fall back to the raw binding create;
     // no FGA tuples written.
-    const id = await binding.create(tenantId, spec);
+    const outcome = await binding.create(tenantId, spec);
+    if (outcome.kind !== 'ok') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('project', outcome.slug)
+          : outcome.kind === 'org-not-found'
+            ? orgNotFoundError(outcome.orgId as unknown as string)
+            : projectDefaultAlreadyExistsError();
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
+    }
     c.status(201);
-    return c.json({ id: id as unknown as string });
+    return c.json({ id: outcome.projectId as unknown as string });
   });
 
   // ---------- GET /:projectId/memberships ----------
@@ -346,42 +371,41 @@ export function projectsRouter(
         ),
       );
     }
-    try {
-      // With an authorizer, add through the tenant-hierarchy binding — it
-      // writes the FGA `<role>@project` tuple atomically so the granted
-      // user's permissions land in FGA.
-      if (authorizer !== undefined) {
-        const res = await tenantHierarchy.addProjectMember({
-          tenantId,
-          projectId,
-          userId: b.userId as unknown as UserId,
-          role: b.role as ProjectRole,
-        });
-        if (res.kind === 'err') throw new Error(res.error.message);
-      } else {
-        await membershipBinding.add(tenantId, {
-          projectId,
-          userId: b.userId as unknown as UserId,
-          role: b.role,
-        });
-      }
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('project-not-found')) {
-        // Racy — project was deleted between preliminary get and add.
-        c.status(statusFor('project-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-not-found',
-              message: `No project with id "${projectId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-            },
-            requestId,
-          ),
-        );
+    // Racy — the project can be deleted between the preliminary get and the add.
+    const projectGone = () => {
+      c.status(statusFor('project-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-not-found',
+            message: `No project with id "${projectId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    };
+    // With an authorizer, add through the tenant-hierarchy binding — it
+    // writes the FGA `<role>@project` tuple atomically so the granted
+    // user's permissions land in FGA.
+    if (authorizer !== undefined) {
+      const res = await tenantHierarchy.addProjectMember({
+        tenantId,
+        projectId,
+        userId: b.userId as unknown as UserId,
+        role: b.role as ProjectRole,
+      });
+      if (res.kind === 'err') {
+        if (res.error.code === 'project-not-found') return projectGone();
+        throw new Error(res.error.message, { cause: res.error });
       }
-      throw cause;
+    } else {
+      const outcome = await membershipBinding.add(tenantId, {
+        projectId,
+        userId: b.userId as unknown as UserId,
+        role: b.role,
+      });
+      if (outcome.kind === 'project-not-found') return projectGone();
     }
     c.status(201);
     return c.json({
@@ -436,38 +460,33 @@ export function projectsRouter(
         ),
       );
     }
-    try {
-      await membershipBinding.updateRole(tenantId, projectId, userId, b.role);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('project-membership-not-found')) {
-        c.status(statusFor('project-membership-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-membership-not-found',
-              message: `No membership for project "${projectId as unknown as string}" + user "${userId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-              userId: userId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      if (message.startsWith('project-not-found')) {
-        c.status(statusFor('project-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-not-found',
-              message: `No project with id "${projectId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await membershipBinding.updateRole(tenantId, projectId, userId, b.role);
+    if (outcome.kind === 'project-membership-not-found') {
+      c.status(statusFor('project-membership-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-membership-not-found',
+            message: `No membership for project "${projectId as unknown as string}" + user "${userId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+            userId: userId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'project-not-found') {
+      c.status(statusFor('project-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-not-found',
+            message: `No project with id "${projectId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
     }
     c.status(204);
     return c.body(null);
@@ -571,24 +590,27 @@ export function projectsRouter(
         );
       }
     }
-    try {
-      await binding.update(tenantId, projectId, shaped);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('project-not-found')) {
-        c.status(statusFor('project-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'project-not-found',
-              message: `No project with id "${projectId as unknown as string}"`,
-              projectId: projectId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await binding.update(tenantId, projectId, shaped);
+    if (outcome.kind === 'project-not-found') {
+      c.status(statusFor('project-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'project-not-found',
+            message: `No project with id "${projectId as unknown as string}"`,
+            projectId: projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'slug-conflict' || outcome.kind === 'org-not-found') {
+      const error =
+        outcome.kind === 'slug-conflict'
+          ? slugConflictError('project', outcome.slug)
+          : orgNotFoundError(outcome.orgId as unknown as string);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
     }
     c.status(204);
     return c.body(null);

package/src/routes/providers.ts

@@ -9,6 +9,7 @@ import {
   type Feature,
   type ModelInfo,
   type ProviderMetadata,
+  validateProviderLabels,
 } from '@kindgi/capabilities';
 import type { Cursor, TenantId } from '@kindgi/types';
 
@@ -316,6 +317,7 @@ function serializeProvider(m: ProviderMetadata): Record<string, unknown> {
     ...(m.description !== undefined && { description: m.description }),
     ...(m.capabilityKind !== undefined && { capabilityKind: m.capabilityKind }),
     ...(m.fallback !== undefined && { fallback: m.fallback }),
+    ...(m.labels !== undefined && { labels: m.labels }),
   };
 }
 
@@ -432,6 +434,8 @@ function validateProviderMetadata(
       },
     };
   }
+  const badLabels = validateProviderLabels(b.id, b.labels);
+  if (badLabels !== undefined) return { kind: 'err', error: badLabels };
   const value: ProviderMetadata = {
     id: b.id,
     region: b.region,
@@ -440,6 +444,7 @@ function validateProviderMetadata(
     ...(b.description !== undefined && { description: b.description }),
     ...(b.capabilityKind !== undefined && { capabilityKind: b.capabilityKind as string }),
     ...(b.fallback !== undefined && { fallback: b.fallback as boolean }),
+    ...(b.labels !== undefined && { labels: b.labels as Readonly<Record<string, string>> }),
   };
   return { kind: 'ok', value };
 }

package/src/routes/runs.ts

@@ -654,7 +654,8 @@ function invokeFromBody(
  * Wire row for a run. `output` is the run's output once it completed;
  * single-run responses carry it, lists only with `?include=output`
  * (outputs can be large). Child runs carry their parent's run + node;
- * an agent's turns, the agent, its version and the conversation.
+ * an agent's turns, the agent, its version and the conversation; a
+ * replay run, the run it replays and its eval run.
  */
 function serializeRun(
   row: KernelRunRecord,
@@ -682,6 +683,9 @@ function serializeRun(
         conversationId: row.agent.conversationId as unknown as string,
       },
     }),
+    ...(row.replayOf != null && { replayOf: row.replayOf as unknown as string }),
+    ...(row.evalRunId != null && { evalRunId: row.evalRunId }),
+    ...(row.versions != null && { versions: row.versions }),
   };
 }
 
@@ -742,6 +746,8 @@ function listRunsInput(input: {
     ...(filter.parentRunId !== undefined && { parent: { runId: filter.parentRunId } }),
     ...(filter.topLevelOnly && { topLevelOnly: true }),
     ...(filter.agentId !== undefined && { agentId: filter.agentId }),
+    replays: filter.replays,
+    ...(filter.evalRunId !== undefined && { evalRunId: filter.evalRunId }),
   };
 }
 
@@ -749,17 +755,21 @@ interface RunListFilter {
   readonly parentRunId?: RunId;
   readonly topLevelOnly: boolean;
   readonly agentId?: string;
+  readonly replays: 'exclude' | 'include' | 'only';
+  readonly evalRunId?: string;
   readonly includeOutput: boolean;
 }
 
 /**
  * `?parentRunId=` (children of a run), `?topLevel=true`, `?agentId=` (an
- * agent's turns), `?include=output`.
+ * agent's turns), `?replays=exclude|include|only` (default `exclude`),
+ * `?evalRunId=` (one eval run's replays; implies they are included),
+ * `?include=output`.
  */
 function parseRunListFilter(
   query: Readonly<Record<string, string>>,
 ): { kind: 'ok'; value: RunListFilter } | { kind: 'err'; message: string } {
-  const { parentRunId, topLevel, agentId, include } = query;
+  const { parentRunId, topLevel, agentId, replays, evalRunId, include } = query;
   if (agentId !== undefined && agentId.trim() === '') {
     return { kind: 'err', message: '`agentId` must not be empty' };
   }
@@ -773,6 +783,20 @@ function parseRunListFilter(
   if (parentRunId !== undefined && topLevelOnly) {
     return { kind: 'err', message: '`parentRunId` and `topLevel=true` cannot be combined' };
   }
+  if (
+    replays !== undefined &&
+    replays !== 'exclude' &&
+    replays !== 'include' &&
+    replays !== 'only'
+  ) {
+    return { kind: 'err', message: '`replays` must be `exclude`, `include` or `only`' };
+  }
+  if (evalRunId !== undefined && evalRunId.trim() === '') {
+    return { kind: 'err', message: '`evalRunId` must not be empty' };
+  }
+  if (evalRunId !== undefined && replays === 'exclude') {
+    return { kind: 'err', message: '`evalRunId` and `replays=exclude` cannot be combined' };
+  }
   const includes = include === undefined ? [] : include.split(',').map((i) => i.trim());
   const unknown = includes.filter((i) => i !== 'output');
   if (unknown.length > 0) {
@@ -784,6 +808,8 @@ function parseRunListFilter(
       ...(parentRunId !== undefined && { parentRunId: parentRunId as RunId }),
       topLevelOnly,
       ...(agentId !== undefined && { agentId }),
+      replays: replays ?? (evalRunId !== undefined ? 'include' : 'exclude'),
+      ...(evalRunId !== undefined && { evalRunId }),
       includeOutput: includes.includes('output'),
     },
   };