@k2b/cloud 0.39.0 → 0.41.0

package/src/ai/store.ts

@@ -1,13 +1,19 @@
 import type { DoneReason, InboundEvent, LoopAggregate, Message, SessionStore, StoreEntry } from "@k2b/nessi";
 import type { Usage } from "@k2b/nessi/ai";
 import { type SQL, sql } from "bun";
-import { type CapabilityActionReview, CapabilityActionReviewSchema } from "../contracts/capabilities";
+import { type CapabilityActionReviewData, CapabilityActionReviewDataSchema } from "../contracts/capabilities";
 import { logger } from "../services/logging";
 import { toPgTextArray } from "../services/postgres";
+import { AI_TOOL_CHECK_STALE_MS, type AiActionCheck, type AiStoredActionReview } from "./action-review";
+
+export { AI_TOOL_CHECK_STALE_MS };
+
 import { AI_WEBSITE_APPROVAL_TOOL } from "./approvals";
+import { projectSettledAiToolChecks } from "./capability-result";
 import { aiTurnErrorText } from "./chat/turn-error";
 import { AI_MEMORY_LEARNING_DEFAULT_ENABLED } from "./prefs";
 import type { AiTurnBlock } from "./protocol";
+import { collectRecentSentResourceRefs, RECENT_SENT_CONVERSATION_SCAN_LIMIT, RECENT_SENT_MESSAGE_SCAN_LIMIT } from "./recent-sent-refs";
 import { AiRunTimeout } from "./run-timeout";
 import { withAiShortId, withAiShortIdForDb } from "./short-id";
 import { parseAiTodoPlan } from "./todo-contracts";
