@k2b/cloud 0.38.0 → 0.40.0

package/src/ai/approvals.ts

@@ -1,4 +1,8 @@
-import { sql } from "bun";
+import { type SQL, sql } from "bun";
+import type { AccessSubject } from "../contracts/shared";
+import type { RequestActor } from "../server/middleware/auth";
+import { type AuditActor, type AuditRecordParams, audit } from "../services/audit";
+import { toPgTextArray } from "../services/postgres";
 import type { AiToolApprovalPolicy, AiTurnRunConfig } from "./types";
 
 /** Background authority never inherits a user's interactive Always Allow preference. */
@@ -31,6 +35,16 @@ export type AiToolApprovalContext = {
   actorUserId: string;
 };
 
+/**
+ * Request identity for approval changes; never persist this context in a turn run config.
+ * When actor is absent, audit uses { userId: actorUserId } for the approval's owner.
+ * The access subject is derived from actor, or falls back to { type: "user", userId: actorUserId }.
+ */
+export type AiToolApprovalChangeContext = AiToolApprovalContext & {
+  actor?: RequestActor;
+  requestId?: string | null;
+};
+
 /** Where a remembered approval applies: in one chat until it is deleted, or always. */
 export type AiToolApprovalRemember = "chat" | "always";
 
@@ -55,6 +69,59 @@ type AiToolApprovalPreferenceRow = {
   expires_at: Date | string | null;
 };
 
