@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/routes/approvals.ts

@@ -3,7 +3,8 @@
 
 import { Hono } from 'hono';
 
-import type { ConversationBinding } from '@kindgi/agents';
+import { AGENT_GATE_SUBJECTS, TOOL_CALL_GATE_SUBJECT } from '@kindgi/agents';
+import type { ConversationBinding, GateDecisionValue } from '@kindgi/agents';
 import { REVIEWER_ROLE_RANK, type ReviewerRole } from '@kindgi/authz';
 import { serializePublicKeyPem, signEd25519 } from '@kindgi/crypto';
 import type { SigningKeyBinding } from '@kindgi/crypto';
@@ -23,10 +24,18 @@ import type {
 
 import { statusFor, toWireError } from '../errors.js';
 import type { RunHandlerBinding } from '../handler-binding.js';
-import type { Approval, ApprovalStatus, HitlBinding, ReviewDecisionKind } from '../hitl-binding.js';
+import type {
+  Approval,
+  ApprovalStatus,
+  HitlBinding,
+  ReviewDecisionKind,
+  ReviewDecisionRecord,
+} from '../hitl-binding.js';
 import type { ReviewerBinding } from '../reviewer-binding.js';
+import { callerReviewerRole } from '../reviewer-role.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { parseListScope } from './scope-params.js';
 
 const APPROVAL_STATUSES: ReadonlySet<ApprovalStatus> = new Set([
   'pending',
@@ -80,10 +89,11 @@ export interface ApprovalsRouterOptions {
 /**
  * Approvals resource routes.
  *
- * Reviewer-role scoping: routes require `c.get('reviewerRole')` to be
- * set by the auth middleware (see `TokenResolution.reviewerRole`).
- * Tokens without a reviewer role get `403 permission-denied` on every
- * approvals route — this surface is reviewer-only.
+ * Reviewer-role scoping: routes require a reviewer role — the token's
+ * (`TokenResolution.reviewerRole`), or its user's in the reviewer roster
+ * (`ReviewerBinding.resolveReviewerRole`). A caller with neither gets
+ * `403 permission-denied` on every approvals route — this surface is
+ * reviewer-only.
  *
  * Visibility filter: a caller with role `R` sees approvals whose
  * `requiredRole` rank ≤ their rank (standard < senior < admin). The
@@ -103,9 +113,11 @@ export function approvalsRouter(
   const runHandler = options.runHandler;
 
   // ---------- role gate for the whole resource ----------
+  // A reviewer: a token that carries a role, or whose user the roster
+  // names (a session or API key of a registered reviewer).
   r.use('*', async (c, next) => {
     const requestId = c.get('requestId');
-    const role = c.get('reviewerRole');
+    const role = await callerReviewerRole(c, reviewerBinding);
     if (role === undefined) {
       c.status(statusFor('permission-denied') as never);
       return c.json(
@@ -113,7 +125,7 @@ export function approvalsRouter(
           {
             code: 'permission-denied',
             message:
-              'This token was not provisioned with a reviewer role; approvals surface is reviewer-only.',
+              "The caller isn't a reviewer: its token carries no reviewer role, and its user isn't registered as one (`kindgi reviewers register`). The approvals surface is reviewer-only.",
           },
           requestId,
         ),
@@ -130,6 +142,14 @@ export function approvalsRouter(
     const role = c.get('reviewerRole') as ReviewerRole;
     const limit = clampLimit(c.req.query('limit'));
 
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
     const statusRaw = c.req.query('status');
     let statusFilter: ApprovalStatus | undefined;
     if (statusRaw !== undefined && statusRaw.length > 0) {
@@ -213,6 +233,7 @@ export function approvalsRouter(
     const listInput = {
       tenantId,
       limit: HITL_LIMIT_CAP,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(statusFilter !== undefined && { status: statusFilter }),
       ...(requiredRoleFilter !== undefined && { requiredRole: requiredRoleFilter }),
       ...(createdAfterIso !== undefined && { since: createdAfterIso as unknown as Timestamp }),
@@ -327,6 +348,22 @@ export function approvalsRouter(
       );
     }
 
+    // An agent's tool-call and session gates resume on the decision alone
+    // (`readGateDecision` fails closed on anything else), so a `value`
+    // can't stand in for it: refused before anything is recorded.
+    if (parsed.value.value !== undefined && AGENT_GATE_SUBJECTS.has(approval.subjectKind)) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `An approval of an agent's ${approval.subjectKind === TOOL_CALL_GATE_SUBJECT ? 'tool call' : 'session'} takes a decision (approve or reject) and an optional rationale, not a \`value\`: the turn resumes on the decision alone.`,
+          },
+          requestId,
+        ),
+      );
+    }
+
     const reviewerId = await reviewerBinding.resolveReviewer({
       tenantId,
       userId: userId as UserId,
@@ -362,23 +399,25 @@ export function approvalsRouter(
     // stays suspended until the new (escalated) approval terminates,
     // or the run is cancelled explicitly.
     //
-    // Resume value shape: `{ decided, rationale? }` — the shape the
-    // agent's approval gate consumes. The caller CAN supply an explicit
-    // `value` in the wire body to override it, when the resume payload
-    // must carry more than the decision.
+    // Resume value shape: `GateDecisionValue`, `{ decided, rationale?,
+    // decidedBy, approvalId }`, the shape the agent's approval gate
+    // consumes; the run's journal keeps who decided which approval. For
+    // another subject, the caller CAN supply an explicit `value` to
+    // override it, when the resume payload must carry more than the
+    // decision (an agent gate refuses one, above).
     let waitpointResolved = false;
     if (
       approval.waitTokenId !== undefined &&
       approval.provenanceRef?.runId !== undefined &&
       (parsed.value.decision === 'approve' || parsed.value.decision === 'reject')
     ) {
-      const resumeValue =
-        parsed.value.value !== undefined
-          ? parsed.value.value
-          : {
-              decided: parsed.value.decision as 'approve' | 'reject',
-              ...(parsed.value.rationale !== undefined && { rationale: parsed.value.rationale }),
-            };
+      const decided: GateDecisionValue = {
+        decided: parsed.value.decision,
+        ...(parsed.value.rationale !== undefined && { rationale: parsed.value.rationale }),
+        decidedBy: `user:${userId as unknown as string}`,
+        approvalId: approval.id as unknown as string,
+      };
+      const resumeValue = parsed.value.value !== undefined ? parsed.value.value : decided;
       const resolved = await runBinding.completeToken(
         tenantId,
         approval.provenanceRef.runId as RunId,
@@ -661,6 +700,18 @@ function serializeApproval(a: Approval): Record<string, unknown> {
     updatedAt: a.updatedAt,
     decidedAt: a.decidedAt,
     expiresAt: a.expiresAt,
+    decision: a.decision === undefined ? undefined : serializeApprovalDecision(a.decision),
+  };
+}
+
+function serializeApprovalDecision(d: ReviewDecisionRecord): Record<string, unknown> {
+  return {
+    decision: d.decision,
+    ...(d.decidedBy !== undefined && { decidedBy: d.decidedBy }),
+    reviewerId: d.reviewerId,
+    reviewerRoleAtDecision: d.reviewerRoleAtDecision,
+    decidedAt: d.decidedAt,
+    ...(d.rationale !== undefined && { rationale: d.rationale }),
   };
 }
 

package/src/routes/blocks.ts

@@ -0,0 +1,362 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Context, Hono } from 'hono';
+
+import {
+  BLOCK_KINDS,
+  type BlockDefinition,
+  type BlockKind,
+  settingsSchemaIssues,
+  validateBlock,
+} from '@kindgi/agents';
+import { ref } from '@kindgi/authz';
+import type { Cursor, ProjectId, TenantId } from '@kindgi/types';
+
+import type { BlockPublishOutcome, BlockRecord, BlockRegistryBinding } from '../block-binding.js';
+import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+import { clampLimit } from './pagination.js';
+import { parseScopeParams } from './scope-params.js';
+
+/**
+ * Data blocks: versioned prompts and settings that agent versions pin
+ * (`/v1/blocks`).
+ *
+ * A block belongs to one project and is authorized through it: reading
+ * is `read` on the project, publishing, unregistering and reinstating
+ * are `write` on it. A block the caller can't read answers 404, as one
+ * that doesn't exist.
+ *
+ * A version never changes, nor does a block's kind. A settings block's
+ * values must satisfy the latest version's schema as well as their
+ * own, so whatever reads them sees a stable shape.
+ */
+export function blocksRouter(binding: BlockRegistryBinding, authorizer?: Authorizer): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+
+  async function canProject(
+    c: Context<AppEnv>,
+    action: 'read' | 'write',
+    projectId: ProjectId,
+  ): Promise<boolean> {
+    return authorizer === undefined || authorizer.can(c, action, ref('project', projectId));
+  }
+
+  function notFound(c: Context<AppEnv>, blockId: string, version?: string) {
+    c.status(statusFor('block-not-found') as never);
+    return c.json(
+      toWireError(
+        {
+          code: 'block-not-found',
+          message: `No block "${blockId}"${version !== undefined ? ` at version "${version}"` : ''}`,
+          blockId,
+          ...(version !== undefined && { version }),
+        },
+        c.get('requestId'),
+      ),
+    );
+  }
+
+  function badInput(c: Context<AppEnv>, message: string) {
+    c.status(statusFor('bad-input') as never);
+    return c.json(toWireError({ code: 'bad-input', message }, c.get('requestId')));
+  }
+
+  // ---------- GET / (each block's latest version) ----------
+  r.get('/', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const kind = c.req.query('kind');
+    if (kind !== undefined && kind.length > 0 && !isBlockKind(kind)) {
+      return badInput(
+        c,
+        `Unknown block kind "${kind}". Expected one of: ${BLOCK_KINDS.join(', ')}.`,
+      );
+    }
+    const scope = parseScopeParams(c.req.query(), { tenantId });
+    if (scope.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scope.message }, c.get('requestId')),
+      );
+    }
+    const cursor = c.req.query('cursor');
+    const name = c.req.query('name');
+    const page = await binding.list({
+      tenantId,
+      limit: clampLimit(c.req.query('limit')),
+      ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor as Cursor }),
+      ...(kind !== undefined && kind.length > 0 && { blockKind: kind as BlockKind }),
+      ...(name !== undefined && name.length > 0 && { nameFilter: name }),
+      ...(scope.scope !== undefined && { scope: scope.scope }),
+    });
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (b) => ref('project', b.projectId));
+    return c.json({
+      data: visible.map(serializeBlock),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:blockId (latest version) ----------
+  r.get('/:blockId', async (c) => {
+    const blockId = c.req.param('blockId');
+    const block = await binding.get({ tenantId: c.get('tenantId') as TenantId, blockId });
+    if (block === null || !(await canProject(c, 'read', block.projectId))) {
+      return notFound(c, blockId);
+    }
+    return c.json(serializeBlock(block));
+  });
+
+  // ---------- GET /:blockId/versions ----------
+  r.get('/:blockId/versions', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const blockId = c.req.param('blockId');
+    const cursor = c.req.query('cursor');
+    const page = await binding.listVersions({
+      tenantId,
+      blockId,
+      limit: clampLimit(c.req.query('limit')),
+      includeTombstoned: c.req.query('includeTombstoned') === 'true',
+      ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor as Cursor }),
+    });
+    const owner = page.data[0] ?? (await anyVersion(tenantId, blockId));
+    if (owner === null || !(await canProject(c, 'read', owner.projectId))) {
+      return notFound(c, blockId);
+    }
+    return c.json({
+      data: page.data.map(serializeBlock),
+      hasMore: page.nextCursor !== undefined,
+      ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
+    });
+  });
+
+  // ---------- GET /:blockId/versions/:version ----------
+  r.get('/:blockId/versions/:version', async (c) => {
+    const blockId = c.req.param('blockId');
+    const version = c.req.param('version');
+    const block = await binding.getVersion({
+      tenantId: c.get('tenantId') as TenantId,
+      blockId,
+      version,
+    });
+    if (block === null || !(await canProject(c, 'read', block.projectId))) {
+      return notFound(c, blockId, version);
+    }
+    return c.json(serializeBlock(block));
+  });
+
+  // ---------- POST / (publish a version) ----------
+  r.post('/', async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return badInput(c, 'Request body must be valid JSON');
+    }
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+      return badInput(c, 'Request body must be an object');
+    }
+    const { projectId, ...definition } = body as Record<string, unknown>;
+    if (typeof projectId !== 'string' || projectId.length === 0) {
+      return badInput(c, '`projectId` is required');
+    }
+    if (!(await canProject(c, 'write', projectId as ProjectId))) {
+      c.status(statusFor('permission-denied') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'permission-denied',
+            message: `Publishing a block needs write on project "${projectId}"`,
+          },
+          requestId,
+        ),
+      );
+    }
+    const validated = validateBlock(definition);
+    if (validated.kind === 'err')
+      return validationFailed(c, validated.error.message, validated.error.issues);
+    const block = validated.value;
+
+    // A block keeps its kind, and a settings block's latest schema holds.
+    const latest = await binding.get({ tenantId, blockId: block.id });
+    const continuity = continuityIssues(latest, block);
+    if (continuity.length > 0) {
+      return validationFailed(c, `Block "${block.id}" can't take this version`, continuity);
+    }
+
+    const outcome = await binding.publish({ tenantId, projectId: projectId as ProjectId, block });
+    return published(c, outcome);
+  });
+
+  // ---------- POST /:blockId/versions/:version/unregister ----------
+  r.post('/:blockId/versions/:version/unregister', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const blockId = c.req.param('blockId');
+    const version = c.req.param('version');
+    const block = await binding.getVersion({ tenantId, blockId, version });
+    if (block === null || !(await canProject(c, 'read', block.projectId))) {
+      return notFound(c, blockId, version);
+    }
+    if (!(await canProject(c, 'write', block.projectId))) return denied(c, block.projectId);
+    const outcome = await binding.unregister({ tenantId, blockId, version });
+    if (!outcome.unregistered) return notFound(c, blockId, version);
+    return c.json({ blockId, version, unregistered: true });
+  });
+
+  // ---------- POST /:blockId/versions/:version/reinstate ----------
+  r.post('/:blockId/versions/:version/reinstate', async (c) => {
+    const tenantId = c.get('tenantId') as TenantId;
+    const blockId = c.req.param('blockId');
+    const version = c.req.param('version');
+    const block = await binding.getVersion({ tenantId, blockId, version });
+    if (block === null || !(await canProject(c, 'read', block.projectId))) {
+      return notFound(c, blockId, version);
+    }
+    if (!(await canProject(c, 'write', block.projectId))) return denied(c, block.projectId);
+    const outcome = await binding.reinstateVersion({ tenantId, blockId, version });
+    if (outcome.kind === 'not-found') return notFound(c, blockId, version);
+    return c.json({ blockId, version, wasTombstoned: outcome.wasTombstoned });
+  });
+
+  /** Any version of a block, unregistered ones included: whose project it is. */
+  async function anyVersion(tenantId: TenantId, blockId: string): Promise<BlockRecord | null> {
+    const page = await binding.listVersions({
+      tenantId,
+      blockId,
+      limit: 1,
+      includeTombstoned: true,
+    });
+    return page.data[0] ?? null;
+  }
+
+  return r;
+}
+
+function isBlockKind(value: string): value is BlockKind {
+  return (BLOCK_KINDS as readonly string[]).includes(value);
+}
+
+/** A new version against the block's latest: same kind, and a settings block's schema holds. */
+function continuityIssues(
+  latest: BlockRecord | null,
+  block: BlockDefinition,
+): { path: string; message: string }[] {
+  if (latest === null) return [];
+  if (latest.kind !== block.kind) {
+    return [
+      {
+        path: '/kind',
+        message: `block "${block.id}" is a ${latest.kind} block; a version can't change its kind`,
+      },
+    ];
+  }
+  if (
+    latest.kind === 'settings' &&
+    block.kind === 'settings' &&
+    latest.content.schema !== undefined
+  ) {
+    return settingsSchemaIssues(block.content.values, latest.content.schema).map((i) => ({
+      ...i,
+      message: `${i.message} (the schema of version ${latest.version})`,
+    }));
+  }
+  return [];
+}
+
+/** The response to a publish outcome. */
+function published(c: Context<AppEnv>, outcome: BlockPublishOutcome) {
+  const requestId = c.get('requestId');
+  switch (outcome.kind) {
+    case 'ok':
+      c.status(201);
+      return c.json({ blockId: outcome.blockId, version: outcome.version });
+    case 'already-registered':
+      c.status(statusFor('block-already-registered') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'block-already-registered',
+            message: `Block "${outcome.blockId}" version "${outcome.version}" is already published; versions never change, so publish a new one`,
+            blockId: outcome.blockId,
+            version: outcome.version,
+          },
+          requestId,
+        ),
+      );
+    case 'project-mismatch':
+      c.status(statusFor('block-project-mismatch') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'block-project-mismatch',
+            message: `Block "${outcome.blockId}" belongs to project "${outcome.projectId as unknown as string}"; publish its versions there`,
+            blockId: outcome.blockId,
+            projectId: outcome.projectId as unknown as string,
+          },
+          requestId,
+        ),
+      );
+    case 'project-not-found':
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`projectId\` "${outcome.projectId as unknown as string}" does not resolve to a project in this tenant`,
+          },
+          requestId,
+        ),
+      );
+  }
+}
+
+function validationFailed(
+  c: Context<AppEnv>,
+  message: string,
+  issues: readonly { readonly path: string; readonly message: string }[],
+) {
+  c.status(statusFor('validation-failed') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'validation-failed',
+        message,
+        issues: issues as unknown as Record<string, unknown>[],
+      },
+      c.get('requestId'),
+    ),
+  );
+}
+
+function denied(c: Context<AppEnv>, projectId: ProjectId) {
+  c.status(statusFor('permission-denied') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'permission-denied',
+        message: `This needs write on the block's project "${projectId as unknown as string}"`,
+      },
+      c.get('requestId'),
+    ),
+  );
+}
+
+function serializeBlock(b: BlockRecord): Record<string, unknown> {
+  return {
+    id: b.id,
+    version: b.version,
+    kind: b.kind,
+    ...(b.description !== undefined && { description: b.description }),
+    content: b.content,
+    projectId: b.projectId as unknown as string,
+    publishedAt: b.publishedAt,
+    ...(b.unregisteredAt !== undefined && { unregisteredAt: b.unregisteredAt }),
+  };
+}

