@k2b/cloud 0.40.0 → 0.41.0

package/src/ai/open-questions.ts

@@ -0,0 +1,172 @@
+import { sql } from "bun";
+import { z } from "zod";
+import { APPROVALS_PAGE_SIZE } from "../contracts/approvals";
+import {
+  CapabilityActionCallReviewSchema,
+  CapabilityActionReviewDataSchema,
+  CapabilitySemanticLinkSchema,
+} from "../contracts/capabilities";
+import { openRequests } from "../services/approvals/list";
+import { logger } from "../services/logging";
+import { reviewShortText, toolActionCard, toolBlockReview } from "./chat/action-card";
+import { aiToolIcon } from "./chat/message-utils";
+import { legacyOutcomeWords } from "./chat/tool-action-words";
+import { type AiTurnBlock, toolBlockId } from "./protocol";
+
+export type AiOpenQuestion = {
+  /** The approval request id (approvals.requests.id). */
+  id: string;
+  /** Short id of the chat the question waits in. */
+  conversationId: string;
+  /** The chat's current title, at most 200 code points; chat content, never Cloud's words. */
+  conversationTitle: string | null;
+  /** The question's data-chat-anchor: the id of the tool block the chat renders it in. */
+  anchor: string;
+  /** The question's short form, plain text, at most 160 code points. */
+  short: string;
+  /** The app the question is about, as the card shows it. */
+  app: { name: string; icon: string; accent?: string };
+  createdAt: string;
+};
+
+export type AiOpenQuestions = {
+  items: AiOpenQuestion[];
+  /** All open questions of the person, across pages. */
+  count: number;
+};
+
+type QuestionRow = {
+  id: string;
+  conversationId: string;
+  conversationTitle: string | null;
+  displayCallId: string;
+  appId: string;
+  sentence: string;
+  toolName: string;
+  createdAt: Date;
+  block: Extract<AiTurnBlock, { kind: "tool" }> | null;
+};
+
+const log = logger("ai:open-questions");
+const legacyReviewSchema = z.object({
+  question: z.string().min(1),
+  rows: z.array(z.object({ label: z.string(), value: z.string(), format: z.enum(["date", "date-time"]).optional() })),
+  markdown: z.string().optional(),
+  summary: z.string().optional(),
+  links: z.array(CapabilitySemanticLinkSchema).optional(),
+});
+
+const ownedRequests = (ownerUserId: string) => sql`
+  SELECT r.* FROM (${openRequests(ownerUserId)}) r
+  WHERE EXISTS (
+    SELECT 1 FROM ai.pending_actions p JOIN ai.conversations c ON c.id=p.conversation_id
+    WHERE p.approval_id=r.id AND p.status='pending' AND p.kind IN ('approval','custom_approval')
+      AND c.created_by_user_id=${ownerUserId}::uuid
+  )`;
+
+/** One bounded, owner-scoped snapshot, using exactly the chat's stored question card. */
+export const listAiOpenQuestions = async (input: { ownerUserId: string; locale: string; timeZone: string }): Promise<AiOpenQuestions> => {
+  const [counts] = await sql<{ count: number }[]>`
+    SELECT count(*)::int AS count FROM (${ownedRequests(input.ownerUserId)}) r`;
+  const rows = await sql<QuestionRow[]>`
+    WITH page AS (
+      SELECT * FROM (${ownedRequests(input.ownerUserId)}) r
+      ORDER BY r.created_at DESC, r.id DESC LIMIT ${APPROVALS_PAGE_SIZE}
+    )
+    SELECT r.id, r.app_id AS "appId", r.sentence, r.created_at AS "createdAt",
+      question.short_id AS "conversationId", question.title AS "conversationTitle",
+      question.display_call_id AS "displayCallId", question.tool_name AS "toolName", question.block
+    FROM page r JOIN LATERAL (
+      SELECT c.short_id, c.title, p.tool_name,
+        CASE WHEN p.kind='custom_approval'
+          THEN COALESCE(substring(p.call_id FROM '^(.*)-approval-[0-9]+$'), p.call_id)
+          ELSE p.call_id END AS display_call_id,
+        (SELECT block FROM jsonb_array_elements(
+          CASE WHEN jsonb_typeof(t.live_blocks)='array' THEN t.live_blocks ELSE '[]'::jsonb END
+        ) AS blocks(block)
+          WHERE block->>'kind'='tool' AND block->>'callId'=p.call_id LIMIT 1) AS block
+      FROM ai.pending_actions p JOIN ai.conversations c ON c.id=p.conversation_id
+        JOIN ai.turns t ON t.id=p.turn_id
+      WHERE p.approval_id=r.id AND p.status='pending' AND p.kind IN ('approval','custom_approval')
+        AND c.created_by_user_id=${input.ownerUserId}::uuid
+      ORDER BY p.created_at DESC, p.id DESC LIMIT 1
+    ) question ON true
+    ORDER BY r.created_at DESC, r.id DESC`;
+
+  return {
+    count: counts?.count ?? 0,
+    items: rows.map((row) => openQuestionFromRow(row, input)),
+  };
+};
+
+/** Stop at the payload bound without splitting a Unicode code point or copying the rest of a legacy message. */
+const boundedText = (text: string, max: number): string => {
+  const points: string[] = [];
+  for (const point of text) {
+    if (points.length === max) return `${points.slice(0, max - 1).join("")}…`;
+    points.push(point);
+  }
+  return text;
+};
+
+/** Present one stored question without database access. */
+export const openQuestionFromRow = (row: QuestionRow, input: { locale: string; timeZone: string }): AiOpenQuestion => {
+  const block = row.block;
+  const presentation = block?.presentation;
+  const question: AiOpenQuestion = {
+    id: row.id,
+    conversationId: row.conversationId,
+    conversationTitle: row.conversationTitle === null ? null : boundedText(row.conversationTitle, 200),
+    // The id the chat renders the card under: a custom approval's card carries its parent call, also when a stored
+    // block still has the approval's own id (see normalizeCustomApprovalBlocks in client/projection.ts).
+    anchor: toolBlockId(row.displayCallId),
+    short: boundedText(row.sentence.split(/\r?\n/, 1)[0] ?? "", 160),
+    app: {
+      name: typeof presentation?.appName === "string" ? presentation.appName : block ? "Cloud" : row.appId,
+      icon: aiToolIcon(
+        typeof block?.name === "string" ? block.name : row.toolName,
+        typeof presentation?.appIcon === "string" ? presentation.appIcon : undefined,
+      ),
+      ...(typeof presentation?.appAccent === "string" ? { accent: presentation.appAccent } : {}),
+    },
+    createdAt: row.createdAt.toISOString(),
+  };
+  if (!block) return question;
+  try {
+    if (
+      typeof block.id !== "string" ||
+      !block.id ||
+      typeof block.name !== "string" ||
+      !block.name ||
+      typeof block.callId !== "string" ||
+      !["running", "awaiting_approval", "awaiting_client", "completed", "failed", "rejected"].includes(block.status)
+    )
+      throw new Error("Malformed tool block");
+    if (block.review == null && block.approval?.review != null) CapabilityActionReviewDataSchema.parse(block.approval.review);
+    const review = toolBlockReview(block);
+    if (review !== null) {
+      if ("legacy" in review) legacyReviewSchema.parse(review.legacy);
+      else CapabilityActionCallReviewSchema.parse(review);
+    }
+    const card = toolActionCard(block, {
+      locale: input.locale,
+      timeZone: input.timeZone,
+      outcome: legacyOutcomeWords(block, input.locale, input.timeZone),
+    });
+    const short =
+      review && !("legacy" in review)
+        ? reviewShortText(review, { locale: input.locale, timeZone: input.timeZone, app: card.app })
+        : card.questionText;
+    if (
+      typeof short !== "string" ||
+      typeof card.app.name !== "string" ||
+      typeof card.app.icon !== "string" ||
+      (card.app.accent !== undefined && typeof card.app.accent !== "string")
+    )
+      throw new Error("Malformed question card");
+    return { ...question, short: boundedText(short, 160), app: card.app };
+  } catch {
+    log.warn("Failed to present open question", { approvalId: row.id, conversationId: row.conversationId });
+    return question;
+  }
+};

