@kindgi/api 0.1.2 → 0.1.3

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,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.
+ * (outputs can be large). Child runs carry their parent's run + node;
+ * an agent's turns, the agent, its version and the conversation.
  */
 function serializeRun(
   row: KernelRunRecord,
@@ -654,6 +675,13 @@ 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,
+      },
+    }),
   };
 }
 
@@ -698,7 +726,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,38 +734,41 @@ 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 }),
   };
 }
 
 interface RunListFilter {
   readonly parentRunId?: RunId;
   readonly topLevelOnly: boolean;
+  readonly agentId?: 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), `?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, 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' };
@@ -752,6 +783,7 @@ function parseRunListFilter(
     value: {
       ...(parentRunId !== undefined && { parentRunId: parentRunId as RunId }),
       topLevelOnly,
+      ...(agentId !== undefined && { agentId }),
       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/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 {