@kindgi/api 0.1.4 → 0.1.5-rc.0

package/src/routes/runs.ts

@@ -13,9 +13,10 @@ import type {
   ScopeSegment,
   Semver,
   TenantId,
+  TriggerId,
 } from '@kindgi/types';
 
-import { ref } from '@kindgi/authz';
+import { type Principal, denyPayload, ref } from '@kindgi/authz';
 
 import { type WireErrorBody, statusFor, toWireError } from '../errors.js';
 import type { EventBusBinding, EventPayload, Subscription } from '../event-bus-binding.js';
@@ -27,10 +28,12 @@ import type {
 } from '../handler-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { MintPublicRunTokenResult } from '../public-run-token.js';
+import { type RunFailure, runFailure } from '../run-failure.js';
 import type { AppEnv } from '../types.js';
+import { deniedBy } from './denied.js';
 import { liveScopeToWire } from './live-scope-wire.js';
 import type { DecodedCursor } from './pagination.js';
-import { clampLimit, decodeCursor } from './pagination.js';
+import { clampLimit, decodeCursor, isCursorTime } from './pagination.js';
 import { parseListScope } from './scope-params.js';
 import { parseSegmentsBody } from './segments.js';
 import {
@@ -60,6 +63,16 @@ export interface RunsRouterOptions {
   readonly publicRunTokens?: {
     readonly mint: (tenantId: TenantId, runIds: readonly RunId[]) => MintPublicRunTokenResult;
   };
+  /**
+   * Whether the tenant has the agent or flow a run names. With an
+   * authorizer, starting a run needs `execute` on an existing target; one
+   * that doesn't exist is left to the run handler's 404. Absent: the
+   * check always runs.
+   */
+  readonly targetExists?: (
+    tenantId: TenantId,
+    target: { readonly kind: 'agent' | 'flow'; readonly id: string },
+  ) => Promise<boolean>;
 }
 
 /** How far up the parent chain a public token's grant reaches. */
@@ -88,58 +101,55 @@ export function runsRouter(
   // Each check resolves the run's project (by run id) and asks the
   // authorizer about that project:
   //
-  // POST /              — no route-level check; `execute` on the agent
-  //                       or flow is up to the run handler binding.
+  // POST /              — execute on the agent or flow it names (an
+  //                       existing one; a missing one is the handler's 404)
   // GET /:runId         — read on the run's project
   // POST /:runId/cancel — write on the run's project
-  // POST /:runId/resume — execute on the run's project
+  // POST /:runId/resume — write on the run's project
   // GET /:runId/journal — read on the run's project
   // GET /:runId/stream  — read on the run's project
-  // GET /               — list; tenant-scoped, the scope filter narrows
-  //                       further (rows are not filtered per permission)
+  // GET /               — list; rows filtered to `read` on their project
   if (authorizer !== undefined) {
+    // A run that isn't there is the handler's 404: `read` on the tenant
+    // (which every reader has) lets it through without masking it. An id
+    // that isn't a run id is never looked up (its uuid cast would fail
+    // the query as a 500): the route's own 400 answers it.
     const projectFromRun = async (c: import('hono').Context<AppEnv>) => {
       const tenantId = c.get('tenantId') as TenantId;
       const runId = c.req.param('runId') ?? '';
-      if (runId.length === 0) return ref('tenant', tenantId as unknown as string);
-      const row = await runBinding.getRun(tenantId, runId as RunId);
-      if (row === null) {
-        // Fall back to tenant so the underlying handler surfaces
-        // 404 rather than the middleware masking it as 403.
-        return ref('tenant', tenantId as unknown as string);
-      }
-      return ref('project', row.projectId as unknown as string);
+      const row = UUID_RE.test(runId) ? await runBinding.getRun(tenantId, runId as RunId) : null;
+      return row === null
+        ? ref('tenant', tenantId as unknown as string)
+        : ref('project', row.projectId as unknown as string);
     };
+    const onRunProject =
+      (action: 'read' | 'write') =>
+      async (c: import('hono').Context<AppEnv>, next: import('hono').Next) => {
+        const resource = await projectFromRun(c);
+        const mw = authorizer.authorize(
+          resource.type === 'tenant' ? 'read' : action,
+          () => resource,
+        );
+        return mw(c, next);
+      };
     r.use('/:runId', async (c, next) => {
       if (c.req.method !== 'GET') return next();
-      const mw = authorizer.authorize('read', projectFromRun);
-      return mw(c, next);
-    });
-    r.use('/:runId/journal', async (c, next) => {
-      const mw = authorizer.authorize('read', projectFromRun);
-      return mw(c, next);
-    });
-    r.use('/:runId/stream', async (c, next) => {
-      const mw = authorizer.authorize('read', projectFromRun);
-      return mw(c, next);
+      return onRunProject('read')(c, next);
     });
+    r.use('/:runId/journal', onRunProject('read'));
+    r.use('/:runId/stream', onRunProject('read'));
     // Progress: `read` for API tokens. A public run token has no
     // principal; the handlers check that its grant covers the run.
     const progressAuth = async (c: import('hono').Context<AppEnv>, next: import('hono').Next) => {
       if (c.get('tokenKind') === 'public-run') return next();
-      const mw = authorizer.authorize('read', projectFromRun);
-      return mw(c, next);
+      return onRunProject('read')(c, next);
     };
     r.use('/:runId/progress', progressAuth);
     r.use('/:runId/progress/stream', progressAuth);
-    r.use('/:runId/cancel', async (c, next) => {
-      const mw = authorizer.authorize('write', projectFromRun);
-      return mw(c, next);
-    });
-    r.use('/:runId/resume', async (c, next) => {
-      const mw = authorizer.authorize('execute', projectFromRun);
-      return mw(c, next);
-    });
+    r.use('/:runId/cancel', onRunProject('write'));
+    // As cancel: changing a run is `write` on its project (a project has
+    // no `execute`; asking for it refused everyone, T243 A).
+    r.use('/:runId/resume', onRunProject('write'));
   }
 
   // ---------- POST / (start a run — agent | flow) ----------
@@ -162,11 +172,46 @@ export function runsRouter(
       return c.json(toWireError(parsed.error, requestId));
     }
 
+    const target =
+      parsed.value.kind === 'agent'
+        ? { kind: 'agent' as const, id: parsed.value.agentId as unknown as string }
+        : { kind: 'flow' as const, id: parsed.value.flowId as unknown as string };
+    if ((await options.targetExists?.(tenantId, target)) !== false) {
+      const refused = await deniedBy(authorizer, c, 'execute', ref(target.kind, target.id));
+      if (refused !== undefined) return refused;
+    }
+    // A run filed under a project the caller names needs `write` on it:
+    // the run lands there, readable by that project's viewers (T307).
+    // Unnamed, the runtime files it under the conversation's, the agent's
+    // or the flow's own project, so a caller who may only run it needs no
+    // more, and the refusal says so.
+    if (authorizer !== undefined && parsed.value.projectId !== undefined) {
+      const named = ref('project', parsed.value.projectId as unknown as string);
+      const decision = await authorizer.check(c, 'write', named);
+      if (!decision.allowed) {
+        const deny = denyPayload('write', named.type, named.id, decision.reason);
+        c.status(403);
+        return c.json(
+          toWireError(
+            {
+              code: deny.code,
+              message: `Permission denied: naming project ${named.id} needs write on it; omit \`projectId\` to run in the ${target.kind}'s own project`,
+              action: deny.action,
+              resource: deny.resource,
+              reason: deny.reason,
+            },
+            requestId,
+          ),
+        );
+      }
+    }
+
     const trace = c.get('trace');
     const invocation = await invokeFromBody(
       binding,
       tenantId,
       parsed.value,
+      c.get('principal') as Principal | undefined,
       trace !== undefined ? { traceId: trace.traceId, spanId: trace.spanId } : undefined,
     );
 
@@ -245,7 +290,7 @@ export function runsRouter(
     const rawCursor = c.req.query('cursor');
     if (rawCursor !== undefined && rawCursor.length > 0) {
       const decoded = decodeCursor(rawCursor);
-      if (decoded === null) {
+      if (decoded === null || !isCursorTime(decoded.createdAt)) {
         c.status(statusFor('bad-input') as never);
         return c.json(
           toWireError({ code: 'bad-input', message: '`cursor` is malformed' }, requestId),
@@ -277,8 +322,14 @@ export function runsRouter(
         filter: listFilter.value,
       }),
     );
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (row) =>
+            ref('project', row.projectId as unknown as string),
+          );
     return c.json({
-      data: page.data.map((row) => serializeRun(row, { output: includeOutput })),
+      data: visible.map((row) => serializeRun(row, { output: includeOutput })),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -631,10 +682,13 @@ function invokeFromBody(
   binding: RunHandlerBinding,
   tenantId: TenantId,
   body: ParsedStartRunBody,
+  principal: Principal | undefined,
   trace?: RunTrace,
 ): Promise<RunHandlerOutcome> {
   const common = {
     tenantId,
+    // Whom the run acts for: the authenticated caller, never the body.
+    ...(principal !== undefined && { principal }),
     ...(trace !== undefined && { trace }),
     ...(body.projectId !== undefined && { projectId: body.projectId }),
     input: body.input,
@@ -678,6 +732,7 @@ function serializeRun(
     updatedAt: row.updatedAt as unknown as string,
     completedAt: row.completedAt ?? undefined,
     failureMessage: row.failureMessage ?? undefined,
+    ...withFailure(row),
     ...(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 }),
@@ -694,7 +749,20 @@ function serializeRun(
     }),
     ...(row.replayOf != null && { replayOf: row.replayOf as unknown as string }),
     ...(row.evalRunId != null && { evalRunId: row.evalRunId }),
+    ...(row.trigger !== undefined && {
+      trigger: {
+        triggerId: row.trigger.triggerId as unknown as string,
+        kind: row.trigger.kind,
+        fireId: row.trigger.fireId,
+        ...(row.trigger.scheduledFor !== undefined && {
+          scheduledFor: row.trigger.scheduledFor as unknown as string,
+        }),
+      },
+    }),
     ...(row.versions != null && { versions: row.versions }),
+    ...(row.contentErasedAt !== undefined && {
+      contentErasedAt: row.contentErasedAt as unknown as string,
+    }),
     ...(row.segments !== undefined &&
       row.segments.length > 0 && {
         segments: row.segments.map(({ key, value }) => ({ key, value })),
@@ -703,6 +771,12 @@ function serializeRun(
   };
 }
 
+/** `failure` on a failed run's wire row: its error, decoded once, here. */
+function withFailure(row: KernelRunRecord): { readonly failure?: RunFailure } {
+  const failure = runFailure(row);
+  return failure !== undefined ? { failure } : {};
+}
+
 /** A run's progress: status and timing, no data. */
 function serializeRunProgress(row: KernelRunRecord): Record<string, unknown> {
   return {
@@ -762,6 +836,7 @@ function listRunsInput(input: {
     ...(filter.agentId !== undefined && { agentId: filter.agentId }),
     replays: filter.replays,
     ...(filter.evalRunId !== undefined && { evalRunId: filter.evalRunId }),
+    ...(filter.triggerId !== undefined && { triggerId: filter.triggerId }),
   };
 }
 
@@ -771,6 +846,7 @@ interface RunListFilter {
   readonly agentId?: string;
   readonly replays: 'exclude' | 'include' | 'only';
   readonly evalRunId?: string;
+  readonly triggerId?: TriggerId;
   readonly includeOutput: boolean;
 }
 
@@ -778,12 +854,15 @@ interface RunListFilter {
  * `?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`.
+ * `?triggerId=` (the runs a trigger started), `?include=output`.
  */
 function parseRunListFilter(
   query: Readonly<Record<string, string>>,
 ): { kind: 'ok'; value: RunListFilter } | { kind: 'err'; message: string } {
-  const { parentRunId, topLevel, agentId, replays, evalRunId, include } = query;
+  const { parentRunId, topLevel, agentId, replays, evalRunId, triggerId, include } = query;
+  if (triggerId !== undefined && !UUID_RE.test(triggerId)) {
+    return { kind: 'err', message: '`triggerId` must be a trigger id (a UUID)' };
+  }
   if (agentId !== undefined && agentId.trim() === '') {
     return { kind: 'err', message: '`agentId` must not be empty' };
   }
@@ -824,6 +903,7 @@ function parseRunListFilter(
       ...(agentId !== undefined && { agentId }),
       replays: replays ?? (evalRunId !== undefined ? 'include' : 'exclude'),
       ...(evalRunId !== undefined && { evalRunId }),
+      ...(triggerId !== undefined && { triggerId: triggerId as TriggerId }),
       includeOutput: includes.includes('output'),
     },
   };