@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/routes/runs.ts

@@ -2,10 +2,11 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
 
 import type { AgentId } from '@kindgi/agents';
 import type { KernelRunRecord, ListRunsInput, RunBinding } from '@kindgi/runtime';
-import type { FlowId, OrgId, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
+import type { FlowId, ListScope, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
 
 import { ref } from '@kindgi/authz';
 
@@ -21,7 +22,7 @@ import type { MintPublicRunTokenResult } from '../public-run-token.js';
 import type { AppEnv } from '../types.js';
 import type { DecodedCursor } from './pagination.js';
 import { clampLimit, decodeCursor } from './pagination.js';
-import { type ParseScopeParamsOutcome, parseScopeParams } from './scope-params.js';
+import { parseListScope } from './scope-params.js';
 import {
   formatSseFrame,
   isTerminalWireKind,
@@ -60,6 +61,24 @@ const MAX_RUN_ANCESTRY = 16;
  * `POST /:runId/cancel`, `POST /:runId/resume`, `GET /:runId/stream`
  * (SSE), `GET /:runId/journal`.
  */
+/** A run id: a UUID. */
+const RUN_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * A `:runId` that isn't a run id is a 400, before it reaches a query (where
+ * Postgres's uuid cast would fail it as a 500).
+ */
+const refuseMalformedRunId: MiddlewareHandler<AppEnv> = async (c, next) => {
+  if (RUN_ID_RE.test(c.req.param('runId') ?? '')) return next();
+  c.status(statusFor('bad-input') as never);
+  return c.json(
+    toWireError(
+      { code: 'bad-input', message: '`runId` must be a run id (a UUID)' },
+      c.get('requestId'),
+    ),
+  );
+};
+
 export function runsRouter(
   binding: RunHandlerBinding,
   runBinding: RunBinding,
@@ -179,7 +198,7 @@ export function runsRouter(
   });
 
   // ---------- GET /:runId ----------
-  r.get('/:runId', async (c) => {
+  r.get('/:runId', refuseMalformedRunId, async (c) => {
     const requestId = c.get('requestId');
     const runId = c.req.param('runId') as RunId;
 
@@ -194,7 +213,7 @@ export function runsRouter(
   });
 
   // ---------- GET /:runId/progress ----------
-  r.get('/:runId/progress', async (c) => {
+  r.get('/:runId/progress', refuseMalformedRunId, async (c) => {
     const requestId = c.get('requestId');
     const runId = c.req.param('runId') as RunId;
     const loaded = await readableRun(runBinding, c, runId);
@@ -209,7 +228,8 @@ export function runsRouter(
 
   // ---------- GET / (list, cursor-paginated) ----------
   //
-  // Content-scoped list; scope filter threaded via `parseScopeParams`.
+  // Content-scoped list; scope filter threaded via `parseListScope` (a
+  // `scopeId` that isn't a UUID is a 400 here, not a failed query).
   // Every run belongs to exactly one project; `scope.kind === 'project'`
   // narrows to that project, `scope.kind === 'org'` to the org's
   // projects, and tenant / undefined behave as documented in
@@ -232,7 +252,7 @@ export function runsRouter(
       cursorFilter = decoded;
     }
 
-    const scopeParsed = parseScopeParams(c.req.query(), { tenantId });
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
     if (scopeParsed.kind === 'err') {
       c.status(statusFor('scope-invalid') as never);
       return c.json(
@@ -263,7 +283,7 @@ export function runsRouter(
   });
 
   // ---------- POST /:runId/cancel ----------
-  r.post('/:runId/cancel', async (c) => {
+  r.post('/:runId/cancel', refuseMalformedRunId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const runId = c.req.param('runId') as RunId;
@@ -562,11 +582,11 @@ export function runsRouter(
       },
     });
   };
-  r.get('/:runId/stream', (c) => streamRun(c, 'full'));
-  r.get('/:runId/progress/stream', (c) => streamRun(c, 'progress'));
+  r.get('/:runId/stream', refuseMalformedRunId, (c) => streamRun(c, 'full'));
+  r.get('/:runId/progress/stream', refuseMalformedRunId, (c) => streamRun(c, 'progress'));
 
   // ---------- GET /:runId/journal ----------
-  r.get('/:runId/journal', async (c) => {
+  r.get('/:runId/journal', refuseMalformedRunId, async (c) => {
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const runId = c.req.param('runId') as RunId;
@@ -633,7 +653,9 @@ 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.
+ * (outputs can be large). Child runs carry their parent's run + node;
+ * 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,
@@ -654,6 +676,15 @@ function serializeRun(
     ...(opts.output && row.output !== undefined && { output: row.output }),
     ...(row.parentRunId != null && { parentRunId: row.parentRunId as unknown as string }),
     ...(row.parentNodeId != null && { parentNodeId: row.parentNodeId as unknown as string }),
+    ...(row.agent !== undefined && {
+      agent: {
+        id: row.agent.id,
+        version: row.agent.version,
+        conversationId: row.agent.conversationId as unknown as string,
+      },
+    }),
+    ...(row.replayOf != null && { replayOf: row.replayOf as unknown as string }),
+    ...(row.evalRunId != null && { evalRunId: row.evalRunId }),
   };
 }
 
@@ -698,7 +729,7 @@ async function readableRun(
 /** The binding query for `GET /v1/runs`: scope, page, and the parent filters. */
 function listRunsInput(input: {
   readonly tenantId: TenantId;
-  readonly scope: Extract<ParseScopeParamsOutcome, { kind: 'ok' }>['scope'];
+  readonly scope: ListScope | undefined;
   readonly limit: number;
   readonly cursor: DecodedCursor | null;
   readonly filter: RunListFilter;
@@ -706,42 +737,65 @@ function listRunsInput(input: {
   const { tenantId, scope, limit, cursor, filter } = input;
   return {
     tenantId,
-    ...(scope?.kind === 'project' && {
-      scope: { kind: 'project' as const, projectId: scope.projectId as ProjectId },
-    }),
-    ...(scope?.kind === 'org' && {
-      scope: { kind: 'org' as const, orgId: scope.orgId as unknown as OrgId },
-    }),
+    ...(scope !== undefined && { scope }),
     limit,
     ...(cursor !== null && {
       cursor: { createdAt: cursor.createdAt as never, id: cursor.id as RunId },
     }),
     ...(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 }),
   };
 }
 
 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`, `?include=output`. */
+/**
+ * `?parentRunId=` (children of a run), `?topLevel=true`, `?agentId=` (an
+ * 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, include } = query;
+  const { parentRunId, topLevel, agentId, replays, evalRunId, include } = query;
+  if (agentId !== undefined && agentId.trim() === '') {
+    return { kind: 'err', message: '`agentId` must not be empty' };
+  }
   if (topLevel !== undefined && topLevel !== 'true' && topLevel !== 'false') {
     return { kind: 'err', message: '`topLevel` must be `true` or `false`' };
   }
   const topLevelOnly = topLevel === 'true';
-  if (parentRunId !== undefined && parentRunId.length === 0) {
-    return { kind: 'err', message: '`parentRunId` must be a run id' };
+  if (parentRunId !== undefined && !RUN_ID_RE.test(parentRunId)) {
+    return { kind: 'err', message: '`parentRunId` must be a run id (a UUID)' };
   }
   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) {
@@ -752,6 +806,9 @@ function parseRunListFilter(
     value: {
       ...(parentRunId !== undefined && { parentRunId: parentRunId as RunId }),
       topLevelOnly,
+      ...(agentId !== undefined && { agentId }),
+      replays: replays ?? (evalRunId !== undefined ? 'include' : 'exclude'),
+      ...(evalRunId !== undefined && { evalRunId }),
       includeOutput: includes.includes('output'),
     },
   };

package/src/routes/scope-params.ts

@@ -3,7 +3,7 @@
 
 import { type ResourceRef, ref } from '@kindgi/authz';
 import type { Scope } from '@kindgi/platform';
-import type { OrgId, ProjectId, TenantId } from '@kindgi/types';
+import type { ListScope, OrgId, ProjectId, TenantId } from '@kindgi/types';
 
 /**
  * The authorization resource for a request scope: the project or org it
@@ -131,3 +131,37 @@ export function parseScopeParams(
 
   return { kind: 'ok', scope, ...(inherit !== undefined && { inherit }) };
 }
+
+const SCOPE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * A content list's `?scopeKind` + `?scopeId` as a `ListScope`: a project
+ * or an org narrows the list; no scope, or `tenant`, is the whole tenant.
+ * Project and org ids are UUIDs, so a malformed `scopeId` is an error
+ * here (the route's 400), not a failed query.
+ */
+export function parseListScope(
+  query: QuerySource,
+  session: { readonly tenantId: TenantId },
+):
+  | { readonly kind: 'ok'; readonly scope?: ListScope }
+  | { readonly kind: 'err'; readonly message: string } {
+  const parsed = parseScopeParams(query, session);
+  if (parsed.kind === 'err') return parsed;
+  const scope = parsed.scope;
+  if (scope === undefined || scope.kind === 'tenant') return { kind: 'ok' };
+  const id = (scope.kind === 'project' ? scope.projectId : scope.orgId) as unknown as string;
+  if (!SCOPE_ID_RE.test(id)) {
+    return {
+      kind: 'err',
+      message: `scope query parameters malformed: scopeId must be ${scope.kind === 'project' ? 'a project' : 'an org'} id (a UUID), got "${id}"`,
+    };
+  }
+  return {
+    kind: 'ok',
+    scope:
+      scope.kind === 'project'
+        ? { kind: 'project', projectId: scope.projectId }
+        : { kind: 'org', orgId: scope.orgId },
+  };
+}

package/src/routes/teams.ts

@@ -19,6 +19,7 @@ import type { Cursor, OrgId, TeamId, 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 { slugConflictError } from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -29,9 +30,13 @@ import { clampLimit } from './pagination.js';
  *                                         `?limit=` / `?cursor=` / `?orgId=` /
  *                                         `?nameContains=`.
  *   - `POST   /`                        — create; body `{ name, slug,
- *                                         description?, orgId? }`; 201 `{ id }`.
+ *                                         description?, orgId? }`; 201 `{ id }`;
+ *                                         409 `slug-conflict` when the tenant
+ *                                         has a team with that slug.
  *   - `GET    /:teamId`                 — get; 200 or 404 `team-not-found`.
- *   - `PATCH  /:teamId`                 — partial update; 204 or 404.
+ *   - `PATCH  /:teamId`                 — partial update; 204, 404
+ *                                         `team-not-found` or 409
+ *                                         `slug-conflict`.
  *   - `DELETE /:teamId`                 — 204 idempotent.
  *   - `GET    /:teamId/memberships`     — list; cursor-paginated.
  *   - `POST   /:teamId/memberships`     — add member; body `{ userId, role }`;
@@ -193,17 +198,24 @@ export function teamsRouter(
           : ('00000000-0000-0000-0000-000000000000' as UserId);
       const result = await tenantHierarchy.createTeam({ 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('team', 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.teamId 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('team', 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.teamId as unknown as string });
   });
 
   // ---------- GET /:teamId/memberships ----------
@@ -300,39 +312,38 @@ export function teamsRouter(
         ),
       );
     }
-    try {
-      if (authorizer !== undefined) {
-        const res = await tenantHierarchy.addTeamMember({
-          tenantId,
-          teamId,
-          userId: b.userId as unknown as UserId,
-          role: b.role as TeamRole,
-        });
-        if (res.kind === 'err') throw new Error(res.error.message);
-      } else {
-        await membershipBinding.add(tenantId, {
-          teamId,
-          userId: b.userId as unknown as UserId,
-          role: b.role,
-        });
-      }
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('team-not-found')) {
-        // Racy — team was deleted between the preliminary get and the add.
-        c.status(statusFor('team-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'team-not-found',
-              message: `No team with id "${teamId as unknown as string}"`,
-              teamId: teamId as unknown as string,
-            },
-            requestId,
-          ),
-        );
+    // Racy — the team can be deleted between the preliminary get and the add.
+    const teamGone = () => {
+      c.status(statusFor('team-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'team-not-found',
+            message: `No team with id "${teamId as unknown as string}"`,
+            teamId: teamId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    };
+    if (authorizer !== undefined) {
+      const res = await tenantHierarchy.addTeamMember({
+        tenantId,
+        teamId,
+        userId: b.userId as unknown as UserId,
+        role: b.role as TeamRole,
+      });
+      if (res.kind === 'err') {
+        if (res.error.code === 'team-not-found') return teamGone();
+        throw new Error(res.error.message, { cause: res.error });
       }
-      throw cause;
+    } else {
+      const outcome = await membershipBinding.add(tenantId, {
+        teamId,
+        userId: b.userId as unknown as UserId,
+        role: b.role,
+      });
+      if (outcome.kind === 'team-not-found') return teamGone();
     }
     c.status(201);
     return c.json({
@@ -387,38 +398,33 @@ export function teamsRouter(
         ),
       );
     }
-    try {
-      await membershipBinding.updateRole(tenantId, teamId, userId, b.role);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('team-membership-not-found')) {
-        c.status(statusFor('team-membership-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'team-membership-not-found',
-              message: `No membership for team "${teamId as unknown as string}" + user "${userId as unknown as string}"`,
-              teamId: teamId as unknown as string,
-              userId: userId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      if (message.startsWith('team-not-found')) {
-        c.status(statusFor('team-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'team-not-found',
-              message: `No team with id "${teamId as unknown as string}"`,
-              teamId: teamId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await membershipBinding.updateRole(tenantId, teamId, userId, b.role);
+    if (outcome.kind === 'team-membership-not-found') {
+      c.status(statusFor('team-membership-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'team-membership-not-found',
+            message: `No membership for team "${teamId as unknown as string}" + user "${userId as unknown as string}"`,
+            teamId: teamId as unknown as string,
+            userId: userId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'team-not-found') {
+      c.status(statusFor('team-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'team-not-found',
+            message: `No team with id "${teamId as unknown as string}"`,
+            teamId: teamId as unknown as string,
+          },
+          requestId,
+        ),
+      );
     }
     c.status(204);
     return c.body(null);
@@ -522,24 +528,24 @@ export function teamsRouter(
         );
       }
     }
-    try {
-      await binding.update(tenantId, teamId, shaped);
-    } catch (cause) {
-      const message = cause instanceof Error ? cause.message : String(cause);
-      if (message.startsWith('team-not-found')) {
-        c.status(statusFor('team-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'team-not-found',
-              message: `No team with id "${teamId as unknown as string}"`,
-              teamId: teamId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      throw cause;
+    const outcome = await binding.update(tenantId, teamId, shaped);
+    if (outcome.kind === 'team-not-found') {
+      c.status(statusFor('team-not-found') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'team-not-found',
+            message: `No team with id "${teamId as unknown as string}"`,
+            teamId: teamId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    }
+    if (outcome.kind === 'slug-conflict') {
+      const error = slugConflictError('team', outcome.slug);
+      c.status(statusFor(error.code) as never);
+      return c.json(toWireError(error, requestId));
     }
     c.status(204);
     return c.body(null);

package/src/types.ts

@@ -15,9 +15,10 @@ export interface AppEnv {
     tenantId: TenantId;
     /**
      * Set by `bearerAuthMiddleware` when the token's `TokenResolution`
-     * carried a `reviewerRole`. Approvals routes gate visibility +
-     * decisions on this: `standard < senior < admin`. Absent for
-     * tokens that were never provisioned with a reviewer role.
+     * carried a `reviewerRole`, or by the approvals routes (and `whoami`)
+     * from the reviewer roster for a token whose user is a registered
+     * reviewer (`ReviewerBinding.resolveReviewerRole`). Approvals routes
+     * gate visibility + decisions on this: `standard < senior < admin`.
      */
     reviewerRole?: ReviewerRole;
     /**

package/src/webhook-endpoint-binding.ts

@@ -12,6 +12,7 @@ import type {
   WebhookEndpointId,
   WebhookEventId,
 } from '@kindgi/types';
+import type { CostTokenTotals } from './cost-binding.js';
 
 /**
  * Outbound webhook endpoints: URLs the platform sends signed events to,
@@ -175,6 +176,16 @@ export interface FinishedRun {
   readonly failureMessage: string | null;
   readonly createdAt: Timestamp;
   readonly completedAt: Timestamp;
+  /**
+   * The model calls of the whole run tree (this run and every run it
+   * started), from the cost ledger, summed when the run ended. Absent
+   * when the runtime records no usage.
+   */
+  readonly usage?: {
+    readonly calls: number;
+    readonly costUsd: number;
+    readonly tokens: CostTokenTotals;
+  };
 }
 
 export interface RunFinishedEvent {