@@ -65,6 +71,45 @@ export const resolveAiTurnShortIds = async (input: {
   return new Map(rows.map((row) => [row.id, row.short_id]));
 };
 
+/**
+ * Marker texts of the owner's latest sent messages, newest first. The candidates carry no message bodies; only the
+ * newest few are read for their resource markers.
+ */
+export const recentSentResourceMarkersQuery = (ownerUserId: string) => sql<
+  { conversation_id: string; short_id: string; created_at: Date | string; markers: string[] }[]
+>`
+      WITH conversations AS MATERIALIZED (
+        SELECT id FROM ai.conversations
+        WHERE created_by_user_id = ${ownerUserId}::uuid AND archived_at IS NULL
+        ORDER BY updated_at DESC
+        LIMIT ${RECENT_SENT_CONVERSATION_SCAN_LIMIT}
+      ), recent_messages AS MATERIALIZED (
+        SELECT candidate.id, candidate.conversation_id, candidate.created_at FROM conversations
+        CROSS JOIN LATERAL (
+          SELECT message.id, message.conversation_id, message.created_at
+          FROM ai.messages message
+          WHERE message.conversation_id = conversations.id
+            AND message.role = 'user' AND message.kind = 'message'
+            AND NOT (COALESCE(message.meta, '{}'::jsonb) ? 'scheduledTask')
+            AND NOT (COALESCE(message.meta, '{}'::jsonb) ? 'agentMessage')
+          ORDER BY message.seq DESC
+          LIMIT ${RECENT_SENT_MESSAGE_SCAN_LIMIT}
+        ) candidate
+        ORDER BY candidate.created_at DESC, candidate.id DESC
+        LIMIT ${RECENT_SENT_MESSAGE_SCAN_LIMIT}
+      )
+      SELECT recent_messages.conversation_id, sent.short_id, recent_messages.created_at,
+             array_agg(part->>'text' ORDER BY ordinal) AS markers
+      FROM recent_messages
+      JOIN ai.messages sent ON sent.id = recent_messages.id
+      CROSS JOIN LATERAL jsonb_array_elements(
+        CASE WHEN jsonb_typeof(sent.message->'content') = 'array' THEN sent.message->'content' ELSE '[]'::jsonb END
+      ) WITH ORDINALITY AS content(part, ordinal)
+      WHERE part->>'type' = 'text' AND ltrim(part->>'text') LIKE '[Attached Cloud resource %'
+      GROUP BY recent_messages.id, recent_messages.conversation_id, sent.short_id, recent_messages.created_at
+      ORDER BY recent_messages.created_at DESC, recent_messages.id DESC
+    `;
+
 type ConversationSearchBackend = "native" | "bm25";
 let conversationSearchBackendPromise: Promise<ConversationSearchBackend> | null = null;
 
@@ -485,9 +530,9 @@ const parseJsonValue = <T>(value: unknown): T => {
   return value as T;
 };
 
-const parseCapabilityActionReview = (value: unknown): CapabilityActionReview | undefined => {
+const parseCapabilityActionReview = (value: unknown): CapabilityActionReviewData | undefined => {
   if (value === null || value === undefined) return undefined;
-  const parsed = CapabilityActionReviewSchema.safeParse(parseJsonValue(value));
+  const parsed = CapabilityActionReviewDataSchema.safeParse(parseJsonValue(value));
   return parsed.success ? parsed.data : undefined;
 };
 
@@ -530,6 +575,13 @@ const conversationRunStatus = (status: AiTurnStatus | null | undefined, browserP
 const todoMessageJson = () => sql`(CASE WHEN jsonb_typeof(message) = 'string' THEN (message #>> '{}')::jsonb ELSE message END)`;
 const todoMetaJson = () => sql`(CASE WHEN jsonb_typeof(meta) = 'string' THEN (meta #>> '{}')::jsonb ELSE meta END)`;
 
+/** What a copied message keeps of its meta: its todo plan, and its calls' reviews and checks, so a fork reads the same. */
+const copiedMessageMetaJson = () => sql`NULLIF(jsonb_strip_nulls(jsonb_build_object(
+  'todoPlan', ${todoMetaJson()}->'todoPlan',
+  'toolReviews', ${todoMetaJson()}->'toolReviews',
+  'toolChecks', ${todoMetaJson()}->'toolChecks'
+)), '{}'::jsonb)`;
+
 // A scheduled result arriving during an interactive turn becomes context on the next turn.
 const visibleToTurn = (turnId?: string) => sql`(
   ${turnId ?? null}::text IS NULL OR NOT COALESCE(meta ? 'scheduledTask', false) OR seq < ALL (
@@ -929,6 +981,114 @@ export const recordAiWebsiteReceipts = async (input: {
   `;
 };
 
+/** Reviews and outcome checks belong to the assistant message containing the call, including scheduled turns. */
+const recordAiToolMeta = async (
+  input: { conversationId: string; turnId: string; callId: string },
+  key: "toolReviews" | "toolChecks",
+  value: AiStoredActionReview | AiActionCheck,
+  db = sql,
+): Promise<void> => {
+  let written = false;
+  for (const table of ["ai.messages", "ai.task_messages"]) {
+    const rows = await db<{ id: string }[]>`
+      UPDATE ${db(table)}
+      SET meta = COALESCE(meta, '{}'::jsonb) || jsonb_build_object(
+        ${key}::text, COALESCE(meta->${key}::text, '{}'::jsonb) ||
+          jsonb_build_object(${input.callId}::text, ${JSON.stringify(value)}::text::jsonb)
+      )
+      WHERE conversation_id = ${input.conversationId}::uuid AND loop_id = ${input.turnId}::text
+        AND role = 'assistant'
+        AND message->'content' @> jsonb_build_array(jsonb_build_object('type', 'tool_call', 'id', ${input.callId}::text))
+      RETURNING id`;
+    written ||= rows.length > 0;
+  }
+  if (!written) throw new Error("AI tool call message is unavailable.");
+};
+
+export const recordAiToolReview = (input: { conversationId: string; turnId: string; callId: string; review: AiStoredActionReview }) =>
+  recordAiToolMeta(input, "toolReviews", input.review);
+
+export const recordAiToolCheck = (input: { conversationId: string; turnId: string; callId: string; check: AiActionCheck }, db = sql) =>
+  recordAiToolMeta(input, "toolChecks", input.check, db);
+
+/**
+ * Writes one call's check only where `allowed` holds for its current state, in one statement per table, so two Core
+ * replicas or the executor and a person's re-check can never both hold a check, and a settled result is never replaced.
+ */
+const writeAiToolCheckWhere = async (
+  input: { conversationId: string; turnId: string; callId: string },
+  check: AiActionCheck,
+  allowed: (current: SQL.Query<unknown>) => SQL.Query<unknown>,
+): Promise<boolean> => {
+  let written = false;
+  for (const table of ["ai.messages", "ai.task_messages"]) {
+    const current = sql`meta->'toolChecks'->${input.callId}::text`;
+    const rows = await sql<{ id: string }[]>`
+      UPDATE ${sql(table)}
+      SET meta = COALESCE(meta, '{}'::jsonb) || jsonb_build_object(
+        'toolChecks', COALESCE(meta->'toolChecks', '{}'::jsonb) ||
+          jsonb_build_object(${input.callId}::text, ${JSON.stringify(check)}::text::jsonb)
+      )
+      WHERE conversation_id = ${input.conversationId}::uuid AND loop_id = ${input.turnId}::text
+        AND role = 'assistant'
+        AND message->'content' @> jsonb_build_array(jsonb_build_object('type', 'tool_call', 'id', ${input.callId}::text))
+        AND (${allowed(current)})
+      RETURNING id`;
+    written ||= rows.length > 0;
+  }
+  return written;
+};
+
+/**
+ * Claims the check of one call: stores `checking` at `at`, which is the claim's token, when no check holds and none
+ * settled. A call without any check yet may be claimed only with `first`, which the executor uses after an unknown
+ * outcome. A `checking` older than `staleBefore` belonged to a worker or request that stopped and may be taken over.
+ */
+export const claimAiToolCheck = (input: {
+  conversationId: string;
+  turnId: string;
+  callId: string;
+  at: string;
+  staleBefore: string;
+  first?: boolean;
+}): Promise<boolean> =>
+  writeAiToolCheckWhere(
+    input,
+    { state: "checking", at: input.at },
+    (current) => sql`
+      ${input.first ? sql`${current} IS NULL OR` : sql``}
+      ${current}->>'state' IN ('pending', 'failed')
+      OR (${current}->>'state' = 'checking' AND COALESCE(${current}->>'at', '') < ${input.staleBefore}::text)`,
+  );
+
+/** Stores the result of the claim made at `claimedAt`, only while that claim still holds. */
+export const settleAiToolCheck = (input: {
+  conversationId: string;
+  turnId: string;
+  callId: string;
+  claimedAt: string;
+  check: AiActionCheck;
+}): Promise<boolean> =>
+  writeAiToolCheckWhere(
+    input,
+    input.check,
+    (current) => sql`${current}->>'state' = 'checking' AND ${current}->>'at' = ${input.claimedAt}::text`,
+  );
+
+/** The stored check of one call, or null. */
+export const readAiToolCheck = async (input: { conversationId: string; turnId: string; callId: string }): Promise<AiActionCheck | null> => {
+  for (const table of ["ai.messages", "ai.task_messages"]) {
+    const [row] = await sql<{ check: AiActionCheck | null }[]>`
+      SELECT meta->'toolChecks'->${input.callId}::text AS check FROM ${sql(table)}
+      WHERE conversation_id = ${input.conversationId}::uuid AND loop_id = ${input.turnId}::text
+        AND role = 'assistant'
+        AND message->'content' @> jsonb_build_array(jsonb_build_object('type', 'tool_call', 'id', ${input.callId}::text))
+      LIMIT 1`;
+    if (row?.check) return row.check;
+  }
+  return null;
+};
+
 /** Insert a message inside an open conversation-lock transaction and bump the conversation. */
 const insertMessageLocked = async (
   input: {
@@ -1219,15 +1379,17 @@ export const aiConversations: AiConversationService = {
       );
       const target = rows[0];
       if (!target) throw new Error("Failed to fork conversation.");
+      // Copies keep their original send time because Recent orders by it.
       await tx`
         INSERT INTO ai.messages (
           short_id, conversation_id, seq, kind, role, message, search_text, loop_id,
-          model_profile_id, provider_model, usage, stop_reason, loop_aggregate, loop_done_reason, meta
+          model_profile_id, provider_model, usage, stop_reason, loop_aggregate, loop_done_reason, meta, created_at
         )
         SELECT
           short_id, ${target.id}::uuid, seq, kind, role, message, search_text, loop_id,
           model_profile_id, provider_model, usage, stop_reason, loop_aggregate, loop_done_reason,
-          CASE WHEN ${todoMetaJson()} ? 'todoPlan' THEN jsonb_build_object('todoPlan', ${todoMetaJson()}->'todoPlan') ELSE NULL END
+          ${copiedMessageMetaJson()},
+          created_at
         FROM ai.messages
         WHERE conversation_id = ${input.sourceConversationId}::uuid
           AND compacted_at IS NULL
@@ -1563,6 +1725,18 @@ export const aiConversations: AiConversationService = {
     };
   },
 
+  listRecentSentResourceRefs: async ({ ownerUserId }) => {
+    const rows = await recentSentResourceMarkersQuery(ownerUserId);
+    return collectRecentSentResourceRefs(
+      rows.map((row) => ({
+        conversationId: row.conversation_id,
+        messageId: row.short_id,
+        lastSentAt: iso(row.created_at),
+        markers: row.markers,
+      })),
+    );
+  },
+
   listUserConversationResources: async (input) => {
     const limit = Math.min(Math.max(Math.floor(input.limit ?? 20), 1), 100);
     const pattern = searchPattern(input.search);
@@ -2507,6 +2681,7 @@ export const aiConversations: AiConversationService = {
 
     await sql.begin(async (tx) => {
       await tx`SELECT id FROM ai.conversations WHERE id = ${input.targetConversationId} FOR UPDATE`;
+      // Copies keep their original send time because Recent orders by it.
       await tx`
         INSERT INTO ai.messages (
           short_id,
@@ -2523,7 +2698,8 @@ export const aiConversations: AiConversationService = {
           stop_reason,
           loop_aggregate,
           loop_done_reason,
-          meta
+          meta,
+          created_at
         )
         SELECT
           short_id,
@@ -2540,7 +2716,8 @@ export const aiConversations: AiConversationService = {
           stop_reason,
           loop_aggregate,
           loop_done_reason,
-          CASE WHEN ${todoMetaJson()} ? 'todoPlan' THEN jsonb_build_object('todoPlan', ${todoMetaJson()}->'todoPlan') ELSE NULL END
+          ${copiedMessageMetaJson()},
+          created_at
         FROM ai.messages
         WHERE conversation_id = ${input.sourceConversationId}
           AND compacted_at IS NULL
@@ -2862,10 +3039,33 @@ export const aiConversations: AiConversationService = {
     `;
     if (!rows[0]) return null;
     // The waits let a reconnecting client show work time without time spent waiting for the user.
-    const waits = await activeTurnWaits(rows[0].id);
+    const [waits, metadata] = await Promise.all([
+      activeTurnWaits(rows[0].id),
+      sql<{ tool_reviews: Record<string, AiStoredActionReview> | null; tool_checks: Record<string, AiActionCheck> | null }[]>`
+        SELECT meta->'toolReviews' AS tool_reviews, meta->'toolChecks' AS tool_checks
+        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 = ${rows[0].id}
+          AND role = 'assistant'
+          AND (meta ? 'toolReviews' OR meta ? 'toolChecks')
+        ORDER BY seq ASC
+      `,
+    ]);
+    // A person may re-check while the model continues. Durable checks outrank the worker's earlier live snapshot.
+    const reviews = new Map(metadata.flatMap((row) => Object.entries(row.tool_reviews ?? {})));
+    const checks = new Map(metadata.flatMap((row) => Object.entries(row.tool_checks ?? {})));
     return {
       turn: rowToTurn(rows[0]),
-      liveBlocks: rowToLiveBlocks(rows[0]),
+      liveBlocks: rowToLiveBlocks(rows[0]).map((block) => {
+        if (block.kind !== "tool") return block;
+        const review = reviews.get(block.callId);
+        const check = checks.get(block.callId);
+        return { ...block, ...(review ? { review } : {}), ...(check ? { check } : {}) };
+      }),
       liveSeq: Number(rows[0].live_seq ?? 0),
       actionWaitMs: Math.max(0, Math.round(waits.actionWaitMs)),
       waitingSince: waits.waitingSince,
@@ -3407,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 *
@@ -3578,7 +3796,7 @@ export const aiConversations: AiConversationService = {
       if (input.background && input.turnId) {
         const own = await aiConversations.listTurnMessages({ conversationId: input.conversationId, loopId: input.turnId });
         const context = input.background.context;
-        return [...context, ...own.map((row) => ({ seq: context.length + row.seq, kind: row.kind, message: row.message }))];
+        return [...context, ...projectSettledAiToolChecks(own.map((row) => ({ ...row, seq: context.length + row.seq })))];
       }
       // Results delivered after this turn started belong to the next turn's context.
       // Compare durable message sequences rather than wall-clock timestamps.
@@ -3592,20 +3810,23 @@ export const aiConversations: AiConversationService = {
           `
           ).map(rowToMessage)
         : await aiConversations.listContextMessages({ conversationId: input.conversationId });
-      return rows.map((row) => ({
-        seq: row.seq,
-        kind: row.kind,
-        message:
-          input.turnInput !== undefined && input.turnId === row.loopId && row.message.role === "user" && !row.meta?.steerId
-            ? {
-                role: "user" as const,
-                content:
-                  typeof input.turnInput === "string"
-                    ? [{ type: "text" as const, text: input.turnInput }]
-                    : input.turnInput.map((part) => (typeof part === "string" ? { type: "text" as const, text: part } : part)),
-              }
-            : row.message,
-      }));
+      return projectSettledAiToolChecks(
+        rows.map((row) => ({
+          seq: row.seq,
+          kind: row.kind,
+          meta: row.meta,
+          message:
+            input.turnInput !== undefined && input.turnId === row.loopId && row.message.role === "user" && !row.meta?.steerId
+              ? {
+                  role: "user" as const,
+                  content:
+                    typeof input.turnInput === "string"
+                      ? [{ type: "text" as const, text: input.turnInput }]
+                      : input.turnInput.map((part) => (typeof part === "string" ? { type: "text" as const, text: part } : part)),
+                }
+              : row.message,
+        })),
+      );
     },
     append: async (message, opts) => {
       // Initial input and durable steering are already persisted transactionally before Nessi appends them.

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-audit.ts

@@ -30,6 +30,14 @@ export const aiToolAudit = {
       LIMIT 1`;
     return row?.conversation_id ?? null;
   },
+  hasCapabilityDispatch: async (input: { turnId: string; callId: string }): Promise<boolean> => {
+    const rows = await sql`
+      SELECT 1 FROM ai.tool_calls
+      WHERE turn_id = ${input.turnId} AND call_id = ${input.callId} AND request_id IS NOT NULL
+      LIMIT 1
+    `;
+    return rows.length > 0;
+  },
   noteCapabilityDispatch: async (input: {
     conversationId: string;
     turnId: string;

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;
+};