create-ailk 0.12.1 → 0.13.0

package/templates/apps/api/src/services/audit-log.ts

@@ -1,10 +1,19 @@
 /**
  * @file audit-log.ts
- * @description The agent-action audit writer (#6040, REL-017 row 5 / FEAT-084
- * SUB-096) — `recordAgentAction`, the first production write site for
- * `ops.AuditLog`. Writes exactly one row per agent action: tenant, actor,
- * tool, and outcome, with personal data redacted before it can reach the
- * stored row.
+ * @description The audit writer (#6040, REL-017 row 5 / FEAT-084 SUB-096;
+ * reshaped by #3591 D8) — `recordAuditAction`, the one production write site
+ * for `ops.AuditLog`. Writes exactly one row per audited action: tenant,
+ * actor, action, and outcome, with personal data redacted before it can
+ * reach the stored row.
+ *
+ * ## WHO ACTED
+ *
+ * The caller names the actor: a person (`actorType: "user"`, `actorId` their
+ * user id), or an agent acting on behalf of a person (`actorType: "agent"`,
+ * `actorId` the agent's id, `metadata.onBehalfOf` the person's user id). The
+ * `action` column is `<domain>.<tool>` — `inbox.accept_message`,
+ * `magnets.magnet.create` — and never says who acted; that is the
+ * `actorType` column's job.
  *
  * ## AUDIT FAILURE DOES NOT BLOCK THE AUDITED ACTION
  *
@@ -16,7 +25,7 @@
  * about what happened. The compensating control is that the failure is
  * loud: a typed `{ ok: false }` the caller can branch on, plus a
  * `logger.error` line. Nothing in TypeScript FORCES a caller to read the
- * result — `await recordAgentAction(input)` as a bare statement compiles
+ * result — `await recordAuditAction(input)` as a bare statement compiles
  * and lints clean — so the caller issue (#6041 or SUB-097) owns branching on
  * `ok` and raising its own alert; a lint/metric enforcing that belongs to
  * whichever issue adds the first caller.
@@ -70,7 +79,7 @@
  * — a caller may inject its own, e.g. an interactive `$transaction` client).
  */
 
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 import type { Prisma } from "@working-theory/database";
 import {
@@ -89,12 +98,20 @@ import { isUniqueViolation, type TenantContext } from "./default-tenant.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
-/** The full actor-kind vocabulary the model comments (not a DB CHECK). Only
- * `"agent"` is ever written by this file — `"user"`/`"system"` are exported
- * so a future writer for those actors (#3591) shares one union. */
+/** The full actor-kind vocabulary the model comments (not a DB CHECK). This
+ * file writes `"user"` and `"agent"` (#3591 D8); `"system"` is kept so a
+ * future writer for that actor shares one union. */
 export type AuditActorType = "user" | "agent" | "system";
 
-export type AgentActionOutcome =
+/**
+ * Who acted (#3591 D8) — the same shape as `request.actor`
+ * (`middleware/auth.ts`'s `RequestActor`), so a route passes it through.
+ */
+export type AuditActor =
+  | { type: "user"; userId: Id<"user"> }
+  | { type: "agent"; agentId: Id<"agent">; onBehalfOfUserId: Id<"user"> };
+
+export type AuditActionOutcome =
   "succeeded" | "failed" | "refused" | "awaiting_approval";
 
 /** One row as this writer assembles it — never re-exported; a caller sees
@@ -104,10 +121,12 @@ export type AgentActionOutcome =
  * Prisma's `InputJsonValue` under `exactOptionalPropertyTypes` — an
  * `unknown`-valued record does not. */
 interface AuditLogMetadata {
-  v: 1;
-  outcome: AgentActionOutcome;
+  v: 2;
+  outcome: AuditActionOutcome;
   tool: string;
   idempotencyKey: string;
+  /** The person an agent acted for (#3591 D8) — present only on an agent row. */
+  onBehalfOf?: string;
   summary?: string;
   failureReason?: string;
 }
@@ -146,16 +165,22 @@ export interface AuditWriteClient {
  * its constraint is an `invalid_input` refusal, never a truncation or a
  * silent coercion — a coerced audit row is a wrong audit row.
  */
-export interface RecordAgentActionInput {
+export interface RecordAuditActionInput {
   /** MUST come from `resolveActiveTenant` / `resolveDefaultTenant` — never
    * assembled from request input. See the file docblock. */
   tenant: TenantContext;
-  /** <=128 chars, `/^[A-Za-z0-9_:.-]+$/`, then personal-data-scanned. */
-  actorId: string;
+  /** Who acted — `request.actor`. Each id it carries is <=128 chars,
+   * `/^[A-Za-z0-9_:.-]+$/`, then personal-data-scanned unless it is a
+   * registry-minted `user_` or `agent_` id. */
+  actor: AuditActor;
+  /** <=32 chars, `/^[a-z][a-z0-9_]*$/` — the area the action belongs to
+   * (`"inbox"`, `"magnets"`, `"scheduling"`), the first segment of
+   * `action`. */
+  domain: string;
   /** <=64 chars, `/^[a-z0-9_.-]+$/` — an identifier, so `action` cannot
    * carry prose. */
   tool: string;
-  outcome: AgentActionOutcome;
+  outcome: AuditActionOutcome;
   /** <=256 chars, `/^[A-Za-z0-9_:.-]+$/`, then personal-data-scanned.
    * REQUIRED — an optional key would silently degrade to "no dedup" for a
    * caller who forgets it. Stable across a replay of the same logical
@@ -185,7 +210,7 @@ export interface RecordAgentActionInput {
   targetId?: string;
 }
 
-export type RecordAgentActionResult =
+export type RecordAuditActionResult =
   | { ok: true; outcome: "recorded" | "duplicate"; id: Id<"auditLog"> }
   | {
       ok: false;
@@ -211,10 +236,11 @@ export interface AuditRowDigestInput {
   workspaceId: string;
   actorId: string;
   actorType: AuditActorType;
+  onBehalfOf: string | undefined;
   action: string;
   targetType: string | undefined;
   targetId: string | undefined;
-  outcome: AgentActionOutcome;
+  outcome: AuditActionOutcome;
   summary: string | undefined;
   failureReason: string | undefined;
   idempotencyKey: string;
@@ -228,13 +254,16 @@ export interface AuditRowDigestInput {
 const MAX_TEXT = 2_000;
 
 /** An MCP tool name is an identifier — this charset cannot express an `@`,
- * and it bounds the `action` column (`"agent.commerce." + tool`). */
+ * and it bounds the `action` column (`domain + "." + tool`). */
 const TOOL_RE = /^[a-z0-9_.-]{1,64}$/;
 
+/** The action's first segment — `"inbox"`, `"magnets"`, `"scheduling"`. */
+const DOMAIN_RE = /^[a-z][a-z0-9_]{0,31}$/;
+
 /** The schema's own examples are `"workspace"`, `"lead"`, `"user"`. */
 const TARGET_TYPE_RE = /^[a-z][a-z0-9_]{0,31}$/;
 
-/** `actorId`'s shape is open (Q2) — an opaque, non-registry identifier. */
+/** An actor id's shape is open (Q2) — any identifier, registry-minted or not. */
 const ACTOR_ID_RE = /^[A-Za-z0-9_:.-]{1,128}$/;
 
 /** `targetId` when `targetType` does not name a known registry entity. */
@@ -271,6 +300,24 @@ const PHONE_RE = /\+?\d(?:[ .-]?\d){6,14}/g;
  * runs are already consumed above; this is the residual). */
 const LONG_DIGIT_RUN_RE = /\d{9,}/g;
 
+/**
+ * Where free text splits into tokens for the registry-id exemption below:
+ * whitespace and `=` (so `responsibleUserId=<id>` holds the id as a token).
+ */
+const FREE_TEXT_TOKEN_SEPARATOR_RE = /(\s+|=)/;
+
+/**
+ * Whether a free-text token is EXACTLY a registry-minted `user_` or `agent_`
+ * id (#3591 D8) — the same anchored pattern `actorIdRefusal` exempts. Such an
+ * id's hex can hold a digit run the phone pattern flags (about one id in
+ * three), which would turn a `summary` that names a person by id — the agent
+ * lifecycle rows' "for whom" — into `[REDACTED:phone]`. A token that merely
+ * contains one, or only looks like one, is scanned like any other text.
+ */
+function isRegistryActorId(token: string): boolean {
+  return idRegex("user").test(token) || idRegex("agent").test(token);
+}
+
 const EMAIL_MARKER = "[REDACTED:email]";
 const PHONE_MARKER = "[REDACTED:phone]";
 const NUMBER_MARKER = "[REDACTED:number]";
@@ -292,8 +339,8 @@ function isKnownEntity(value: string): value is Entity {
  * `redactHighEntropy` first (catches a live secret pasted into
  * `failureReason` — the natural home for provider error text), then applies
  * the three anchored, bounded personal-data patterns. Exported — directly
- * unit-testable, and reused (as a detection predicate) for `actorId` and
- * `idempotencyKey` below.
+ * unit-testable, and reused (as a detection predicate) for the actor's ids
+ * and `idempotencyKey` below.
  *
  * What this does NOT catch, stated rather than implied: a postal address or
  * a personal name in free text (no achievable regex exists across locales),
@@ -318,9 +365,31 @@ export function redactPersonalData(text: string): string {
   return out;
 }
 
+/**
+ * `summary` / `failureReason`'s redaction: `redactPersonalData`, except that a
+ * token which is exactly a registry `user_` / `agent_` id is kept whole (see
+ * `isRegistryActorId`). The text between such tokens is scanned as ONE run,
+ * separators included, so a phone number written with spaces is still caught.
+ * Identifier fields are not routed here — an actor id has its own exemption,
+ * and `idempotencyKey` stays scanned.
+ */
+function redactFreeText(text: string): string {
+  let out = "";
+  let run = "";
+  for (const part of text.normalize("NFKC").split(FREE_TEXT_TOKEN_SEPARATOR_RE)) {
+    if (isRegistryActorId(part)) {
+      out += redactPersonalData(run) + part;
+      run = "";
+    } else {
+      run += part;
+    }
+  }
+  return out + redactPersonalData(run);
+}
+
 /** True when `redactPersonalData` would change `text` — used to REFUSE
  * (never silently rewrite) an identifier-shaped field that happens to
- * contain a personal-data-shaped substring (`actorId`, `idempotencyKey`). */
+ * contain a personal-data-shaped substring (an actor id, `idempotencyKey`). */
 function personalDataDetected(text: string): boolean {
   // Checked by MARKER PRESENCE, not by inequality against the input — an
   // inequality check is a call-order-dependent accident: NFKC alone can
@@ -365,6 +434,7 @@ export function deriveAuditRowId(input: AuditRowDigestInput): string {
     input.workspaceId,
     input.actorId,
     input.actorType,
+    input.onBehalfOf,
     input.action,
     input.targetType,
     input.targetId,
@@ -417,6 +487,8 @@ function classifyError(error: unknown): { code: string; name: string } {
 interface ValidatedFields {
   workspaceId: string;
   actorId: string;
+  actorType: "user" | "agent";
+  onBehalfOf: string | undefined;
   tool: string;
   targetType: string | undefined;
   targetId: string | undefined;
@@ -445,34 +517,60 @@ function validateFreeText(
       message: "contains a NUL or other C0 control character",
     };
   }
-  return { ok: true, value: redactPersonalData(text) };
+  return { ok: true, value: redactFreeText(text) };
+}
+
+/**
+ * An actor's id: the identifier grammar, then the personal-data scan — except
+ * for a registry-minted `user_` or `agent_` id, which is an identifier, not
+ * personal data. Its hex can still hold a digit run the phone pattern flags
+ * (about one id in three), which silently dropped real actors' rows (#7636
+ * D7, security review finding 1; #3591 D8). Every other id is still scanned.
+ * Returns the refusal message, or `undefined` when the id is admitted.
+ */
+function actorIdRefusal(id: string, field: string): string | undefined {
+  if (!ACTOR_ID_RE.test(id)) {
+    return `${field} does not match the required identifier grammar`;
+  }
+  const registryId = idRegex("user").test(id) || idRegex("agent").test(id);
+  if (!registryId && personalDataDetected(id)) {
+    return `${field} appears to carry personal data`;
+  }
+  return undefined;
 }
 
 /**
  * Validates every string member before it is digested or written (F9).
  * Identifier-shaped members are REFUSED on a constraint violation, never
- * coerced — a coerced audit row is a wrong audit row (D5). `actorId` and
- * `idempotencyKey` additionally fail the personal-data scan as a REFUSAL
+ * coerced — a coerced audit row is a wrong audit row (D5). The actor's ids
+ * and `idempotencyKey` additionally fail the personal-data scan as a REFUSAL
  * (never a silent rewrite of an identifier field) rather than as a
  * redaction, unlike `summary` / `failureReason`.
  */
-function validateInput(input: RecordAgentActionInput): ValidationResult {
+function validateInput(input: RecordAuditActionInput): ValidationResult {
   if (!zWorkspaceId.safeParse(input.tenant.workspaceId).success) {
     return {
       ok: false,
       message: "tenant.workspaceId is not a valid workspace id",
     };
   }
-  if (!ACTOR_ID_RE.test(input.actorId)) {
-    return {
-      ok: false,
-      message: "actorId does not match the required identifier grammar",
-    };
+  const { actor } = input;
+  const actorId = actor.type === "agent" ? actor.agentId : actor.userId;
+  const actorRefusal = actorIdRefusal(actorId, "actorId");
+  if (actorRefusal !== undefined) {
+    return { ok: false, message: actorRefusal };
   }
-  if (personalDataDetected(input.actorId)) {
+  const onBehalfOf = actor.type === "agent" ? actor.onBehalfOfUserId : undefined;
+  if (onBehalfOf !== undefined) {
+    const onBehalfOfRefusal = actorIdRefusal(onBehalfOf, "onBehalfOf");
+    if (onBehalfOfRefusal !== undefined) {
+      return { ok: false, message: onBehalfOfRefusal };
+    }
+  }
+  if (!DOMAIN_RE.test(input.domain)) {
     return {
       ok: false,
-      message: "actorId appears to carry personal data",
+      message: "domain does not match the required identifier grammar",
     };
   }
   if (!TOOL_RE.test(input.tool)) {
@@ -531,7 +629,9 @@ function validateInput(input: RecordAgentActionInput): ValidationResult {
     ok: true,
     value: {
       workspaceId: input.tenant.workspaceId,
-      actorId: input.actorId,
+      actorId,
+      actorType: actor.type,
+      onBehalfOf,
       tool: input.tool,
       targetType: input.targetType,
       targetId: input.targetId,
@@ -541,18 +641,39 @@ function validateInput(input: RecordAgentActionInput): ValidationResult {
   };
 }
 
+/**
+ * One fresh, process-independent audit idempotency key (#6231; moved here
+ * from `routes/magnets/index.ts` so every route writer shares it, #7636): a
+ * `crypto.randomUUID()` with its dashes removed and its 32 hex characters
+ * regrouped into runs of six joined by `_` (e.g.
+ * `e4a940_bf8d33_4c2281_4b1b27_4461cd_19`).
+ *
+ * The regrouping is load-bearing, not cosmetic. `recordAuditAction` REFUSES
+ * an `idempotencyKey` its personal-data scan flags — a refusal writes no row
+ * at all — and that scan's phone pattern treats `-` as a digit separator,
+ * so a raw dashed uuid whose hex happens to be digit-heavy reads as a phone
+ * number: measured over 200k uuids, 37% are refused. `_` is not one of that
+ * pattern's separators (and is inside the key's allowed charset), so
+ * grouping caps every digit run at six — under the phone pattern's 7-digit
+ * floor and the long-digit-run pattern's 9 — and no generated key can be
+ * refused. Entropy is untouched: the same 128 bits, re-spelled.
+ */
+export function freshAuditIdempotencyKey(): string {
+  return randomUUID().replace(/-/g, "").replace(/(.{6})(?=.)/g, "$1_");
+}
+
 // ─── The writer ─────────────────────────────────────────────────────────────
 
 /**
- * Writes exactly one `audit_logs` row for one agent action. Never throws;
+ * Writes exactly one `audit_logs` row for one audited action. Never throws;
  * never blocks the caller's action (see the file docblock heading). Not
  * gated on the `commerce` license claim (see the file docblock) — gating
  * stays upstream, at the caller's own claim check.
  */
-export async function recordAgentAction(
-  input: RecordAgentActionInput,
+export async function recordAuditAction(
+  input: RecordAuditActionInput,
   db: AuditWriteClient = prisma,
-): Promise<RecordAgentActionResult> {
+): Promise<RecordAuditActionResult> {
   const validated = validateInput(input);
   if (!validated.ok) {
     return {
@@ -568,19 +689,21 @@ export async function recordAgentAction(
   const {
     workspaceId,
     actorId,
+    actorType,
+    onBehalfOf,
     tool,
     targetType,
     targetId,
     redactedSummary,
     redactedFailureReason,
   } = validated.value;
-  const actorType: AuditActorType = "agent";
-  const action = `agent.commerce.${tool}`;
+  const action = `${input.domain}.${tool}`;
 
   const id = deriveAuditRowId({
     workspaceId,
     actorId,
     actorType,
+    onBehalfOf,
     action,
     targetType,
     targetId,
@@ -603,17 +726,18 @@ export async function recordAgentAction(
       ok: false,
       error: {
         kind: "write_failed",
-        message: "agent action row write failed",
+        message: "audit row write failed",
         persisted: false,
       },
     };
   }
 
   const metadata: AuditLogMetadata = {
-    v: 1,
+    v: 2,
     outcome: input.outcome,
     tool,
     idempotencyKey: input.idempotencyKey,
+    ...(onBehalfOf !== undefined && { onBehalfOf }),
     ...(redactedSummary !== undefined && { summary: redactedSummary }),
     ...(redactedFailureReason !== undefined && {
       failureReason: redactedFailureReason,
@@ -645,7 +769,7 @@ export async function recordAgentAction(
       // no read is needed to report it.
       logger.warn(
         { workspaceId, action, actorType, auditLogId: id },
-        "[audit-log] duplicate agent action row suppressed by primary key",
+        "[audit-log] duplicate audit row suppressed by primary key",
       );
       return { ok: true, outcome: "duplicate", id: id as Id<"auditLog"> };
     }
@@ -654,15 +778,122 @@ export async function recordAgentAction(
     // argument IS the audit row (N7, D10).
     logger.error(
       { workspaceId, action, actorType, errorCode: code, errorName: name },
-      "[audit-log] agent action row write failed",
+      "[audit-log] audit row write failed",
     );
     return {
       ok: false,
       error: {
         kind: "write_failed",
-        message: "agent action row write failed",
+        message: "audit row write failed",
         persisted: false,
       },
     };
   }
 }
+
+// ─── Route helpers (#3591 D8) ───────────────────────────────────────────────
+
+/**
+ * The actor a route records: `request.actor`, which the auth preHandler sets
+ * on every authenticated request. A route reached without it (a harness that
+ * seats `request.tenant` directly) is filed as the tenant's own person, with a
+ * `warn` — an auth path that forgot to bind the actor must not pass silently.
+ */
+export function auditActorFor(
+  actor: AuditActor | undefined,
+  tenant: TenantContext,
+): AuditActor {
+  if (actor) return actor;
+  logger.warn(
+    { workspaceId: tenant.workspaceId },
+    "[audit-log] no request actor; filing the tenant's person",
+  );
+  return { type: "user", userId: tenant.userId };
+}
+
+/** A service call's result, as far as the audit row needs it. */
+export type AuditedResult = { ok: true } | { ok: false; error: { kind: string } };
+
+/**
+ * Who a route says acted, as far as `recordAgentWrite` reads it: the request
+ * itself (`request.actor`, and `request.agent` on the agent path), or — the
+ * older call shape — `request.actor` alone.
+ */
+export type AgentWriteCaller =
+  | AuditActor
+  | undefined
+  | { actor?: AuditActor; agent?: { agentId: Id<"agent"> } };
+
+/**
+ * #3591 D8 — one row for an agent's inbox write, recorded after the write
+ * returns: `succeeded` when it did, else `failed` with the service's error
+ * kind. A person's write records nothing (spec § 2.3: a person's inbox
+ * actions are not audited). A failed audit write is logged at `error` once —
+ * by the writer for a failed insert, here for a refused row — and returns
+ * normally, so it never changes the caller's response.
+ *
+ * Pass the request, not `request.actor` alone, so an agent write cannot go
+ * unrecorded in silence: a request with `request.agent` but no
+ * `request.actor` (an auth path that forgot to bind the actor) is logged at
+ * `error` and still recorded, from `request.agent`. Its person is
+ * `tenant.userId`: on the agent path the tenant guard grants the workspace
+ * through the agent's responsible membership, so the tenant's person IS the
+ * person the agent acts for — read from the grant, not guessed.
+ */
+export async function recordAgentWrite(
+  caller: AgentWriteCaller,
+  input: Omit<
+    RecordAuditActionInput,
+    "actor" | "outcome" | "failureReason" | "idempotencyKey"
+  >,
+  result: AuditedResult,
+  db: AuditWriteClient = prisma,
+): Promise<void> {
+  const actor = agentWriteActor(caller, input);
+  if (actor?.type !== "agent") return;
+  const audit = await recordAuditAction(
+    {
+      ...input,
+      actor,
+      idempotencyKey: freshAuditIdempotencyKey(),
+      ...(result.ok
+        ? { outcome: "succeeded" as const }
+        : { outcome: "failed" as const, failureReason: result.error.kind }),
+    },
+    db,
+  );
+  if (!audit.ok && audit.error.kind === "invalid_input") {
+    logger.error(
+      {
+        workspaceId: input.tenant.workspaceId,
+        action: `${input.domain}.${input.tool}`,
+        actorId: actor.agentId,
+        error: audit.error,
+      },
+      "[audit-log] agent write audit refused",
+    );
+  }
+}
+
+/** The actor `recordAgentWrite` files — see its docblock for the fallback. */
+function agentWriteActor(
+  caller: AgentWriteCaller,
+  input: { tenant: TenantContext; domain: string; tool: string },
+): AuditActor | undefined {
+  if (caller === undefined || "type" in caller) return caller;
+  if (caller.actor) return caller.actor;
+  if (!caller.agent) return undefined;
+  logger.error(
+    {
+      workspaceId: input.tenant.workspaceId,
+      action: `${input.domain}.${input.tool}`,
+      actorId: caller.agent.agentId,
+    },
+    "[audit-log] agent write without request.actor; recording from request.agent",
+  );
+  return {
+    type: "agent",
+    agentId: caller.agent.agentId,
+    onBehalfOfUserId: input.tenant.userId,
+  };
+}

package/templates/apps/api/src/services/default-tenant.ts

@@ -43,7 +43,9 @@ import {
   resolveDefaultWorkspaceRow as resolveDefaultWorkspaceRowShared,
 } from "@working-theory/database/tenancy";
 import type { Id } from "@working-theory/ids";
+import { lowerRole } from "@working-theory/validation";
 
+import type { AgentGrant } from "../lib/agent-store.js";
 import { prisma } from "../lib/prisma.js";
 
 import { findVerifiedEmail } from "./verified-email.js";
@@ -204,6 +206,40 @@ export async function resolveDefaultTenantForOperator(
   return (await isPinnedOperator(userId)) ? resolveDefaultTenant(userId) : null;
 }
 
+/**
+ * The base-build grant for an AGENT (#3591 spec D5, D7). The same steps as
+ * `resolveDefaultTenantForOperator` — the pin check, then the default
+ * resolution and its one Membership read — so an agent and its person's
+ * session drive the same reads. On top of them: the resolved workspace must
+ * be the one the agent is bound to, and the Membership the read found must be
+ * the one the agent was created under. The role is then clamped to the
+ * agent's ceiling (`lowerRole`), so the operator's agent acts as a member.
+ *
+ * The membership id is compared here rather than carried on `TenantContext`,
+ * which stays one shape for every caller. On a base build only the pinned,
+ * verified operator holds a membership this admits, so only the operator's
+ * agents, bound to the default workspace, ever pass.
+ */
+export async function resolveDefaultTenantForAgent(
+  userId: Id<"user">,
+  agent: AgentGrant,
+): Promise<TenantContext | null> {
+  if (!(await isPinnedOperator(userId))) return null;
+  const granted = await resolveDefaultGrant(userId);
+  if (
+    !granted ||
+    granted.tenant.workspaceId !== agent.workspaceId ||
+    granted.tenant.organizationId !== agent.organizationId ||
+    granted.membershipId !== agent.responsibleMembershipId
+  ) {
+    return null;
+  }
+  return {
+    ...granted.tenant,
+    role: lowerRole(granted.tenant.role, agent.permissionLevel),
+  };
+}
+
 /**
  * The one pin-match predicate in `apps/api` (#7523 D2): `true` only when
  * `AILK_OPERATOR_EMAIL` is set and the caller's VERIFIED `User.email` equals
@@ -297,6 +333,17 @@ export async function resolveDefaultWorkspaceId(): Promise<Id<"workspace"> | nul
 export async function resolveDefaultTenant(
   userId: Id<"user">,
 ): Promise<TenantContext | null> {
+  return (await resolveDefaultGrant(userId))?.tenant ?? null;
+}
+
+/**
+ * `resolveDefaultTenant`'s body, also handing back the id of the Membership
+ * it read, which the agent path compares (#3591 D5). One read serves both:
+ * its `select` is widened from `{ role }` to `{ id, role }`.
+ */
+async function resolveDefaultGrant(
+  userId: Id<"user">,
+): Promise<{ tenant: TenantContext; membershipId: string } | null> {
   const workspace = await resolveDefaultWorkspaceRow();
   if (!workspace) {
     return null;
@@ -309,15 +356,18 @@ export async function resolveDefaultTenant(
         userId,
       },
     },
-    select: { role: true },
+    select: { id: true, role: true },
   });
   if (!membership) {
     return null;
   }
   return {
-    userId,
-    organizationId: workspace.organizationId as Id<"organization">,
-    workspaceId: workspace.id as Id<"workspace">,
-    role: membership.role as MembershipRole,
+    tenant: {
+      userId,
+      organizationId: workspace.organizationId as Id<"organization">,
+      workspaceId: workspace.id as Id<"workspace">,
+      role: membership.role as MembershipRole,
+    },
+    membershipId: membership.id,
   };
 }