package/src/ai/question-text.ts

@@ -0,0 +1,8 @@
+/**
+ * The plain-text form of an Assistant question, the same one the chat card shows: for `cld`, notifications, and Cloud
+ * Login. Pure and browser-safe, in its own entry so neither the CLI bundle nor browser bundles that use
+ * `@k2b/cloud/ai/browser` pull it in by accident.
+ */
+export { type ApprovalCardInput, approvalCard } from "../approvals/approval-card";
+export type { ActionCard } from "./chat/action-card";
+export { type ActionQuestionText, type ActionTextRow, actionCardText, actionQuestionLines } from "./chat/action-text";

package/src/ai/routes.ts

@@ -2,10 +2,11 @@ import { type Context, Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
-import { listCapabilities } from "../_internal/registry";
+import { getApp, listCapabilities } from "../_internal/registry";
 import { QUERY_TIMEOUT_MS } from "../api/capabilities";
 import { ErrorResponseSchema } from "../contracts";
 import { APPROVAL_CLIENT_HEADER } from "../contracts/approvals";
+import { capabilityActionPolicy } from "../contracts/capabilities";
 import {
   type AccessSubject,
   type AuthContext,
@@ -26,12 +27,14 @@ import { isAppSessionActor } from "../server/actor";
 import { isRequestCredentialCurrent } from "../server/middleware/auth";
 import { noTransform } from "../server/middleware/no-transform";
 import { REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "../server/request-timeout";
-import { approvalDecisionChannel } from "../services/approvals";
+import { approvalDecisionChannel, approvals } from "../services/approvals";
+import { pendingApprovalReview } from "../services/approvals/question";
 import { ImageMetadataError } from "../services/image-metadata";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
+import { resolveAppIdentityPresentation } from "../shared/app-presentation";
 import { readThemeFromCookieHeader } from "../shared/theme";
-import { isUnknownActionOutcome } from "./action-review";
+import { type AiStoredActionReview, isLegacyActionReview, isUnknownActionOutcome, storedActionReview } from "./action-review";
 import { assistantAiSettingsState, listAssistantAiModels, resolveAssistantAudioModel, selectAssistantAiModelId } from "./assistant-models";
 import { AI_AUDIO_MAX_BYTES } from "./audio-format";
 import { buildAiCapabilityCatalog } from "./capabilities";
@@ -1352,8 +1355,51 @@ export const aiRoutes = (() => {
         if (!conversation) return notFound(c);
         const turn = await loadTurn(conversation, c.req.param("turnId"));
         if (!turn) return notFound(c);
-        const actions = await listPendingAiTurnActions({ conversationId: conversation.id, turnId: turn.id });
-        return respond(c, ok(actions.map((action) => publicPendingAction(action, conversation.shortId, turn.shortId))));
+        const scope = { conversationId: conversation.id, turnId: turn.id };
+        const actions = await listPendingAiTurnActions(scope);
+        if (!actions.some((action) => action.type === "approval_request"))
+          return respond(c, ok(actions.map((action) => publicPendingAction(action, conversation.shortId, turn.shortId))));
+        const [records, reviews, config] = await Promise.all([
+          aiConversations.listPendingActionRecords(scope),
+          aiConversations.listTurnToolReviews(scope),
+          aiConversations.getTurnRunConfig(scope),
+        ]);
+        const locale = config?.kind !== "compact" ? (config?.locale ?? getLocale(c)) : getLocale(c);
+        let capabilities: Promise<Awaited<ReturnType<typeof listCapabilities>> | null> | undefined;
+        const presented = await Promise.all(
+          actions.map(async (action) => {
+            const result = publicPendingAction(action, conversation.shortId, turn.shortId);
+            if (action.type !== "approval_request") return result;
+            const record = records.find((record) => record.callId === action.callId);
+            const request = record?.approvalId ? await approvals.get(record.approvalId) : null;
+            const reviewCallId = record?.kind === "custom_approval" ? action.callId.replace(/-approval-[0-9]+$/, "") : action.callId;
+            const stored = reviews.get(reviewCallId);
+            let review: AiStoredActionReview | null = stored && !isLegacyActionReview(stored) ? stored : null;
+            if (!review && request) {
+              review = pendingApprovalReview({ storedReview: null, details: request.details });
+              if (review && !isLegacyActionReview(review) && !review.ask) {
+                // As the approvals page: the declared reason when the review names none, read once per listing.
+                capabilities ??= listCapabilities().catch(() => null);
+                const manifest = (await capabilities)?.find((entry) => entry.appId === request.appId)?.manifest;
+                review = storedActionReview(review, manifest ? capabilityActionPolicy(manifest, request.action) : undefined);
+              }
+            }
+            const appId = request?.appId;
+            // The name is presentation: a registry that cannot answer leaves the app ID, never the waiting approvals unread.
+            const app = appId && appId !== "assistant" ? await getApp(appId).catch(() => null) : null;
+            return {
+              ...result,
+              ...(review && !isLegacyActionReview(review) ? { review } : {}),
+              app: {
+                id: appId ?? "assistant",
+                name: app ? resolveAppIdentityPresentation(app, locale).name : appId && appId !== "assistant" ? appId : "Cloud",
+              },
+              chatTitle: conversation.title,
+              ...(request ? { expiresAt: request.expiresAt.toISOString() } : {}),
+            };
+          }),
+        );
+        return respond(c, ok(presented));
       })
       .get("/conversations/:conversationId/stream", async (c) => {
         const ctx = await resolveContext(c);

package/src/ai/store.ts

@@ -3607,6 +3607,24 @@ export const aiConversations: AiConversationService = {
     return row ? rowToPendingActionRecord(row) : null;
   },
 
+  listTurnToolReviews: async (input) => {
+    // Only the review metadata, never the messages themselves, which can carry large tool results.
+    const rows = await sql<{ tool_reviews: Record<string, AiStoredActionReview> | null }[]>`
+      SELECT meta->'toolReviews' AS tool_reviews
+      FROM (
+        SELECT meta, seq, conversation_id, loop_id, role FROM ai.messages
+        UNION ALL
+        SELECT meta, seq, conversation_id, loop_id, role FROM ai.task_messages
+      ) messages
+      WHERE conversation_id = ${input.conversationId}
+        AND loop_id = ${input.turnId}
+        AND role = 'assistant'
+        AND meta ? 'toolReviews'
+      ORDER BY seq ASC
+    `;
+    return new Map(rows.flatMap((row) => Object.entries(row.tool_reviews ?? {})));
+  },
+
   listPendingActionRecords: async (input) => {
     const rows = await sql<PendingActionRow[]>`
       SELECT *

package/src/ai/testing.ts

@@ -0,0 +1,36 @@
+import { actionFixtures } from "./chat/action-question.fixtures";
+import { type AiOpenQuestion, openQuestionFromRow } from "./open-questions";
+import type { AiTurnBlock } from "./protocol";
+
+/**
+ * Demo Assistant questions for host tests and screenshots, in German and English, with fixed times. The demo data may
+ * change in any release: assert on what your host renders from it, not on its wording.
+ */
+export const aiQuestionFixtures = (locale: "de" | "en"): Record<string, { block: Extract<AiTurnBlock, { kind: "tool" }> }> =>
+  actionFixtures(locale);
+
+/** A waiting question as `listAiOpenQuestions` presents it from the chat's tool block. */
+export const aiOpenQuestionFixture = (
+  input: {
+    id: string;
+    conversationId: string;
+    conversationTitle: string | null;
+    createdAt: string;
+    block: Extract<AiTurnBlock, { kind: "tool" }>;
+  },
+  context: { locale: string; timeZone: string },
+): AiOpenQuestion =>
+  openQuestionFromRow(
+    {
+      id: input.id,
+      conversationId: input.conversationId,
+      conversationTitle: input.conversationTitle,
+      displayCallId: input.block.callId,
+      appId: input.block.presentation?.kind === "capability" ? input.block.presentation.appId : "core",
+      sentence: "",
+      toolName: input.block.name,
+      createdAt: new Date(input.createdAt),
+      block: input.block,
+    },
+    context,
+  );

package/src/ai/tool-sentences.ts

@@ -1,38 +1,156 @@
-import type { CapabilityPresentationCatalog } from "../contracts/capabilities";
+import { actionReview } from "../capabilities/reviews";
+import type { CapabilityActionCallReview } from "../contracts/capabilities";
+import { CodeActionInput } from "./browser-code-contracts";
 
-/**
- * Sentences for Cloud's own Assistant tools that act on something, in the catalog shape every app uses for
- * its Actions and keyed by tool name. The chat words these calls through the same renderer as app Actions;
- * a test checks every placeholder against the tool's input schema. A tool that only reads or does several
- * things, such as `memory` searching, adding, or forgetting, keeps its title with what it acted on instead.
- */
-export const CLOUD_AI_TOOL_PRESENTATION = {
-  baseLocale: "en",
-  sentences: {
-    // Code asks for approvals of what it does inside the run, so a rejection or a stop does not mean the code did not run.
-    code_run: { approval: "Run code", done: "Ran code" },
-    code_action: { approval: "Run app action {input.action}", done: "Ran app action {input.action}" },
-    web_extract: { approval: "Read {input.url}", done: "Read {input.url}", notRun: "{input.url} not read" },
-    fetch_file: { approval: "Download {input.url}", done: "Downloaded {input.url}", notRun: "{input.url} not downloaded" },
-    write_file: { approval: "Write {input.path}", done: "Wrote {input.path}", notRun: "{input.path} not written" },
+// Like the catalog these forms replace, code runs name no "not run" form: code asks about what it does inside the run,
+// so a declined or stopped question does not mean the code did not run. No tool names a "rejected" form, so a declined
+// call keeps Cloud's own words.
+const forms = {
+  en: {
+    code_run: {
+      action: "Run code",
+      running: "Running code",
+      done: "Ran code",
+      confirm: "Run code",
+      decline: "Do not run",
+    },
+    code_action: {
+      action: "Run app action {action}",
+      running: "Running app action {action}",
+      done: "Ran app action {action}",
+      confirm: "Run action",
+      decline: "Do not run",
+    },
+    web_extract: {
+      action: "Read page on {site}",
+      running: "Reading page on {site}",
+      done: "Read page on {site}",
+      confirm: "Read page",
+      decline: "Do not read",
+      notRun: "Page on {site} not read",
+    },
+    fetch_file: {
+      action: "Download file from {site}",
+      running: "Downloading file from {site}",
+      done: "Downloaded file from {site}",
+      confirm: "Download file",
+      decline: "Do not download",
+      notRun: "File from {site} not downloaded",
+    },
+    write_file: {
+      action: "Write {file}",
+      running: "Writing {file}",
+      done: "Wrote {file}",
+      confirm: "Write file",
+      decline: "Do not write",
+      notRun: "{file} not written",
+    },
   },
-  translations: {
-    de: {
-      actions: {
-        code_run: { sentences: { approval: "Code ausführen", done: "Code ausgeführt" } },
-        code_action: { sentences: { approval: "App-Aktion {input.action} ausführen", done: "App-Aktion {input.action} ausgeführt" } },
-        web_extract: { sentences: { approval: "{input.url} lesen", done: "{input.url} gelesen", notRun: "{input.url} nicht gelesen" } },
-        fetch_file: {
-          sentences: {
-            approval: "{input.url} herunterladen",
-            done: "{input.url} heruntergeladen",
-            notRun: "{input.url} nicht heruntergeladen",
-          },
-        },
-        write_file: {
-          sentences: { approval: "{input.path} schreiben", done: "{input.path} geschrieben", notRun: "{input.path} nicht geschrieben" },
-        },
-      },
+  de: {
+    code_run: {
+      action: "Code ausführen",
+      running: "Code wird ausgeführt",
+      done: "Code ausgeführt",
+      confirm: "Code ausführen",
+      decline: "Nicht ausführen",
+    },
+    code_action: {
+      action: "App-Aktion {action} ausführen",
+      running: "App-Aktion {action} wird ausgeführt",
+      done: "App-Aktion {action} ausgeführt",
+      confirm: "Aktion ausführen",
+      decline: "Nicht ausführen",
+    },
+    web_extract: {
+      action: "Seite auf {site} lesen",
+      running: "Seite auf {site} wird gelesen",
+      done: "Seite auf {site} gelesen",
+      confirm: "Seite lesen",
+      decline: "Nicht lesen",
+      notRun: "Seite auf {site} nicht gelesen",
+    },
+    fetch_file: {
+      action: "Datei von {site} herunterladen",
+      running: "Datei von {site} wird heruntergeladen",
+      done: "Datei von {site} heruntergeladen",
+      confirm: "Datei herunterladen",
+      decline: "Nicht herunterladen",
+      notRun: "Datei von {site} nicht heruntergeladen",
+    },
+    write_file: {
+      action: "{file} schreiben",
+      running: "{file} wird geschrieben",
+      done: "{file} geschrieben",
+      confirm: "Datei schreiben",
+      decline: "Nicht schreiben",
+      notRun: "{file} nicht geschrieben",
     },
   },
-} as const satisfies CapabilityPresentationCatalog;
+} as const;
+
+/** The bound of a `fields` preview value. */
+const ADDRESS_MAX = 2000;
+const readableAddress = (address: string): string | null => {
+  try {
+    return decodeURI(address);
+  } catch {
+    return null;
+  }
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Cloud tools use the same per-call review contract as application Actions. Safe for historical, incomplete inputs. */
+export const cloudToolReview = (name: string, args: unknown, locale: string): CapabilityActionCallReview | null => {
+  if (!isRecord(args)) return null;
+  const language = /^de(?:-|$)/i.test(locale) ? "de" : "en";
+  const input = args;
+  const sentence = forms[language];
+  try {
+    if (name === "code_run") {
+      return actionReview({ locale: language, sentence: sentence.code_run }, {});
+    }
+    if (name === "code_action") {
+      const parsed = CodeActionInput.shape.action.safeParse(input.action);
+      if (!parsed.success) return null;
+      return actionReview({ locale: language, sentence: sentence.code_action }, { action: { kind: "text", value: parsed.data } });
+    }
+    if (name === "web_extract" || name === "fetch_file") {
+      if (typeof input.url !== "string" || !input.url.trim()) return null;
+      const href = input.url;
+      const url = new URL(href);
+      if (!url.host) return null;
+      const label = language === "de" ? "Adresse" : "Address";
+      const review = (rows: { label: string; value: string }[]) =>
+        actionReview(
+          { locale: language, sentence: sentence[name] },
+          // A place title holds 200 characters; the address rows keep the whole host.
+          { site: { kind: "place", title: url.host.length > 200 ? `${url.host.slice(0, 99)}…${url.host.slice(-100)}` : url.host } },
+          { preview: { kind: "fields", rows } },
+        );
+      // One address row holds at most 2,000 characters. An address whose encoded form is longer shows as written;
+      // if even that does not fit, the encoded address continues over numbered rows, so every character stays visible.
+      for (const address of [href, readableAddress(href)])
+        if (address && address.length <= ADDRESS_MAX) {
+          try {
+            return review([{ label, value: address }]);
+          } catch {
+            // Try the next form.
+          }
+        }
+      const parts = Array.from({ length: Math.ceil(href.length / ADDRESS_MAX) }, (_, index) =>
+        href.slice(index * ADDRESS_MAX, (index + 1) * ADDRESS_MAX),
+      );
+      return review(parts.map((value, index) => ({ label: `${label} ${index + 1}/${parts.length}`, value })));
+    }
+    if (name === "write_file") {
+      if (typeof input.path !== "string" || !input.path.trim()) return null;
+      const file = input.path.trim().split("/").at(-1);
+      if (!file) return null;
+      return actionReview({ locale: language, sentence: sentence.write_file }, { file: { kind: "object", title: file.slice(0, 200) } });
+    }
+  } catch {
+    // Historical calls can predate the current bounds or carry partial input; they keep their generic tool title.
+  }
+  return null;
+};

package/src/ai/tool-wording.ts

@@ -4,13 +4,12 @@ import {
   capabilityActionSubject,
   capabilityReviewSentence,
   capabilitySentenceText,
-  resolveCapabilityActionSentences,
 } from "../_internal/capability-sentences";
 import { CapabilityActionReceiptSchema } from "../contracts/capabilities";
 import { type AiStoredActionReview, isLegacyActionReview, storedActionReview } from "./action-review";
-import { displayToolName, isRecord } from "./chat/message-utils";
+import { isRecord } from "./chat/message-utils";
 import type { AiTurnBlock } from "./protocol";
-import { CLOUD_AI_TOOL_PRESENTATION } from "./tool-sentences";
+import { cloudToolReview } from "./tool-sentences";
 
 type ToolBlock = Extract<AiTurnBlock, { kind: "tool" }>;
 
@@ -20,7 +19,7 @@ const reviewOf = (block: ToolBlock): AiStoredActionReview | null =>
 
 /**
  * How the chat words one call that acts on something: an app Action through its saved presentation, a
- * Cloud tool through Cloud's own catalog of the same shape. `null` for calls that only read.
+ * Cloud tool through its per-call review. `null` for calls that only read.
  */
 export const toolWording = (block: ToolBlock, locale: string): CapabilityActionWording | null => {
   const presentation = block.presentation;
@@ -32,8 +31,10 @@ export const toolWording = (block: ToolBlock, locale: string): CapabilityActionW
       ...(presentation.fields ? { fields: presentation.fields } : {}),
     };
   }
-  const sentences = resolveCapabilityActionSentences(block.name, CLOUD_AI_TOOL_PRESENTATION, locale);
-  return sentences ? { title: displayToolName(block.name, locale), sentences } : null;
+  const review = cloudToolReview(block.name, block.args, locale);
+  return review
+    ? { title: capabilitySentenceText(review.sentence.action, review.slots, { locale: review.locale, timeZone: "UTC" }) }
+    : null;
 };
 
 /**
@@ -45,6 +46,8 @@ export const toolSubject = (block: ToolBlock, locale: string, timeZone: string):
   const review = reviewOf(block);
   if (review && !isLegacyActionReview(review))
     return capabilitySentenceText(review.sentence.action, review.slots, { locale: review.locale, timeZone });
+  const cloudReview = cloudToolReview(block.name, block.args, locale);
+  if (cloudReview) return capabilitySentenceText(cloudReview.sentence.action, cloudReview.slots, { locale: cloudReview.locale, timeZone });
   const wording = toolWording(block, locale);
   return wording ? capabilityActionSubject(wording, block.args, { locale, timeZone }) : null;
 };
@@ -59,6 +62,9 @@ export const toolOutcome = (block: ToolBlock, key: "done" | "rejected" | "notRun
     return capabilityReviewSentence(review, key, { timeZone });
   }
   if (review && key === "done" && review.legacy.summary) return review.legacy.summary;
+  const cloudReview = cloudToolReview(block.name, block.args, locale);
+  // Only a form the tool names; otherwise the card keeps Cloud's own outcome words for the call.
+  if (cloudReview) return key === "done" || cloudReview.sentence[key] ? capabilityReviewSentence(cloudReview, key, { timeZone }) : null;
   const wording = toolWording(block, locale);
   if (!wording) return null;
   // App Actions return their data inside the result envelope; Cloud tools return the data itself.

package/src/ai/tools.ts

@@ -1,6 +1,7 @@
 import type { Tool, ToolContext } from "@k2b/nessi";
 import { defineTool as defineNessiTool } from "@k2b/nessi";
 import type { z } from "zod";
+import type { CapabilityActionCallReview } from "../contracts/capabilities";
 import type { RequestActor } from "../server";
 import { aiToolNeedsApproval } from "./approvals";
 import type {
@@ -64,7 +65,7 @@ export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
           /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
-          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          requestApprovalFor?: (message: string, target: AiApprovalTarget, review?: CapabilityActionCallReview) => Promise<boolean>;
           /** Relays a decision for an effect another platform component consumes and executes. */
           requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
           /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
@@ -122,6 +123,8 @@ export type AiToolPreparationContext = {
   linkApproval?: (approvalCallId: string, approvalId: string) => void;
   /** Hears what a nested approval asks for before the approval is requested. */
   describeApproval?: (approvalCallId: string, target: AiApprovalTarget) => void;
+  /** Registers the deterministic review before requesting or consuming a nested approval. */
+  describeReview?: (approvalCallId: string, review: CapabilityActionCallReview) => void | Promise<void>;
   reportWebsiteReceipts?: (callId: string, receipts: AiWebsiteReceipt[]) => Promise<void>;
 };
 
@@ -168,10 +171,11 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
     }
     // Nessi numbers the approvals of one execution in request order; count them to name each one's call ID.
     let approvals = 0;
-    const requestApproval = async (message: string, target?: AiApprovalTarget): Promise<boolean> => {
+    const requestApproval = async (message: string, target?: AiApprovalTarget, review?: CapabilityActionCallReview): Promise<boolean> => {
       while (true) {
         const approvalCallId = `${callId}-approval-${approvals++}`;
         if (target) input.describeApproval?.(approvalCallId, target);
+        if (review) await input.describeReview?.(approvalCallId, review);
         if (!(await ctx.requestApproval(message))) return false;
         const used = await use(approvalCallId);
         if (used === "approved") return true;
@@ -182,7 +186,8 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
     return {
       ...ctx,
       requestApproval,
-      requestApprovalFor: (message: string, target: AiApprovalTarget) => requestApproval(message, target),
+      requestApprovalFor: (message: string, target: AiApprovalTarget, review?: CapabilityActionCallReview) =>
+        requestApproval(message, target, review),
       requestRelayedApproval: async (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => {
         const approvalCallId = `${callId}-approval-${approvals++}`;
         if (options.approvalId) input.linkApproval?.(approvalCallId, options.approvalId);