+type ApprovalAuditRow = Pick<AiToolApprovalPreferenceRow, "id" | "tool_name" | "approval_scope" | "conversation_id">;
+type ApprovalAuditIdentity = {
+  actor: AuditActor | null;
+  accessSubject: AccessSubject | null;
+  serviceAccountId?: string;
+  requestId?: string | null;
+  reason?: string;
+};
+
+const approvalAuditIdentity = (context: AiToolApprovalChangeContext): ApprovalAuditIdentity => {
+  const user = context.actor?.kind === "user" ? context.actor.user : context.actor?.delegatedUser;
+  return {
+    actor: context.actor
+      ? user
+        ? { userId: user.id, uid: user.uid, provider: user.provider, roles: user.roles }
+        : null
+      : { userId: context.actorUserId },
+    // Match aiChatAccessSubject locally: importing assistant-models creates a cycle through firecrawl-tools.
+    accessSubject: user
+      ? {
+          type: "user",
+          userId: user.id,
+          ...(context.actor?.kind === "service_account" ? { delegatedByServiceAccountId: context.actor.serviceAccount.id } : {}),
+        }
+      : context.actor?.kind === "service_account"
+        ? { type: "service_account", serviceAccountId: context.actor.serviceAccount.id }
+        : { type: "user", userId: context.actorUserId },
+    ...(context.actor?.kind === "service_account" ? { serviceAccountId: context.actor.serviceAccount.id } : {}),
+    requestId: context.requestId,
+  };
+};
+
+const approvalAuditEvent = (
+  action: "ai.approval.remember" | "ai.approval.revoke",
+  row: ApprovalAuditRow,
+  identity: ApprovalAuditIdentity,
+): AuditRecordParams => ({
+  action,
+  outcome: "allowed",
+  actor: identity.actor,
+  target: { type: "ai_approval", id: row.id, label: row.tool_name },
+  requestId: identity.requestId,
+  reason: identity.reason,
+  metadata: {
+    toolName: row.tool_name,
+    approvalScope: row.approval_scope,
+    remember: row.conversation_id !== null ? "chat" : "always",
+    ...(row.conversation_id !== null ? { conversationId: row.conversation_id } : {}),
+    accessSubject: identity.accessSubject,
+    ...(identity.serviceAccountId ? { serviceAccountId: identity.serviceAccountId } : {}),
+  },
+});
+
 export const aiToolApprovalScope = (toolName: string, policy: AiToolApprovalPolicy | undefined): string => {
   if (policy && typeof policy === "object") return policy.scope ?? toolName;
   return toolName;
@@ -100,20 +167,12 @@ export const hasRememberedAiToolApproval = async (
 
 /** Remembers an approval everywhere, or in one chat when `conversationId` is set; a chat approval ends with its chat. */
 export const rememberAiToolApproval = async (
-  context: AiToolApprovalContext,
+  context: AiToolApprovalChangeContext,
   input: { toolName: string; approvalScope: string; conversationId?: string | null; expiresAt?: Date | null },
 ): Promise<void> => {
   const conversationId = input.conversationId ?? null;
-  await sql.begin(async () => {
-    await sql`
-      DELETE FROM ai.tool_approval_preferences
-      WHERE actor_user_id = ${context.actorUserId}
-        AND tool_name = ${input.toolName}
-        AND approval_scope = ${input.approvalScope}
-        AND conversation_id IS NOT DISTINCT FROM ${conversationId}::uuid
-    `;
-
-    await sql`
+  await sql.begin(async (tx) => {
+    const [row] = await tx<{ id: string }[]>`
       INSERT INTO ai.tool_approval_preferences (
         actor_user_id,
         tool_name,
@@ -130,24 +189,46 @@ export const rememberAiToolApproval = async (
         now(),
         ${input.expiresAt ?? null}
       )
+      ON CONFLICT (actor_user_id, tool_name, approval_scope, conversation_id)
+      DO UPDATE SET
+        created_at = EXCLUDED.created_at,
+        last_used_at = EXCLUDED.last_used_at,
+        expires_at = EXCLUDED.expires_at
+      RETURNING id
     `;
+    await audit.record(
+      approvalAuditEvent(
+        "ai.approval.remember",
+        {
+          id: row!.id,
+          tool_name: input.toolName,
+          approval_scope: input.approvalScope,
+          conversation_id: conversationId,
+        },
+        approvalAuditIdentity(context),
+      ),
+      tx,
+    );
   });
 };
 
 /** Forgets the approval with exactly this reach: everywhere, or in the one chat `conversationId` names. */
 export const forgetAiToolApproval = async (
-  context: AiToolApprovalContext,
+  context: AiToolApprovalChangeContext,
   input: { toolName: string; approvalScope: string; conversationId?: string | null },
 ): Promise<boolean> => {
-  const rows = await sql<{ id: string }[]>`
-    DELETE FROM ai.tool_approval_preferences
-    WHERE actor_user_id = ${context.actorUserId}
-      AND tool_name = ${input.toolName}
-      AND approval_scope = ${input.approvalScope}
-      AND conversation_id IS NOT DISTINCT FROM ${input.conversationId ?? null}::uuid
-    RETURNING id
-  `;
-  return rows.length > 0;
+  return sql.begin(async (tx) => {
+    const rows = await tx<ApprovalAuditRow[]>`
+      DELETE FROM ai.tool_approval_preferences
+      WHERE actor_user_id = ${context.actorUserId}
+        AND tool_name = ${input.toolName}
+        AND approval_scope = ${input.approvalScope}
+        AND conversation_id IS NOT DISTINCT FROM ${input.conversationId ?? null}::uuid
+      RETURNING id, tool_name, approval_scope, conversation_id
+    `;
+    for (const row of rows) await audit.record(approvalAuditEvent("ai.approval.revoke", row, approvalAuditIdentity(context)), tx);
+    return rows.length > 0;
+  });
 };
 
 const toIsoString = (value: Date | string): string => (value instanceof Date ? value : new Date(value)).toISOString();
@@ -186,12 +267,42 @@ export const listAiToolApprovalPreferences = async (
   return rows.map(approvalPreferenceFromRow);
 };
 
-export const revokeAiToolApprovalPreference = async (actorUserId: string, preferenceId: string): Promise<boolean> => {
-  const rows = await sql<{ id: string }[]>`
+export const revokeAiToolApprovalPreference = async (
+  actorUserId: string,
+  preferenceId: string,
+  change?: { actor?: RequestActor; requestId?: string | null },
+): Promise<boolean> =>
+  sql.begin(async (tx) => {
+    const rows = await tx<ApprovalAuditRow[]>`
+      DELETE FROM ai.tool_approval_preferences
+      WHERE id = ${preferenceId}
+        AND actor_user_id = ${actorUserId}
+      RETURNING id, tool_name, approval_scope, conversation_id
+    `;
+    for (const row of rows)
+      await audit.record(approvalAuditEvent("ai.approval.revoke", row, approvalAuditIdentity({ ...change, actorUserId })), tx);
+    return rows.length > 0;
+  });
+
+/** Core migrations supply their transaction so deletion and system audit events commit together. */
+export const revokeAiToolApprovalPreferencesAsSystem = async (
+  db: SQL,
+  input: { ids: readonly string[]; reason: string },
+): Promise<number> => {
+  if (input.ids.length === 0) return 0;
+  const rows = await db<(ApprovalAuditRow & { actor_user_id: string | null })[]>`
     DELETE FROM ai.tool_approval_preferences
-    WHERE id = ${preferenceId}
-      AND actor_user_id = ${actorUserId}
-    RETURNING id
+    WHERE id = ANY(${toPgTextArray([...input.ids])}::uuid[])
+    RETURNING id, tool_name, approval_scope, conversation_id, actor_user_id
   `;
-  return rows.length > 0;
+  for (const row of rows)
+    await audit.record(
+      approvalAuditEvent("ai.approval.revoke", row, {
+        actor: null,
+        accessSubject: row.actor_user_id === null ? null : { type: "user", userId: row.actor_user_id },
+        reason: input.reason,
+      }),
+      db,
+    );
+  return rows.length;
 };

package/src/ai/background-review.ts

@@ -0,0 +1,72 @@
+import type { CapabilityActionPolicy, CapabilityActionReviewData } from "../contracts/capabilities";
+import { aiChatTasks } from "./chat-tasks";
+
+export class AiBackgroundApprovalRequiredError extends Error {
+  readonly code = "NEEDS_APPROVAL";
+
+  constructor(readonly action: string) {
+    super(
+      `NEEDS_APPROVAL: ${action} needs the user's approval every time, and routines never ask. Stop and say in one sentence what was missing.`,
+    );
+    this.name = "AiBackgroundApprovalRequiredError";
+  }
+}
+
+type BackgroundActionInput = {
+  turnId: string;
+  mandate: { id: string; revision: number };
+  appId: string;
+  capabilityId: string;
+  kind: "query" | "action";
+  args: unknown;
+  policy?: CapabilityActionPolicy;
+  approval?: "none" | "rememberable" | "always";
+  hasReview: boolean;
+  action: string;
+  review: () => Promise<CapabilityActionReviewData | null>;
+  signal?: AbortSignal;
+};
+
+/** Core routine gate. A review can narrow a mandate, never grant authority. */
+export const authorizeBackgroundActionWith = async (
+  input: BackgroundActionInput,
+  authorizeCapability: typeof aiChatTasks.authorizeCapability,
+): Promise<CapabilityActionReviewData | null> => {
+  // These declarations can never be granted to a routine. Stop with the approval state even if a stale grant exists.
+  if (input.kind === "action" && input.policy && (!("silent" in input.policy) || input.policy.routines === false)) {
+    await aiChatTasks.markNeedsApproval({ turnId: input.turnId, action: input.action });
+    throw new AiBackgroundApprovalRequiredError(input.action);
+  }
+  await authorizeCapability({
+    mandate: input.mandate,
+    appId: input.appId,
+    capabilityId: input.capabilityId,
+    kind: input.kind,
+    input: input.args,
+    approval: input.approval,
+    ...(input.policy ? { policy: input.policy } : {}),
+  });
+  if (input.kind === "query" || (!input.policy && input.approval === "none")) return null;
+  input.signal?.throwIfAborted();
+  if (!input.policy && input.approval !== "rememberable") {
+    await aiChatTasks.markNeedsApproval({ turnId: input.turnId, action: input.action });
+    throw new AiBackgroundApprovalRequiredError(input.action);
+  }
+  let review: CapabilityActionReviewData | null = null;
+  if (input.hasReview && !input.signal?.aborted) {
+    try {
+      review = await input.review();
+    } catch {
+      // An unavailable review cannot authorize an unattended effect.
+      input.signal?.throwIfAborted();
+    }
+  }
+  input.signal?.throwIfAborted();
+  if (review && (input.policy ? "sentence" in review && review.ask === undefined : !("sentence" in review) && review.approvalScope))
+    return review;
+  await aiChatTasks.markNeedsApproval({ turnId: input.turnId, action: input.action });
+  throw new AiBackgroundApprovalRequiredError(input.action);
+};
+
+export const authorizeBackgroundAction = (input: BackgroundActionInput): Promise<CapabilityActionReviewData | null> =>
+  authorizeBackgroundActionWith(input, aiChatTasks.authorizeCapability);

package/src/ai/browser.ts

@@ -189,6 +189,16 @@ export const launchAssistant = async (input: LaunchAssistantInput): Promise<Assi
   };
 };
 
+export {
+  CHAT_TASK_REASON_CODES,
+  type ChatTaskReason,
+  type ChatTaskReasonCode,
+  chatTaskLocale,
+  chatTaskNeedsNewTime,
+  chatTaskReasonSentence,
+  chatTaskReasonState,
+  chatTaskStopSentence,
+} from "./chat-task-reasons";
 export {
   CLOUD_AI_STATS_MAX_ITEMS,
   CLOUD_AI_TABLE_MAX_COLUMNS,

package/src/ai/capabilities.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { Tool, ToolContext, ToolResolver } from "@k2b/nessi";
 import { z } from "zod";
 import { resolveCapabilityActionWording, resolveCapabilityOperationTitle } from "../_internal/capabilities";
+import { capabilityReviewView } from "../_internal/capability-reviews";
 import {
   CAPABILITY_APPROVAL_REASON_FIELD,
   CAPABILITY_APPROVAL_REASON_MAX_CHARS,
@@ -13,8 +14,9 @@ import {
 import { HELP_READ_MAX_CHARS, HELP_SEARCH_MAX_LIMIT, readHelpArticle } from "../_internal/help-catalog";
 import {
   type CapabilityActionManifest,
-  type CapabilityActionReview,
+  type CapabilityActionReviewData,
   type CapabilityQueryManifest,
+  capabilityActionPolicy,
   cloudResourceRefAppId,
   LinkedCloudResourceReferenceSchema,
   resolveCapabilityResourceReader,
@@ -756,9 +758,14 @@ export const createLoadedAiCapabilityTools = (input: {
   actor: RequestActor;
   /** Locale of the turn; the approval text a person reads is worded in it. */
   locale?: string;
-  review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReview | null>;
-  authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown) => Promise<void>;
-  onReview?: (callId: string, review: CapabilityActionReview) => void;
+  review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReviewData | null>;
+  authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<void>;
+  onReview?: (
+    callId: string,
+    review: CapabilityActionReviewData,
+    approval: CapabilityActionManifest["approval"],
+    entry: AiCapabilityCatalogEntry,
+  ) => void | Promise<void>;
   execute: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<unknown>;
 }): AiRuntimeTool[] => {
   const byName = new Map(input.catalog.map((entry) => [entry.name, entry]));
@@ -769,7 +776,7 @@ export const createLoadedAiCapabilityTools = (input: {
       defineAiTool({
         name: entry.providerName,
         canonicalName: entry.name,
-        description: `${entry.title}. ${entry.description} Never retry ACTION_OUTCOME_UNKNOWN. Do not retry unchanged after INTERNAL or INVALID_APP_RESPONSE; report the provider error.`,
+        description: `${entry.title}. ${entry.description} Never retry ACTION_OUTCOME_UNKNOWN or NEEDS_APPROVAL. Never retry IDEMPOTENCY_UNCERTAIN or IDEMPOTENCY_IN_PROGRESS. After ACTION_NOT_DONE, ask the person before trying again. Do not retry unchanged after INTERNAL or INVALID_APP_RESPONSE; report the provider error.`,
         inputSchema: aiCapabilityInputSchema(
           offersApprovalReason(entry) ? withApprovalReason(entry.operation.inputSchema) : entry.operation.inputSchema,
         ),
@@ -779,16 +786,21 @@ export const createLoadedAiCapabilityTools = (input: {
         approval: "never",
       }).server(async (modelArgs, context) => {
         const args = withoutApprovalReason(entry, modelArgs);
-        await input.authorizeBackground?.(entry, args);
+        await input.authorizeBackground?.(entry, args, context);
         if (!input.authorizeBackground && entry.kind === "action" && (entry.operation as CapabilityActionManifest).approval !== "none") {
           const review = (await input.review?.(entry, args, context)) ?? null;
-          if (review && context.callId) input.onReview?.(context.callId, review);
+          if (review && context.callId)
+            await input.onReview?.(context.callId, review, "approval" in entry.operation ? entry.operation.approval : undefined, entry);
           // Text-only readers such as the CLI read what the card shows: the app's sentence, its review, and the model's reason.
           const locale = input.locale ?? DEFAULT_LOCALE;
           const message = capabilityApprovalText({
             appName: entry.display.appName,
             subject: capabilityActionSubject(aiCapabilityActionWording(entry, locale), args, { locale, timeZone: context.timeZone }),
-            review: review?.message,
+            review: review
+              ? capabilityReviewView(review, {
+                  timeZone: context.timeZone ?? "UTC",
+                }).message
+              : undefined,
             reason: offersApprovalReason(entry) ? capabilityApprovalReason(modelArgs) : null,
             locale,
           });
@@ -873,9 +885,14 @@ export const createAiToolResolver =
     locale?: string;
     maxLoadedTools?: number;
     execute?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<unknown>;
-    review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReview | null>;
-    authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown) => Promise<void>;
-    onReview?: (callId: string, review: CapabilityActionReview) => void;
+    review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReviewData | null>;
+    authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<void>;
+    onReview?: (
+      callId: string,
+      review: CapabilityActionReviewData,
+      approval: CapabilityActionManifest["approval"],
+      entry: AiCapabilityCatalogEntry,
+    ) => void | Promise<void>;
     onPrepared?: (snapshot: {
       prepared: PreparedAiTools;
       presentations: Map<string, AiToolPresentation>;
@@ -907,6 +924,7 @@ export const createAiToolResolver =
           capabilityId: entry.operation.localId,
           kind: entry.kind,
           approval: entry.kind === "action" && "approval" in entry.operation ? entry.operation.approval : undefined,
+          capabilityPolicy: capabilityActionPolicy(entry.app.manifest, entry.operation.localId),
         }));
     const mandateExcluded = new Set(
       fullCapabilityCatalog.filter((entry) => !mandateAllows(entry)).flatMap((entry) => [entry.name, entry.providerName]),

package/src/ai/capability-execution.ts

@@ -1,8 +1,15 @@
 import { createHash } from "node:crypto";
 import type { ToolContext } from "@k2b/nessi";
+import { capabilityActionReceiptIssues, capabilityQueryChecksActionOutcome } from "../_internal/capability-reviews";
 import { type CapabilityDispatchDependencies, dispatchCapability } from "../api/capabilities";
 import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
-import { type CapabilityActionManifest, type CapabilityActionReview, CapabilityActionReviewSchema } from "../contracts/capabilities";
+import {
+  type CapabilityActionCallReview,
+  CapabilityActionCheckSchema,
+  type CapabilityActionManifest,
+  type CapabilityActionReviewData,
+  CapabilityActionReviewDataSchema,
+} from "../contracts/capabilities";
 import type { RequestActor } from "../server";
 import type { AccessSubject } from "../server/services/access";
 import { isAccountCategoryAllowed } from "../services/account-category-policy";
@@ -10,10 +17,14 @@ import { isAccountExpired } from "../services/account-model";
 import { accounts } from "../services/accounts";
 import { withoutAdminRole } from "../services/session/user";
 import { LOCALE_HEADER } from "../shared/locale";
+import type { AiActionCheck } from "./action-review";
 import type { AiCapabilityCatalogEntry } from "./capabilities";
+import { AiCapabilityExecutionError } from "./capability-result";
 import { aiToolAudit } from "./tool-audit";
 import type { AiConversationService } from "./types";
 
+export { AiCapabilityExecutionError, aiCapabilityCheckResult } from "./capability-result";
+
 type CapabilityActor = Extract<RequestActor, { kind: "user" }>;
 
 export const resolveAiCapabilityActor = async (input: {
@@ -38,17 +49,6 @@ export const resolveAiCapabilityActor = async (input: {
   return { actor: { kind: "user", user }, accessSubject: { type: "user", userId: user.id } };
 };
 
-export class AiCapabilityExecutionError extends Error {
-  constructor(
-    readonly code: string,
-    readonly status: number,
-    message: string,
-  ) {
-    super(`${code}: ${message}`);
-    this.name = "AiCapabilityExecutionError";
-  }
-}
-
 const idempotencyKey = (conversationId: string, callId: string): string =>
   `ai-${createHash("sha256").update(`${conversationId}\0${callId}`).digest("hex")}`;
 
@@ -71,13 +71,13 @@ const validationIssueText = (details: unknown): string => {
   return issues.length > 0 ? ` Input issues: ${issues.join("; ")}` : "";
 };
 
-const parseCapabilityResponse = async (response: Response): Promise<unknown> => {
+const parseCapabilityResponse = async (response: Response, dispatched: boolean): Promise<unknown> => {
   const body = (await response.json().catch(() => null)) as { code?: unknown; message?: unknown; details?: unknown } | null;
   if (response.ok) return body;
   const code = typeof body?.code === "string" ? body.code : "CAPABILITY_FAILED";
   const message = typeof body?.message === "string" ? body.message : "Capability execution failed";
   const issueText = code === "VALIDATION_FAILED" ? validationIssueText(body?.details) : "";
-  throw new AiCapabilityExecutionError(code, response.status, `${message}${issueText}`);
+  throw new AiCapabilityExecutionError(code, response.status, `${message}${issueText}`, dispatched);
 };
 
 type AiCapabilityCall = {
@@ -96,7 +96,10 @@ type AiCapabilityCall = {
   };
 };
 
-const dispatchAiCapability = async (input: AiCapabilityCall, review: boolean): Promise<unknown> => {
+const dispatchAiCapability = async (
+  input: Omit<AiCapabilityCall, "context"> & { context: Pick<ToolContext, "callId" | "signal"> },
+  review: boolean,
+): Promise<unknown> => {
   if (input.authority.accessSubject.type !== "user" || input.authority.accessSubject.userId !== input.authority.actor.user.id) {
     throw new Error("Cloud capability authority is inconsistent.");
   }
@@ -128,41 +131,71 @@ const dispatchAiCapability = async (input: AiCapabilityCall, review: boolean): P
     headers,
     signal: input.context.signal,
   });
-  return await parseCapabilityResponse(
-    await dispatch({
-      request,
-      kind: input.entry.kind === "query" ? "queries" : "actions",
-      origin: "assistant",
-      review,
-      appId: input.entry.appId,
-      capabilityId: input.entry.operation.localId,
-      input: input.args,
-      authority: {
-        actor: input.authority.actor,
-        accessSubject: input.authority.accessSubject,
-        credentialKind: "session",
-        scopes: [],
-      },
-      mandate: input.mandate
-        ? {
-            mandateId: input.mandate.id,
-            mandateRevision: input.mandate.revision,
-            ownerAppId: "core",
-            ...(!review && input.actionApproval ? { actionApproval: input.actionApproval } : {}),
-          }
-        : undefined,
-      dependencies: input.dependencies,
-    }),
-  );
+  let dispatched = false;
+  const response = await dispatch({
+    request,
+    kind: input.entry.kind === "query" ? "queries" : "actions",
+    origin: "assistant",
+    review,
+    appId: input.entry.appId,
+    capabilityId: input.entry.operation.localId,
+    input: input.args,
+    authority: {
+      actor: input.authority.actor,
+      accessSubject: input.authority.accessSubject,
+      credentialKind: "session",
+      scopes: [],
+    },
+    mandate: input.mandate
+      ? {
+          mandateId: input.mandate.id,
+          mandateRevision: input.mandate.revision,
+          ownerAppId: "core",
+          ...(!review && input.actionApproval ? { actionApproval: input.actionApproval } : {}),
+        }
+      : undefined,
+    dependencies: input.dependencies,
+    onUpstreamAttempt: () => {
+      dispatched = true;
+    },
+  });
+  return await parseCapabilityResponse(response, dispatched);
 };
 
-export const reviewAiCapability = async (input: AiCapabilityCall): Promise<CapabilityActionReview | null> => {
+export const reviewAiCapability = async (input: AiCapabilityCall): Promise<CapabilityActionReviewData | null> => {
   if (input.entry.kind !== "action" || !(input.entry.operation as CapabilityActionManifest).review) return null;
-  return CapabilityActionReviewSchema.parse(await dispatchAiCapability(input, true));
+  return CapabilityActionReviewDataSchema.parse(await dispatchAiCapability(input, true));
 };
 
 export const executeAiCapability = (input: AiCapabilityCall): Promise<unknown> => dispatchAiCapability(input, false);
 
+/** Run only the app-owned read-only outcome Query, once. Invalid answers stay unknown and remain recoverable. */
+export const checkAiCapability = async (
+  input: Omit<AiCapabilityCall, "args" | "actionApproval" | "context"> & {
+    context: Pick<ToolContext, "callId" | "signal">;
+    check: NonNullable<CapabilityActionCallReview["check"]>;
+    /** The app's catalog, in which the check Query is looked up; the caller builds it (no import cycle). */
+    catalog: readonly AiCapabilityCatalogEntry[];
+  },
+): Promise<AiActionCheck> => {
+  try {
+    const query = input.catalog.find(
+      (entry) => entry.appId === input.entry.appId && entry.kind === "query" && entry.operation.localId === input.check.query,
+    );
+    if (!query || "idempotency" in query.operation || !capabilityQueryChecksActionOutcome(query.operation))
+      throw new Error("Action outcome Query is unavailable.");
+    // The Action's audit keeps its own dispatch identity; the Query has its separate platform execution record.
+    const result = await dispatchAiCapability({ ...input, turnId: undefined, entry: query, args: input.check.input }, false);
+    if (!result || typeof result !== "object" || !("data" in result)) throw new Error("Invalid outcome check envelope.");
+    const checked = CapabilityActionCheckSchema.parse(result.data);
+    if (checked.receipt && capabilityActionReceiptIssues(checked.receipt, "links" in result ? result.links : undefined).length)
+      throw new Error("Invalid outcome check receipt.");
+    return { state: checked.outcome, ...(checked.receipt ? { receipt: checked.receipt } : {}), at: new Date().toISOString() };
+  } catch {
+    return { state: "failed", at: new Date().toISOString() };
+  }
+};
+
 /**
  * A rejected approval never reaches the dispatcher, so the assistant records
  * the same execution row the dispatcher would have written for the attempt.