package/src/routes/conversations.ts

@@ -10,12 +10,16 @@ import type {
   ConversationMessage,
   ConversationPageCursor,
 } from '@kindgi/agents';
+import type { ProjectBinding } from '@kindgi/platform';
 import type { RunBinding } from '@kindgi/runtime';
-import type { AgentId, Semver, TenantId } from '@kindgi/types';
+import type { AgentId, ProjectId, Semver, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
+import { parseListScope } from './scope-params.js';
+
+const PROJECT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /**
  * Conversations resource routes. All storage access goes through the
@@ -27,6 +31,11 @@ import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
 export function conversationsRouter(
   conversationBinding: ConversationBinding,
   runBinding: RunBinding,
+  /**
+   * When wired, a `projectId` given to `POST /` must be one of the
+   * tenant's projects, and an omitted one is the tenant's Default project.
+   */
+  projectBinding?: ProjectBinding,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
@@ -53,6 +62,14 @@ export function conversationsRouter(
 
     const agentIdRaw = c.req.query('agentId');
 
+    const scopeParsed = parseListScope(c.req.query(), { tenantId });
+    if (scopeParsed.kind === 'err') {
+      c.status(statusFor('scope-invalid') as never);
+      return c.json(
+        toWireError({ code: 'scope-invalid', message: scopeParsed.message }, requestId),
+      );
+    }
+
     let before: ConversationPageCursor | undefined;
     const rawCursor = c.req.query('cursor');
     if (rawCursor !== undefined && rawCursor.length > 0) {
@@ -68,6 +85,7 @@ export function conversationsRouter(
 
     const listResult = await conversationBinding.listConversationsPage({
       tenantId,
+      ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(agentIdRaw !== undefined && agentIdRaw.length > 0 && { agentId: agentIdRaw as AgentId }),
       ...(statusFilter !== undefined && { status: statusFilter }),
       ...(before !== undefined && { before }),
@@ -126,9 +144,30 @@ export function conversationsRouter(
       c.status(statusFor(parsed.error.code) as never);
       return c.json(toWireError(parsed.error, requestId));
     }
+    const supplied = parsed.value.projectId;
+    if (
+      supplied !== undefined &&
+      projectBinding !== undefined &&
+      (await projectBinding.get(tenantId, supplied)) === undefined
+    ) {
+      c.status(statusFor('bad-input') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'bad-input',
+            message: `\`projectId\` "${supplied as unknown as string}" does not resolve to a project in this tenant`,
+          },
+          requestId,
+        ),
+      );
+    }
+    // Omitted: the tenant's Default project, as for a run. No Default (or
+    // no project binding): no project, never a refusal.
+    const projectId = supplied ?? (await projectBinding?.getDefault(tenantId))?.id;
 
     const opened = await conversationBinding.openConversation({
       tenantId,
+      ...(projectId !== undefined && { projectId }),
       agentId: parsed.value.agentId,
       agentVersion: parsed.value.agentVersion,
       title: parsed.value.title,
@@ -232,6 +271,7 @@ function serializeConversation(c: Conversation): Record<string, unknown> {
     agentVersion: c.agentVersion as unknown as string,
     title: c.title,
     ...(c.participantId !== undefined && { participantId: c.participantId }),
+    ...(c.projectId !== undefined && { projectId: c.projectId as unknown as string }),
     scope: c.scope,
     status: (c.closedAt === undefined ? 'open' : 'closed') as 'open' | 'closed',
     openedAt: c.openedAt as unknown as string,
@@ -283,6 +323,7 @@ interface ParsedOpenBody {
   readonly agentVersion: Semver;
   readonly title: string;
   readonly scope: Readonly<Record<string, unknown>>;
+  readonly projectId?: ProjectId;
   readonly participantId?: string;
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
@@ -335,6 +376,20 @@ function parseOpenBody(
     scope = scopeRaw as Readonly<Record<string, unknown>>;
   }
 
+  const projectIdRaw = b.projectId;
+  if (
+    projectIdRaw !== undefined &&
+    (typeof projectIdRaw !== 'string' || !PROJECT_ID_RE.test(projectIdRaw))
+  ) {
+    return {
+      kind: 'err',
+      error: {
+        code: 'bad-input',
+        message: '`projectId` must be a project id (a UUID) when supplied',
+      },
+    };
+  }
+
   const participantIdRaw = b.participantId;
   if (participantIdRaw !== undefined && typeof participantIdRaw !== 'string') {
     return {
@@ -362,6 +417,7 @@ function parseOpenBody(
       agentVersion: agentVersion as Semver,
       title,
       scope,
+      ...(projectIdRaw !== undefined && { projectId: projectIdRaw as ProjectId }),
       ...(participantIdRaw !== undefined && { participantId: participantIdRaw }),
       ...(metadata !== undefined && { metadata }),
     },